@thi.ng/args 2.10.2 → 3.1.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-09-25T11:10:32Z
+- **Last updated**: 2025-09-26T13:50:05Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,34 @@ 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.
 
+## [3.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@3.1.0) (2025-09-26)
+
+#### 🚀 Features
+
+- add ARG_TYPES index ([5f68489](https://github.com/thi-ng/umbrella/commit/5f68489))
+
+#### ♻️ Refactoring
+
+- update factory fns to only take single arg (spec) ([2766125](https://github.com/thi-ng/umbrella/commit/2766125))
+  - update `oneOf`, `oneOfMulti`, `tuple`, `size`, `vec`
+  - fix `required`-handling in `ARG_OUT_DIR` & `ARG_OUT_FILE` presets
+  - fix code example for `tuple()`
+  - update tests
+
+# [3.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@3.0.0) (2025-09-26)
+
+#### 🛑 Breaking changes
+
+- update arg specs & arg factory fns, simplify types ([7ad3efb](https://github.com/thi-ng/umbrella/commit/7ad3efb))
+- BREAKING CHANGES: update arg specs & arg factory fns, simplify types
+  - add `type` field in all arg specs
+  - add/update arg-related types
+  - update required arg handling: `optional: false` => `required: true`
+  - update delimiter handling (move into arg specs)
+  - update `tuple()` arg order
+  - remove obsolete coercion fns (`coerceFloats()` etc.)
+  - update tests
+
 ## [2.10.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/args@2.10.0) (2025-09-04)
 
 #### 🚀 Features

package/README.md

@@ -19,6 +19,7 @@
   - [Re-usable argument presets](#re-usable-argument-presets)
   - [CLI app framework](#cli-app-framework)
 - [Status](#status)
+  - [Breaking changes in 3.0.0](#breaking-changes-in-300)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [Projects using this package](#projects-using-this-package)
@@ -97,6 +98,19 @@ section](#projects-using-this-package) in this readme.
 
 [Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Bargs%5D+in%3Atitle)
 
+### Breaking changes in 3.0.0
+
+- Required arguments are now to be specified using either `required: true` or
+  given a `default` value
+- All factory functions now only accept a single arg spec, with any type-specific
+  options moved into the spec, for example:
+    - old: `oneOf(["a","b","c"], {...})`
+    - new: `oneOf({ opts: ["a","b","c"], ...})`
+    - old: `tuple(identity, 3, {...})`
+    - new: `tuple({ size: 3, coerce: identity, ...})`
+- Where applicable, `delim`iters are now to be included in the arg spec (rather
+  than given as separate function arg)
+
 ## Installation
 
 ```bash
@@ -115,7 +129,7 @@ For Node.js REPL:
 const args = await import("@thi.ng/args");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 3.31 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.47 KB
 
 ## Dependencies
 
@@ -191,42 +205,51 @@ const specs: Args<TestArgs> = {
         hint: "PATH",
         desc: "Config file path (CLI args always take precedence over those settings)",
     }),
+
     // boolean flag (default: false)
     force: flag({
         alias: "f",
         desc: "Force operation",
-        // side effect & predicate
-        // parsing only continues if fn returns true
+        // side effect and/or validation
+        // parsing only continues if function returns true
         fn: (_) => (console.log("force mode enabled"), true),
     }),
+
     // hex int value
     bg: hex({
         desc: "Background color",
-        // mandatory args require a `default` value and/or `optional: false`
+        // mandatory args require a `default` value and/or `required: true`
         default: 0xffffff,
         defaultHint: "ffffff",
     }),
+
     // enum value (mandatory)
-    type: oneOf(["png", "jpg", "gif", "tiff"], {
+    type: oneOf({
         alias: "t",
         desc: "Image type",
-        // mandatory args require a `default` value and/or `optional: false`
-        optional: false,
+        opts: ["png", "jpg", "gif", "tiff"],
+        // mandatory args require a `default` value and/or `required: true`
+        required: true,
     }),
+
     // fixed size numeric tuple w/ `x` as delimiter
-    // size: tuple(coerceInt, 2, { hint: "WxH", desc: "Target size" }, "x"),
-    // syntax sugar for above:
-    size: size(2, { hint: "WxH", desc: "Target size" }),
+    size: size({ size: 2, hint: "WxH", desc: "Target size", delim: "x" }),
+    // syntax sugar for:
+    // size: tuple(2, coerceInt, { hint: "WxH", desc: "Target size" }, "x"),
+
     // another version for tuples of floating point values
-    // pos: tuple(coerceFloat, 2, { desc: "Lat/Lon" }, ","),
-    pos: vec(2, { desc: "Lat/Lon coordinates" }),
+    pos: vec({ size: 2, desc: "Lat/Lon coordinates", hint: "LAT,LON" }),
+    // syntax sugar for:
+    // pos: tuple(2, coerceFloat, { desc: "Lat/Lon" }),
+
     // JSON string arg
     xtra: json({
         alias: "x",
         desc: "Extra options",
         group: "extra",
     }),
-    // key-value pairs parsed into an object
+
+    // key-value pairs parsed into an object (multiple allowed)
     define: kvPairs({
         alias: "D",
         desc: "Define dict entry",
@@ -382,7 +405,7 @@ const HELLO: Command<HelloOpts, CommonOpts> = {
         name: string({
             alias: "n",
             desc: "Name for greeting",
-            optional: false,
+            required: true,
         }),
     },
     // this command does not accept any inputs

package/api.d.ts

@@ -1,7 +1,11 @@
-import type { Fn, Fn2, IDeref, IObjectOf } from "@thi.ng/api";
+import type { Fn, Fn2, IDeref, IObjectOf, Predicate } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import type { FormatPresets } from "@thi.ng/text-format";
 export interface ArgSpecBase {
+    /**
+     * Unique arg type ID
+     */
+    type: string;
     /**
      * Shorthand for given arg/option
      */
@@ -31,44 +35,82 @@ export interface ArgSpecBase {
      */
     group?: string;
 }
-export type ArgSpecRestrict<T> = undefined extends T ? {} : {
-    optional: false;
+export type ArgSpec<T> = ArgSpecBase & ArgSpecRequired<T>;
+export type ArgSpecRequired<T> = undefined extends T ? {
+    default?: T;
+} : {
+    required: true;
 } | {
     default: T;
 };
-export type ArgSpec<T> = ArgSpecBase & ArgSpecRestrict<T>;
+export type Args<T extends object> = {
+    [id in keyof T]: ArgSpec<T[id]>;
+};
+/**
+ * Partial arg spec given to various argument factory functions.
+ */
+export type ArgDef = Omit<ArgSpecBase, "type">;
+/**
+ * Partial arg spec (for required arguments) given to various argument factory
+ * functions.
+ */
+export type ArgDefRequired<T> = ArgDef & ({
+    default: T;
+} | {
+    required: true;
+});
+/**
+ * @internal
+ */
 export type ArgSpecExt = ArgSpec<any> & {
+    /**
+     * Value coercion fn.
+     */
     coerce?: Fn<any, any>;
+    /**
+     * Delimiter to split values (only used for `multi` args and if `split=false`)
+     */
     delim?: string;
+    /**
+     * Default value
+     */
     default?: any;
-    flag?: boolean;
-    fn?: Fn<string, boolean>;
+    /**
+     * User defined validation fn (can be used for side effects too).
+     */
+    fn?: Predicate<string>;
+    /**
+     * Indicator flag for args accepting multiple values
+     */
     multi?: boolean;
-    optional?: any;
-};
-export type Args<T extends IObjectOf<any>> = {
-    [id in keyof T]: boolean extends T[id] ? ArgSpec<T[id]> & {
-        flag: true;
-    } : any[] extends T[id] ? ArgSpec<T[id]> & {
-        coerce: Fn<string[], Exclude<T[id], undefined>>;
-        multi: true;
-        delim?: string;
-    } : KVDict extends T[id] ? ArgSpec<T[id]> & {
-        coerce: Fn<string[], Exclude<T[id], undefined>>;
-        multi: true;
-    } : KVMultiDict extends T[id] ? ArgSpec<T[id]> & {
-        coerce: Fn<string[], Exclude<T[id], undefined>>;
-        multi: true;
-    } : ArgSpec<T[id]> & {
-        coerce: Fn<string, Exclude<T[id], undefined>>;
-    };
+    /**
+     * Indicator flag for required args.
+     */
+    required?: true;
+    /**
+     * Unless false, collected values are split via `delim` prior to calling
+     * coercion function. Only used for `multi` specs.
+     */
+    split?: boolean;
 };
 export type KVDict = IObjectOf<string>;
 export type KVMultiDict = IObjectOf<string[]>;
 export interface ParseResult<T> {
+    /**
+     * Parsed arguments
+     */
     result: T;
+    /**
+     * `process.argv` index (+1) where parsing stopped
+     */
     index: number;
+    /**
+     * If true, all elements of `process.argv` have been consumed
+     */
     done: boolean;
+    /**
+     * Remaining unparsed elements of `process.argv` (if any)
+     */
     rest: string[];
 }
 export interface ParseOpts {

package/args.d.ts

@@ -1,13 +1,13 @@
 import { type Fn } from "@thi.ng/api/fn";
-import type { ArgSpec, KVDict, KVMultiDict, Tuple } from "./api.js";
+import type { ArgDef, ArgDefRequired, ArgSpec, KVDict, KVMultiDict, Tuple } from "./api.js";
 /**
  * Returns a full {@link ArgSpec} for a boolean flag. The mere presence of this
  * arg will enable the flag.
  *
  * @param spec -
  */
-export declare const flag: <S extends Partial<ArgSpec<boolean>>>(spec: S) => S & {
-    flag: true;
+export declare const flag: <S extends ArgDef>(spec: S) => S & {
+    type: "flag";
     default: boolean;
     group: string;
 };
@@ -16,7 +16,8 @@ export declare const flag: <S extends Partial<ArgSpec<boolean>>>(spec: S) => S &
  *
  * @param spec -
  */
-export declare const string: <S extends Partial<ArgSpec<string>>>(spec: S) => S & {
+export declare const string: <S extends ArgDef | ArgDefRequired<string>>(spec: S) => S & {
+    type: "string";
     coerce: Fn<string, string>;
     hint: string;
     group: string;
@@ -28,13 +29,15 @@ export declare const string: <S extends Partial<ArgSpec<string>>>(spec: S) => S
  *
  * @param spec -
  */
-export declare const strings: <S extends Partial<ArgSpec<string[]> & {
-    delim: string;
-}>>(spec: S) => S & {
-    coerce: Fn<string[], string[]>;
+export declare const strings: <S extends ArgDef | ArgDefRequired<unknown[]>>(spec: S & {
+    delim?: string;
+}) => S & {
+    type: "strings";
+    coerce: Fn<string[], unknown[]>;
     hint: string;
-    multi: true;
     group: string;
+    delim: string;
+    multi: true;
 };
 /**
  * Returns a full {@link ArgSpec} for a floating point value arg. The value
@@ -42,21 +45,28 @@ export declare const strings: <S extends Partial<ArgSpec<string[]> & {
  *
  * @param spec -
  */
-export declare const float: <S extends Partial<ArgSpec<number>>>(spec: S) => S & {
+export declare const float: <S extends ArgDef | ArgDefRequired<number>>(spec: S) => S & {
+    type: "float";
     coerce: Fn<string, number>;
     hint: string;
     group: string;
 };
 /**
- * Returns a full {@link ArgSpec} for a single hex integer value arg. The value
- * will be autoatically coerced into a number using {@link coerceHexInt}.
+ * Multi-arg version of {@link float}. Returns a full {@link ArgSpec} for a
+ * multi floating point value arg. This argument can be provided mutiple times
+ * with values being coerced into numbers and collected into an array.
  *
  * @param spec -
  */
-export declare const hex: <S extends Partial<ArgSpec<number>>>(spec: S) => S & {
-    coerce: Fn<string, number>;
+export declare const floats: <S extends ArgDef | ArgDefRequired<unknown[]>>(spec: S & {
+    delim?: string;
+}) => S & {
+    type: "floats";
+    coerce: Fn<string[], unknown[]>;
     hint: string;
     group: string;
+    delim: string;
+    multi: true;
 };
 /**
  * Returns a full {@link ArgSpec} for a single integer value arg. The value
@@ -64,66 +74,57 @@ export declare const hex: <S extends Partial<ArgSpec<number>>>(spec: S) => S & {
  *
  * @param spec -
  */
-export declare const int: <S extends Partial<ArgSpec<number>>>(spec: S) => S & {
+export declare const int: <S extends ArgDef | ArgDefRequired<number>>(spec: S) => S & {
+    type: "int";
     coerce: Fn<string, number>;
     hint: string;
     group: string;
 };
 /**
- * Multi-arg version of {@link float}. Returns a full {@link ArgSpec} for a
- * multi floating point value arg. This argument can be provided mutiple times
- * with values being coerced into numbers and collected into an array.
+ * Multi-arg version of {@link int}. Returns a full {@link ArgSpec} for a multi
+ * integer value arg. This argument can be provided mutiple times with values
+ * being coerced into numbers and collected into an array.
  *
  * @param spec -
  */
-export declare const floats: <S extends Partial<ArgSpec<number[]> & {
-    delim: string;
-}>>(spec: S) => S & {
-    coerce: Fn<string[], number[]>;
+export declare const ints: <S extends ArgDef | ArgDefRequired<unknown[]>>(spec: S & {
+    delim?: string;
+}) => S & {
+    type: "ints";
+    coerce: Fn<string[], unknown[]>;
     hint: string;
-    multi: true;
     group: string;
-};
-/**
- * Multi-arg version of {@link hex}. Returns a full {@link ArgSpec} for a multi
- * hex integer value arg. This argument can be provided mutiple times with
- * values being coerced into numbers and collected into an array.
- *
- * @param spec -
- */
-export declare const hexes: <S extends Partial<ArgSpec<number[]> & {
     delim: string;
-}>>(spec: S) => S & {
-    coerce: Fn<string[], number[]>;
-    hint: string;
     multi: true;
-    group: string;
 };
 /**
- * Multi-arg version of {@link int}. Returns a full {@link ArgSpec} for a multi
- * integer value arg. This argument can be provided mutiple times with values
- * being coerced into numbers and collected into an array.
+ * Returns a full {@link ArgSpec} for a single hex integer value arg. The value
+ * will be autoatically coerced into a number using {@link coerceHexInt}.
  *
  * @param spec -
  */
-export declare const ints: <S extends Partial<ArgSpec<number[]> & {
-    delim: string;
-}>>(spec: S) => S & {
-    coerce: Fn<string[], number[]>;
+export declare const hex: <S extends ArgDef | ArgDefRequired<number>>(spec: S) => S & {
+    type: "hex";
+    coerce: Fn<string, number>;
     hint: string;
-    multi: true;
     group: string;
 };
 /**
- * Returns full {@link ArgSpec} for a JSON value arg. The raw CLI value string
- * will be automcatically coerced using {@link coerceJson}.
+ * Multi-arg version of {@link hex}. Returns a full {@link ArgSpec} for a multi
+ * hex integer value arg. This argument can be provided mutiple times with
+ * values being coerced into numbers and collected into an array.
  *
  * @param spec -
  */
-export declare const json: <T, S extends Partial<ArgSpec<T>>>(spec: S) => S & {
-    coerce: Fn<string, T>;
+export declare const hexes: <S extends ArgDef | ArgDefRequired<unknown[]>>(spec: S & {
+    delim?: string;
+}) => S & {
+    type: "hexes";
+    coerce: Fn<string[], unknown[]>;
     hint: string;
     group: string;
+    delim: string;
+    multi: true;
 };
 /**
  * Returns full {@link ArgSpec} for an enum-like string value arg. The raw CLI
@@ -132,12 +133,15 @@ export declare const json: <T, S extends Partial<ArgSpec<T>>>(spec: S) => S & {
  * @param opts -
  * @param spec -
  */
-export declare const oneOf: <K extends string, S extends Partial<ArgSpec<K>>>(opts: readonly K[], spec: S) => S & {
+export declare const oneOf: <K extends string, S extends ArgDef | ArgDefRequired<K>>(spec: S & {
+    opts: readonly K[];
+}) => S & {
+    type: "oneOf";
     coerce: Fn<string, K>;
+    desc: string;
     hint: string;
     group: string;
-} & {
-    desc: string;
+    opts: readonly K[];
 };
 /**
  * Multi-arg version of {@link oneOf}. Returns full {@link ArgSpec} for multiple
@@ -147,15 +151,18 @@ export declare const oneOf: <K extends string, S extends Partial<ArgSpec<K>>>(op
  * @param opts -
  * @param spec -
  */
-export declare const oneOfMulti: <K extends string, S extends Partial<ArgSpec<K[]> & {
-    delim: string;
-}>>(opts: readonly K[], spec: S) => S & {
-    coerce: Fn<string[], K[]>;
+export declare const oneOfMulti: <K extends string, S extends ArgDef | ArgDefRequired<K>>(spec: S & {
+    opts: readonly K[];
+    delim?: string;
+}) => S & {
+    type: "oneOfMulti";
+    coerce: Fn<string, K>;
+    desc: string;
     hint: string;
-    multi: true;
     group: string;
-} & {
-    desc: string;
+    multi: true;
+    opts: readonly K[];
+    delim?: string;
 };
 /**
  * Returns a full {@link ArgSpec} for multiple `key=value` pair args, coerced
@@ -167,13 +174,19 @@ export declare const oneOfMulti: <K extends string, S extends Partial<ArgSpec<K[
  * is true, only full KV pairs are allowed.
  *
  * @param spec -
- * @param delim -
  */
-export declare const kvPairs: <S extends Partial<ArgSpec<KVDict>>>(spec: S, delim?: string, strict?: boolean) => S & {
+export declare const kvPairs: <S extends ArgDef | ArgDefRequired<KVDict>>(spec: S & {
+    delim?: string;
+    strict?: boolean;
+}) => S & {
+    type: "kvPairs";
     coerce: Fn<string[], KVDict>;
     hint: string;
-    multi: true;
     group: string;
+    multi: true;
+    kvDelim?: string;
+    strict?: boolean;
+    split: false;
 };
 /**
  * Like {@link kvPairs}, but coerces KV pairs into a result {@link KVMultiDict}
@@ -181,20 +194,24 @@ export declare const kvPairs: <S extends Partial<ArgSpec<KVDict>>>(spec: S, deli
  * into arrays).
  *
  * @param spec -
- * @param delim -
- * @param strict -
  */
-export declare const kvPairsMulti: <S extends Partial<ArgSpec<KVMultiDict>>>(spec: S, delim?: string, strict?: boolean) => S & {
+export declare const kvPairsMulti: <S extends ArgDef | ArgDefRequired<KVMultiDict>>(spec: S & {
+    delim?: string;
+    strict?: boolean;
+}) => S & {
+    type: "kvPairsMulti";
     coerce: Fn<string[], KVMultiDict>;
     hint: string;
-    multi: true;
     group: string;
+    multi: true;
+    delim?: string;
+    strict?: boolean;
 };
 /**
  * Returns a full {@link ArgSpec} for a fixed `size` tuple extracted from a
- * single value string. The individual values are delimited by `delim` and will
- * be coerced into their target type via `coerce`. The result tuple will be
- * wrapped in a {@link Tuple} instance.
+ * single value string. The individual values are delimited by `delim` (default:
+ * `,`) and will be coerced into their target type via `coerce`. The result
+ * tuple will be wrapped in a {@link Tuple} instance.
  *
  * @remarks
  * An error will be thrown if the number of extracted values differs from the
@@ -202,10 +219,18 @@ export declare const kvPairsMulti: <S extends Partial<ArgSpec<KVMultiDict>>>(spe
  *
  * @example
  * ```ts tangle:../export/tuple.ts
- * import { coerceInt, parse, tuple } from "@thi.ng/args";
+ * import { coerceInt, parse, tuple, type Tuple } from "@thi.ng/args";
+ *
+ * interface A {
+ *   a?: Tuple<number>;
+ * }
  *
  * console.log(
- *   parse({ a: tuple(coerceInt, 2, {})}, ["--a", "1,2"])
+ *   parse<A>(
+ *     { a: tuple({ size: 2, coerce: coerceInt }) },
+ *     ["--a", "1,2"],
+ *     { start: 0 }
+ *   )
  * );
  * // {
  * //   result: { a: Tuple { value: [1, 2] } },
@@ -215,40 +240,78 @@ export declare const kvPairsMulti: <S extends Partial<ArgSpec<KVMultiDict>>>(spe
  * // }
  * ```
  *
- * @param coerce -
- * @param size -
  * @param spec -
- * @param delim -
  */
-export declare const tuple: <T, S extends Partial<ArgSpec<Tuple<T>>>>(coerce: Fn<string, T>, size: number, spec: S, delim?: string) => S & {
+export declare const tuple: <T, S extends ArgDef | ArgDefRequired<Tuple<T>>>(spec: S & {
+    size: number;
+    coerce: Fn<string, T>;
+    delim?: string;
+}) => S & {
+    type: "tuple";
     coerce: Fn<string, Tuple<T>>;
     hint: string;
     group: string;
+    size: number;
+    delim?: string;
 };
 /**
- * Syntax sugar for `tuple(coerceInt, size, {...}, delim)`.
+ * Syntax sugar for `tuple(size, coerceInt, {...})`. See {@link tuple} for
+ * further details.
  *
- * @param size -
  * @param spec -
- * @param delim -
  */
-export declare const size: <S extends Partial<ArgSpec<Tuple<number>>>>(size: number, spec: S, delim?: string) => S & {
+export declare const size: <S extends ArgDef | ArgDefRequired<Tuple<number>>>(spec: S & {
+    size: number;
+    delim?: string;
+}) => S & {
+    coerce: (x: string) => number;
+    size: number;
+    delim?: string;
+} & {
+    type: "tuple";
     coerce: Fn<string, Tuple<number>>;
     hint: string;
     group: string;
+    size: number;
+    delim?: string;
 };
 /**
- * Syntax sugar for `tuple(coerceFloat, size, {...}, delim)`.
+ * Syntax sugar for `tuple(size, coerceFloat, {...})`. See {@link tuple} for
+ * further details.
  *
- * @param size -
  * @param spec -
- * @param delim -
  */
-export declare const vec: <S extends Partial<ArgSpec<Tuple<number>>>>(size: number, spec: S, delim?: string) => S & {
+export declare const vec: <S extends ArgDef | ArgDefRequired<Tuple<number>>>(spec: S & {
+    size: number;
+    delim?: string;
+}) => S & {
+    coerce: (x: string) => number;
+    size: number;
+    delim?: string;
+} & {
+    type: "tuple";
     coerce: Fn<string, Tuple<number>>;
     hint: string;
     group: string;
+    size: number;
+    delim?: string;
 };
+/**
+ * Returns full {@link ArgSpec} for a JSON value arg. The raw CLI value string
+ * will be automcatically coerced using {@link coerceJson}.
+ *
+ * @param spec -
+ */
+export declare const json: <T, S extends ArgDef | ArgDefRequired<T>>(spec: S) => S & {
+    type: "json";
+    coerce: Fn<string, T>;
+    hint: string;
+    group: string;
+};
+/**
+ * Index which maps arg type IDs to their factory functions
+ */
+export declare const ARG_TYPES: Record<string, Fn<any, ArgSpec<any>>>;
 /**
  * Re-usable preset arg spec for a `--dry-run` flag.
  */
@@ -256,7 +319,7 @@ export declare const ARG_DRY_RUN: {
     dryRun: {
         desc: string;
     } & {
-        flag: true;
+        type: "flag";
         default: boolean;
         group: string;
     };
@@ -269,7 +332,7 @@ export declare const ARG_QUIET: {
         alias: string;
         desc: string;
     } & {
-        flag: true;
+        type: "flag";
         default: boolean;
         group: string;
     };
@@ -282,7 +345,7 @@ export declare const ARG_VERBOSE: {
         alias: string;
         desc: string;
     } & {
-        flag: true;
+        type: "flag";
         default: boolean;
         group: string;
     };

package/args.js

@@ -2,88 +2,118 @@ import { identity } from "@thi.ng/api/fn";
 import { repeat } from "@thi.ng/strings/repeat";
 import {
   coerceFloat,
-  coerceFloats,
   coerceHexInt,
-  coerceHexInts,
   coerceInt,
-  coerceInts,
   coerceJson,
   coerceKV,
   coerceOneOf,
   coerceTuple
 } from "./coerce.js";
-const $single = (coerce, hint) => (spec) => ({
+const __desc = (opts, prefix) => `${prefix ? prefix + ": " : ""}${opts.map((x) => `"${x}"`).join(", ")}`;
+const __hint = (hint, delim) => hint + (delim ? `[${delim}..]` : "");
+const defSingle = (type, coerce, hint) => (spec) => ({
+  type,
   coerce,
   hint,
   group: "main",
   ...spec
 });
-const $multi = (coerce, hint) => (spec) => ({
-  hint: $hint(hint, spec.delim),
-  multi: true,
-  coerce,
+const defMulti = (type, coerce, hint, delim = ",") => (spec) => ({
+  type,
+  delim,
+  hint: __hint(hint, spec.delim ?? delim),
+  coerce: (x) => x.map(coerce),
   group: "main",
+  multi: true,
   ...spec
 });
-const $hint = (hint, delim) => hint + (delim ? `[${delim}..]` : "");
 const flag = (spec) => ({
-  flag: true,
-  default: false,
+  type: "flag",
   group: "flags",
+  default: false,
   ...spec
 });
-const string = $single(identity, "STR");
-const strings = $multi(identity, "STR");
-const float = $single(coerceFloat, "NUM");
-const hex = $single(coerceHexInt, "HEX");
-const int = $single(coerceInt, "INT");
-const floats = $multi(coerceFloats, "NUM");
-const hexes = $multi(coerceHexInts, "HEX");
-const ints = $multi(coerceInts, "INT");
-const json = (spec) => ({
-  coerce: coerceJson,
-  hint: "JSON",
-  group: "main",
-  ...spec
-});
-const $desc = (opts, prefix) => `${prefix ? prefix + ": " : ""}${opts.map((x) => `"${x}"`).join(", ")}`;
-const oneOf = (opts, spec) => ({
-  coerce: coerceOneOf(opts),
-  hint: "ID",
-  group: "main",
+const string = defSingle("string", identity, "STR");
+const strings = defMulti("strings", identity, "STR");
+const float = defSingle("float", coerceFloat, "NUM");
+const floats = defMulti("floats", coerceFloat, "NUM");
+const int = defSingle("int", coerceInt, "INT");
+const ints = defMulti("ints", coerceInt, "INT");
+const hex = defSingle("hex", coerceHexInt, "HEX");
+const hexes = defMulti("hexes", coerceHexInt, "HEX");
+const oneOf = (spec) => ({
   ...spec,
-  desc: $desc(opts, spec.desc)
+  type: "oneOf",
+  coerce: coerceOneOf(spec.opts),
+  hint: spec.hint ?? "ID",
+  group: spec.group ?? "main",
+  desc: __desc(spec.opts, spec.desc)
 });
-const oneOfMulti = (opts, spec) => ({
-  coerce: (values) => values.map(coerceOneOf(opts)),
-  hint: $hint("ID", spec.delim),
-  multi: true,
-  group: "main",
+const oneOfMulti = (spec) => ({
   ...spec,
-  desc: $desc(opts, spec.desc)
+  type: "oneOfMulti",
+  coerce: coerceOneOf(spec.opts),
+  hint: spec.hint ?? __hint("ID", spec.delim),
+  group: spec.group ?? "main",
+  desc: __desc(spec.opts, spec.desc),
+  multi: true
 });
-const kvPairs = (spec, delim = "=", strict) => ({
-  coerce: coerceKV(delim, strict),
-  hint: `key${delim}val`,
-  multi: true,
+const kvPairs = (spec) => {
+  if (!spec.delim) spec.delim = "=";
+  return {
+    type: "kvPairs",
+    coerce: coerceKV(spec.delim, spec.strict, false),
+    hint: `key${spec.delim}val`,
+    group: "main",
+    multi: true,
+    split: false,
+    ...spec
+  };
+};
+const kvPairsMulti = (spec) => ({
+  type: "kvPairsMulti",
+  coerce: coerceKV(spec.delim, spec.strict, true),
+  hint: `key${spec.delim}val`,
   group: "main",
-  ...spec
-});
-const kvPairsMulti = (spec, delim = "=", strict) => ({
-  coerce: coerceKV(delim, strict, true),
-  hint: `key${delim}val(s)`,
   multi: true,
-  group: "main",
   ...spec
 });
-const tuple = (coerce, size2, spec, delim = ",") => ({
-  coerce: coerceTuple(coerce, size2, delim),
-  hint: [...repeat("N", size2)].join(delim),
+const tuple = (spec) => {
+  if (!spec.delim) spec.delim = ",";
+  return {
+    ...spec,
+    type: "tuple",
+    coerce: coerceTuple(spec.coerce, spec.size, spec.delim),
+    hint: spec.hint ?? [...repeat("N", spec.size)].join(spec.delim),
+    group: spec.group ?? "main"
+  };
+};
+const size = (spec) => tuple({ ...spec, coerce: coerceInt });
+const vec = (spec) => tuple({ ...spec, coerce: coerceFloat });
+const json = (spec) => ({
+  type: "json",
+  coerce: coerceJson,
+  hint: "JSON",
   group: "main",
   ...spec
 });
-const size = (size2, spec, delim = "x") => tuple(coerceInt, size2, spec, delim);
-const vec = (size2, spec, delim = ",") => tuple(coerceFloat, size2, spec, delim);
+const ARG_TYPES = {
+  flag,
+  float,
+  floats,
+  hex,
+  hexes,
+  int,
+  ints,
+  json,
+  kvPairs,
+  kvPairsMulti,
+  oneOf,
+  oneOfMulti,
+  string,
+  strings,
+  tuple
+};
 const ARG_DRY_RUN = {
   dryRun: flag({
     desc: "Dry run (no changes applied)"
@@ -107,7 +137,7 @@ const ARG_OUT_DIR = (defaultVal, desc) => ({
     desc: "Output directory" + (desc ?? ""),
     hint: "PATH",
     default: defaultVal,
-    optional: !!defaultVal
+    required: !!defaultVal
   })
 });
 const ARG_OUT_FILE = (defaultVal, desc) => ({
@@ -116,7 +146,7 @@ const ARG_OUT_FILE = (defaultVal, desc) => ({
     desc: "Output file" + (desc ?? ""),
     hint: "PATH",
     default: defaultVal,
-    optional: !!defaultVal
+    required: !!defaultVal
   })
 });
 export {
@@ -124,6 +154,7 @@ export {
   ARG_OUT_DIR,
   ARG_OUT_FILE,
   ARG_QUIET,
+  ARG_TYPES,
   ARG_VERBOSE,
   flag,
   float,

package/coerce.d.ts

@@ -2,11 +2,8 @@ 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: (values: string[]) => number[];
 export declare const coerceHexInt: (x: string) => number;
-export declare const coerceHexInts: (values: string[]) => number[];
 export declare const coerceInt: (x: string) => number;
-export declare const coerceInts: (values: string[]) => number[];
 export declare const coerceJson: <T>(x: string) => T;
 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>;

package/coerce.js

@@ -4,11 +4,8 @@ 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 = (values) => values.map(coerceFloat);
 const coerceHexInt = (x) => isHex(x) ? parseInt(x, 16) : illegalArgs(`not a hex value: ${x}`);
-const coerceHexInts = (values) => values.map(coerceHexInt);
 const coerceInt = (x) => isNumericInt(x) ? parseInt(x) : illegalArgs(`not an integer: ${x}`);
-const coerceInts = (values) => values.map(coerceInt);
 const coerceJson = (x) => JSON.parse(x);
 const coerceOneOf = (values) => (x) => values.includes(x) ? x : illegalArgs(`invalid option: ${x}`);
 function coerceKV(delim = "=", strict = false, multi = false) {
@@ -38,11 +35,8 @@ const coerceTuple = (coerce, size, delim = ",") => (src) => {
 };
 export {
   coerceFloat,
-  coerceFloats,
   coerceHexInt,
-  coerceHexInts,
   coerceInt,
-  coerceInts,
   coerceJson,
   coerceKV,
   coerceOneOf,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/args",
-  "version": "2.10.2",
+  "version": "3.1.0",
   "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",
@@ -110,5 +110,5 @@
     "tag": "cli",
     "year": 2018
   },
-  "gitHead": "3c3531350eec56011982583c694aeb1a2e0d0ff4\n"
+  "gitHead": "d86306c5375d19fa95bc900e433d097226516b1e\n"
 }

package/parse.js

@@ -58,25 +58,23 @@ const __aliasIndex = (specs) => Object.entries(specs).reduce(
   {}
 );
 const __parseKey = (specs, aliases, acc, a) => {
-  if (a[0] === "-") {
-    let id;
-    if (a[1] === "-") {
-      if (a === "--") return { state: 1 };
-      id = camel(a.substring(2));
-    } else {
-      id = aliases[a.substring(1)];
-      !id && illegalArgs(`unknown option: ${a}`);
-    }
-    const spec = specs[id];
-    !spec && illegalArgs(id);
-    if (spec.flag) {
-      acc[id] = true;
-      id = void 0;
-      if (spec.fn && !spec.fn("true")) return { state: 1, spec };
-    }
-    return { state: 0, id, spec };
+  if (a[0] !== "-") return { state: 2 };
+  let id;
+  if (a[1] === "-") {
+    if (a.length === 2) return { state: 1 };
+    id = camel(a.substring(2));
+  } else {
+    id = aliases[a.substring(1)];
+    !id && illegalArgs(`unknown option: ${a}`);
+  }
+  const spec = specs[id];
+  !spec && illegalArgs(id);
+  if (spec.type === "flag") {
+    acc[id] = true;
+    id = void 0;
+    if (spec.fn && !spec.fn("true")) return { state: 1, spec };
   }
-  return { state: 2 };
+  return { state: 0, id, spec };
 };
 const __parseValue = (spec, acc, id, a) => {
   if (spec.multi) {
@@ -93,7 +91,7 @@ const __processResults = (specs, acc) => {
     if (acc[id] === void 0) {
       if (spec.default !== void 0) {
         acc[id] = spec.default;
-      } else if (spec.optional === false) {
+      } else if (spec.required) {
         illegalArgs(`missing arg: --${kebab(id)}`);
       }
     } else if (spec.coerce) {
@@ -104,7 +102,7 @@ const __processResults = (specs, acc) => {
 };
 const __coerceValue = (spec, acc, id) => {
   try {
-    if (spec.multi && spec.delim) {
+    if (spec.multi && spec.delim && spec.split !== false) {
       acc[id] = acc[id].reduce(
         (acc2, x) => (acc2.push(...x.split(spec.delim)), acc2),
         []

package/usage.js

@@ -48,7 +48,7 @@ const __argUsage = (id, spec, opts, theme, indent) => {
   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 isRequired = !!spec.required && spec.default === void 0;
   const prefixes = [];
   isRequired && prefixes.push("required");
   spec.multi && prefixes.push("multiple");