erii 2.0.6 → 3.0.0-beta.1

package/readme.md

@@ -1,152 +1,167 @@
-# 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)
+
+[![npm version](https://badge.fury.io/js/erii.svg)](https://badge.fury.io/js/erii)
+
+## Installation
+`npm install erii --save`
+This package is ESM-only and requires Node.js 22.18 or later. Use `import` from an ESM project (`"type": "module"` in package.json, or an `.mjs` file).
+
+## Development
+
+- `npm run build`: bundle ESM and TypeScript declarations with tsdown.
+- `npm run typecheck`: check source and consumer types in strict mode.
+- `npm test`: build, check types, and run regression tests.
+- `npm run test:coverage`: run the same checks with coverage gates (100% lines/functions, 95% branches).
+
+See [test/README.md](test/README.md) for the test scenario matrix. Runtime tests exercise the built ESM package; utility tests also cover source functions that are removed from the bundle when unused.
+
+## TypeScript
+
+The package exports `Command`, `Option`, `Argument`, `CommandCtx`, `CommandHandler`, `CommandOptions`, `ArgumentValue`, `ArgumentValidator`, `ValidatorName`, `ParsedArguments`, and `MetaInfo` types. Handler options are always provided; individual options and `getArgument()` can be `undefined`. Values retain the parser's strings, numbers, booleans, arrays, and nested objects, so narrow them before use. String validators accept only validator.js methods callable with one string and returning a boolean.
+
+## Usage
+
+```JavaScript
+import Erii from 'erii';
+
+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 { verbose } = options; // option aliases use the primary name
+    console.log(verbose); // 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(String(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.
+```

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;