cli-kiss 0.2.8 → 0.2.9

package/src/lib/Type.ts

@@ -12,9 +12,20 @@ import {
  * Decodes a raw CLI string into a typed value.
  * A pair of a human-readable `content` name and a `decoder` function.
  *
- * Built-in: {@link type}, {@link typeBoolean}, {@link typeNumber},
- * {@link typeInteger}, {@link typeDatetime}, {@link typeUrl}.
- * Composite: {@link typeChoice}, {@link typeConverted}, {@link typeTuple}, {@link typeList}.
+ * Primitive Types:
+ * - {@link typeString}
+ * - {@link typeBoolean}
+ * - {@link typeNumber},
+ * - {@link typeInteger}
+ * - {@link typeDatetime}
+ * - {@link typeUrl}
+ * - {@link typePath}
+ * - {@link typeChoice}
+ *
+ * Composed Types:
+ * - {@link typeMapped}
+ * - {@link typeTuple}
+ * - {@link typeList}
  *
  * @typeParam Value - Type produced by the decoder.
  */
@@ -33,6 +44,22 @@ export type Type<Value> = {
   decoder(input: string): Value;
 };
 
+/**
+ * A named type that accepts any string as input.
+ * @param name - Name shown in help and errors (e.g. `"my-value"`).
+ * @example
+ * ```ts
+ * typeString("greeting").decoder("hello") // → "hello"
+ * typeString("greeting").decoder("")      // → ""
+ * ```
+ */
+export function typeString(name?: string): Type<string> {
+  return {
+    content: name ?? "string",
+    decoder: (input: string) => input,
+  };
+}
+
 /**
  * Decodes a string to `boolean` (case-insensitive).
  * Used by {@link optionFlag} for `--flag=<value>`.
@@ -41,10 +68,11 @@ export type Type<Value> = {
  * ```ts
  * typeBoolean("flag").decoder("true")  // → true
  * typeBoolean("flag").decoder("yes")   // → true
- * typeBoolean("flag").decoder("y")     // → true
- * typeBoolean("flag").decoder("false") // → false
- * typeBoolean("flag").decoder("no")    // → false
+ * typeBoolean("flag").decoder("Y")     // → true
+ * typeBoolean("flag").decoder("FALSE") // → false
+ * typeBoolean("flag").decoder("NO")    // → false
  * typeBoolean("flag").decoder("n")     // → false
+ * typeBoolean("flag").decoder("maybe") // throws
  * ```
  */
 export function typeBoolean(name?: string): Type<boolean> {
@@ -62,36 +90,6 @@ export function typeBoolean(name?: string): Type<boolean> {
     },
   };
 }
-const typeBooleanValuesTrue = new Set(["true", "yes", "on", "y"]);
-const typeBooleanValuesFalse = new Set(["false", "no", "off", "n"]);
-
-/**
- * Parses a date/time string via `Date.parse`.
- * Accepts any format supported by `Date.parse`, including ISO 8601.
- *
- * @example
- * ```ts
- * typeDatetime("my-datetime").decoder("2024-01-15") // → Date object for 2024-01-15
- * typeDatetime("my-datetime").decoder("2024-01-15T13:45:30Z") // → Date object for 2024-01-15 13:45:30 UTC
- * typeDatetime("my-datetime").decoder("not a date") // throws TypoError
- * ```
- */
-export function typeDatetime(name?: string): Type<Date> {
-  return {
-    content: name ?? "datetime",
-    decoder(input: string) {
-      try {
-        const timestampMs = Date.parse(input);
-        if (isNaN(timestampMs)) {
-          throw new Error();
-        }
-        return new Date(timestampMs);
-      } catch {
-        throwInvalidValue("a valid ISO_8601 datetime", input);
-      }
-    },
-  };
-}
 
 /**
  * Parses a string to `number` via `Number()`; `NaN` throws.
@@ -145,118 +143,68 @@ export function typeInteger(name?: string): Type<bigint> {
 }
 
 /**
- * Parses an absolute URL string to a `URL` object.
- * Relative or malformed URLs throws.
+ * Parses a date/time string via `Date.parse`.
+ * Accepts any format supported by `Date.parse`, including ISO 8601.
  *
  * @example
  * ```ts
- * typeUrl("my-url").decoder("https://example.com") // → URL { href: "https://example.com/", ... }
- * typeUrl("my-url").decoder("not-a-url")           // throws
+ * typeDatetime("start").decoder("2024-01-15") // → Date object for 2024-01-15
+ * typeDatetime("start").decoder("2024-01-15T13:45:30Z") // → Date object for 2024-01-15 13:45:30 UTC
+ * typeDatetime("start").decoder("not a date") // throws
  * ```
  */
