@thi.ng/args 2.2.45 → 2.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-12-09T19:12:03Z
+- **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.39 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/api.js

@@ -1,19 +1,19 @@
-export const DEFAULT_THEME = {
-    default: 95,
-    hint: 90,
-    multi: 90,
-    param: 96,
-    required: 33,
+const DEFAULT_THEME = {
+  default: 95,
+  hint: 90,
+  multi: 90,
+  param: 96,
+  required: 33
 };
-/**
- * Wrapper for fixed size tuple values produced by {@link tuple}.
- */
-export class Tuple {
-    value;
-    constructor(value) {
-        this.value = value;
-    }
-    deref() {
-        return this.value;
-    }
+class Tuple {
+  constructor(value) {
+    this.value = value;
+  }
+  deref() {
+    return this.value;
+  }
 }
+export {
+  DEFAULT_THEME,
+  Tuple
+};

package/args.js

@@ -1,214 +1,105 @@
 import { identity } from "@thi.ng/api/fn";
 import { repeat } from "@thi.ng/strings/repeat";
-import { coerceFloat, coerceFloats, coerceHexInt, coerceHexInts, coerceInt, coerceInts, coerceJson, coerceKV, coerceOneOf, coerceTuple, } from "./coerce.js";
+import {
+  coerceFloat,
+  coerceFloats,
+  coerceHexInt,
+  coerceHexInts,
+  coerceInt,
+  coerceInts,
+  coerceJson,
+  coerceKV,
+  coerceOneOf,
+  coerceTuple
+} from "./coerce.js";
 const $single = (coerce, hint) => (spec) => ({
-    coerce,
-    hint,
-    group: "main",
-    ...spec,
+  coerce,
+  hint,
+  group: "main",
+  ...spec
 });
 const $multi = (coerce, hint) => (spec) => ({
-    hint: $hint(hint, spec.delim),
-    multi: true,
-    coerce,
-    group: "main",
-    ...spec,
+  hint: $hint(hint, spec.delim),
+  multi: true,
+  coerce,
+  group: "main",
+  ...spec
 });
 const $hint = (hint, delim) => hint + (delim ? `[${delim}..]` : "");
-/**
- * Returns a full {@link ArgSpec} for a boolean flag. The mere presence of this
- * arg will enable the flag.
- *
- * @param spec -
- */
-export const flag = (spec) => ({
-    flag: true,
-    default: false,
-    group: "flags",
-    ...spec,
+const flag = (spec) => ({
+  flag: true,
+  default: false,
+  group: "flags",
+  ...spec
 });
-/**
- * Returns a full {@link ArgSpec} for a string value arg.
- *
- * @param spec -
- */
-export const string = $single(identity, "STR");
-/**
- * Multi-arg version of {@link string}. Returns a full {@link ArgSpec} for a
- * multi string value arg. This argument can be provided mutiple times with
- * values collected into an array.
- *
- * @param spec -
- */
-export const strings = $multi(identity, "STR");
-/**
- * Returns a full {@link ArgSpec} for a floating point value arg. The value
- * will be autoatically coerced into a number using {@link coerceFloat}.
- *
- * @param spec -
- */
-export const float = $single(coerceFloat, "NUM");
-/**
- * Returns a full {@link ArgSpec} for a single hex integer value arg. The value
- * will be autoatically coerced into a number using {@link coerceHexInt}.
- *
- * @param spec -
- */
-export const hex = $single(coerceHexInt, "HEX");
-/**
- * Returns a full {@link ArgSpec} for a single integer value arg. The value
- * will be autoatically coerced into a number using {@link coerceInt}.
- *
- * @param spec -
- */
-export const int = $single(coerceInt, "INT");
-/**
- * Multi-arg version of {@link float}. Returns a full {@link ArgSpec} for a
- * multi floating point value arg. This argument can be provided mutiple times
- * with values being coerced into numbers and collected into an array.
- *
- * @param spec -
- */
-export const floats = $multi(coerceFloats, "NUM");
-/**
- * Multi-arg version of {@link hex}. Returns a full {@link ArgSpec} for a multi
- * hex integer value arg. This argument can be provided mutiple times with
- * values being coerced into numbers and collected into an array.
- *
- * @param spec -
- */
-export const hexes = $multi(coerceHexInts, "HEX");
-/**
- * Multi-arg version of {@link int}. Returns a full {@link ArgSpec} for a multi
- * integer value arg. This argument can be provided mutiple times with values
- * being coerced into numbers and collected into an array.
- *
- * @param spec -
- */
-export const ints = $multi(coerceInts, "INT");
-/**
- * Returns full {@link ArgSpec} for a JSON value arg. The raw CLI value string
- * will be automcatically coerced using {@link coerceJson}.
- *
- * @param spec -
- */
-export const json = (spec) => ({
-    coerce: coerceJson,
-    hint: "JSON",
-    group: "main",
-    ...spec,
+const string = $single(identity, "STR");
+const strings = $multi(identity, "STR");
+const float = $single(coerceFloat, "NUM");
+const hex = $single(coerceHexInt, "HEX");
+const int = $single(coerceInt, "INT");
+const floats = $multi(coerceFloats, "NUM");
+const hexes = $multi(coerceHexInts, "HEX");
+const ints = $multi(coerceInts, "INT");
+const json = (spec) => ({
+  coerce: coerceJson,
+  hint: "JSON",
+  group: "main",
+  ...spec
 });
 const $desc = (opts, prefix) => `${prefix ? prefix + ": " : ""}${opts.map((x) => `"${x}"`).join(", ")}`;
-/**
- * Returns full {@link ArgSpec} for an enum-like string value arg. The raw CLI
- * value string will be automcatically validated using {@link coerceOneOf}.
- *
- * @param opts -
- * @param spec -
- */
-export const oneOf = (opts, spec) => ({
-    coerce: coerceOneOf(opts),
-    hint: "ID",
-    group: "main",
-    ...spec,
-    desc: $desc(opts, spec.desc),
+const oneOf = (opts, spec) => ({
+  coerce: coerceOneOf(opts),
+  hint: "ID",
+  group: "main",
+  ...spec,
+  desc: $desc(opts, spec.desc)
 });
-/**
- * Multi-arg version of {@link oneOf}. Returns full {@link ArgSpec} for multiple
- * enum-like string value args. The raw CLI value strings will be automcatically
- * validated using {@link coerceOneOf} and collected into an array.
- *
- * @param opts -
- * @param spec -
- */
-export const oneOfMulti = (opts, spec) => ({
-    coerce: (xs) => xs.map(coerceOneOf(opts)),
-    hint: $hint("ID", spec.delim),
-    multi: true,
-    group: "main",
-    ...spec,
-    desc: $desc(opts, spec.desc),
+const oneOfMulti = (opts, spec) => ({
+  coerce: (xs) => xs.map(coerceOneOf(opts)),
+  hint: $hint("ID", spec.delim),
+  multi: true,
+  group: "main",
+  ...spec,
+  desc: $desc(opts, spec.desc)
 });
-/**
- * Returns a full {@link ArgSpec} for multiple `key=value` pair args, coerced
- * into a result object.
- *
- * @remarks
- * The default delimiter (`=`) can be overridden. Also by default, key-only args
- * are allowed and will receive a `"true"` as their value. However, if `strict`
- * is true, only full KV pairs are allowed.
- *
- * @param spec -
- * @param delim -
- */
-export const kvPairs = (spec, delim = "=", strict) => ({
-    coerce: coerceKV(delim, strict),
-    hint: `key${delim}val`,
-    multi: true,
-    group: "main",
-    ...spec,
+const kvPairs = (spec, delim = "=", strict) => ({
+  coerce: coerceKV(delim, strict),
+  hint: `key${delim}val`,
+  multi: true,
+  group: "main",
+  ...spec
 });
-/**
- * Like {@link kvPairs}, but coerces KV pairs into a result {@link KVMultiDict}
- * which supports multiple values per given key (each key's values are collected
- * into arrays).
- *
- * @param spec -
- * @param delim -
- * @param strict -
- */
-export const kvPairsMulti = (spec, delim = "=", strict) => ({
-    coerce: coerceKV(delim, strict, true),
-    hint: `key${delim}val(s)`,
-    multi: true,
-    group: "main",
-    ...spec,
+const kvPairsMulti = (spec, delim = "=", strict) => ({
+  coerce: coerceKV(delim, strict, true),
+  hint: `key${delim}val(s)`,
+  multi: true,
+  group: "main",
+  ...spec
 });
-/**
- * Returns a full {@link ArgSpec} for a fixed `size` tuple extracted from a
- * single value string. The individual values are delimited by `delim` and will
- * be coerced into their target type via `coerce`. The result tuple will be
- * wrapped in a {@link Tuple} instance.
- *
- * @remarks
- * An error will be thrown if the number of extracted values differs from the
- * specified tuple size or any value coercion fails.
- *
- * @example
- * ```ts
- * parse({ a: tuple(coerceInt, 2, {})}, ["--a", "1,2"])
- * // {
- * //   result: { a: Tuple { value: [1, 2] } },
- * //   index: 2,
- * //   rest: [],
- * //   done: true
- * // }
- * ```
- *
- * @param coerce -
- * @param size -
- * @param spec -
- * @param delim -
- */
-export const tuple = (coerce, size, spec, delim = ",") => ({
-    coerce: coerceTuple(coerce, size, delim),
-    hint: [...repeat("N", size)].join(delim),
-    group: "main",
-    ...spec,
+const tuple = (coerce, size2, spec, delim = ",") => ({
+  coerce: coerceTuple(coerce, size2, delim),
+  hint: [...repeat("N", size2)].join(delim),
+  group: "main",
+  ...spec
 });
-/**
- * Syntax sugar for `tuple(coerceInt, size, {...}, delim)`.
- *
- * @param size -
- * @param spec -
- * @param delim -
- */
-export const size = (size, spec, delim = "x") => tuple(coerceInt, size, spec, delim);
-/**
- * Syntax sugar for `tuple(coerceFloat, size, {...}, delim)`.
- *
- * @param size -
- * @param spec -
- * @param delim -
- */
-export const vec = (size, spec, delim = ",") => tuple(coerceFloat, size, spec, delim);
+const size = (size2, spec, delim = "x") => tuple(coerceInt, size2, spec, delim);
+const vec = (size2, spec, delim = ",") => tuple(coerceFloat, size2, spec, delim);
+export {
+  flag,
+  float,
+  floats,
+  hex,
+  hexes,
+  int,
+  ints,
+  json,
+  kvPairs,
+  kvPairsMulti,
+  oneOf,
+  oneOfMulti,
+  size,
+  string,
+  strings,
+  tuple,
+  vec
+};

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/coerce.js

@@ -2,42 +2,50 @@ import { isHex } from "@thi.ng/checks/is-hex";
 import { isNumericFloat, isNumericInt } from "@thi.ng/checks/is-numeric";
 import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { Tuple } from "./api.js";
-export const coerceString = (x) => x;
-export const coerceFloat = (x) => isNumericFloat(x)
-    ? parseFloat(x)
-    : illegalArgs(`not a numeric value: ${x}`);
-export const coerceFloats = (xs) => xs.map(coerceFloat);
-export const coerceHexInt = (x) => isHex(x) ? parseInt(x, 16) : illegalArgs(`not a hex value: ${x}`);
-export const coerceHexInts = (xs) => xs.map(coerceHexInt);
-export const coerceInt = (x) => isNumericInt(x) ? parseInt(x) : illegalArgs(`not an integer: ${x}`);
-export const coerceInts = (xs) => xs.map(coerceInt);
-export const coerceJson = (x) => JSON.parse(x);
-export const coerceOneOf = (xs) => (x) => xs.includes(x) ? x : illegalArgs(`invalid option: ${x}`);
-export function coerceKV(delim = "=", strict = false, multi = false) {
-    return (pairs) => pairs.reduce((acc, x) => {
-        const idx = x.indexOf(delim);
-        strict &&
-            idx < 1 &&
-            illegalArgs(`got '${x}', but expected a 'key${delim}value' pair`);
-        if (idx > 0) {
-            const id = x.substring(0, idx);
-            const val = x.substring(idx + 1);
-            if (multi) {
-                acc[id] ? acc[id].push(val) : (acc[id] = [val]);
-            }
-            else {
-                acc[id] = val;
-            }
-        }
-        else {
-            acc[x] = multi ? ["true"] : "true";
-        }
-        return acc;
-    }, {});
+const coerceString = (x) => x;
+const coerceFloat = (x) => isNumericFloat(x) ? parseFloat(x) : illegalArgs(`not a numeric value: ${x}`);
+const coerceFloats = (xs) => xs.map(coerceFloat);
+const coerceHexInt = (x) => isHex(x) ? parseInt(x, 16) : illegalArgs(`not a hex value: ${x}`);
+const coerceHexInts = (xs) => xs.map(coerceHexInt);
+const coerceInt = (x) => isNumericInt(x) ? parseInt(x) : illegalArgs(`not an integer: ${x}`);
+const coerceInts = (xs) => xs.map(coerceInt);
+const coerceJson = (x) => JSON.parse(x);
+const coerceOneOf = (xs) => (x) => xs.includes(x) ? x : illegalArgs(`invalid option: ${x}`);
+function coerceKV(delim = "=", strict = false, multi = false) {
+  return (pairs) => pairs.reduce((acc, x) => {
+    const idx = x.indexOf(delim);
+    strict && idx < 1 && illegalArgs(
+      `got '${x}', but expected a 'key${delim}value' pair`
+    );
+    if (idx > 0) {
+      const id = x.substring(0, idx);
+      const val = x.substring(idx + 1);
+      if (multi) {
+        acc[id] ? acc[id].push(val) : acc[id] = [val];
+      } else {
+        acc[id] = val;
+      }
+    } else {
+      acc[x] = multi ? ["true"] : "true";
+    }
+    return acc;
+  }, {});
 }
-export const coerceTuple = (coerce, size, delim = ",") => (src) => {
-    const parts = src.split(delim);
-    parts.length !== size &&
-        illegalArgs(`got '${src}', but expected a tuple of ${size} values`);
-    return new Tuple(parts.map(coerce));
+const coerceTuple = (coerce, size, delim = ",") => (src) => {
+  const parts = src.split(delim);
+  parts.length !== size && illegalArgs(`got '${src}', but expected a tuple of ${size} values`);
+  return new Tuple(parts.map(coerce));
+};
+export {
+  coerceFloat,
+  coerceFloats,
+  coerceHexInt,
+  coerceHexInts,
+  coerceInt,
+  coerceInts,
+  coerceJson,
+  coerceKV,
+  coerceOneOf,
+  coerceString,
+  coerceTuple
 };

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.45",
+  "version": "2.3.0",
   "description": "Declarative, functional & typechecked CLI argument/options parser, value coercions etc.",
   "type": "module",
   "module": "./index.js",
@@ -24,7 +24,9 @@
   "author": "Karsten Schmidt (https://thi.ng)",
   "license": "Apache-2.0",
   "scripts": {
-    "build": "yarn clean && tsc --declaration",
+    "build": "yarn build:esbuild && yarn build:decl",
+    "build:decl": "tsc --declaration --emitDeclarationOnly",
+    "build:esbuild": "esbuild --format=esm --platform=neutral --target=es2022 --tsconfig=tsconfig.json --outdir=. src/**/*.ts",
     "clean": "rimraf --glob '*.js' '*.d.ts' '*.map' doc",
     "doc": "typedoc --excludePrivate --excludeInternal --out doc src/index.ts",
     "doc:ae": "mkdir -p .ae/doc .ae/temp && api-extractor run --local --verbose",
@@ -33,13 +35,16 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.11",
-    "@thi.ng/checks": "^3.4.11",
-    "@thi.ng/errors": "^2.4.5",
-    "@thi.ng/strings": "^3.7.2"
+    "@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",
+    "esbuild": "^0.19.8",
     "rimraf": "^5.0.5",
     "tools": "^0.0.1",
     "typedoc": "^0.25.4",
@@ -55,6 +60,7 @@
     "declarative",
     "functional",
     "hex",
+    "logger",
     "nodejs",
     "parser",
     "tuple",
@@ -65,7 +71,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=12.7"
+    "node": ">=18"
   },
   "files": [
     "./*.js",
@@ -81,6 +87,9 @@
     "./args": {
       "default": "./args.js"
     },
+    "./cli": {
+      "default": "./cli.js"
+    },
     "./coerce": {
       "default": "./coerce.js"
     },
@@ -94,5 +103,5 @@
   "thi.ng": {
     "year": 2018
   },
-  "gitHead": "25f2ac8ff795a432a930119661b364d4d93b59a0\n"
+  "gitHead": "25a42a81fac8603a1e440a7aa8bc343276211ff4\n"
 }

package/parse.js

@@ -3,118 +3,120 @@ import { defError } from "@thi.ng/errors/deferror";
 import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { camel } from "@thi.ng/strings/case";
 import { usage } from "./usage.js";
-export const ParseError = defError(() => "parse error");
-export const parse = (specs, argv, opts) => {
-    opts = { start: 2, showUsage: true, help: ["--help", "-h"], ...opts };
-    try {
-        return parseOpts(specs, argv, opts);
-    }
-    catch (e) {
-        if (opts.showUsage) {
-            console.log(e.message + "\n\n" + usage(specs, opts.usageOpts));
-        }
-        throw new ParseError(e.message);
+const ParseError = defError(() => "parse error");
+const parse = (specs, argv, opts) => {
+  opts = { start: 2, showUsage: true, help: ["--help", "-h"], ...opts };
+  try {
+    return parseOpts(specs, argv, opts);
+  } catch (e) {
+    if (opts.showUsage) {
+      console.log(
+        e.message + "\n\n" + usage(specs, opts.usageOpts)
+      );
     }
+    throw new ParseError(e.message);
+  }
 };
 const parseOpts = (specs, argv, opts) => {
-    const aliases = aliasIndex(specs);
-    const acc = {};
-    let id;
-    let spec;
-    let i = opts.start;
-    for (; i < argv.length;) {
-        const a = argv[i];
-        if (!id) {
-            if (opts.help.includes(a)) {
-                console.log(usage(specs, opts.usageOpts));
-                return;
-            }
-            const state = parseKey(specs, aliases, acc, a);
-            id = state.id;
-            spec = state.spec;
-            i = i + ~~(state.state < 2);
-            if (state.state)
-                break;
-        }
-        else {
-            if (parseValue(spec, acc, id, a))
-                break;
-            id = null;
-            i++;
-        }
+  const aliases = aliasIndex(specs);
+  const acc = {};
+  let id;
+  let spec;
+  let i = opts.start;
+  for (; i < argv.length; ) {
+    const a = argv[i];
+    if (!id) {
+      if (opts.help.includes(a)) {
+        console.log(usage(specs, opts.usageOpts));
+        return;
+      }
+      const state = parseKey(specs, aliases, acc, a);
+      id = state.id;
+      spec = state.spec;
+      i = i + ~~(state.state < 2);
+      if (state.state)
+        break;
+    } else {
+      if (parseValue(spec, acc, id, a))
+        break;
+      id = null;
+      i++;
     }
-    id && illegalArgs(`missing value for: --${id}`);
-    return {
-        result: processResults(specs, acc),
-        index: i,
-        rest: argv.slice(i),
-        done: i >= argv.length,
-    };
+  }
+  id && illegalArgs(`missing value for: --${id}`);
+  return {
+    result: processResults(specs, acc),
+    index: i,
+    rest: argv.slice(i),
+    done: i >= argv.length
+  };
 };
-const aliasIndex = (specs) => Object.entries(specs).reduce((acc, [k, v]) => (v.alias ? ((acc[v.alias] = k), acc) : acc), {});
+const aliasIndex = (specs) => Object.entries(specs).reduce(
+  (acc, [k, v]) => v.alias ? (acc[v.alias] = k, acc) : acc,
+  {}
+);
 const parseKey = (specs, aliases, acc, a) => {
-    if (a[0] === "-") {
-        let id;
-        if (a[1] === "-") {
-            // terminator arg, stop parsing
-            if (a === "--")
-                return { state: 1 };
-            id = camel(a.substring(2));
-        }
-        else {
-            id = aliases[a.substring(1)];
-            !id && illegalArgs(`unknown option: ${a}`);
-        }
-        const spec = specs[id];
-        !spec && illegalArgs(id);
-        if (spec.flag) {
-            acc[id] = true;
-            id = undefined;
-            // stop parsing if fn returns false
-            if (spec.fn && !spec.fn("true"))
-                return { state: 1, spec };
-        }
-        return { state: 0, id, spec };
+  if (a[0] === "-") {
+    let id;
+    if (a[1] === "-") {
+      if (a === "--")
+        return { state: 1 };
+      id = camel(a.substring(2));
+    } else {
+      id = aliases[a.substring(1)];
+      !id && illegalArgs(`unknown option: ${a}`);
+    }
+    const spec = specs[id];
+    !spec && illegalArgs(id);
+    if (spec.flag) {
+      acc[id] = true;
+      id = void 0;
+      if (spec.fn && !spec.fn("true"))
+        return { state: 1, spec };
     }
-    // no option arg, stop parsing
-    return { state: 2 };
+    return { state: 0, id, spec };
+  }
+  return { state: 2 };
 };
 const parseValue = (spec, acc, id, a) => {
-    /^-[a-z]/i.test(a) && illegalArgs(`missing value for: --${id}`);
-    if (spec.multi) {
-        isArray(acc[id]) ? acc[id].push(a) : (acc[id] = [a]);
-    }
-    else {
-        acc[id] = a;
-    }
-    return spec.fn && !spec.fn(a);
+  /^-[a-z]/i.test(a) && illegalArgs(`missing value for: --${id}`);
+  if (spec.multi) {
+    isArray(acc[id]) ? acc[id].push(a) : acc[id] = [a];
+  } else {
+    acc[id] = a;
+  }
+  return spec.fn && !spec.fn(a);
 };
 const processResults = (specs, acc) => {
-    let spec;
-    for (let id in specs) {
-        spec = specs[id];
-        if (acc[id] === undefined) {
-            if (spec.default !== undefined) {
-                acc[id] = spec.default;
-            }
-            else if (spec.optional === false) {
-                illegalArgs(`missing arg: --${id}`);
-            }
-        }
-        else if (spec.coerce) {
-            coerceValue(spec, acc, id);
-        }
+  let spec;
+  for (let id in specs) {
+    spec = specs[id];
+    if (acc[id] === void 0) {
+      if (spec.default !== void 0) {
+        acc[id] = spec.default;
+      } else if (spec.optional === false) {
+        illegalArgs(`missing arg: --${id}`);
+      }
+    } else if (spec.coerce) {
+      coerceValue(spec, acc, id);
     }
-    return acc;
+  }
+  return acc;
 };
 const coerceValue = (spec, acc, id) => {
-    try {
-        if (spec.multi && spec.delim) {
-            acc[id] = acc[id].reduce((acc, x) => (acc.push(...x.split(spec.delim)), acc), []);
-        }
-        acc[id] = spec.coerce(acc[id]);
-    }
-    catch (e) {
-        throw new Error(`arg --${id}: ${e.message}`);
+  try {
+    if (spec.multi && spec.delim) {
+      acc[id] = acc[id].reduce(
+        (acc2, x) => (acc2.push(...x.split(spec.delim)), acc2),
+        []
+      );
     }
+    acc[id] = spec.coerce(acc[id]);
+  } catch (e) {
+    throw new Error(`arg --${id}: ${e.message}`);
+  }
+};
+export {
+  ParseError,
+  parse
 };

package/usage.js

@@ -1,76 +1,76 @@
+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";
 import { repeat } from "@thi.ng/strings/repeat";
 import { stringify } from "@thi.ng/strings/stringify";
 import { SPLIT_ANSI, wordWrapLines } from "@thi.ng/strings/word-wrap";
-import { DEFAULT_THEME, } from "./api.js";
-export const usage = (specs, opts = {}) => {
-    opts = {
-        lineWidth: 80,
-        paramWidth: 32,
-        showDefaults: true,
-        prefix: "",
-        suffix: "",
-        groups: ["flags", "main"],
-        ...opts,
-    };
-    const theme = opts.color !== false
-        ? { ...DEFAULT_THEME, ...opts.color }
-        : {};
-    const indent = repeat(" ", opts.paramWidth);
-    const format = (ids) => ids.map((id) => argUsage(id, specs[id], opts, theme, indent));
-    const sortedIDs = Object.keys(specs).sort();
-    const groups = opts.groups
-        ? opts.groups
-            .map((gid) => [
-            gid,
-            sortedIDs.filter((id) => specs[id].group === gid),
-        ])
-            .filter((g) => !!g[1].length)
-        : [["options", sortedIDs]];
-    return [
-        ...wrap(opts.prefix, opts.lineWidth),
-        ...groups.map(([gid, ids]) => [
-            ...(opts.showGroupNames ? [`${capitalize(gid)}:\n`] : []),
-            ...format(ids),
-            "",
-        ].join("\n")),
-        ...wrap(opts.suffix, opts.lineWidth),
-    ].join("\n");
+import {
+  DEFAULT_THEME
+} from "./api.js";
+const usage = (specs, opts = {}) => {
+  opts = {
+    lineWidth: 80,
+    paramWidth: 32,
+    showDefaults: true,
+    prefix: "",
+    suffix: "",
+    groups: ["flags", "main"],
+    ...opts
+  };
+  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();
+  const groups = opts.groups ? opts.groups.map(
+    (gid) => [
+      gid,
+      sortedIDs.filter((id) => specs[id].group === gid)
+    ]
+  ).filter((g) => !!g[1].length) : [["options", sortedIDs]];
+  return [
+    ...wrap(opts.prefix, opts.lineWidth),
+    ...groups.map(
+      ([gid, ids]) => [
+        ...opts.showGroupNames ? [`${capitalize(gid)}:
+`] : [],
+        ...format(ids),
+        ""
+      ].join("\n")
+    ),
+    ...wrap(opts.suffix, opts.lineWidth)
+  ].join("\n");
 };
 const argUsage = (id, spec, opts, theme, indent) => {
-    const hint = argHint(spec, theme);
-    const alias = argAlias(spec, theme, hint);
-    const name = ansi(`--${kebab(id)}`, theme.param);
-    const params = `${alias}${name}${hint}`;
-    const isRequired = spec.optional === false && spec.default === undefined;
-    const prefixes = [];
-    isRequired && prefixes.push("required");
-    spec.multi && prefixes.push("multiple");
-    const body = argPrefix(prefixes, theme, isRequired) +
-        (spec.desc || "") +
-        argDefault(spec, opts, theme);
-    return (padRight(opts.paramWidth)(params, lengthAnsi(params)) +
-        wrap(body, opts.lineWidth - opts.paramWidth)
-            .map((l, i) => (i > 0 ? indent + l : l))
-            .join("\n"));
+  const hint = argHint(spec, theme);
+  const alias = argAlias(spec, theme, hint);
+  const name = ansi(`--${kebab(id)}`, theme.param);
+  const params = `${alias}${name}${hint}`;
+  const isRequired = spec.optional === false && spec.default === void 0;
+  const prefixes = [];
+  isRequired && prefixes.push("required");
+  spec.multi && prefixes.push("multiple");
+  const body = argPrefix(prefixes, theme, isRequired) + (spec.desc || "") + argDefault(spec, opts, theme);
+  return padRight(opts.paramWidth)(params, lengthAnsi(params)) + wrap(body, opts.lineWidth - opts.paramWidth).map((l, i) => i > 0 ? indent + l : l).join("\n");
 };
 const argHint = (spec, theme) => spec.hint ? ansi(" " + spec.hint, theme.hint) : "";
 const argAlias = (spec, theme, hint) => spec.alias ? `${ansi("-" + spec.alias, theme.param)}${hint}, ` : "";
-const argPrefix = (prefixes, theme, isRequired) => prefixes.length
-    ? ansi(`[${prefixes.join(", ")}] `, isRequired ? theme.required : theme.multi)
-    : "";
-const argDefault = (spec, opts, theme) => opts.showDefaults && spec.default != null && spec.default !== false
-    ? ansi(` (default: ${stringify(true)(spec.defaultHint != undefined
-        ? spec.defaultHint
-        : spec.default)})`, theme.default)
-    : "";
-const ansi = (x, col) => col != null ? `\x1b[${col}m${x}\x1b[0m` : x;
-const wrap = (str, width) => str
-    ? wordWrapLines(str, {
-        width,
-        splitter: SPLIT_ANSI,
-        hard: true,
-    })
-    : [];
+const argPrefix = (prefixes, theme, isRequired) => prefixes.length ? ansi(
+  `[${prefixes.join(", ")}] `,
+  isRequired ? theme.required : theme.multi
+) : "";
+const argDefault = (spec, opts, theme) => opts.showDefaults && spec.default != null && spec.default !== false ? ansi(
+  ` (default: ${stringify(true)(
+    spec.defaultHint != void 0 ? spec.defaultHint : spec.default
+  )})`,
+  theme.default
+) : "";
+const ansi = (x, col) => col != null ? `\x1B[${col}m${x}\x1B[0m` : x;
+const wrap = (str, width) => str ? wordWrapLines(str, {
+  width,
+  splitter: SPLIT_ANSI,
+  hard: true
+}) : [];
+export {
+  usage
+};