@thi.ng/args 2.3.32 → 2.3.34

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-04-23T07:02:17Z
+- **Last updated**: 2024-06-21T19:34:38Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,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.3.34](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@2.3.34) (2024-06-21)
+
+#### ♻️ Refactoring
+
+- rename various rest args to be more semantically meaningful ([8088a56](https://github.com/thi-ng/umbrella/commit/8088a56))
+- enforce uniform naming convention of internal functions ([56992b2](https://github.com/thi-ng/umbrella/commit/56992b2))
+
 ### [2.3.31](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@2.3.31) (2024-04-20)
 
 #### ♻️ Refactoring

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 192 standalone projects, maintained as part
+> This is one of 193 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >

package/args.js

@@ -55,7 +55,7 @@ const oneOf = (opts, spec) => ({
   desc: $desc(opts, spec.desc)
 });
 const oneOfMulti = (opts, spec) => ({
-  coerce: (xs) => xs.map(coerceOneOf(opts)),
+  coerce: (values) => values.map(coerceOneOf(opts)),
   hint: $hint("ID", spec.delim),
   multi: true,
   group: "main",

package/cli.js

@@ -18,15 +18,13 @@ const cliApp = async (config) => {
     let start = config.start ?? 2;
     if (config.single) {
       cmdID = Object.keys(config.commands)[0];
-      if (!cmdID)
-        illegalArgs("no command provided");
+      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);
+      if (!cmd) __usageAndExit(config, usageOpts);
       start++;
     }
     let parsed;
@@ -38,8 +36,7 @@ const cliApp = async (config) => {
       });
     } catch (_) {
     }
-    if (!parsed)
-      process.exit(1);
+    if (!parsed) process.exit(1);
     if (cmd.inputs !== void 0 && cmd.inputs !== parsed.rest.length) {
       process.stderr.write(`expected ${cmd.inputs || 0} input(s)
 `);
@@ -55,8 +52,7 @@ const cliApp = async (config) => {
       cmd
     );
     await cmd.fn(ctx);
-    if (config.post)
-      await config.post(ctx, cmd);
+    if (config.post) await config.post(ctx, cmd);
   } catch (e) {
     process.stderr.write(e.message + "\n\n");
     process.exit(1);

package/coerce.d.ts

@@ -2,13 +2,13 @@ import type { Fn } from "@thi.ng/api";
 import { Tuple, type KVDict, type KVMultiDict } from "./api.js";
 export declare const coerceString: (x: string) => string;
 export declare const coerceFloat: (x: string) => number;
-export declare const coerceFloats: (xs: string[]) => number[];
+export declare const coerceFloats: (values: string[]) => number[];
 export declare const coerceHexInt: (x: string) => number;
-export declare const coerceHexInts: (xs: string[]) => number[];
+export declare const coerceHexInts: (values: string[]) => number[];
 export declare const coerceInt: (x: string) => number;
-export declare const coerceInts: (xs: string[]) => number[];
+export declare const coerceInts: (values: string[]) => number[];
 export declare const coerceJson: <T>(x: string) => T;
-export declare const coerceOneOf: <K extends string>(xs: readonly K[]) => (x: string) => K;
+export declare const coerceOneOf: <K extends string>(values: readonly K[]) => (x: string) => K;
 export declare function coerceKV(delim?: string, strict?: boolean, multi?: false): Fn<string[], KVDict>;
 export declare function coerceKV(delim?: string, strict?: boolean, multi?: true): Fn<string[], KVMultiDict>;
 export declare const coerceTuple: <T>(coerce: Fn<string, T>, size: number, delim?: string) => (src: string) => Tuple<T>;

package/coerce.js

@@ -4,13 +4,13 @@ import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
 import { Tuple } from "./api.js";
 const coerceString = (x) => x;
 const coerceFloat = (x) => isNumericFloat(x) ? parseFloat(x) : illegalArgs(`not a numeric value: ${x}`);
-const coerceFloats = (xs) => xs.map(coerceFloat);
+const coerceFloats = (values) => values.map(coerceFloat);
 const coerceHexInt = (x) => isHex(x) ? parseInt(x, 16) : illegalArgs(`not a hex value: ${x}`);
-const coerceHexInts = (xs) => xs.map(coerceHexInt);
+const coerceHexInts = (values) => values.map(coerceHexInt);
 const coerceInt = (x) => isNumericInt(x) ? parseInt(x) : illegalArgs(`not an integer: ${x}`);
-const coerceInts = (xs) => xs.map(coerceInt);
+const coerceInts = (values) => values.map(coerceInt);
 const coerceJson = (x) => JSON.parse(x);
-const coerceOneOf = (xs) => (x) => xs.includes(x) ? x : illegalArgs(`invalid option: ${x}`);
+const coerceOneOf = (values) => (x) => values.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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/args",
-  "version": "2.3.32",
+  "version": "2.3.34",
   "description": "Declarative, functional & typechecked CLI argument/options parser, value coercions etc.",
   "type": "module",
   "module": "./index.js",
@@ -10,7 +10,7 @@
     "type": "git",
     "url": "https://github.com/thi-ng/umbrella.git"
   },
-  "homepage": "https://github.com/thi-ng/umbrella/tree/develop/packages/args#readme",
+  "homepage": "https://thi.ng/args",
   "funding": [
     {
       "type": "github",
@@ -36,18 +36,18 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.1",
-    "@thi.ng/checks": "^3.6.3",
-    "@thi.ng/errors": "^2.5.6",
-    "@thi.ng/logger": "^3.0.11",
-    "@thi.ng/strings": "^3.7.32",
-    "@thi.ng/text-format": "^2.2.4"
+    "@thi.ng/api": "^8.11.3",
+    "@thi.ng/checks": "^3.6.5",
+    "@thi.ng/errors": "^2.5.8",
+    "@thi.ng/logger": "^3.0.13",
+    "@thi.ng/strings": "^3.7.34",
+    "@thi.ng/text-format": "^2.2.6"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.43.0",
-    "esbuild": "^0.20.2",
-    "typedoc": "^0.25.12",
-    "typescript": "^5.4.3"
+    "@microsoft/api-extractor": "^7.47.0",
+    "esbuild": "^0.21.5",
+    "typedoc": "^0.25.13",
+    "typescript": "^5.5.2"
   },
   "keywords": [
     "argument",
@@ -103,5 +103,5 @@
   "thi.ng": {
     "year": 2018
   },
-  "gitHead": "5dd66c18a3862a3af69a5b2f49563f7cbdd960c2\n"
+  "gitHead": "154c95cf9d6bab32174498ec3b5b5d87e42be7f9\n"
 }

package/parse.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 import type { IObjectOf, Maybe } from "@thi.ng/api";
 import type { Args, ParseOpts, ParseResult } from "./api.js";
 export declare const ParseError: {
@@ -6,10 +5,10 @@ export declare const ParseError: {
         origMessage: string;
         name: string;
         message: string;
-        stack?: string | undefined;
+        stack?: string;
         cause?: unknown;
     };
-    captureStackTrace(targetObject: object, constructorOpt?: Function | undefined): void;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
     prepareStackTrace?: ((err: Error, stackTraces: NodeJS.CallSite[]) => any) | undefined;
     stackTraceLimit: number;
 };

package/parse.js

@@ -7,7 +7,7 @@ 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);
+    return __parseOpts(specs, argv, opts);
   } catch (e) {
     if (opts.showUsage) {
       console.log(
@@ -17,8 +17,8 @@ const parse = (specs, argv, opts) => {
     throw new ParseError(e.message);
   }
 };
-const parseOpts = (specs, argv, opts) => {
-  const aliases = aliasIndex(specs);
+const __parseOpts = (specs, argv, opts) => {
+  const aliases = __aliasIndex(specs);
   const acc = {};
   let id;
   let spec;
@@ -30,37 +30,34 @@ const parseOpts = (specs, argv, opts) => {
         console.log(usage(specs, opts.usageOpts));
         return;
       }
-      const state = parseKey(specs, aliases, acc, a);
+      const state = __parseKey(specs, aliases, acc, a);
       id = state.id;
       spec = state.spec;
       i = i + ~~(state.state < 2);
-      if (state.state)
-        break;
+      if (state.state) break;
     } else {
-      if (parseValue(spec, acc, id, a))
-        break;
+      if (__parseValue(spec, acc, id, a)) break;
       id = null;
       i++;
     }
   }
   id && illegalArgs(`missing value for: --${id}`);
   return {
-    result: processResults(specs, acc),
+    result: __processResults(specs, acc),
     index: i,
     rest: argv.slice(i),
     done: i >= argv.length
   };
 };
-const aliasIndex = (specs) => Object.entries(specs).reduce(
+const __aliasIndex = (specs) => Object.entries(specs).reduce(
   (acc, [k, v]) => v.alias ? (acc[v.alias] = k, acc) : acc,
   {}
 );
-const parseKey = (specs, aliases, acc, a) => {
+const __parseKey = (specs, aliases, acc, a) => {
   if (a[0] === "-") {
     let id;
     if (a[1] === "-") {
-      if (a === "--")
-        return { state: 1 };
+      if (a === "--") return { state: 1 };
       id = camel(a.substring(2));
     } else {
       id = aliases[a.substring(1)];
@@ -71,14 +68,13 @@ const parseKey = (specs, aliases, acc, a) => {
     if (spec.flag) {
       acc[id] = true;
       id = void 0;
-      if (spec.fn && !spec.fn("true"))
-        return { state: 1, spec };
+      if (spec.fn && !spec.fn("true")) return { state: 1, spec };
     }
     return { state: 0, id, spec };
   }
   return { state: 2 };
 };
-const parseValue = (spec, acc, id, a) => {
+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];
@@ -87,7 +83,7 @@ const parseValue = (spec, acc, id, a) => {
   }
   return spec.fn && !spec.fn(a);
 };
-const processResults = (specs, acc) => {
+const __processResults = (specs, acc) => {
   let spec;
   for (let id in specs) {
     spec = specs[id];
@@ -98,12 +94,12 @@ const processResults = (specs, acc) => {
         illegalArgs(`missing arg: --${id}`);
       }
     } else if (spec.coerce) {
-      coerceValue(spec, acc, id);
+      __coerceValue(spec, acc, id);
     }
   }
   return acc;
 };
-const coerceValue = (spec, acc, id) => {
+const __coerceValue = (spec, acc, id) => {
   try {
     if (spec.multi && spec.delim) {
       acc[id] = acc[id].reduce(

package/usage.js

@@ -20,7 +20,7 @@ const usage = (specs, 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, indent));
   const sortedIDs = Object.keys(specs).sort();
   const groups = opts.groups ? opts.groups.map(
     (gid) => [
@@ -29,7 +29,7 @@ const usage = (specs, opts = {}) => {
     ]
   ).filter((g) => !!g[1].length) : [["options", sortedIDs]];
   return [
-    ...wrap(opts.prefix, opts.lineWidth),
+    ...__wrap(opts.prefix, opts.lineWidth),
     ...groups.map(
       ([gid, ids]) => [
         ...opts.showGroupNames ? [`${capitalize(gid)}:
@@ -38,35 +38,35 @@ const usage = (specs, opts = {}) => {
         ""
       ].join("\n")
     ),
-    ...wrap(opts.suffix, opts.lineWidth)
+    ...__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 __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 === 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 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(
+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(
+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, {
+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