@thi.ng/args - npm Package Compare versions

Comparing version 2.2.46 to 2.3.0

api.d.ts

@@ -1,2 +0,4 @@
-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 {
@@ -115,5 +117,9 @@ /**
      *
+     * @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;
     /**
@@ -176,2 +182,93 @@ * If true (default), display argument default values. Nullish or false
 }
+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

CHANGELOG.md

 # Change Log
 
-- **Last updated**: 2023-12-11T10:07:09Z
+- **Last updated**: 2023-12-18T13:41:19Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
@@ -12,2 +12,20 @@
 
+## [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)
@@ -14,0 +32,0 @@

index.d.ts

 export * from "./api.js";
 export * from "./args.js";
+export * from "./cli.js";
 export * from "./coerce.js";
@@ -4,0 +5,0 @@ export * from "./parse.js";

index.js

 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.json

 {
   "name": "@thi.ng/args",
-  "version": "2.2.46",
+  "version": "2.3.0",
   "description": "Declarative, functional & typechecked CLI argument/options parser, value coercions etc.",
@@ -38,6 +38,8 @@ "type": "module",
   "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"
   },
@@ -62,2 +64,3 @@ "devDependencies": {
     "hex",
+    "logger",
     "nodejs",
@@ -73,3 +76,3 @@ "parser",
   "engines": {
-    "node": ">=12.7"
+    "node": ">=18"
   },
@@ -90,2 +93,5 @@ "files": [
     },
+    "./cli": {
+      "default": "./cli.js"
+    },
     "./coerce": {
@@ -104,3 +110,3 @@ "default": "./coerce.js"
   },
-  "gitHead": "5e7bafedfc3d53bc131469a28de31dd8e5b4a3ff\n"
+  "gitHead": "25a42a81fac8603a1e440a7aa8bc343276211ff4\n"
 }

README.md

@@ -72,3 +72,3 @@ <!-- This file is generated - DO NOT EDIT! -->
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.31 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.75 KB
 
@@ -80,3 +80,5 @@ ## Dependencies
 - [@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)
 
@@ -83,0 +85,0 @@ ## API

usage.js

@@ -0,1 +1,2 @@
+import { isPlainObject } from "@thi.ng/checks/is-plain-object";
 import { lengthAnsi } from "@thi.ng/strings/ansi";
@@ -20,3 +21,3 @@ import { capitalize, kebab } from "@thi.ng/strings/case";
   };
-  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);
@@ -23,0 +24,0 @@ const format = (ids) => ids.map((id) => argUsage(id, specs[id], opts, theme, indent));

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

63609

increased by12.71%

Number of package files

18

increased by12.5%

Lines of code

1015

increased by21.56%

Number of lines in readme file

305

increased by0.66%

Worsened metrics

Dependency count

6

increased by50%

Number of low supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + [e-mail]/logger@^2.1.0

• + [e-mail]/text-format@^2.0.0

• + [e-mail]/logger@2.1.10(transitive)

• + [e-mail]/text-format@2.2.21(transitive)

• [e-mail]/api@^8.9.13

• [e-mail]/checks@^3.4.13

• [e-mail]/errors@^2.4.7

• [e-mail]/strings@^3.7.4