@thi.ng/args 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-09-26T11:53:06Z
+- **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,20 @@ 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

package/README.md

@@ -102,8 +102,12 @@ section](#projects-using-this-package) in this readme.
 
 - Required arguments are now to be specified using either `required: true` or
   given a `default` value
-- Tuple argument order has been swapped (to be more aligned with `size` and
-  `vec`) to: `tuple(size, coerce, {...})`
+- 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)
 
@@ -125,7 +129,7 @@ For Node.js REPL:
 const args = await import("@thi.ng/args");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 3.39 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.47 KB
 
 ## Dependencies
 
@@ -220,20 +224,21 @@ const specs: Args<TestArgs> = {
     }),
 
     // enum value (mandatory)
-    type: oneOf(["png", "jpg", "gif", "tiff"], {
+    type: oneOf({
         alias: "t",
         desc: "Image type",
+        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: size(2, { hint: "WxH", desc: "Target size", delim: "x" }),
+    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: vec(2, { desc: "Lat/Lon coordinates", hint: "LAT,LON" }),
+    pos: vec({ size: 2, desc: "Lat/Lon coordinates", hint: "LAT,LON" }),
     // syntax sugar for:
     // pos: tuple(2, coerceFloat, { desc: "Lat/Lon" }),
 

package/args.d.ts

@@ -1,5 +1,5 @@
 import { type Fn } from "@thi.ng/api/fn";
-import type { ArgDef, ArgDefRequired, 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.
@@ -133,7 +133,9 @@ export declare const hexes: <S extends ArgDef | ArgDefRequired<unknown[]>>(spec:
  * @param opts -
  * @param spec -
  */
-export declare const oneOf: <K extends string, S extends ArgDef | ArgDefRequired<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;
@@ -149,7 +151,8 @@ export declare const oneOf: <K extends string, S extends ArgDef | ArgDefRequired
  * @param opts -
  * @param spec -
  */
-export declare const oneOfMulti: <K extends string, S extends ArgDef | ArgDefRequired<K>>(opts: readonly K[], spec: S & {
+export declare const oneOfMulti: <K extends string, S extends ArgDef | ArgDefRequired<K>>(spec: S & {
+    opts: readonly K[];
     delim?: string;
 }) => S & {
     type: "oneOfMulti";
@@ -216,10 +219,18 @@ export declare const kvPairsMulti: <S extends ArgDef | ArgDefRequired<KVMultiDic
  *
  * @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(2, coerceInt, {})}, ["--a", "1,2"])
+ *   parse<A>(
+ *     { a: tuple({ size: 2, coerce: coerceInt }) },
+ *     ["--a", "1,2"],
+ *     { start: 0 }
+ *   )
  * );
  * // {
  * //   result: { a: Tuple { value: [1, 2] } },
@@ -229,11 +240,11 @@ export declare const kvPairsMulti: <S extends ArgDef | ArgDefRequired<KVMultiDic
  * // }
  * ```
  *
- * @param size -
- * @param coerce -
  * @param spec -
  */
-export declare const tuple: <T, S extends ArgDef | ArgDefRequired<Tuple<T>>>(size: number, coerce: Fn<string, T>, spec: 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";
@@ -247,12 +258,16 @@ export declare const tuple: <T, S extends ArgDef | ArgDefRequired<Tuple<T>>>(siz
  * Syntax sugar for `tuple(size, coerceInt, {...})`. See {@link tuple} for
  * further details.
  *
- * @param size -
  * @param spec -
  */
-export declare const size: <S extends ArgDef | ArgDefRequired<Tuple<number>>>(size: number, spec: 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;
@@ -264,12 +279,16 @@ export declare const size: <S extends ArgDef | ArgDefRequired<Tuple<number>>>(si
  * Syntax sugar for `tuple(size, coerceFloat, {...})`. See {@link tuple} for
  * further details.
  *
- * @param size -
  * @param spec -
  */
-export declare const vec: <S extends ArgDef | ArgDefRequired<Tuple<number>>>(size: number, spec: 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;
@@ -289,6 +308,10 @@ export declare const json: <T, S extends ArgDef | ArgDefRequired<T>>(spec: S) =>
     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.
  */

package/args.js

@@ -41,24 +41,22 @@ 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 = (opts, spec) => ({
+const oneOf = (spec) => ({
   ...spec,
   type: "oneOf",
-  coerce: coerceOneOf(opts),
+  coerce: coerceOneOf(spec.opts),
   hint: spec.hint ?? "ID",
-  desc: __desc(opts, spec.desc),
   group: spec.group ?? "main",
-  opts
+  desc: __desc(spec.opts, spec.desc)
 });
-const oneOfMulti = (opts, spec) => ({
+const oneOfMulti = (spec) => ({
   ...spec,
   type: "oneOfMulti",
-  coerce: coerceOneOf(opts),
+  coerce: coerceOneOf(spec.opts),
   hint: spec.hint ?? __hint("ID", spec.delim),
-  desc: __desc(opts, spec.desc),
   group: spec.group ?? "main",
-  multi: true,
-  opts
+  desc: __desc(spec.opts, spec.desc),
+  multi: true
 });
 const kvPairs = (spec) => {
   if (!spec.delim) spec.delim = "=";
@@ -80,19 +78,18 @@ const kvPairsMulti = (spec) => ({
   multi: true,
   ...spec
 });
-const tuple = (size2, coerce, spec) => {
+const tuple = (spec) => {
   if (!spec.delim) spec.delim = ",";
   return {
+    ...spec,
     type: "tuple",
-    hint: [...repeat("N", size2)].join(spec.delim),
-    coerce: coerceTuple(coerce, size2, spec.delim),
-    group: "main",
-    size: size2,
-    ...spec
+    coerce: coerceTuple(spec.coerce, spec.size, spec.delim),
+    hint: spec.hint ?? [...repeat("N", spec.size)].join(spec.delim),
+    group: spec.group ?? "main"
   };
 };
-const size = (size2, spec) => tuple(size2, coerceInt, spec);
-const vec = (size2, spec) => tuple(size2, coerceInt, spec);
+const size = (spec) => tuple({ ...spec, coerce: coerceInt });
+const vec = (spec) => tuple({ ...spec, coerce: coerceFloat });
 const json = (spec) => ({
   type: "json",
   coerce: coerceJson,
@@ -100,6 +97,23 @@ const json = (spec) => ({
   group: "main",
   ...spec
 });
+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)"
@@ -123,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) => ({
@@ -132,7 +146,7 @@ const ARG_OUT_FILE = (defaultVal, desc) => ({
     desc: "Output file" + (desc ?? ""),
     hint: "PATH",
     default: defaultVal,
-    optional: !!defaultVal
+    required: !!defaultVal
   })
 });
 export {
@@ -140,6 +154,7 @@ export {
   ARG_OUT_DIR,
   ARG_OUT_FILE,
   ARG_QUIET,
+  ARG_TYPES,
   ARG_VERBOSE,
   flag,
   float,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/args",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "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",
@@ -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.2.0",
+    "@thi.ng/logger": "^3.2.1",
     "@thi.ng/strings": "^3.9.22",
     "@thi.ng/text-format": "^2.2.41"
   },
@@ -110,5 +110,5 @@
     "tag": "cli",
     "year": 2018
   },
-  "gitHead": "f3fa7a4798132f2faf9eb1ef12d99b9ca2148ec3\n"
+  "gitHead": "fbf4b46ba8a5ecff8c5423f4c2d158d208d20fc8\n"
 }