@thi.ng/args 2.2.46 → 2.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-12-11T10:07:09Z
+- **Last updated**: 2023-12-18T13:41:19Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,24 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@2.3.0) (2023-12-18)
+
+#### 🚀 Features
+
+- add cliApp() runner ([b2248fa](https://github.com/thi-ng/umbrella/commit/b2248fa))
+- update lifecycle hooks, add NO_COLOR support, add docs ([4a0ebda](https://github.com/thi-ng/umbrella/commit/4a0ebda))
+  - add CLIAppConfig pre/post lifecycle hooks
+  - update UsageOpts.color handling
+  - add `NO_COLOR` env var support in cliApp()
+  - add doc strings
+  - update deps
+- update cliApp() to support command context extensions ([61d9fb8](https://github.com/thi-ng/umbrella/commit/61d9fb8))
+- update cliApp() error handling ([019e5a1](https://github.com/thi-ng/umbrella/commit/019e5a1))
+- update argv handling in cliApp() ([b1ed768](https://github.com/thi-ng/umbrella/commit/b1ed768))
+- add NO_COLOR aware formatters to CommandCtx ([0e7ddda](https://github.com/thi-ng/umbrella/commit/0e7ddda))
+  - update deps
+- update cliApp() to use StreamLogger (target: process.stderr) ([b249295](https://github.com/thi-ng/umbrella/commit/b249295))
+
 ### [2.2.28](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@2.2.28) (2023-08-04)
 
 #### ♻️ Refactoring

package/README.md

@@ -69,14 +69,16 @@ For Node.js REPL:
 const args = await import("@thi.ng/args");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.31 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.75 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
+- [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)
 - [@thi.ng/strings](https://github.com/thi-ng/umbrella/tree/develop/packages/strings)
+- [@thi.ng/text-format](https://github.com/thi-ng/umbrella/tree/develop/packages/text-format)
 
 ## API
 

package/api.d.ts

@@ -1,4 +1,6 @@
-import type { Fn, IDeref, IObjectOf } from "@thi.ng/api";
+import type { Fn, Fn2, IDeref, IObjectOf } from "@thi.ng/api";
+import type { ILogger } from "@thi.ng/logger";
+import type { FormatPresets } from "@thi.ng/text-format";
 export interface ArgSpecBase {
     /**
      * Shorthand for given arg/option
@@ -112,9 +114,13 @@ export interface UsageOpts {
     /**
      * If false, ANSI colors will be stripped from output.
      *
+     * @remarks
+     * When using {@link cliApp}, the default for this value will depend on the
+     * `NO_COLOR` env var being set. See https://no-color.org/ for details.
+     *
      * @defaultValue true
      */
-    color: Partial<ColorTheme> | false;
+    color: Partial<ColorTheme> | boolean;
     /**
      * If true (default), display argument default values. Nullish or false
      * default values will never be shown.
@@ -172,4 +178,95 @@ export declare class Tuple<T> implements IDeref<T[]> {
     constructor(value: T[]);
     deref(): T[];
 }
+export interface CLIAppConfig<OPTS extends object, CTX extends CommandCtx<OPTS, OPTS> = CommandCtx<OPTS, OPTS>> {
+    /**
+     * App (CLI command) short name.
+     */
+    name: string;
+    /**
+     * Shared args for all commands
+     */
+    opts: Args<OPTS>;
+    /**
+     * Command spec registry
+     */
+    commands: IObjectOf<Command<any, OPTS, CTX>>;
+    /**
+     * If true, the app will only use the single command entry in
+     * {@link CLIAppConfig.commands} and not expect the first CLI args to be a
+     * command name.
+     */
+    single?: boolean;
+    /**
+     * Usage options, same as {@link UsageOpts}. Usage will be shown
+     * automatically in case of arg parse errors.
+     */
+    usage: Partial<UsageOpts>;
+    /**
+     * Arguments vector to use for arg parsing. If omitted, uses `process.argv`
+     */
+    argv?: string[];
+    /**
+     * {@link CLIAppConfig.argv} index to start parsing from.
+     *
+     * @defaultValue 2
+     */
+    start?: number;
+    /**
+     * {@link CommandCtx} augmentation handler, i.e. an async function which
+     * will be called just before the actual command for additional setup/config
+     * purposes. The context object returned will be the one passed to the
+     * command.
+     */
+    ctx: Fn2<CommandCtx<OPTS, OPTS>, Command<any, OPTS, CTX>, Promise<CTX>>;
+    /**
+     * Lifecycle hook. Function which will be called just after the actual
+     * command handler, e.g. for teardown purposes.
+     */
+    post?: Fn2<CTX, Command<any, OPTS, CTX>, Promise<void>>;
+}
+export interface Command<OPTS extends BASE, BASE extends object, CTX extends CommandCtx<OPTS, BASE> = CommandCtx<OPTS, BASE>> {
+    /**
+     * Command description (short, single line)
+     */
+    desc: string;
+    /**
+     * Command specific CLI arg specs
+     */
+    opts: Args<Omit<OPTS, keyof BASE>>;
+    /**
+     * Number of required rest input value (after all parsed options). Leave
+     * unset to allow any number.
+     */
+    inputs?: number;
+    /**
+     * Actual command function/implementation.
+     */
+    fn: Fn<CTX, Promise<void>>;
+}
+export interface CommandCtx<OPTS extends BASE, BASE extends object> {
+    /**
+     * Logger to be used by all commands. By default uses a console logger with
+     * log level INFO. Can be customized via {@link CLIAppConfig.pre}.
+     */
+    logger: ILogger;
+    /**
+     * `NO_COLOR`-aware text formatting presets. If color output is NOT disabled
+     * via the `NO_COLOR` env var, this defaults to
+     * [`PRESET_ANSI16`](https://github.com/thi-ng/umbrella/blob/develop/packages/text-format/README.md),
+     * otherwise `PRESET_NONE` (i.e. same API, but ignoring any color requests).
+     *
+     * See https://no-color.org for context.
+     */
+    format: FormatPresets;
+    /**
+     * Parsed CLI args (according to provided command spec)
+     */
+    opts: OPTS;
+    /**
+     * Array of remaining CLI args (after parsed options). Individual commands
+     * can specify the number of items required via {@link Command.inputs}.
+     */
+    inputs: string[];
+}
 //# sourceMappingURL=api.d.ts.map

package/cli.d.ts

@@ -0,0 +1,3 @@
+import type { CLIAppConfig, CommandCtx } from "./api.js";
+export declare const cliApp: <OPTS extends object, CTX extends CommandCtx<OPTS, OPTS>>(config: CLIAppConfig<OPTS, CTX>) => Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/cli.js

@@ -0,0 +1,78 @@
+import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
+import { StreamLogger } from "@thi.ng/logger/stream";
+import { padRight } from "@thi.ng/strings/pad-right";
+import { PRESET_ANSI16, PRESET_NONE } from "@thi.ng/text-format/presets";
+import { parse } from "./parse.js";
+import { usage } from "./usage.js";
+const cliApp = async (config) => {
+  const argv = config.argv || process.argv;
+  const isColor = !process.env.NO_COLOR;
+  const usageOpts = {
+    prefix: "",
+    color: isColor,
+    ...config.usage
+  };
+  try {
+    let cmdID;
+    let cmd;
+    let start = config.start ?? 2;
+    if (config.single) {
+      cmdID = Object.keys(config.commands)[0];
+      if (!cmdID)
+        illegalArgs("no command provided");
+      cmd = config.commands[cmdID];
+    } else {
+      cmdID = argv[start];
+      cmd = config.commands[cmdID];
+      usageOpts.prefix += __descriptions(config.commands);
+      if (!cmd)
+        __usageAndExit(config, usageOpts);
+      start++;
+    }
+    let parsed;
+    try {
+      parsed = parse({ ...config.opts, ...cmd.opts }, argv, {
+        showUsage: true,
+        usageOpts,
+        start
+      });
+    } catch (_) {
+    }
+    if (!parsed)
+      process.exit(1);
+    if (cmd.inputs !== void 0 && cmd.inputs !== parsed.rest.length) {
+      process.stderr.write(`expected ${cmd.inputs || 0} input(s)
+`);
+      __usageAndExit(config, usageOpts);
+    }
+    const ctx = await config.ctx(
+      {
+        logger: new StreamLogger(process.stderr, config.name, "INFO"),
+        format: isColor ? PRESET_ANSI16 : PRESET_NONE,
+        opts: parsed.result,
+        inputs: parsed.rest
+      },
+      cmd
+    );
+    await cmd.fn(ctx);
+    if (config.post)
+      await config.post(ctx, cmd);
+  } catch (e) {
+    process.stderr.write(e.message + "\n\n");
+    process.exit(1);
+  }
+};
+const __usageAndExit = (config, usageOpts) => {
+  process.stderr.write(usage(config.opts, usageOpts));
+  process.exit(1);
+};
+const __descriptions = (commands) => [
+  "\nAvailable commands:\n",
+  ...Object.keys(commands).map(
+    (x) => `${padRight(16)(x)}: ${commands[x].desc}`
+  ),
+  "\n"
+].join("\n");
+export {
+  cliApp
+};

package/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./api.js";
 export * from "./args.js";
+export * from "./cli.js";
 export * from "./coerce.js";
 export * from "./parse.js";
 export * from "./usage.js";

package/index.js

@@ -1,5 +1,6 @@
 export * from "./api.js";
 export * from "./args.js";
+export * from "./cli.js";
 export * from "./coerce.js";
 export * from "./parse.js";
 export * from "./usage.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/args",
-  "version": "2.2.46",
+  "version": "2.3.0",
   "description": "Declarative, functional & typechecked CLI argument/options parser, value coercions etc.",
   "type": "module",
   "module": "./index.js",
@@ -35,10 +35,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.12",
-    "@thi.ng/checks": "^3.4.12",
-    "@thi.ng/errors": "^2.4.6",
-    "@thi.ng/strings": "^3.7.3"
+    "@thi.ng/api": "^8.9.13",
+    "@thi.ng/checks": "^3.4.13",
+    "@thi.ng/errors": "^2.4.7",
+    "@thi.ng/logger": "^2.1.0",
+    "@thi.ng/strings": "^3.7.4",
+    "@thi.ng/text-format": "^2.0.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.38.3",
@@ -58,6 +60,7 @@
     "declarative",
     "functional",
     "hex",
+    "logger",
     "nodejs",
     "parser",
     "tuple",
@@ -68,7 +71,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=12.7"
+    "node": ">=18"
   },
   "files": [
     "./*.js",
@@ -84,6 +87,9 @@
     "./args": {
       "default": "./args.js"
     },
+    "./cli": {
+      "default": "./cli.js"
+    },
     "./coerce": {
       "default": "./coerce.js"
     },
@@ -97,5 +103,5 @@
   "thi.ng": {
     "year": 2018
   },
-  "gitHead": "5e7bafedfc3d53bc131469a28de31dd8e5b4a3ff\n"
+  "gitHead": "25a42a81fac8603a1e440a7aa8bc343276211ff4\n"
 }

package/usage.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from "@thi.ng/checks/is-plain-object";
 import { lengthAnsi } from "@thi.ng/strings/ansi";
 import { capitalize, kebab } from "@thi.ng/strings/case";
 import { padRight } from "@thi.ng/strings/pad-right";
@@ -17,7 +18,7 @@ const usage = (specs, opts = {}) => {
     groups: ["flags", "main"],
     ...opts
   };
-  const theme = opts.color !== false ? { ...DEFAULT_THEME, ...opts.color } : {};
+  const theme = isPlainObject(opts.color) ? { ...DEFAULT_THEME, ...opts.color } : opts.color ? DEFAULT_THEME : {};
   const indent = repeat(" ", opts.paramWidth);
   const format = (ids) => ids.map((id) => argUsage(id, specs[id], opts, theme, indent));
   const sortedIDs = Object.keys(specs).sort();