-export function typeUrl(name?: string): Type<URL> {
+export function typeDatetime(name?: string): Type<Date> {
   return {
-    content: name ?? "url",
+    content: name ?? "datetime",
     decoder(input: string) {
       try {
-        return new URL(input);
+        const timestampMs = Date.parse(input);
+        if (isNaN(timestampMs)) {
+          throw new Error();
+        }
+        return new Date(timestampMs);
       } catch {
-        throwInvalidValue("an URL", input);
+        throwInvalidValue("a valid ISO_8601 datetime", input);
       }
     },
   };
 }
 
 /**
- * A named type that accepts any string as input.
- * @param name - Name shown in help and errors (e.g. `"my-value"`).
- * @example
- * ```ts
- * type("greeting").decoder("hello") // → "hello"
- * type("greeting").decoder("")      // → ""
- * ```
- */
-export function type(name?: string): Type<string> {
-  return {
-    content: name ?? "string",
-    decoder: (input: string) => input,
-  };
-}
-
-/**
- * Chains `before`'s decoder with an `after` transformation.
- * `before` errors are prefixed with `"from: <content>"` for traceability.
- *
- * @typeParam Before - Intermediate type from `before.decoder`.
- * @typeParam After - Final type from `after.decoder`.
- *
- * @param name - Name shown in help and errors (e.g. `"my-value"`).
- * @param before - Base type to decode the raw string.
- * @param mapper - Transforms `before`'s output to the final value; errors are wrapped with context.
- * @returns A {@link Type}`<After>`.
+ * Parses an absolute URL string to a `URL` object.
+ * Relative or malformed URLs throws.
  *
  * @example
  * ```ts
- * const typePort = typeConverted("port", typeNumber(), (n) => {
- *   if (n < 1 || n > 65535) throw new Error("Out of range");
- *   return n;
- * });
- * // "--port 8080"   →  8080
- * // "--port 99999"  →  TypoError: --port: <PORT>: Port: Out of range
+ * typeUrl("my-url").decoder("https://example.com") // → URL { href: "https://example.com/", ... }
+ * typeUrl("my-url").decoder("not-a-url")           // throws
  * ```
  */
-export function typeConverted<Before, After>(
-  name: string,
-  before: Type<Before>,
-  mapper: (value: Before) => After,
-): Type<After> {
-  return {
-    content: name,
-    decoder: (input: string) => {
-      return mapper(
-        TypoError.tryWithContext(
-          () => before.decoder(input),
-          () =>
-            new TypoText(
-              new TypoString("from: "),
-              new TypoString(before.content, typoStyleLogic),
-            ),
-        ),
-      );
-    },
-  };
-}
-
-/**
- * Adds a name to a {@link Type} for clearer error messages and help text.
- *
- * @param name - Name to use for the type.
- * @param type - Base type to name.
- * @returns A {@link Type} with the given name.
- */
-export function typeRenamed<Value>(
-  type: Type<Value>,
-  name: string,
-): Type<Value> {
+export function typeUrl(name?: string): Type<URL> {
   return {
-    content: name,
-    decoder: (input: string) => {
-      return TypoError.tryWithContext(
-        () => type.decoder(input),
-        () =>
-          new TypoText(
-            new TypoString("from: "),
-            new TypoString(type.content, typoStyleLogic),
-          ),
-      );
+    content: name ?? "url",
+    decoder(input: string) {
+      try {
+        return new URL(input);
+      } catch {
+        throwInvalidValue("an URL", input);
+      }
     },
   };
 }
 
 /**
  * Creates a {@link Type} for filesystem paths with optional existence checks.
+ *
  * @param checks - Optional checks for path existence and type (file/directory).
  * @returns A {@link Type}`<string>` representing the path.
+ *
+ * @example
+ * ```ts
+ * const typeInputFile = typePath("input-file", { checkSyncExistAs: "file" });
+ * typeInputFile.decoder("data.txt"); // → "data.txt" if it exists and is a file, otherwise throws
+ * typeInputFile.decoder("somedir");  // throws if "somedir" exists and is a directory
+ * ```
  */
 export function typePath(
   name?: string,
@@ -365,6 +313,78 @@ export function typeChoice<const Value extends string>(
   };
 }
 
+/**
+ * Chains `before`'s decoder with an `after` transformation.
+ * `before` errors are prefixed with `"from: <content>"` for traceability.
+ *
+ * @typeParam Before - Intermediate type from `before.decoder`.
+ * @typeParam After - Final type from `after.decoder`.
+ *
+ * @param name - Name shown in help and errors (e.g. `"my-value"`).
+ * @param before - Base type to decode the raw string.
+ * @param mapper - Transforms `before`'s output to the final value; errors are wrapped with context.
+ * @returns A {@link Type}`<After>`.
+ *
+ * @example
+ * ```ts
+ * const typePort = typeMapped("port", typeNumber(), (n) => {
+ *   if (n < 1 || n > 65535) {
+ *     throw new Error("Out of range");
+ *   }
+ *   return n;
+ * });
+ * typePort.decoder("8080");  // → 8080
+ * typePort.decoder("70000"); // throws
+ * ```
+ */
+export function typeMapped<Before, After>(
+  name: string,
+  before: Type<Before>,
+  mapper: (value: Before) => After,
+): Type<After> {
+  return {
+    content: name,
+    decoder: (input: string) => {
+      return mapper(
+        TypoError.tryWithContext(
+          () => before.decoder(input),
+          () =>
+            new TypoText(
+              new TypoString("from: "),
+              new TypoString(before.content, typoStyleLogic),
+            ),
+        ),
+      );
+    },
+  };
+}
+
+/**
+ * Adds a name to a {@link Type} for clearer error messages and help text.
+ *
+ * @param name - Name to use for the type.
+ * @param type - Base type to name.
+ * @returns A {@link Type} with the given name.
+ */
+export function typeRenamed<Value>(
+  type: Type<Value>,
+  name: string,
+): Type<Value> {
+  return {
+    content: name,
+    decoder: (input: string) => {
+      return TypoError.tryWithContext(
+        () => type.decoder(input),
+        () =>
+          new TypoText(
+            new TypoString("from: "),
+            new TypoString(type.content, typoStyleLogic),
+          ),
+      );
+    },
+  };
+}
+
 /**
  * Splits a delimited string into a typed tuple.
  * Each part is decoded by the corresponding element type; wrong count or decode failure throws.
@@ -436,7 +456,9 @@ export function typeTuple<const Elements extends Array<any>>(
  * typeNumbers.decoder("1,2,3")  // → [1, 2, 3]
  * typeNumbers.decoder("1,x,3")  // throws
  * const typePaths = typeList(typePath(), ":");
- * typePaths.decoder("/usr/bin:/usr/local/bin") // → ["/usr/bin", "/usr/local/bin"]
+ * typePaths.decoder("/bin:/usr") // → ["/bin", "/usr"]
+ * typePaths.decoder("/usr/bin")  // → ["/usr/bin"]
+ * typePaths.decoder("")          // → throws
  * ```
  */
 export function typeList<Value>(
@@ -470,3 +492,6 @@ function throwInvalidValue(kind: string, input: string): never {
     ),
   );
 }
+
+const typeBooleanValuesTrue = new Set(["true", "yes", "on", "y"]);
+const typeBooleanValuesFalse = new Set(["false", "no", "off", "n"]);

package/src/lib/Typo.ts

@@ -402,7 +402,7 @@ export class TypoSupport {
       return TypoSupport.tty();
     }
     if (envForceColor === "3") {
-      return TypoSupport.tty(); // TODO - should there be fancy colors possible?
+      return TypoSupport.tty();
     }
     if (envForceColor) {
       return TypoSupport.tty();

package/tests/unit.Reader.commons.ts

@@ -1,9 +1,5 @@
 import { expect, it } from "@jest/globals";
-import {
-  ReaderArgs,
-  ReaderOptionNextGuard,
-  ReaderOptionRestGuard,
-} from "../src";
+import { ReaderArgs, ReaderOptionNextGuard } from "../src";
 
 it("run", async function () {
   const stream = new ReaderArgs([
@@ -78,59 +74,59 @@ it("run", async function () {
 
   const kA = stream.registerOptionShort({
     key: "a",
-    restGuard: optionFlagRestGuard,
     nextGuard: optionFlagNextGuard,
+    consumeGroupRestAsValue: false,
   });
   const kB = stream.registerOptionShort({
     key: "b",
-    restGuard: optionValuedRestGuard,
     nextGuard: optionValuedNextGuard,
+    consumeGroupRestAsValue: true,
   });
 
   const kC = stream.registerOptionShort({
     key: "c",
-    restGuard: optionFlagRestGuard,
     nextGuard: optionFlagNextGuard,
+    consumeGroupRestAsValue: false,
   });
   const kD = stream.registerOptionShort({
     key: "d",
-    restGuard: optionValuedRestGuard,
     nextGuard: optionValuedNextGuard,
+    consumeGroupRestAsValue: true,
   });
 
   const kE = stream.registerOptionShort({
     key: "e",
-    restGuard: optionFlagRestGuard,
     nextGuard: optionFlagNextGuard,
+    consumeGroupRestAsValue: false,
   });
   const kF = stream.registerOptionShort({
     key: "f",
-    restGuard: optionValuedRestGuard,
     nextGuard: optionValuedNextGuard,
+    consumeGroupRestAsValue: true,
   });
 
   expect(stream.consumePositional()).toStrictEqual("positional-2");
 
   const kG = stream.registerOptionShort({
     key: "g",
-    restGuard: optionFlagRestGuard,
     nextGuard: optionFlagNextGuard,
+    consumeGroupRestAsValue: false,
   });
   const kH = stream.registerOptionShort({
     key: "h",
-    restGuard: optionValuedRestGuard,
     nextGuard: optionValuedNextGuard,
+    consumeGroupRestAsValue: true,
   });
 
   const kI = stream.registerOptionShort({
     key: "i",
-    restGuard: optionFlagRestGuard,
     nextGuard: optionFlagNextGuard,
+    consumeGroupRestAsValue: false,
   });
   const kJ = stream.registerOptionShort({
     key: "j",
-    restGuard: optionValuedRestGuard,
     nextGuard: optionValuedNextGuard,
+    consumeGroupRestAsValue: true,
   });
 
   expect(stream.consumePositional()).toStrictEqual("positional-3");
@@ -141,56 +137,47 @@ it("run", async function () {
   expect(stream.consumePositional()).toStrictEqual("positional-4");
   expect(stream.consumePositional()).toStrictEqual(undefined);
 
-  expect(kFlagUnset().values).toStrictEqual([]);
-  expect(kFlagNo().values).toStrictEqual([{ inlined: null, separated: [] }]);
-  expect(kFlagNormal().values).toStrictEqual([
-    { inlined: null, separated: [] },
-  ]);
-  expect(kFlagPositive().values).toStrictEqual([
-    { inlined: "true", separated: [] },
-  ]);
-  expect(kFlagNegative().values).toStrictEqual([
-    { inlined: "false", separated: [] },
-  ]);
+  expect(kFlagUnset()).toStrictEqual([]);
+  expect(kFlagNo()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kFlagNormal()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kFlagPositive()).toStrictEqual([{ inlined: "true", separated: [] }]);
+  expect(kFlagNegative()).toStrictEqual([{ inlined: "false", separated: [] }]);
 
-  expect(kOptionUnset().values).toStrictEqual([]);
-  expect(kOptionSplit().values).toStrictEqual([
+  expect(kOptionUnset()).toStrictEqual([]);
+  expect(kOptionSplit()).toStrictEqual([
     { inlined: null, separated: ["1.1"] },
     { inlined: null, separated: ["1.2"] },
   ]);
-  expect(kOptionJoin().values).toStrictEqual([
+  expect(kOptionJoin()).toStrictEqual([
     { inlined: "2.1", separated: [] },
     { inlined: "2.2", separated: [] },
   ]);
 
-  expect(kA().values).toStrictEqual([{ inlined: null, separated: [] }]);
-  expect(kB().values).toStrictEqual([
+  expect(kA()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kB()).toStrictEqual([
     { inlined: null, separated: ["3.1"] },
     { inlined: null, separated: ["3.2"] },
   ]);
 
-  expect(kC().values).toStrictEqual([{ inlined: null, separated: [] }]);
-  expect(kD().values).toStrictEqual([
+  expect(kC()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kD()).toStrictEqual([
     { inlined: "4.1", separated: [] },
     { inlined: "4.2", separated: [] },
   ]);
 
-  expect(kE().values).toStrictEqual([{ inlined: null, separated: [] }]);
-  expect(kF().values).toStrictEqual([
+  expect(kE()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kF()).toStrictEqual([
     { inlined: "5.1", separated: [] },
     { inlined: "5.2", separated: [] },
   ]);
 
-  expect(kG().values).toStrictEqual([{ inlined: null, separated: [] }]);
-  expect(kH().values).toStrictEqual([{ inlined: "FALSE", separated: [] }]);
+  expect(kG()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kH()).toStrictEqual([{ inlined: "FALSE", separated: [] }]);
 
-  expect(kI().values).toStrictEqual([{ inlined: null, separated: [] }]);
-  expect(kJ().values).toStrictEqual([{ inlined: "TRUE", separated: [] }]);
+  expect(kI()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kJ()).toStrictEqual([{ inlined: "TRUE", separated: [] }]);
 });
 
-const optionFlagRestGuard: ReaderOptionRestGuard = () => false;
 const optionFlagNextGuard: ReaderOptionNextGuard = () => false;
-
-const optionValuedRestGuard: ReaderOptionRestGuard = () => true;
 const optionValuedNextGuard: ReaderOptionNextGuard = (value) =>
   value.inlined === null && value.separated.length === 0;

package/tests/unit.Reader.parsings.ts

@@ -11,7 +11,7 @@ it("run", async function () {
   });
   expect(readerArgs1.consumePositional()).toStrictEqual("C");
   expect(readerArgs1.consumePositional()).toStrictEqual(undefined);
-  expect(kOptionVariadicStop().values).toStrictEqual([
+  expect(kOptionVariadicStop()).toStrictEqual([
     { inlined: "1", separated: ["A", "B", "STOP"] },
   ]);
 
@@ -21,7 +21,7 @@ it("run", async function () {
     nextGuard: (_value, nextArg) => nextArg !== undefined,
   });
   expect(readerArgs2.consumePositional()).toStrictEqual(undefined);
-  expect(kOptionVariadicFull().values).toStrictEqual([
+  expect(kOptionVariadicFull()).toStrictEqual([
     { inlined: "1", separated: ["A", "B", "C"] },
   ]);
 
@@ -31,7 +31,7 @@ it("run", async function () {
     nextGuard: (value) => value.separated.length < Number(value.inlined ?? "0"),
   });
   expect(readerArgs3.consumePositional()).toStrictEqual(undefined);
-  expect(kOptionVariadicKeyed().values).toStrictEqual([
+  expect(kOptionVariadicKeyed()).toStrictEqual([
     { inlined: "2", separated: ["A", "B"] },
     { inlined: "1", separated: ["C"] },
   ]);