@thi.ng/args 2.10.0 → 2.10.2

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-09-04T09:11:23Z
+- **Last updated**: 2025-09-25T11:10:32Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.

package/README.md

@@ -15,22 +15,29 @@
 > GitHub](https://github.com/sponsors/postspectacular). Thank you! ❤️
 
 - [About](#about)
+  - [Built-in argument types](#built-in-argument-types)
+  - [Re-usable argument presets](#re-usable-argument-presets)
+  - [CLI app framework](#cli-app-framework)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [Projects using this package](#projects-using-this-package)
 - [API](#api)
-  - [Basic usage](#basic-usage)
-    - [Generate & display help](#generate--display-help)
-    - [Parsing, value coercions & side effects](#parsing-value-coercions--side-effects)
+- [Basic usage](#basic-usage)
+  - [Generate & display help](#generate--display-help)
+  - [Parsing, value coercions & side effects](#parsing-value-coercions--side-effects)
+- [Declarative, multi-command CLI application](#declarative-multi-command-cli-application)
 - [Authors](#authors)
 - [License](#license)
 
 ## About
 
-Declarative, functional CLI argument/options parser, value coercions, sub-commands etc..
+Declarative, functional CLI argument/options parser, app framework, arg value coercions, multi/sub-commands, usage generation, error handling etc..
 
-Includes built-in support for the following argument types (of course custom arg types are supported too):
+### Built-in argument types
+
+The parser includes built-in support for the following argument types (of course
+custom arg types are supported too):
 
 | **Argument type**    | **Multiple** | **Example**                | **Result**                        |
 |----------------------|--------------|----------------------------|-----------------------------------|
@@ -45,8 +52,44 @@ Includes built-in support for the following argument types (of course custom arg
 
 If multiple values/repetitions are allowed for an argument, the values will be
 collected into an array (apart from KV pairs, which will yield an object).
-Furthermore, for multi-args, an optional delimiter can be specified to extract
-individual values, e.g. `-a 1,2,3` equals `-a 1 -a 2 -a 3`
+Furthermore, for multi-args and tuples, an optional delimiter can be specified
+to extract individual values, e.g. `-a 1,2,3` equals `-a 1 -a 2 -a 3`
+
+### Re-usable argument presets
+
+The following commonly used arguments are available as predefined presets:
+
+- [`ARG_DRY_RUN`](https://docs.thi.ng/umbrella/args/variables/ARG_DRY_RUN.html)
+- [`ARG_QUIET`](https://docs.thi.ng/umbrella/args/variables/ARG_QUIET.html)
+- [`ARG_VERBOSE`](https://docs.thi.ng/umbrella/args/variables/ARG_VERBOSE.html)
+
+Higher order, configurable preset specs:
+
+- [`ARG_OUT_DIR`](https://docs.thi.ng/umbrella/args/functions/ARG_OUT_DIR.html)
+- [`ARG_OUT_FILE`](https://docs.thi.ng/umbrella/args/functions/ARG_OUT_FILE.html)
+
+To use these presets, simply import and splice them into your own arg
+definitions (see code examples below).
+
+### CLI app framework
+
+The package provides a simple framework to conveniently define single and
+multi-command applications in a declarative and modular manner. Such apps are
+defined via command specs and other configuration options. The framework then
+handles all argument parsing, validation, usage display and delegation to
+sub-commands.
+
+The wrapper defines a user-customizable [command
+context](https://docs.thi.ng/umbrella/args/interfaces/CommandCtx.html) with all
+important information which is passed to the commands and also includes a logger
+(writing to `stderr`). Other help/usage and error output also respects the
+[`NO_COLOR` convention](https://no-color.org/).
+
+A [fully documented code example](#declarative-multi-command-cli-application) is
+further below.
+
+For some _publicly available_ production uses, please see the [related packages
+section](#projects-using-this-package) in this readme.
 
 ## Status
 
@@ -72,7 +115,7 @@ For Node.js REPL:
 const args = await import("@thi.ng/args");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 3.29 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.31 KB
 
 ## Dependencies
 
@@ -97,15 +140,17 @@ Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
   tangling / codegen utility, inspired by org-mode & noweb
 - [@thi.ng/wasm-api-bindgen](https://thi.ng/wasm-api-bindgen): Polyglot bindings
   code generators (TS/JS, Zig, C11) for hybrid WebAssembly projects
+- [thing-tools](https://codeberg.org/thi.ng/thing-tools)
 
 ## API
 
 [Generated API docs](https://docs.thi.ng/umbrella/args/)
 
-### Basic usage
+## Basic usage
 
 ```ts tangle:export/readme.ts
 import {
+    ARG_VERBOSE,
     flag,
     hex,
     json,
@@ -132,10 +177,14 @@ interface TestArgs {
     pos?: Tuple<number>;
     xtra?: { a: number; b: string };
     define?: KVDict;
+    verbose: boolean;
 }
 
 // arg specifications
 const specs: Args<TestArgs> = {
+    // re-use predefined preset (see readme section above)
+    ...ARG_VERBOSE,
+
     // string arg
     configPath: string({
         alias: "c",
@@ -223,6 +272,7 @@ illegal argument(s): missing arg: --type
 Flags:
 
 -f, --force                     Force operation
+-v, --verbose                   Display extra information
 
 Main:
 
@@ -240,7 +290,7 @@ Extra:
 -x JSON, --xtra JSON            Extra options
 ```
 
-#### Generate & display help
+### Generate & display help
 
 Usage information can be generated via `usage()` and is automatically triggered
 via the special `--help` option (configurable, see
@@ -256,23 +306,7 @@ By default, ANSI colors are used to format the result string of `usage()`, but
 can be disabled (see
 [`UsageOpts`](https://docs.thi.ng/umbrella/args/interfaces/UsageOpts.html)).
 
-```text
-bun index.ts --help
-
--f, --force                     Force operation
-
---bg HEX                        Background color
--c PATH, --config-path PATH     Config file path (CLI args always take
-                                precedence over those settings)
--D key=val, --define key=val    [multiple] Define dict entry
---pos N,N                       Lat/Lon
---size WxH                      Target size
--t ID, --type ID                [required] Image type: 'png', 'jpg', 'gif',
-                                'tiff'
--x JSON, --xtra JSON            Extra options
-```
-
-#### Parsing, value coercions & side effects
+### Parsing, value coercions & side effects
 
 The below invocation demonstrates how the various argument types are handled &
 represented in the result. Parsing stops with the first non-argument value (here
@@ -295,6 +329,7 @@ bun index.ts \
 #     size: Tuple { value: [640, 480] }
 #     define: { author: 'toxi', date: '2018-03-24' },
 #     xtra: { foo: [23] },
+#     verbose: false,
 #   },
 #   index: 15,
 #   rest: [ 'sourcefile.png' ],
@@ -302,6 +337,196 @@ bun index.ts \
 # }
 ```
 
+## Declarative, multi-command CLI application
+
+The following example defines a CLI app with two sub-commands: `hello` and
+`list`. Each command has its own options, in addition to common/shared ones.
+Each command is defined in a modular manner (usually in its own source file).
+All aspects like arg parsing, validation, and command selection/delegation is
+handled by the `cliApp()` wrapper.
+
+```ts tangle:export/readme-cliapp.ts
+import {
+    ARG_VERBOSE,
+    cliApp,
+    configureLogLevel,
+    int,
+    string,
+    type Command,
+    type CommandCtx,
+} from "@thi.ng/args";
+import { files } from "@thi.ng/file-io";
+
+// common command opts
+interface CommonOpts {
+    verbose: boolean;
+}
+
+// custom command context
+interface AppCtx<T extends CommonOpts> extends CommandCtx<T, CommonOpts> {
+    // plus any custom additions here...
+}
+
+// command-specific options
+interface HelloOpts extends CommonOpts {
+    name: string;
+}
+
+// command definition
+const HELLO: Command<HelloOpts, CommonOpts> = {
+    // brief description (for `--help` usage)
+    desc: "Print out a greeting",
+    // command specific options (arguments)
+    // (will be combined with common opts)
+    opts: {
+        name: string({
+            alias: "n",
+            desc: "Name for greeting",
+            optional: false,
+        }),
+    },
+    // this command does not accept any inputs
+    inputs: 0,
+    // command implementation
+    fn: async (ctx) => {
+        // log message only shown if `--verbose`/`-v` given
+        ctx.logger.debug("opts", ctx.opts);
+        console.log(`Hello, ${ctx.opts.name}!`);
+    },
+};
+
+// command-specific options
+interface ListFilesOpts extends CommonOpts {
+    depth: number;
+    filter?: string;
+}
+
+// command definition
+const LIST_FILES: Command<ListFilesOpts, CommonOpts> = {
+    // brief description (for `--help` usage)
+    desc: "List files in given dir",
+    // command specific options
+    opts: {
+        filter: string({
+            alias: "f",
+            desc: "Filter regexp",
+        }),
+        depth: int({
+            alias: "d",
+            desc: "Recursion depth (directory levels)",
+            default: Infinity,
+        }),
+    },
+    // this command requires exactly 1 input
+    // (if supporting a range, use `[min, max]`)
+    inputs: 1,
+    // command implementation
+    fn: async (ctx) => {
+        for (let f of files(ctx.inputs[0], ctx.opts.filter, ctx.opts.depth)) {
+            console.log(f);
+        }
+    },
+};
+
+// define & start CLI app
+cliApp<CommonOpts, AppCtx<any>>({
+    // app name
+    name: "example",
+    // process.argv index from which to start parsing from
+    start: 2,
+    // list common command opts here
+    opts: {
+        // re-use verbose flag arg spec preset
+        ...ARG_VERBOSE,
+    },
+    // list of commands
+    commands: {
+        hello: HELLO,
+        list: LIST_FILES,
+    },
+    // set to true if only a single command
+    // in this case the command name would NOT be required/expected
+    // single: true,
+
+    // usage opts
+    usage: {
+        // prefix/header string
+        prefix: `Example app
+===================================
+Usage: example [opts] [inputs]\n`,
+        // configure column width for param usage info
+        paramWidth: 24,
+        lineWidth: 80,
+    },
+
+    // context initialization/augmentation
+    // (called before arg parsing commences)
+    ctx: async (ctx) => {
+        configureLogLevel(ctx.logger, ctx.opts.verbose);
+        return ctx;
+    },
+});
+```
+
+Example usage (here using `bun` to launch the above CLI app, though the usage
+info is written to assume an `example` launcher/wrapper):
+
+```bash
+bun readme-cliapp.ts
+
+# Example app
+# ===================================
+# Usage: example [opts] [inputs]
+#
+# Available commands:
+#
+# hello : Print out a greeting
+# list  : List files in given dir
+#
+# -v, --verbose           Display extra information
+```
+
+```bash
+# displaying help for a sub-command
+bun readme-cliapp.ts hello --help
+
+# Example app
+# ===================================
+# Usage: example [opts] [inputs]
+#
+# Current command:
+#
+# hello : Print out a greeting
+#
+# -v, --verbose           Display extra information
+#
+# -n STR, --name STR      [required] Name for greeting
+```
+
+```bash
+# invoking `hello` sub-command (with verbose flag)
+bun readme-cliapp.ts hello --name thi.ng -v
+# [DEBUG] example: opts {"name":"thi.ng","verbose":true}
+# Hello, thi.ng!
+```
+
+```bash
+# invoking `list` sub-command
+bun readme-cliapp.ts list -d 2 -f '.js' .
+# ./dev/api.js
+# ./dev/runtime.js
+# ./dev/test/main.js
+# ./index.js
+```
+
+```bash
+# missing arg error
+bun readme-cliapp.ts hello
+# illegal argument(s): missing arg: --name
+#
+# (...additional usage output omitted for brevity)
+```
+
 ## Authors
 
 - [Karsten Schmidt](https://thi.ng)

package/cli.js

@@ -60,7 +60,7 @@ const cliApp = async (config) => {
       if (isArray(cmd.inputs)) {
         const [min, max] = cmd.inputs;
         if (num < min || num > max) {
-          err = max < Infinity ? `expected ${min}-${max} inputs` : `expected at least ${min} inputs`;
+          err = max < Infinity ? `expected ${min}-${max} inputs` : `expected at least ${min} input(s)`;
         }
       } else if (num !== cmd.inputs) {
         err = `expected ${cmd.inputs} input(s)`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/args",
-  "version": "2.10.0",
-  "description": "Declarative, functional CLI argument/options parser, value coercions, sub-commands etc.",
+  "version": "2.10.2",
+  "description": "Declarative, functional CLI argument/options parser, app framework, arg value coercions, multi/sub-commands, usage generation, error handling etc.",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -42,7 +42,7 @@
     "@thi.ng/api": "^8.12.2",
     "@thi.ng/checks": "^3.7.18",
     "@thi.ng/errors": "^2.5.42",
-    "@thi.ng/logger": "^3.1.17",
+    "@thi.ng/logger": "^3.2.0",
     "@thi.ng/strings": "^3.9.22",
     "@thi.ng/text-format": "^2.2.41"
   },
@@ -110,5 +110,5 @@
     "tag": "cli",
     "year": 2018
   },
-  "gitHead": "5bda911600ff3c98232d0382a45c60ed0bd1a380\n"
+  "gitHead": "3c3531350eec56011982583c694aeb1a2e0d0ff4\n"
 }