@hapipal/hpal-debug

中文文档
2.1.0发布于 2022/11/28MITCommonJS近 30 天下载 4634

hapijs debugging tools for the hpal CLI

原始使用文档
文档目录3 节
  1. Installation
  2. Usage
  3. Commands

hpal-debug

hapijs debugging tools for the hpal CLI

Build Status Coverage Status

Lead Maintainer - Devin Ivy

hpal-debug was designed to help you,

  • :ant: display information about your routes in a neat, customizable table.

    hpal run debug:routes --show cors

  • :beetle: use your hapi server, models, services, etc. interactively through a REPL.

    hpal run debug:repl

  • :bug: hit your routes from the command line without having to restart your server.

    hpal run debug:curl post /user --name Pal -v

Installation

If you're getting started with the pal boilerplate, then your project is already setup with hpal-debug!

  1. Install the hpal-debug package from npm as a dev dependency.

    npm install --save-dev @hapipal/hpal-debug
    
  2. Register hpal-debug on your server as a hapi plugin.

    await server.register(require('@hapipal/hpal-debug'));
    
  3. Ensure server.js or server/index.js exports a function named deployment that returns your configured hapi server.

    Below is a very simple example of boilerplate code to configure a hapi server server, and is not necessarily "production-ready." For a more complete setup, consider using the pal boilerplate, or check-out its approach as seen here.

    // server.js
    
    'use strict';
    
    const Hapi = require('hapi');
    const AppPlugin = require('./app');
    
    // hpal will look for and use exports.deployment()
    // as defined below to obtain a hapi server
    
    exports.deployment = async ({ start } = {}) => {
    
        const server = Hapi.server();
    
        // Assuming your application (its routes, etc.) live in a plugin
        await server.register(AppPlugin);
    
        if (process.env.NODE_ENV !== 'production') {
            await server.register(require('@hapipal/hpal-debug'));
        }
    
        if (start) {
            await server.start();
            console.log(`Server started at ${server.info.uri}`);
        }
    
        return server;
    };
    
    // Start the server only when this file is
    // run directly from the CLI, i.e. "node ./server"
    
    if (!module.parent) {
        exports.deployment({ start: true });
    }
    

And that's it! Now the hpal-debug commands should be available through the hpal CLI. A simple way to check that hpal-debug is setup correctly is to output a pretty display of your route table,

npx hpal run debug:routes

Usage

hpal-debug is intended for use with hapi v19+ and nodejs v12+ (see v1 for lower support).

Commands

hpal run debug:routes

hpal run debug:routes [<route-identifier>] --hide <column-name> --show <column-name>
  e.g. hpal run debug:routes --show cors

This command outputs a neat display of your server's route table.

In order to display a single route, you may specify <route-identifier> as a route id (e.g. user-create), route method and path (e.g. post /users), or route path (e.g. /users, method defaulting to get).

Columns may be hidden or shown using the -H --hide and -s --show flags respectively. Use the flag multiple times to hide or show multiple columns. Below is the list of available columns.

method path id plugin vhost auth cors tags description

The -r --raw flag will output a minimally formatted table with columns separated by tab characters. Non-TTY usage automatically defaults to raw output.

A summary of these options can be displayed with the -h --help flag.

hpal run debug:repl

hpal run debug:repl

This command starts a fully-featured interactive REPL with your initialized server in context. Each of your server's methods, properties, schwifty models, and schmervice services are also made directly available for convenience. Under hpal v2 you can use top-level await. You may also call this command using hpal run debug.

Example
$ hpal run debug:repl

hpal> server.info                 // you can always use the server directly
{ created: 1527567336111,
  started: 0,
  host: 'your-computer.local',
  ...
hpal>                             // or you can omit the "server." for public properties and methods...
hpal>
hpal> info.uri                    // at what URI would I access my server?
'http://your-computer.local'
hpal> Object.keys(registrations)  // what plugins are registered?
[ '@hapipal/hpal-debug', 'my-app' ]
hpal> table().length              // how many routes are defined?
12
hpal> !!match('get', '/my/user')  // does this route exist?
true
hpal> .exit

hpal run debug:curl

hpal run debug:curl <route-identifier> [<route-parameters>] --data <raw-payload> --header <header-info> --raw --verbose
  e.g. hpal run debug:curl post /users --firstName Paldo -v

This command makes a request to a route and displays the result. Notably, you don't need a running server in order to test your route using hpal run debug:curl!

It's required that you determine which route to hit by specifying a <route-identifier> as a route id (e.g. user-create), route method and path (e.g. post /users), or route path (e.g. /users, method defaulting to get).

You may specify any payload, query, or path params as <route-parameters> flags or in the <route-identifier>. Any parameter that utilizes Joi validation through route.options.validate has a command line flag. For example, a route with id user-update, method patch, and path /user/{id} that validates the id path parameter and a hometown payload parameter might be hit using the following commands,

hpal run debug:curl patch /user/42 --hometown "Buenos Aires"

# or

hpal run debug:curl user-update --id 42 --hometown "Buenos Aires"

Nested parameters may also be specified. If the route in the previous example validated payloads of the form { user: { hometown } }, one might use one of the following commands instead,

hpal run debug:curl user-update --id 42 --user-hometown "Buenos Aires"

# or

hpal run debug:curl user-update --id 42 --user '{ "hometown": "Buenos Aires" }'

The -d --data flag may be used to specify a request payload as a raw string.

The -H --header flag may be used to specify a request header in the format header-name: header value. This flag may be used multiple times to set multiple headers.

The -r --raw and -v --verbose flags affect the command's output, and may be used in tandem with each other or separately. The -r --raw flag ensures all output is unformatted, while the -v --verbose flag shows information about the request and response including timing, the request payload, request headers, response headers, status code, and response payload. Non-TTY usage automatically defaults to raw output.

A summary of these options can be displayed with the -h --help flag.

Example
$ hpal run debug:curl /user -v

get /user (30ms)

request headers
───────────────────────────────────────────────────────────────────
 user-agent    shot
 host          your-computer.local:0

response headers
───────────────────────────────────────────────────────────────────
 content-type      application/json; charset=utf-8
 vary              origin
 cache-control     no-cache
 content-length    55
 accept-ranges     bytes

result (200 ok)
───────────────────────────────────────────────────────────────────
{
  id: 42,
  firstName: 'Paldo',
  hometown: 'Buenos Aires'
}

版本与发布记录

@hapipal/hpal-debug 共发布 2 个版本,首次发布于 2021/01/06;过去 12 个月发布了 0 个版本。

版本发布日期距今
2.1.0latest2022/11/283 年前
2.0.02021/01/065 年前

关于 @hapipal/hpal-debug 的常见问题

@hapipal/hpal-debug 是什么?

hapijs debugging tools for the hpal CLI

如何安装 @hapipal/hpal-debug?

在项目目录运行 npm install @hapipal/hpal-debug,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@hapi/hapi(>=19 <22)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@hapipal/hpal-debug 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/hapipal__hpal-debug 是否存在。

@hapipal/hpal-debug 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@hapipal/hpal-debug 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=12。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@hapipal/hpal-debug 可以商用吗?

@hapipal/hpal-debug 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hapipal/hpal-debug 的下载量有多少?

根据 npm 官方下载统计,@hapipal/hpal-debug 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,634 次,日均约 154 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hapipal/hpal-debug 还在维护吗?

最新版本 2.1.0 发布于 2022/11/28(3 年前);至今共发布 2 个版本,其中过去 12 个月发布了 0 个;首次发布于 2021/01/06。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。