erii 2.0.6 → 3.0.0-beta.2

package/readme.md

@@ -1,152 +1,145 @@
-# Erii
-
-![](./logo.png)
-
-[![npm version](https://badge.fury.io/js/erii.svg)](https://badge.fury.io/js/erii)
-
-## Installation
-`npm install erii --save`
-## Usage
-
-```JavaScript
-const Erii = require('erii').default;
-
-Erii.setMetaInfo({
-    version: '0.0.1',
-    name: 'example'
-});
-
-// Bind commands
-Erii.bind({
-    name: ['help', 'h'], // `h` will be set as an alias
-    description: 'Show Help', // command description
-    argument: {
-        name: 'command',
-        description: 'query help of a specified command'
-    }
-}, (ctx, options) => {
-    ctx.showHelp(); // show help text
-});
-
-// add options for `help` command
-Erii.addOption({
-    name: ['verbose', 'debug'], 
-    command: 'help', // bind to command
-    description: 'debug output', // option description
-    argument: { // definition of option argument
-        name: 'level',
-        description: 'level of debug output'
-    }
-});
-
-Erii.addOption({
-    name: ['test'],
-    // without binding to a specified command,
-    // this option will be set as a common option.
-    description: 'show test information',
-    argument: {
-        name: 'test-argument',
-        description: 'test argument'
-    }
-});
-
-Erii.start(); // don't forget to start Erii.
-```
-
-**Example**
-
-Call with 
-
-`node index.js --help xxx --debug 1`
-
-```Javascript
-// ...
-// PART OF CODE
-Erii.bind({
-    name: ['help', 'h'], 
-    description: 'Show Help',
-    argument: {
-        name: 'command',
-        description: 'query help of a specified command'
-    }
-}, (ctx, options) => {
-    const { debug } = options;
-    console.log(debug);  // '1'
-    console.log(ctx.getArgument()); // 'xxx'
-});
-
-Erii.addOption({
-    name: ['verbose', 'debug'],
-    description: 'show verbose output',
-    argument: {
-        name: 'level',
-        description: 'level of verbose output'
-    }
-});
-
-Erii.start();
-```
-
-
-**Help Text**
-```
-example / 0.0.1
-
-Help:
-     Commands                      Description                   Alias
-
-     --help <command>              Show Help                     --h
-         <command>                 query help of a specified comm
-
-Options:
-
-     Options                       Description
-     --verbose, debug <level>      show verbose output
-         <level>                   level of verbose output
-```
-
-**Argument Validation**
-
-Argument validation are based on [validator.js](https://github.com/chriso/validator.js/).
-
-`Erii.validator` points to a `validator` exported by `validator.js`.
-
-Erii can validate arguments automatically.
-
-Define the validate methods in `argument` parameter.
-
-```JavaScript
-Erii.addOption({
-    name: ['verbose', 'debug'],
-    description: 'show verbose output',
-    argument: {
-        name: 'level',
-        description: 'level of verbose output',
-        validate: 'isInt'
-    }
-});
-```
-
-`validate` can also be a function, for example:
-
-```JavaScript
-Erii.addOption({
-    name: ['verbose', 'debug'],
-    description: 'show verbose output',
-    argument: {
-        name: 'level',
-        description: 'level of verbose output',
-        validate: (value) => Erii.validator.isInt(value)
-    }
-});
-```
-
-`argument.validate` works in both command and option definitions.
-
-**Example Output for Argument Validation**
-
-```
-PS D:\Git\erii.test> node index.js --help --verbose f
-Argument validation failed for option 'verbose'.
-<level> should be a/an Int.
-```
+# Erii
+
+![](./logo.png)
+
+## Installation
+
+Use Node.js 22.18 or later and set `"type": "module"` in your `package.json`.
+
+```sh
+npm install erii
+```
+
+## Usage
+
+Define your commands and options, register handlers, then call `start()`.
+
+```ts
+import Erii from "erii";
+
+type CLI = {
+    commonOptions: {
+        verbose?: boolean;
+    };
+    commands: {
+        build: {
+            aliases: "b";
+            argument: string;
+            options: {
+                outDir?: string;
+                minify?: boolean;
+            };
+        };
+        serve: {
+            options: {
+                port?: number;
+                mode?: "dev" | "prod";
+            };
+        };
+    };
+};
+
+const cli = new Erii<CLI>();
+cli.setMetaInfo({ name: "example", version: "1.0.0" });
+
+cli.bind(
+    {
+        name: ["build", "b"],
+        description: "Build the project",
+        argument: { name: "path", description: "Source directory" },
+    },
+    (ctx, options) => {
+        const path = ctx.getArgument(); // string | undefined
+        const output = options.outDir; // string | undefined
+        const verbose = options.verbose; // boolean | undefined
+        console.log({ path, output, verbose });
+    },
+);
+
+cli.bind({ name: "serve" }, (_, options) => {
+    console.log(options.port, options.mode);
+});
+
+cli.addOption({ name: ["verbose", "v"] });
+cli.addOption({ command: "build", name: ["outDir", "out-dir", "o"] });
+cli.addOption({ command: "b", name: "minify" });
+cli.addOption({ command: "serve", name: "port" });
+cli.addOption({
+    command: "serve",
+    name: "mode",
+    argument: {
+        name: "mode",
+        description: "Server mode",
+        validate: (value) => value === "dev" || value === "prod",
+    },
+});
+
+cli.start(); // okite() is also available.
+```
+
+```sh
+node index.js --build src --out-dir dist --verbose
+node index.js serve --port 3000 --mode dev
+```
+
+## Aliases
+
+Put the primary name first and aliases after it. Read options using the primary name, such as `options.outDir`.
+
+```sh
+node index.js -b src -o dist -v
+```
+
+## Reading arguments
+
+Use `ctx.getArgument()` inside a handler, or look up a command by name:
+
+```ts
+const path = cli.getArgument("build");
+if (path !== undefined) {
+    console.log(path);
+}
+```
+
+## Validation
+
+Use `argument.validate` to check values with a validator.js method:
+
+```ts
+cli.addOption({
+    command: "serve",
+    name: "port",
+    argument: { name: "port", description: "Listening port", validate: "isInt" },
+});
+```
+
+To use a custom validator, return `true` for accepted input:
+
+```ts
+cli.addOption({
+    command: "serve",
+    name: "port",
+    argument: {
+        name: "port",
+        description: "Listening port",
+        validate: (value) => typeof value === "number" && value > 0 && value <= 65535,
+    },
+});
+```
+
+## Help and lifecycle
+
+Register lifecycle handlers before calling `start()`:
+
+```ts
+cli.always(() => {
+    console.log("Starting");
+});
+
+cli.default(() => {
+    cli.showHelp(); // Show help when no arguments are supplied.
+});
+
+cli.showVersion();
+cli.start();
+```

package/dist/index.d.ts

@@ -1,108 +0,0 @@
-export interface Command {
-    name: string | string[];
-    description?: string;
-    argument?: Argument;
-    alias?: string[];
-    redirect?: string;
-    options?: Option[];
-    handler?: (ctx: CommandCtx, options?: object) => any;
-}
-export interface Option {
-    name: string | string[];
-    description?: string;
-    command?: string;
-    argument?: Argument;
-}
-export interface CommandMap {
-    [key: string]: Command;
-}
-export interface CommandCtx {
-    showVersion: () => void;
-    showHelp: () => void;
-    getArgument: (commandName?: string) => string;
-}
-export interface Argument {
-    name: string;
-    description: string;
-    validate?: string | ((value: any, logger: (message: string) => void) => boolean);
-}
-export declare class Erii {
-    rawArguments: string[];
-    parsedArguments: {
-        _?: string[];
-        [key: string]: string | string[];
-    };
-    private version;
-    private name;
-    commands: CommandMap;
-    commonOptions: Option[];
-    validator: any;
-    alwaysHandler: () => void;
-    defaultHandler: () => void;
-    constructor();
-    /**
-     * 绑定命令处理函数
-     * @param config
-     * @param handler
-     */
-    bind(config: Command, handler: (ctx: CommandCtx, ...extraArguments: any[]) => any): void;
-    /**
-     * 总是执行
-     * @param handler
-     */
-    always(handler: () => any): void;
-    /**
-     *
-     */
-    default(handler: () => any): void;
-    /**
-     * 增加设置项
-     * @param config
-     */
-    addOption(config: Option): void;
-    /**
-     *
-     * @param command
-     */
-    private commandCtx;
-    /**
-     * 设定基础信息
-     * @param metaInfo
-     */
-    setMetaInfo({ version, name }?: {
-        version?: string;
-        name?: string;
-    }): void;
-    /**
-     * 显示帮助信息
-     */
-    showHelp(command?: string): void;
-    /**
-     * 显示版本号
-     */
-    showVersion(): void;
-    /**
-     * 启动
-     */
-    start(): void;
-    /**
-     * 执行命令担当函数
-     * @param command
-     * @param extraArguments
-     */
-    private exec;
-    validateArgument(argumentValue: any, argument: Argument): any;
-    /**
-     * 获得命令的参数
-     * @param commandName
-     * @param followRedirect 是否遵循重定向
-     */
-    getArgument(commandName: string, followRedirect?: boolean): string;
-    /**
-     * 启动
-     * エリイ 起きてます❤
-     */
-    okite(): void;
-}
-declare const _default: Erii;
-export default _default;