termkit 1.7.0 → 2.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Jay Deaton
+Copyright (c) 2018–2026 Jay Deaton
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,104 +1,165 @@
 # Termkit
 
-A terminal input parsing kit
+A fluent CLI framework for Node.js with nested subcommands, middleware, and TypeScript support.
 
-## Getting Started
+## Installation
 
-This is how to get started using Termkit
-
-### Installing
-
-Add this package to your project
 ```bash
-npm install --save termkit
+npm install termkit
 ```
 
-### Using
+## Usage
 
-Configure your command line program
-```node
-const { command, middleware, option } = require('termkit')
+### Basic program
 
-const program = command('example')
+```ts
+import { command, option, parse } from 'termkit'
+
+const program = command('my-app')
   .version('1.0.0')
-  .description('example program')
-  .option('a', 'array', '[arr...]', 'Array variable')
-  .option('r', 'required', '<reqA> <reqB>', 'Two required variables')
-  .option('o', 'optional', '[opt]', 'One optional variable')
-  .option('b', 'boolean', null, 'No variable')
-  .middleware((options) => console.log('middleware is run before action, manipulate the options object as needed'))
-  .action((options) => console.log('run action with given options'))
-  .commands([
-    command('first')
-    .description('first nested command')
-    .options([
-      // Same style options as before
-    ])
-    .middleware((options) => console.log('middleware can be nested too'))
-    .action((options) => console.log('run action with given options'))
-    .commands([
-      // So on and so forth
-    ])
-  ])
+  .description('My CLI application')
+  .option('v', 'verbose', null, 'Enable verbose output')
+  .option('o', 'output', '<file>', 'Output file path')
+  .action((options) => {
+    console.log(options.output)
+  })
+
+try {
+  program.parse(process.argv)
+} catch (err) {
+  console.error(err)
+}
 ```
 
-Alternatively supply options and middlewares to command in arrays
-```node
-command('example')
-  .options([
-    option('a', 'array', '[arr...]', 'Array variable'),
-    option('r', 'required', '<reqA> <reqB>', 'Two required variables'),
-    option('o', 'optional', '[opt]', 'One optional variable'),
-    option('b', 'boolean', null, 'No variable')
-  ])
-  .middlewares([
-    middleware(() => console.log(1)),
-    middleware(() => console.log(2)),
-    middleware(() => console.log(3))
+### Options
+
+Options support four variable shapes:
+
+```ts
+command('app')
+  .option('b', 'boolean', null,        'Flag with no value')
+  .option('o', 'optional', '[val]',    'Optional value')
+  .option('r', 'required', '<val>',    'Required value')
+  .option('a', 'array',    '[val...]', 'Array of values')
+```
+
+Accessible in actions and middleware via the long name:
+
+```ts
+.action((options) => {
+  options.boolean  // true | undefined
+  options.optional // string | true
+  options.required // string
+  options.array    // string[]
+})
+```
+
+### Value coercion
+
+Append `:number` or `:boolean` to a variable to coerce the parsed string:
+
+```ts
+command('app')
+  .option('p', 'port',    '<port:number>',     'Port number')
+  .option('v', 'verbose', '[verbose:boolean]', 'Verbose mode')
+  .option('n', 'nums',    '[nums:number...]',  'List of numbers')
+  .action((options) => {
+    options.port    // number
+    options.verbose // boolean
+    options.nums    // number[]
+  })
+```
+
+### Subcommands
+
+Commands nest to any depth. Each level can have its own options and middleware.
+
+```ts
+import { command, option } from 'termkit'
+
+command('app')
+  .commands([
+    command('serve')
+      .option('p', 'port', '<port:number>', 'Port to listen on')
+      .action((options) => startServer(options.port)),
+
+    command('build')
+      .option('w', 'watch', null, 'Watch for changes')
+      .action((options) => runBuild(options)),
   ])
 ```
 
-Commands nest and can have variables themselves
-```node
-command('example').commands([
-  command('another', '[optional]'),
-  command('another', '<required>'),
-  command('another', '[array...]')
-])
+Commands can also carry their own positional variables:
+
+```ts
+command('get', '<id>')        // required
+command('list', '[filter]')   // optional
+command('tag', '[tags...]')   // array
 ```
 
-Variables, and options are passed into middleware and action functions.
-```node
-command('example', <var>)
-  .option('r', 'require', <req>, 'Another example')
-  .middleware(options) => {
-    console.log(options.require)
+### Middleware
+
+Middleware runs before the action. It can mutate the options object and supports async.
+
+```ts
+command('app')
+  .middleware(async (options) => {
+    options.user = await getUser(options.token)
   })
   .action((options) => {
-    console.log(options.require)
+    console.log(options.user)
   })
 ```
 
-After completing constructing the CLI flow, parse the input and catch possible errors
-```node
-try {
-  program.parse(process.argv)
-} catch(err) {
-  console.log(err)
-}
+Use `.middlewares([...])` to register several at once. When navigating into a subcommand, parent middleware runs first.
+
+### Default middleware and options
+
+Apply middleware or options to every command created after the call:
+
+```ts
+import { setDefaults } from 'termkit'
+
+setDefaults({
+  middlewares: [
+    async (options) => { options.timestamp = Date.now() }
+  ]
+})
 ```
 
-Built in terminal help usage function
-```node
-  program.parse('_ _ help'.split(' '))
+### Built-in help
+
+Passing `help` anywhere in argv prints a formatted usage table and stops execution:
+
+```bash
+my-app help
+my-app serve help
 ```
 
-Stay tuned for more
+## API
+
+### Functions
+
+| Function | Signature | Description |
+|---|---|---|
+| `command` | `(name, variables?, info?) => Command` | Create a command |
+| `option` | `(short, long, variables, info) => Option` | Create an option |
+| `middleware` | `(fn) => fn` | Identity helper for typing middleware inline |
+| `parse` | `(argv) => Promise<unknown>` | Parse using the root command |
+| `setDefaults` | `(defaults) => void` | Set defaults applied to all new commands |
+
+### Classes
+
+`Command`, `Option`, `Variable`, `Termkit`
+
+### Types
+
+`ActionFn`, `MiddlewareFn`, `ParsedOptions`, `CommandDefaults`, `VariableType`
 
 ## Authors
 
-* **Jay Deaton** - [Github](https://github.com/jayrdeaton)
+**Jay Deaton** — [GitHub](https://github.com/jayrdeaton)
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
+MIT

package/dist/index.d.mts

@@ -0,0 +1,99 @@
+type VariableType = 'string' | 'number' | 'boolean';
+interface ParsedOptions {
+    _source: string[];
+    _parents?: Record<string, Record<string, unknown>>;
+    [key: string]: unknown;
+}
+type ActionFn = (options: ParsedOptions) => unknown | Promise<unknown>;
+type MiddlewareFn = (options: ParsedOptions) => void | Promise<void>;
+
+interface VariableData {
+    array?: boolean;
+    name?: string;
+    raw?: string;
+    required?: boolean;
+    type?: VariableType;
+}
+declare class Variable {
+    array: boolean;
+    name: string | null;
+    raw: string | null;
+    required: boolean;
+    type: VariableType;
+    value: unknown[] | null;
+    constructor(data?: VariableData);
+}
+
+interface OptionData {
+    short?: string | null;
+    long?: string | null;
+    info?: string | null;
+    variables?: string | null;
+}
+declare class Option {
+    short: string | null;
+    long: string | null;
+    info: string | null;
+    variables: Variable[] | null;
+    constructor(data?: OptionData);
+    description(info: string): this;
+}
+
+interface CommandData {
+    name?: string;
+    variables?: string | null;
+    info?: string;
+    middlewares?: MiddlewareFn[];
+    options?: Option[];
+}
+declare class Command {
+    actionFunction: ActionFn | null;
+    commandsArray: Command[];
+    commandStrings: string[];
+    info: string | null;
+    middlewaresArray: MiddlewareFn[];
+    name: string | null;
+    optionsArray: Option[];
+    variables: Variable[] | null;
+    versionString: string | null;
+    constructor(data?: CommandData);
+    description(info: string): this;
+    variable(string: string): this;
+    action(fn: ActionFn): this;
+    command(cmd: Command): this;
+    commands(cmds: Command[]): this;
+    middleware(fn: MiddlewareFn): this;
+    middlewares(fns: MiddlewareFn[]): this;
+    option(short: string | null, long: string | null, variables: string | null, info: string): this;
+    options(opts: Option[]): this;
+    version(v: string): this;
+    help(_source?: string[]): void;
+    parse(input: string[]): Promise<unknown>;
+}
+
+interface TermkitDefaults {
+    middlewares?: MiddlewareFn[];
+    options?: Option[];
+}
+declare class Termkit {
+    private static base;
+    private static commandDefaults;
+    static set defaults(obj: TermkitDefaults);
+    static setDefaults(obj: TermkitDefaults): void;
+    static command(name: string, variables?: string | null, info?: string): Command;
+    static middleware(action: MiddlewareFn): MiddlewareFn;
+    static option(short: string | null, long: string | null, variables: string | null, info: string): Option;
+    static parse(arr: string[]): Promise<unknown>;
+}
+
+interface CommandDefaults {
+    middlewares?: MiddlewareFn[];
+    options?: Option[];
+}
+declare const command: (name: string, variables?: string | null, info?: string) => Command;
+declare const middleware: (fn: MiddlewareFn) => MiddlewareFn;
+declare const option: (short: string | null, long: string | null, variables: string | null, info: string) => Option;
+declare const parse: (arr: string[]) => Promise<unknown>;
+declare const setDefaults: (data: CommandDefaults) => void;
+
+export { type ActionFn, Command, type CommandDefaults, type MiddlewareFn, Option, type ParsedOptions, Termkit, Variable, type VariableType, command, middleware, option, parse, setDefaults };

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+type VariableType = 'string' | 'number' | 'boolean';
+interface ParsedOptions {
+    _source: string[];
+    _parents?: Record<string, Record<string, unknown>>;
+    [key: string]: unknown;
+}
+type ActionFn = (options: ParsedOptions) => unknown | Promise<unknown>;
+type MiddlewareFn = (options: ParsedOptions) => void | Promise<void>;
+
+interface VariableData {
+    array?: boolean;
+    name?: string;
+    raw?: string;
+    required?: boolean;
+    type?: VariableType;
+}
+declare class Variable {
+    array: boolean;
+    name: string | null;
+    raw: string | null;
+    required: boolean;
+    type: VariableType;
+    value: unknown[] | null;
+    constructor(data?: VariableData);
+}
+
+interface OptionData {
+    short?: string | null;
+    long?: string | null;
+    info?: string | null;
+    variables?: string | null;
+}
+declare class Option {
+    short: string | null;
+    long: string | null;
+    info: string | null;
+    variables: Variable[] | null;
+    constructor(data?: OptionData);
+    description(info: string): this;
+}
+
+interface CommandData {
+    name?: string;
+    variables?: string | null;
+    info?: string;
+    middlewares?: MiddlewareFn[];
+    options?: Option[];
+}
+declare class Command {
+    actionFunction: ActionFn | null;
+    commandsArray: Command[];
+    commandStrings: string[];
+    info: string | null;
+    middlewaresArray: MiddlewareFn[];
+    name: string | null;
+    optionsArray: Option[];
+    variables: Variable[] | null;
+    versionString: string | null;
+    constructor(data?: CommandData);
+    description(info: string): this;
+    variable(string: string): this;
+    action(fn: ActionFn): this;
+    command(cmd: Command): this;
+    commands(cmds: Command[]): this;
+    middleware(fn: MiddlewareFn): this;
+    middlewares(fns: MiddlewareFn[]): this;
+    option(short: string | null, long: string | null, variables: string | null, info: string): this;
+    options(opts: Option[]): this;
+    version(v: string): this;
+    help(_source?: string[]): void;
+    parse(input: string[]): Promise<unknown>;
+}
+
+interface TermkitDefaults {
+    middlewares?: MiddlewareFn[];
+    options?: Option[];
+}
+declare class Termkit {
+    private static base;
+    private static commandDefaults;
+    static set defaults(obj: TermkitDefaults);
+    static setDefaults(obj: TermkitDefaults): void;
+    static command(name: string, variables?: string | null, info?: string): Command;
+    static middleware(action: MiddlewareFn): MiddlewareFn;
+    static option(short: string | null, long: string | null, variables: string | null, info: string): Option;
+    static parse(arr: string[]): Promise<unknown>;
+}
+
+interface CommandDefaults {
+    middlewares?: MiddlewareFn[];
+    options?: Option[];
+}
+declare const command: (name: string, variables?: string | null, info?: string) => Command;
+declare const middleware: (fn: MiddlewareFn) => MiddlewareFn;
+declare const option: (short: string | null, long: string | null, variables: string | null, info: string) => Option;
+declare const parse: (arr: string[]) => Promise<unknown>;
+declare const setDefaults: (data: CommandDefaults) => void;
+
+export { type ActionFn, Command, type CommandDefaults, type MiddlewareFn, Option, type ParsedOptions, Termkit, Variable, type VariableType, command, middleware, option, parse, setDefaults };