@thi.ng/args 2.3.71 → 2.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-06-09T17:24:08Z
+- **Last updated**: 2025-06-27T13:16:16Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,23 @@ 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.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@2.5.0) (2025-06-27)
+
+#### 🚀 Features
+
+- update ColorTheme, add color support for cmd list ([75b1ef1](https://github.com/thi-ng/umbrella/commit/75b1ef1))
+  - add `ColorTheme.command` option
+  - migrate internal formatting helpers to own file
+  - refactor cliApp() & usage() internals
+- add thi.ng logo header tpl ([838e417](https://github.com/thi-ng/umbrella/commit/838e417))
+
+## [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

@@ -164,6 +164,7 @@ export interface UsageOpts {
  */
 export interface ColorTheme {
     default: number;
+    command: number;
     hint: number;
     multi: number;
     param: number;
@@ -227,7 +228,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/api.js

@@ -1,5 +1,6 @@
 const DEFAULT_THEME = {
   default: 95,
+  command: 92,
   hint: 90,
   multi: 90,
   param: 96,

package/cli.js

@@ -1,9 +1,14 @@
 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";
+import {
+  __ansi,
+  __colorTheme,
+  __padRightAnsi,
+  __wrapWithIndent
+} from "./utils.js";
 const cliApp = async (config) => {
   const argv = config.argv || process.argv;
   const isColor = !process.env.NO_COLOR;
@@ -23,7 +28,7 @@ const cliApp = async (config) => {
     } else {
       cmdID = argv[start];
       cmd = config.commands[cmdID];
-      usageOpts.prefix += __descriptions(config.commands);
+      usageOpts.prefix += __descriptions(config.commands, usageOpts);
       if (!cmd) __usageAndExit(config, usageOpts);
       start++;
     }
@@ -62,13 +67,25 @@ 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, { color, lineWidth = 80 } = {}) => {
+  const names = Object.keys(commands);
+  const maxLength = Math.max(...names.map((x) => x.length));
+  const theme = __colorTheme(color);
+  return [
+    "\nAvailable commands:\n",
+    ...names.map(
+      (x) => `${__padRightAnsi(
+        __ansi(x, theme.command),
+        maxLength
+      )} : ${__wrapWithIndent(
+        commands[x].desc,
+        maxLength + 3,
+        lineWidth
+      )}`
+    ),
+    "\n"
+  ].join("\n");
+};
 export {
   cliApp
 };

package/header.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-usable logo header for various thi.ng CLI tools.
+ *
+ * @param name
+ * @param version
+ * @param desc
+ *
+ * @internal
+ */
+export declare const THING_HEADER: (name: string, version: string, desc: string) => string;
+//# sourceMappingURL=header.d.ts.map

package/header.js

@@ -0,0 +1,10 @@
+const THING_HEADER = (name, version, desc) => `
+ \u2588 \u2588   \u2588           \u2502
+\u2588\u2588 \u2588               \u2502
+ \u2588 \u2588 \u2588 \u2588   \u2588 \u2588 \u2588 \u2588 \u2502 ${name} v${version}
+ \u2588 \u2588 \u2588 \u2588 \u2588 \u2588 \u2588 \u2588 \u2588 \u2502 ${desc}
+                 \u2588 \u2502
+               \u2588 \u2588 \u2502`;
+export {
+  THING_HEADER
+};

package/index.d.ts

@@ -2,6 +2,7 @@ export * from "./api.js";
 export * from "./args.js";
 export * from "./cli.js";
 export * from "./coerce.js";
+export * from "./header.js";
 export * from "./parse.js";
 export * from "./usage.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

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

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.5.0",
+  "description": "Declarative, functional CLI argument/options parser, value coercions, sub-commands etc.",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -96,6 +96,9 @@
     "./coerce": {
       "default": "./coerce.js"
     },
+    "./header": {
+      "default": "./header.js"
+    },
     "./parse": {
       "default": "./parse.js"
     },
@@ -107,5 +110,5 @@
     "tag": "cli",
     "year": 2018
   },
-  "gitHead": "b076434a497b291ad33e81b1a15f6a71e2c82cc2\n"
+  "gitHead": "71294b20c04b6ee35db08d30b43b292b07af0d1b\n"
 }

package/usage.js

@@ -1,13 +1,14 @@
-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";
+import {
+  __ansi,
+  __colorTheme,
+  __padRightAnsi,
+  __wrap,
+  __wrapWithIndent
+} from "./utils.js";
 const usage = (specs, opts = {}) => {
   opts = {
     lineWidth: 80,
@@ -18,9 +19,10 @@ const usage = (specs, opts = {}) => {
     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 theme = __colorTheme(opts.color);
+  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 +53,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 __padRightAnsi(params, opts.paramWidth) + __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}, ` : "";
@@ -65,12 +67,6 @@ const __argDefault = (spec, opts, theme) => opts.showDefaults && 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: false
-}) : [];
 export {
   usage
 };

package/utils.d.ts

@@ -0,0 +1,13 @@
+import type { Maybe } from "@thi.ng/api";
+import { type ColorTheme } from "./api.js";
+/** @internal */
+export declare const __ansi: (x: string, col: number) => string;
+/** @internal */
+export declare const __padRightAnsi: (x: string, width: number) => string;
+/** @internal */
+export declare const __wrap: (str: Maybe<string>, width: number) => import("@thi.ng/strings/word-wrap").Line[];
+/** @internal */
+export declare const __wrapWithIndent: (body: string, indent: number, width: number) => string;
+/** @internal */
+export declare const __colorTheme: (color?: boolean | Partial<ColorTheme>) => ColorTheme;
+//# sourceMappingURL=utils.d.ts.map

package/utils.js

@@ -0,0 +1,25 @@
+import { isPlainObject } from "@thi.ng/checks/is-plain-object";
+import { repeat } from "@thi.ng/strings/repeat";
+import { SPLIT_ANSI, wordWrapLines } from "@thi.ng/strings/word-wrap";
+import { DEFAULT_THEME } from "./api.js";
+import { lengthAnsi } from "@thi.ng/strings/ansi";
+import { padRight } from "@thi.ng/strings/pad-right";
+const __ansi = (x, col) => col != null ? `\x1B[${col}m${x}\x1B[0m` : x;
+const __padRightAnsi = (x, width) => padRight(width)(x, lengthAnsi(x));
+const __wrap = (str, width) => str ? wordWrapLines(str, {
+  width,
+  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");
+};
+const __colorTheme = (color) => isPlainObject(color) ? { ...DEFAULT_THEME, ...color } : color ? DEFAULT_THEME : {};
+export {
+  __ansi,
+  __colorTheme,
+  __padRightAnsi,
+  __wrap,
+  __wrapWithIndent
+};