@gustavnikolaj/async-main-wrap

中文文档
4.0.0发布于 2021/07/26ISCCommonJS零依赖近 30 天下载 5.2万

简单的 CLI 工具包.

中文使用文档
文档目录6 节
  1. 通过您的输出通道
  2. 用参数解析器
  3. 与 esm 有关的工作
  4. Shebang( 如何看起来像一个真正的外壳工具)
  5. 打印前修改错误
  6. 自定义对人友好的错误输出

Async 主包装

npm version Build Status Coverage Status

一个简单的工具,用于将 Cli 工具基于 Async 方法.

// cli.js

const wrap = require("@gustavnikolaj/async-main-wrap");
const main = require("./main.js");

wrap(main)(process.cwd(), process.argv.slice(2));

// main.js

module.exports = async function cliTool(cwd, args) {
  if (!condition) {
    throw new Error("foo!"); // Will exit the CLI tool with status code 1.
  }

  console.log("All done!");
};

这个工具背后的动机是 我厌倦了写同样的台词 包装我的主要方法 小cli公用事业.

除了小而简单,这个工具还使测试你的 Cli 工具 a 很简单 你不必通过命令线来测试 它,你可以简单的测试你的主要方法.

下列规则适用于主要方法:

  • 他们应该返回一个承诺(或者,你知道的,是一个主动函数).
  • 如果它们用数字退出属性投出一个错误 当关闭进程时.

这两份文件都有其实例 examples 目录和目录 test/__fixtures__固定装置包含一些不同用途的例子,但 一般来说 大部分会像顶级的榜样 最好的 更真实世界的实施很可能是 光标示例。 。 。 .

提示

通过您的输出通道

在你通过的辩论上 没有什么聪明的事 无论你通过什么 被包裹的方法 传递到你的实际方法。 如果你想让 测试更简单的输出,你可以通过 console 对象.

// cli.js

const wrap = require("@gustavnikolaj/async-main-wrap");
const main = require("./main.js");

wrap(main)(process.cwd(), process.argv.slice(2), console);

// main.js

module.exports = async function cliTool(args, console) {
  const name = args[0] || "world";

  console.log(`Hello, ${name}!`);
};

// main.spec.js

it("should say hello world", async () => {
  const logs = [];
  const mockConsole = {
    log(message) {
      logs.push(message);
    }
  };

  await main([], mockConsole);

  expect(logs, "to equal", ["Hello, world!"]);
});

it("should say hello Gustav", async () => {
  const logs = [];
  const mockConsole = {
    log(message) {
      logs.push(message);
    }
  };

  await main(["Gustav"], mockConsole);

  expect(logs, "to equal", ["Hello, Gustav!"]);
});

你也可以通过原始的 process.stdout 或者说 process.stderr 溪流,如果 你想更严格地控制.

用参数解析器

您可以使用任何您喜欢的参数解析器, 我这里使用 yargs 作为示例 :

// cli.js

const wrap = require("@gustavnikolaj/async-main-wrap");
const main = require("./main.js");

wrap(main)(process.cwd(), process.argv.slice(2));

// main.js

const yargs = require("yargs");

module.exports = async function main(cwd, args) {
  const argv = yargs(args).argv;

  if (argv.help) {
    printHelp();
    return;
  }

  // ...

  console.log("Done!");
};

与 esm 有关的工作

Es模块的节点"polyful": 风向

// cli.js

require = require("esm")(module);
const wrap = require("@gustavnikolaj/async-main-wrap");
const main = require("./main").default;

wrap(main)(process.cwd(), process.argv.slice(2));

// main.js

export default async function main(cwd, args) {
  // ...
}

Shebang( 如何看起来像一个真正的外壳工具)

这个 #! 文件上方的行将告诉 shell 如何执行 脚本,意思是您不再需要使用 node 二进制.

#!/usr/bin/env node

const wrap = require("@gustavnikolaj/async-main-wrap");
const main = require("./main.js");

wrap(main)(process.cwd(), process.argv.slice(2));

为此您需要给出脚本可执行权限 。 这可以 在Linux和Mac上这样做:

$ chmod +x my-awesome-tool

打印前修改错误

有时你会想在打印错误之前做点什么. 例如 无变化 模块将投掷 自定义属性出错 framesToPop 错误处理器可以用作一个 从堆栈跟踪中删除框架的提示 - 模块将自己放入顶端 任何堆栈追踪,因为它是如何运作的。 使用模块 帧弹出器 您可以删除 那些额外的堆放框.

#!/usr/bin/env node

const wrap = require("@gustavnikolaj/async-main-wrap");
const framePopper = require("@gustavnikolaj/frame-popper");
const main = require("./framePopper-main");

wrap(main, { processError: err => framePopper(err) })();

自定义对人友好的错误输出

设置一个 customOutput 属性,您可以覆盖输出 由 async-main-wrap设置 DEBUG 环境变量 禁用 customOutput- 基于输出并打印全部细节.

可以与 processError 选项以生成友好错误 所有你的错误.

// main.js

module.exports = async function(/* ... */) {
  // ...

  const err = new Error("Such an unfriendly error message");
  err.customOutput = "So friendly, but still an error!";
  throw err;

  // ...
};
$ cli
So friendly, but still an error!

版本与发布记录

@gustavnikolaj/async-main-wrap 共发布 8 个版本,首次发布于 2018/06/07;过去 12 个月发布了 0 个版本。

版本发布日期距今
4.0.0latest2021/07/265 年前
3.0.12019/02/197 年前
3.0.02018/08/228 年前
2.2.02018/08/228 年前
2.1.02018/08/218 年前
2.0.02018/07/158 年前

关于 @gustavnikolaj/async-main-wrap 的常见问题

@gustavnikolaj/async-main-wrap 是什么?

简单的 CLI 工具包.

如何安装 @gustavnikolaj/async-main-wrap?

在项目目录运行 npm install @gustavnikolaj/async-main-wrap,或使用 pnpm add / yarn add / bun add。

@gustavnikolaj/async-main-wrap 支持 TypeScript 吗?

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

@gustavnikolaj/async-main-wrap 支持 ESM 还是 CommonJS?

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

@gustavnikolaj/async-main-wrap 可以商用吗?

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

@gustavnikolaj/async-main-wrap 的下载量有多少?

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

@gustavnikolaj/async-main-wrap 还在维护吗?

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