@thi.ng/args 2.3.71 → 2.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-06-09T17:24:08Z
+- **Last updated**: 2025-06-27T11:09:55Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,13 @@ 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.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@2.4.0) (2025-06-27)
+
+#### 🚀 Features
+
+- add word-wrapping for command descriptions ([46a73a3](https://github.com/thi-ng/umbrella/commit/46a73a3))
+  - refactor usage internals for better re-use
+
 ### [2.3.34](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@2.3.34) (2024-06-21)
 
 #### ♻️ Refactoring

package/README.md

@@ -27,7 +27,7 @@
 
 ## About
 
-Declarative, functional & typechecked CLI argument/options parser, value coercions etc..
+Declarative, functional CLI argument/options parser, value coercions, sub-commands etc..
 
 Includes built-in support for the following argument types (of course custom arg types are supported too):
 
@@ -71,7 +71,7 @@ For Node.js REPL:
 const args = await import("@thi.ng/args");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.75 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.80 KB
 
 ## Dependencies
 
@@ -243,7 +243,7 @@ can be disabled (see
 [`UsageOpts`](https://docs.thi.ng/umbrella/args/interfaces/UsageOpts.html)).
 
 ```text
-ts-node index.ts --help
+bun index.ts --help
 
 -f, --force                     Force operation
 
@@ -266,7 +266,7 @@ represented in the result. Parsing stops with the first non-argument value (here
 result object.
 
 ```bash
-ts-node index.ts \
+bun index.ts \
     -f -t png --bg ff00ff --size 640x480 \
     -D author=toxi -D date=2018-03-24 \
     --xtra '{"foo": [23]}' \

package/api.d.ts

@@ -227,7 +227,7 @@ export interface CLIAppConfig<OPTS extends object, CTX extends CommandCtx<OPTS,
 }
 export interface Command<OPTS extends BASE, BASE extends object, CTX extends CommandCtx<OPTS, BASE> = CommandCtx<OPTS, BASE>> {
     /**
-     * Command description (short, single line)
+     * Command description (any length, will be word wrapped if needed)
      */
     desc: string;
     /**

package/cli.js

@@ -3,7 +3,7 @@ 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";
+import { __wrapWithIndent, usage } from "./usage.js";
 const cliApp = async (config) => {
   const argv = config.argv || process.argv;
   const isColor = !process.env.NO_COLOR;
@@ -23,7 +23,10 @@ const cliApp = async (config) => {
     } else {
       cmdID = argv[start];
       cmd = config.commands[cmdID];
-      usageOpts.prefix += __descriptions(config.commands);
+      usageOpts.prefix += __descriptions(
+        config.commands,
+        config.usage.lineWidth
+      );
       if (!cmd) __usageAndExit(config, usageOpts);
       start++;
     }
@@ -62,13 +65,21 @@ 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");
+const __descriptions = (commands, lineWidth = 80) => {
+  const names = Object.keys(commands);
+  const maxLength = Math.max(...names.map((x) => x.length));
+  return [
+    "\nAvailable commands:\n",
+    ...names.map(
+      (x) => `${padRight(maxLength)(x)} : ${__wrapWithIndent(
+        commands[x].desc,
+        maxLength + 3,
+        lineWidth
+      )}`
+    ),
+    "\n"
+  ].join("\n");
+};
 export {
   cliApp
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/args",
-  "version": "2.3.71",
-  "description": "Declarative, functional & typechecked CLI argument/options parser, value coercions etc.",
+  "version": "2.4.0",
+  "description": "Declarative, functional CLI argument/options parser, value coercions, sub-commands etc.",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -107,5 +107,5 @@
     "tag": "cli",
     "year": 2018
   },
-  "gitHead": "b076434a497b291ad33e81b1a15f6a71e2c82cc2\n"
+  "gitHead": "7fa97c11435e6f616bac62b731050784694ee08d\n"
 }

package/usage.d.ts

@@ -1,4 +1,6 @@
 import type { IObjectOf } from "@thi.ng/api";
 import { type Args, type UsageOpts } from "./api.js";
 export declare const usage: <T extends IObjectOf<any>>(specs: Args<T>, opts?: Partial<UsageOpts>) => string;
+/** @internal */
+export declare const __wrapWithIndent: (body: string, indent: number, width: number) => string;
 //# sourceMappingURL=usage.d.ts.map

package/usage.js

@@ -19,8 +19,9 @@ const usage = (specs, opts = {}) => {
     ...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 format = (ids) => ids.map(
+    (id) => __argUsage(id, specs[id], opts, theme, opts.paramWidth)
+  );
   const sortedIDs = Object.keys(specs).sort();
   const groups = opts.groups ? opts.groups.map(
     (gid) => [
@@ -51,7 +52,7 @@ const __argUsage = (id, spec, opts, theme, indent) => {
   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");
+  return padRight(opts.paramWidth)(params, lengthAnsi(params)) + __wrapWithIndent(body, indent, opts.lineWidth);
 };
 const __argHint = (spec, theme) => spec.hint ? __ansi(" " + spec.hint, theme.hint) : "";
 const __argAlias = (spec, theme, hint) => spec.alias ? `${__ansi("-" + spec.alias, theme.param)}${hint}, ` : "";
@@ -71,6 +72,11 @@ const __wrap = (str, width) => str ? wordWrapLines(str, {
   splitter: SPLIT_ANSI,
   hard: false
 }) : [];
+const __wrapWithIndent = (body, indent, width) => {
+  const prefix = repeat(" ", indent);
+  return __wrap(body, width - indent).map((l, i) => i ? prefix + l : l).join("\n");
+};
 export {
+  __wrapWithIndent,
   usage
 };