breadc 0.9.7 → 1.0.0-beta.10

package/README.md

@@ -1,17 +1,21 @@
 # 🥪 Breadc
 
-[![version](https://img.shields.io/npm/v/breadc?label=Breadc)](https://www.npmjs.com/package/breadc) [![CI](https://github.com/yjl9903/Breadc/actions/workflows/ci.yml/badge.svg)](https://github.com/yjl9903/Breadc/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/yjl9903/Breadc/branch/main/graph/badge.svg?token=F7PGOG62EF)](https://codecov.io/gh/yjl9903/Breadc)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/yjl9903/Breadc)
+[![version](https://img.shields.io/npm/v/breadc?label=Breadc)](https://www.npmjs.com/package/breadc)
+[![CI](https://github.com/yjl9903/Breadc/actions/workflows/ci.yml/badge.svg)](https://github.com/yjl9903/Breadc/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/yjl9903/Breadc/branch/main/graph/badge.svg?token=F7PGOG62EF)](https://codecov.io/gh/yjl9903/Breadc)
 
-Yet another Command Line Application Framework with fully strong **[TypeScript](https://www.typescriptlang.org/) support**.
+Yet another **Command Line Application Framework** desgined for **[TypeScript](https://www.typescriptlang.org/)**.
 
-![vscode](https://cdn.jsdelivr.net/gh/yjl9903/Breadc/images/vscode.png)
+- **TypeScript Infer**: infer command arguments, option values, and action signatures in IDE automatically
+- **Command**: support default command, command alias, and nested sub-commands like `git remote add <name> <url>`
+- **Group**: organize commands by modules and build large multi-command CLI applications with clear structure
+- **Option**: support boolean, required, optional, spread options, `--no-*` negation, and `--` passthrough arguments
+- **Middleware**: support middleware pipeline and unknown option handling
+- **Builtin CLI Features**: provide common help / version options and i18n support out of the box
+- **Toolkits**: contains many useful tools to build your next CLI application, such as [ansi color](https://github.com/yjl9903/Breadc/tree/main/packages/color), [process death handler](https://github.com/yjl9903/Breadc/tree/main/packages/death), [shell compelete script generation](https://github.com/yjl9903/Breadc/tree/main/packages/complete) and so on.
 
-## Features
-
-+ 🔍 **TypeScript Infer**: IDE will automatically infer the type of your command action function;
-+ 💻 **Commands**: support default command, command alias and sub-commands like `git remote add <name> <url>`;
-+ 📖 **East to Learn**: very similar with [commander.js](https://github.com/tj/commander.js/), [cac](https://github.com/cacjs/cac) and there are only 5 APIs for building a CLI application: `breadc`, `command`, `option`, `action`, `run`.
-+ 🧰 **Toolkits**: contains many useful tools to build your next CLI application, such as [ansi color](https://github.com/yjl9903/Breadc/tree/main/packages/color), [process death handler](https://github.com/yjl9903/Breadc/tree/main/packages/death), [shell compelete script generation](https://github.com/yjl9903/Breadc/tree/main/packages/complete) and so on.
+![vscode](https://raw.githubusercontent.com/yjl9903/Breadc/v1.0.0-beta.1/assets/typescript.png)
 
 ## Installation
 
@@ -24,52 +28,31 @@ npm i breadc
 Try [./examples/echo.ts](./examples/echo.ts).
 
 ```ts
-import { breadc } from 'breadc'
+import { breadc } from 'breadc';
 
 const cli = breadc('echo', { version: '1.0.0' })
-  .option('--host <host>', { default: 'localhost' })
-  .option('--port <port>', { default: '3000', cast: p => +p })
-
-cli
-  .command('[message]', 'Say something!')
-  .action((message, option) => {
-    const host = option.host
-    const port = option.port
-    console.log(`Host: ${host}`)
-    console.log(`Port: ${port}`)
-  })
-
-cli.run(process.argv.slice(2)).catch(err => console.error(err))
-```
-
-If you are using IDEs that support TypeScript (like [Visual Studio Code](https://code.visualstudio.com/)), input something using `option`, and then you will find the `option` is automatically typed with `{ host: string, port: number }`. In the figure below, [Visual Studio Code](https://code.visualstudio.com/) will automatically infer that the type of `option.host` is `string` and the type of `option.port` is `number`.
-
-![vscode](https://cdn.jsdelivr.net/gh/yjl9903/Breadc/images/vscode.png)
-
-### Limitation
+  .option('--host <host>', 'specify hostname', { initial: 'localhost' })
+  .option('--port <port>', 'specify port', { initial: '3000', cast: (t) => +t });
 
-For the limitation of TypeScript, in the command format string, you can only write up to **5** pieces. That is to say, you can only write format string like `<p1> <p2> <p3> <p4> [p5]`, but `<p1> <p2> <p3> <p4> <p5> [p6]` does not work.
+cli.command('[message]', 'Say something!').action((message, option) => {
+  console.log(message ?? 'You can say anything!');
+  const { host, port } = option; // { host: string, port: number, '--': string[] }
+  console.log(`Host: ${host}`);
+  console.log(`Port: ${port}`);
+});
 
-You should always use method chaining when registering options and commands. The example below will fail to infer the option `--host`.
-
-```ts
-const cli = Breadc('cli')
+cli.run(process.argv.slice(2)).catch((err) => console.error(err));
+```
 
-cli
-  .option('--host')
+If you are using IDEs that support TypeScript (like [Visual Studio Code](https://code.visualstudio.com/)), input something using `option`, and then you will find the `option` is automatically typed with `{ host: string, port: number }`. In the figure below, [Visual Studio Code](https://code.visualstudio.com/) will automatically infer that the type of `option.host` is `string` and the type of `option.port` is `number`.
 
-cli
-  .option('--port')
-  .command('')
-  .action((option) => {
-    // The type of option is only { port: boolean }
-  })
-```
+![vscode](https://raw.githubusercontent.com/yjl9903/Breadc/v1.0.0-beta.1/assets/typescript.png)
 
 ## Inspiration
 
-+ [cac](https://github.com/cacjs/cac): Simple yet powerful framework for building command-line apps.
-+ [TypeScript: Documentation - Template Literal Types](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html)
+- [cac](https://github.com/cacjs/cac): Simple yet powerful framework for building command-line apps.
+- [Commander.js](https://github.com/tj/commander.js): Node.js command-line interfaces made easy.
+- [TypeScript: Documentation - Template Literal Types](https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html)
 
 ## License
 

package/dist/index.d.mts

@@ -1,221 +1,5 @@
-type TokenType = '--' | '-' | 'number' | 'string' | 'long' | 'short';
-declare class Token {
-    private readonly text;
-    private _type;
-    constructor(text: string);
-    /**
-     * @returns Raw argument text
-     */
-    raw(): string;
-    /**
-     * @returns Number representation
-     */
-    number(): number;
-    /**
-     * @returns Remove start - for long or short option
-     */
-    option(): string;
-    isOption(): boolean;
-    isText(): boolean;
-    type(): TokenType;
-}
-declare class Lexer {
-    private readonly rawArgs;
-    private cursor;
-    constructor(rawArgs: string[]);
-    next(): Token | undefined;
-    hasNext(): boolean;
-    peek(): Token | undefined;
-    [Symbol.iterator](): Iterator<Token, undefined>;
-}
-
-type Prettify<T> = {
-    [K in keyof T]: T[K];
-} & {};
-type Lowercase = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
-type Uppercase = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
-type Letter = Lowercase | Uppercase;
-
-type CallbackFn = (result: BreadcParseResult) => any;
-interface ParseResult {
-    /**
-     * Arguments that will be passed to action callback
-     * When parsing, this array is empty
-     */
-    arguments: Array<string | string[] | undefined>;
-    /**
-     * Options map
-     */
-    options: Record<string, any>;
-    /**
-     * Rest arguments.
-     * When parsing, this contains all the non-option arguments
-     */
-    '--': string[];
-}
-type BreadcParseResult = Prettify<ParseResult & {
-    callback?: CallbackFn;
-    meta: Record<string, any>;
-    matched: {
-        node: TreeNode;
-        command?: Command;
-        option?: Option;
-    };
-}>;
-interface Context {
-    /**
-     * Lexer instance
-     */
-    lexer: Lexer;
-    /**
-     * Options supported in the current context
-     */
-    options: Map<string, Option>;
-    /**
-     * Parse result
-     */
-    result: ParseResult;
-    /**
-     * Some other meta information passed
-     */
-    meta: Record<string, any>;
-    /**
-     * Configuration
-     */
-    config: {
-        allowUnknownOption: 'error' | 'skip' | 'rest';
-    };
-    parseOption(cursor: TreeNode, token: Token, context: Context): TreeNode | false;
-}
-interface TreeNode<F extends CallbackFn = CallbackFn> {
-    command?: Command;
-    option?: Option;
-    /**
-     * Out-going edges from this node
-     */
-    children: Map<string, TreeNode>;
-    init(context: Context): void;
-    next(arg: Token, context: Context): TreeNode | false;
-    finish(context: Context): F | undefined;
-}
-
-declare function makeTreeNode(pnode: Partial<TreeNode>): TreeNode;
-
-/**
- * Extract option type, boolean or string
- */
-type ExtractOptionType<T extends string> = T extends `-${Letter}, --${infer R} <${infer U}>` ? string : T extends `-${Letter}, --${infer R}` ? boolean : T extends `--${infer R} <${infer U}>` ? string : T extends `--${infer R}` ? boolean : string | boolean;
-/**
- * Extract option raw name
- *
- * Examples:
- * + const t1: ExtractOption<'--option' | '--hello'> = 'hello'
- * + const t2: ExtractOption<'-r, --root'> = 'root'
- * + const t3: ExtractOption<'--page-index'> = 'pageIndex'
- */
-type ExtractOptionRawName<T extends string> = T extends `-${Letter}, --${infer R} <${infer U}>` ? R : T extends `-${Letter}, --no-${infer R}` ? R : T extends `-${Letter}, --${infer R}` ? R : T extends `--${infer R} <${infer U}>` ? R : T extends `--no-${infer R}` ? R : T extends `--${infer R}` ? R : never;
-/**
- * Extrat camel case option name
- */
-type ExtractOptionName<T extends string, R extends string = ExtractOptionRawName<T>> = R extends `${infer P1}-${infer P2}-${infer P3}` ? `${P1}${Capitalize<P2>}${Capitalize<P3>}` : R extends `${infer P1}-${infer P2}` ? `${P1}${Capitalize<P2>}` : R;
-/**
- * Extract option information
- */
-type ExtractOption<T extends string, D = never> = {
-    [k in ExtractOptionName<T>]: D extends never ? ExtractOptionType<T> : D;
-};
-type Push<T extends any[], U, R> = [...T, U, R];
-type ActionFn<T extends any[], Option extends object = {}, R = any> = (...arg: Push<T, Prettify<Option & {
-    '--': string[];
-}>, {}>) => R | Promise<R>;
-/**
- * Max Dep: 5
- *
- * Generated by: npx tsx examples/genType.ts 5
- */
-type ExtractCommand<T extends string> = T extends `<${infer P1}> <${infer P2}> <${infer P3}> <${infer P4}> [...${infer P5}]` ? [string, string, string, string, string[]] : T extends `<${infer P1}> <${infer P2}> <${infer P3}> <${infer P4}> [${infer P5}]` ? [string, string, string, string, string | undefined] : T extends `<${infer P1}> <${infer P2}> <${infer P3}> <${infer P4}> <${infer P5}>` ? [string, string, string, string, string] : T extends `${infer P1} <${infer P2}> <${infer P3}> <${infer P4}> [...${infer P5}]` ? [string, string, string, string[]] : T extends `${infer P1} <${infer P2}> <${infer P3}> <${infer P4}> [${infer P5}]` ? [string, string, string, string | undefined] : T extends `${infer P1} <${infer P2}> <${infer P3}> <${infer P4}> <${infer P5}>` ? [string, string, string, string] : T extends `${infer P1} ${infer P2} <${infer P3}> <${infer P4}> [...${infer P5}]` ? [string, string, string[]] : T extends `${infer P1} ${infer P2} <${infer P3}> <${infer P4}> [${infer P5}]` ? [string, string, string | undefined] : T extends `${infer P1} ${infer P2} <${infer P3}> <${infer P4}> <${infer P5}>` ? [string, string, string] : T extends `${infer P1} ${infer P2} ${infer P3} <${infer P4}> [...${infer P5}]` ? [string, string[]] : T extends `${infer P1} ${infer P2} ${infer P3} <${infer P4}> [${infer P5}]` ? [string, string | undefined] : T extends `${infer P1} ${infer P2} ${infer P3} <${infer P4}> <${infer P5}>` ? [string, string] : T extends `<${infer P1}> <${infer P2}> <${infer P3}> [...${infer P4}]` ? [string, string, string, string[]] : T extends `<${infer P1}> <${infer P2}> <${infer P3}> [${infer P4}]` ? [string, string, string, string | undefined] : T extends `<${infer P1}> <${infer P2}> <${infer P3}> <${infer P4}>` ? [string, string, string, string] : T extends `${infer P1} <${infer P2}> <${infer P3}> [...${infer P4}]` ? [string, string, string[]] : T extends `${infer P1} <${infer P2}> <${infer P3}> [${infer P4}]` ? [string, string, string | undefined] : T extends `${infer P1} <${infer P2}> <${infer P3}> <${infer P4}>` ? [string, string, string] : T extends `${infer P1} ${infer P2} <${infer P3}> [...${infer P4}]` ? [string, string[]] : T extends `${infer P1} ${infer P2} <${infer P3}> [${infer P4}]` ? [string, string | undefined] : T extends `${infer P1} ${infer P2} <${infer P3}> <${infer P4}>` ? [string, string] : T extends `${infer P1} ${infer P2} ${infer P3} [...${infer P4}]` ? [string[]] : T extends `${infer P1} ${infer P2} ${infer P3} [${infer P4}]` ? [string | undefined] : T extends `${infer P1} ${infer P2} ${infer P3} <${infer P4}>` ? [string] : T extends `<${infer P1}> <${infer P2}> [...${infer P3}]` ? [string, string, string[]] : T extends `<${infer P1}> <${infer P2}> [${infer P3}]` ? [string, string, string | undefined] : T extends `<${infer P1}> <${infer P2}> <${infer P3}>` ? [string, string, string] : T extends `${infer P1} <${infer P2}> [...${infer P3}]` ? [string, string[]] : T extends `${infer P1} <${infer P2}> [${infer P3}]` ? [string, string | undefined] : T extends `${infer P1} <${infer P2}> <${infer P3}>` ? [string, string] : T extends `${infer P1} ${infer P2} [...${infer P3}]` ? [string[]] : T extends `${infer P1} ${infer P2} [${infer P3}]` ? [string | undefined] : T extends `${infer P1} ${infer P2} <${infer P3}>` ? [string] : T extends `${infer P1} ${infer P2} ${infer P3}` ? [] : T extends `<${infer P1}> [...${infer P2}]` ? [string, string[]] : T extends `<${infer P1}> [${infer P2}]` ? [string, string | undefined] : T extends `<${infer P1}> <${infer P2}>` ? [string, string] : T extends `${infer P1} [...${infer P2}]` ? [string[]] : T extends `${infer P1} [${infer P2}]` ? [string | undefined] : T extends `${infer P1} <${infer P2}>` ? [string] : T extends `${infer P1} ${infer P2}` ? [] : T extends `[...${infer P1}]` ? [string[]] : T extends `[${infer P1}]` ? [string | undefined] : T extends `<${infer P1}>` ? [string] : T extends `${infer P1}` ? [] : T extends `` ? [] : never;
-
-interface AppOption {
-    version?: string;
-    description?: string;
-    plugins?: Partial<Plugin>[];
-    builtin?: {
-        version?: false | Partial<{
-            description: string;
-            content: string;
-        }>;
-        help?: false | Partial<{
-            description: string;
-        }>;
-    };
-}
-interface Breadc<GlobalOption extends object = {}> {
-    name: string;
-    description: string;
-    option<OF extends string = string, OT extends string | boolean = ExtractOptionType<OF>, OO extends OptionOption<OT, any> = OptionOption<OT, any>, OR extends any = OO extends {
-        cast(...args: any[]): infer CR;
-    } ? CR : OO['default'] extends OT ? OT : OT extends string ? undefined | string : OT extends boolean ? boolean : undefined | string | boolean>(format: OF, description?: string | OO, option?: OO): Breadc<GlobalOption & ExtractOption<OF, OR>>;
-    command<F extends string = string>(format: F, description?: string, option?: CommandOption): Command<F, ExtractCommand<F>, {}, GlobalOption>;
-    command<F extends string = string>(format: F, option?: CommandOption): Command<F, ExtractCommand<F>, {}, GlobalOption>;
-    parse(args: string[]): BreadcParseResult;
-    run<T = any>(args: string[]): Promise<T>;
-}
-interface Command<F extends string = string, AT extends any[] = ExtractCommand<F>, CommandOption extends object = {}, GlobalOption extends object = {}> {
-    callback?: (result: ParseResult) => Promise<any>;
-    format: F;
-    description: string;
-    _default: boolean;
-    _arguments: Argument[];
-    _options: Option[];
-    option<OF extends string = string, OT extends string | boolean = ExtractOptionType<OF>, OO extends OptionOption<OT, any> = OptionOption<OT, any>, OR extends any = OO extends {
-        cast(...args: any[]): infer CR;
-    } ? CR : OO['default'] extends OT ? OT : OT extends string ? undefined | string : OT extends boolean ? boolean : undefined | string | boolean>(format: OF, description?: string | OO, option?: OO): Command<F, AT, CommandOption & ExtractOption<OF, OR>, GlobalOption>;
-    alias(format: string): Command<F, AT, CommandOption, GlobalOption>;
-    action(fn: ActionFn<AT, CommandOption & GlobalOption>): void;
-}
-interface CommandOption {
-    description?: string;
-    /**
-     * Config how to handle unknown options
-     */
-    allowUnknownOption?: 'error' | 'skip' | 'rest';
-}
-interface Argument {
-    type: 'const' | 'require' | 'optional' | 'rest';
-    name: string;
-}
-interface Option<F extends string = string, T extends string | boolean = ExtractOptionType<F>, R extends unknown = any> {
-    format: F;
-    type: T extends string ? 'string' : T extends boolean ? 'boolean' : never;
-    name: string;
-    short?: string;
-    description: string;
-    order: number;
-    initial?: R;
-    cast?: (value: T extends string ? string : T extends boolean ? boolean : never) => R;
-    parse?: (cursor: TreeNode, token: Token, context: Context) => TreeNode | false;
-}
-interface OptionOption<T extends string | boolean, R extends any = any> {
-    description?: string;
-    default?: T;
-    cast?: (value: T) => R;
-}
-type CommandHookFn = (result: ParseResult) => void | Promise<void>;
-interface Plugin {
-    onInit?(breadc: Breadc, allCommands: Command[], globalOptions: Option[]): void;
-    onPreRun?(breadc: Breadc): void | Promise<void>;
-    onPreCommand?: Record<string, CommandHookFn> | CommandHookFn;
-    onPostCommand?: Record<string, CommandHookFn> | CommandHookFn;
-    onPostRun?(breadc: Breadc): void | Promise<void>;
-}
-
-declare function breadc(name: string, config?: AppOption): Breadc<{}>;
-
-declare function definePlugin(plugin: Partial<Plugin>): Partial<Plugin>;
-
-declare class BreadcError extends Error {
-}
-declare class ParseError extends Error {
-}
-
-export { type AppOption, type Argument, type Breadc, BreadcError, type Command, type Option, ParseError, type Plugin, breadc, definePlugin, makeTreeNode };
+import { ActionMiddleware, Argument, ArgumentInit, Breadc, BreadcAppError, BreadcError, BreadcInit, Command, CommandInit, Group, GroupInit, Option, OptionInit, ResolveCommandError, ResolveGroupError, ResolveOptionError, UnknownCommandMiddleware, UnknownOptionMiddleware, argument, breadc, command, group, option } from "@breadc/core";
+import { ansi256, ansi256Bg, bgBlack, bgBlue, bgCyan, bgGray, bgGreen, bgLightBlue, bgLightCyan, bgLightGray, bgLightGreen, bgLightMagenta, bgLightRed, bgLightYellow, bgMagenta, bgRed, bgWhite, bgYellow, black, blue, bold, cyan, dim, gray, green, hidden, inverse, italic, lightBlue, lightCyan, lightGray, lightGreen, lightMagenta, lightRed, lightYellow, link, magenta, red, reset, strikethrough, underline, white, yellow } from "@breadc/color";
+export * from "@breadc/death";
+export * from "@breadc/tui";
+export { type ActionMiddleware, type Argument, type ArgumentInit, type Breadc, BreadcAppError, BreadcError, type BreadcInit, type Command, type CommandInit, type Group, type GroupInit, type Option, type OptionInit, ResolveCommandError, ResolveGroupError, ResolveOptionError, type UnknownCommandMiddleware, type UnknownOptionMiddleware, ansi256, ansi256Bg, argument, bgBlack, bgBlue, bgCyan, bgGray, bgGreen, bgLightBlue, bgLightCyan, bgLightGray, bgLightGreen, bgLightMagenta, bgLightRed, bgLightYellow, bgMagenta, bgRed, bgWhite, bgYellow, black, blue, bold, breadc, command, cyan, dim, gray, green, group, hidden, inverse, italic, lightBlue, lightCyan, lightGray, lightGreen, lightMagenta, lightRed, lightYellow, link, magenta, option, red, reset, strikethrough, underline, white, yellow };