cli-kiss 0.2.2 → 0.2.4

package/src/lib/Run.ts

@@ -1,56 +1,31 @@
-import { Command, CommandFactory } from "./Command";
+import { Command, CommandDecoder } from "./Command";
 import { ReaderArgs } from "./Reader";
 import { TypoSupport } from "./Typo";
 import { usageToStyledLines } from "./Usage";
 
 /**
- * Parses the provided CLI arguments against the given command descriptor, executes
- * the matched command, and exits the process with an appropriate exit code.
+ * Main entry point: parses CLI arguments, executes the matched command, and exits.
+ * Handles `--help`, `--version`, usage-on-error, and exit codes.
  *
- * This is the primary entry point for running a `cli-kiss`-based CLI application.
- * It handles argument parsing, `--help` / `--version` flags, usage printing on errors,
- * and exit code management.
+ * Exit codes:
+ *  - `0` on success / `--help` / `--version`
+ *  - `1` on parse error or execution error.
  *
- * **Exit codes:**
- * - `0` — Command executed successfully, or `--help` / `--version` was handled.
- * - `1` — Argument parsing failed (a usage summary is also printed to stderr), or the
- *   command threw an unhandled execution error.
+ * @typeParam Context - Forwarded unchanged to the handler.
  *
- * **Built-in flags:**
- * - `--help` — Enabled by default (`usageOnHelp: true`). Prints the usage summary to
- *   stdout and exits with code `0`. This flag takes precedence over `--version`.
- * - `--version` — Enabled when `buildVersion` is provided. Prints `<cliName> <version>`
- *   to stdout and exits with code `0`.
+ * @param cliName - Program name used in usage and `--version` output.
+ * @param cliArgs - Raw arguments, typically `process.argv.slice(2)`.
+ * @param context - Forwarded to the handler.
+ * @param command - Root {@link Command}.
+ * @param options.useTtyColors - Color mode: `true` (always), `false` (never),
+ *   `"mock"` (snapshot-friendly), `undefined` (auto-detect from env).
+ * @param options.usageOnHelp - Enables `--help` flag (default `true`).
+ * @param options.usageOnError - Prints usage to stderr on parse error (default `true`).
+ * @param options.buildVersion - Enables `--version`; prints `<cliName> <buildVersion>`.
+ * @param options.onError - Custom handler for errors.
+ * @param options.onExit - Overrides `process.exit`; useful for testing.
  *
- * @typeParam Context - Arbitrary value passed unchanged to the command's execution handler.
- *   Use this to inject dependencies (e.g. a database connection, a logger) into your commands.
- *
- * @param cliName - The name of the CLI program (e.g. `"my-cli"`). Used in the usage
- *   summary header and in the `--version` output.
- * @param cliArgs - The raw command-line arguments to parse, typically `process.argv.slice(2)`.
- * @param context - The context value forwarded to the command's execution handler.
- * @param command - The root {@link Command} that describes how to parse and execute
- *   the CLI.
- * @param options - Optional configuration for the runner.
- * @param options.useTtyColors - Controls terminal color output in styled messages.
- *   - `true` — Always apply ANSI color codes.
- *   - `false` — Never apply color codes (plain text).
- *   - `"mock"` — Use a deterministic mock style useful for snapshot testing.
- *   - `undefined` (default) — Auto-detect based on `process.stdout.isTTY` and the
- *     `FORCE_COLOR` / `NO_COLOR` environment variables.
- * @param options.usageOnHelp - When `true` (default), registers a `--help` flag that
- *   prints the usage summary and exits with code `0`.
- * @param options.usageOnError - When `true` (default), prints the usage summary to
- *   stderr before the error message whenever argument parsing fails.
- * @param options.buildVersion - When provided, registers a `--version` flag that prints
- *   `<cliName> <buildVersion>` to stdout and exits with code `0`.
- * @param options.onError - Custom handler for errors thrown during command execution.
- *   If omitted, the error is printed to stderr via {@link TypoSupport}.
- * @param options.onExit - Overrides the process exit function (default: `process.exit`).
- *   Useful for testing — supply a function that throws or captures the exit code instead
- *   of actually terminating the process.
- *
- * @returns A `Promise<never>` because the function always terminates by calling `onExit`.
+ * @returns `Promise<never>` — always calls `onExit`.
  *
  * @example
  * ```ts
@@ -60,7 +35,7 @@ import { usageToStyledLines } from "./Usage";
  *   { description: "Greet someone" },
  *   operation(
  *     { options: {}, positionals: [positionalRequired({ type: typeString, label: "NAME" })] },
- *     async (_ctx, { positionals: [name] }) => {
+ *     async function (_ctx, { positionals: [name] }) {
  *       console.log(`Hello, ${name}!`);
  *     },
  *   ),
@@ -77,7 +52,7 @@ export async function runAndExit<Context>(
   context: Context,
   command: Command<Context, void>,
   options?: {
-    useTtyColors?: boolean | undefined | "mock";
+    useTtyColors?: boolean | undefined | "mock"; // TODO - flag setter option
     usageOnHelp?: boolean | undefined;
     usageOnError?: boolean | undefined;
     buildVersion?: string | undefined;
@@ -91,7 +66,10 @@ export async function runAndExit<Context>(
     readerArgs.registerOption({
       shorts: [],
       longs: ["help"],
-      valued: false,
+      parsing: {
+        consumeShortGroup: false,
+        consumeNextArg: () => false,
+      },
     });
   }
   const buildVersion = options?.buildVersion;
@@ -99,7 +77,10 @@ export async function runAndExit<Context>(
     readerArgs.registerOption({
       shorts: [],
       longs: ["version"],
-      valued: false,
+      parsing: {
+        consumeShortGroup: false,
+        consumeNextArg: () => false,
+      },
     });
   }
   /*
@@ -110,7 +91,8 @@ export async function runAndExit<Context>(
     longs: ["completion"],
   });
   */
-  const commandFactory = command.createFactory(readerArgs);
+  // TODO - handle color flag ?
+  const commandDecoder = command.consumeAndMakeDecoder(readerArgs);
   while (true) {
     try {
       const positional = readerArgs.consumePositional();
@@ -119,18 +101,11 @@ export async function runAndExit<Context>(
       }
     } catch (_) {}
   }
+  const typoSupport = computeTypoSupport(options?.useTtyColors);
   const onExit = options?.onExit ?? process.exit;
-  const typoSupport =
-    options?.useTtyColors === undefined
-      ? TypoSupport.inferFromProcess()
-      : options.useTtyColors === "mock"
-        ? TypoSupport.mock()
-        : options.useTtyColors
-          ? TypoSupport.tty()
-          : TypoSupport.none();
   if (usageOnHelp) {
     if (readerArgs.getOptionValues("--help" as any).length > 0) {
-      console.log(computeUsageString(cliName, commandFactory, typoSupport));
+      console.log(computeUsageString(cliName, commandDecoder, typoSupport));
       return onExit(0);
     }
   }
@@ -141,35 +116,55 @@ export async function runAndExit<Context>(
     }
   }
   try {
-    const commandInstance = commandFactory.createInstance();
+    const commandInterpreter = commandDecoder.decodeAndMakeInterpreter();
     try {
-      await commandInstance.executeWithContext(context);
+      await commandInterpreter.executeWithContext(context);
       return onExit(0);
     } catch (executionError) {
-      if (options?.onError) {
-        options.onError(executionError);
-      } else {
-        console.error(typoSupport.computeStyledErrorMessage(executionError));
-      }
+      handleError(options?.onError, executionError, typoSupport);
       return onExit(1);
     }
   } catch (parsingError) {
     if (options?.usageOnError ?? true) {
-      console.error(computeUsageString(cliName, commandFactory, typoSupport));
+      console.error(computeUsageString(cliName, commandDecoder, typoSupport));
     }
-    console.error(typoSupport.computeStyledErrorMessage(parsingError));
+    handleError(options?.onError, parsingError, typoSupport);
     return onExit(1);
   }
 }
 
+function handleError(
+  onError: ((error: unknown) => void) | undefined,
+  error: unknown,
+  typoSupport: TypoSupport,
+) {
+  if (onError !== undefined) {
+    onError(error);
+  } else {
+    console.error(typoSupport.computeStyledErrorMessage(error));
+  }
+}
+
 function computeUsageString<Context, Result>(
   cliName: Lowercase<string>,
-  commandFactory: CommandFactory<Context, Result>,
+  commandDecoder: CommandDecoder<Context, Result>,
   typoSupport: TypoSupport,
 ) {
   return usageToStyledLines({
     cliName,
-    commandUsage: commandFactory.generateUsage(),
+    usage: commandDecoder.generateUsage(),
     typoSupport,
   }).join("\n");
 }
+
+function computeTypoSupport(
+  useTtyColors: boolean | undefined | "mock",
+): TypoSupport {
+  return useTtyColors === undefined
+    ? TypoSupport.inferFromProcess()
+    : useTtyColors === "mock"
+      ? TypoSupport.mock()
+      : useTtyColors
+        ? TypoSupport.tty()
+        : TypoSupport.none();
+}

package/src/lib/Type.ts

@@ -7,79 +7,68 @@ import {
 } from "./Typo";
 
 /**
- * Describes how to decode a raw CLI string token into a typed TypeScript value.
+ * Decodes a raw CLI string into a typed value.
+ * A pair of a human-readable `content` name (e.g. `"Number"`) and a `decoder` function.
  *
- * A `Type` is a pair of:
- * - a `content` string — a human-readable name shown in help/error messages (e.g.
- *   `"String"`, `"Number"`, `"Url"`).
- * - a `decoder` function — converts the raw string or throws a {@link TypoError} on
- *   invalid input.
- *
- * Built-in types: {@link typeString}, {@link typeBoolean}, {@link typeNumber},
+ * Built-in: {@link typeString}, {@link typeBoolean}, {@link typeNumber},
  * {@link typeInteger}, {@link typeDate}, {@link typeUrl}.
+ * Composite: {@link typeOneOf}, {@link typeMapped}, {@link typeTuple}, {@link typeList}.
  *
- * Composite types: {@link typeOneOf}, {@link typeConverted}, {@link typeTuple},
- * {@link typeList}.
- *
- * @typeParam Value - The TypeScript type that the decoder produces.
+ * @typeParam Value - Type produced by the decoder.
  */
 export type Type<Value> = {
   /**
-   * Human-readable name for this type, used in help text and error messages.
-   * Examples: `"String"`, `"Number"`, `"Url"`.
+   * Human-readable name shown in help and errors (e.g. `"String"`, `"Number"`).
    */
   content: string;
   /**
-   * Decodes a raw string token into a `Value`.
+   * Decodes a raw CLI string into `Value`.
    *
-   * @param value - The raw string from the command line.
+   * @param input - Raw string from the command line.
    * @returns The decoded value.
-   * @throws {@link TypoError} if the value cannot be decoded.
+   * @throws {@link TypoError} on invalid input.
    */
-  decoder(value: string): Value;
+  decoder(input: string): Value;
 };
 
 /**
- * A {@link Type} that decodes `"true"` / `"yes"` to `true` and `"false"` / `"no"` to
- * `false` (case-insensitive). Any other value throws a {@link TypoError}.
- *
- * Primarily used internally by {@link optionFlag} for the `--flag=<value>` syntax, but
- * can also be used in positionals or valued options.
+ * Decodes a string to `boolean` (case-insensitive).
+ * Used by {@link optionFlag} for `--flag=<value>`.
  *
  * @example
  * ```ts
+ * typeBoolean.decoder("true")  // → true
  * typeBoolean.decoder("yes")   // → true
+ * typeBoolean.decoder("y")     // → true
  * typeBoolean.decoder("false") // → false
- * typeBoolean.decoder("1")     // throws TypoError
+ * typeBoolean.decoder("no")    // → false
+ * typeBoolean.decoder("n")     // → false
  * ```
  */
 export const typeBoolean: Type<boolean> = {
   content: "Boolean",
-  decoder(value: string) {
-    const lowerValue = value.toLowerCase();
-    if (lowerValue === "true" || lowerValue === "yes") {
+  decoder(input: string) {
+    const lower = input.toLowerCase();
+    if (booleanValuesTrue.has(lower)) {
       return true;
     }
-    if (lowerValue === "false" || lowerValue === "no") {
+    if (booleanValuesFalse.has(lower)) {
       return false;
     }
     throw new TypoError(
       new TypoText(
         new TypoString(`Invalid value: `),
-        new TypoString(`"${value}"`, typoStyleQuote),
+        new TypoString(`"${input}"`, typoStyleQuote),
       ),
     );
   },
 };
+const booleanValuesTrue = new Set(["true", "yes", "on", "1", "y", "t"]);
+const booleanValuesFalse = new Set(["false", "no", "off", "0", "n", "f"]);
 
 /**
- * A {@link Type} that parses a date/time string using `Date.parse`.
- *
- * Accepts any format supported by the JavaScript `Date.parse` API, including ISO 8601
- * strings (e.g. `"2024-01-15"`, `"2024-01-15T10:30:00Z"`). Non-parseable values throw
- * a {@link TypoError}.
- *
- * Produces a `Date` object. The decoded value is the result of `new Date(Date.parse(value))`.
+ * Parses a date/time string via `Date.parse`.
+ * Accepts any format supported by `Date.parse`, including ISO 8601.
  *
  * @example
  * ```ts
@@ -90,9 +79,9 @@ export const typeBoolean: Type<boolean> = {
  */
 export const typeDate: Type<Date> = {
   content: "Date",
-  decoder(value: string) {
+  decoder(input: string) {
     try {
-      const timestampMs = Date.parse(value);
+      const timestampMs = Date.parse(input);
       if (isNaN(timestampMs)) {
         throw new Error();
       }
@@ -101,7 +90,7 @@ export const typeDate: Type<Date> = {
       throw new TypoError(
         new TypoText(
           new TypoString(`Not a valid ISO_8601: `),
-          new TypoString(`"${value}"`, typoStyleQuote),
+          new TypoString(`"${input}"`, typoStyleQuote),
         ),
       );
     }
@@ -109,11 +98,7 @@ export const typeDate: Type<Date> = {
 };
 
 /**
- * A {@link Type} that parses a string into a JavaScript `number` using the `Number()`
- * constructor.
- *
- * Accepts integers, floating-point values, and scientific notation (e.g. `"3.14"`,
- * `"-1"`, `"1e10"`). Values that produce `NaN` throw a {@link TypoError}.
+ * Parses a string to `number` via `Number()`; `NaN` throws {@link TypoError}.
  *
  * @example
  * ```ts
@@ -124,9 +109,9 @@ export const typeDate: Type<Date> = {
  */
 export const typeNumber: Type<number> = {
   content: "Number",
-  decoder(value: string) {
+  decoder(input: string) {
     try {
-      const parsed = Number(value);
+      const parsed = Number(input);
       if (isNaN(parsed)) {
         throw new Error();
       }
@@ -135,7 +120,7 @@ export const typeNumber: Type<number> = {
       throw new TypoError(
         new TypoText(
           new TypoString(`Unable to parse: `),
-          new TypoString(`"${value}"`, typoStyleQuote),
+          new TypoString(`"${input}"`, typoStyleQuote),
         ),
       );
     }
@@ -143,11 +128,8 @@ export const typeNumber: Type<number> = {
 };
 
 /**
- * A {@link Type} that parses a string into a JavaScript `bigint` using the `BigInt()`
- * constructor.
- *
- * Only accepts valid integer strings (e.g. `"42"`, `"-100"`, `"9007199254740993"`).
- * Floating-point strings or non-numeric values throw a {@link TypoError}.
+ * Parses an integer string to `bigint` via `BigInt()`.
+ * Floats and non-numeric strings throw {@link TypoError}.
  *
  * @example
  * ```ts
@@ -158,14 +140,14 @@ export const typeNumber: Type<number> = {
  */
 export const typeInteger: Type<bigint> = {
   content: "Integer",
-  decoder(value: string) {
+  decoder(input: string) {
     try {
-      return BigInt(value);
+      return BigInt(input);
     } catch {
       throw new TypoError(
         new TypoText(
           new TypoString(`Unable to parse: `),
-          new TypoString(`"${value}"`, typoStyleQuote),
+          new TypoString(`"${input}"`, typoStyleQuote),
         ),
       );
     }
@@ -173,10 +155,8 @@ export const typeInteger: Type<bigint> = {
 };
 
 /**
- * A {@link Type} that parses a string into a `URL` object using the `URL` constructor.
- *
- * The string must be a valid absolute URL (e.g. `"https://example.com/path?q=1"`).
- * Relative URLs and malformed strings throw a {@link TypoError}.
+ * Parses an absolute URL string to a `URL` object.
+ * Relative or malformed URLs throw {@link TypoError}.
  *
  * @example
  * ```ts
@@ -186,14 +166,14 @@ export const typeInteger: Type<bigint> = {
  */
 export const typeUrl: Type<URL> = {
   content: "Url",
-  decoder(value: string) {
+  decoder(input: string) {
     try {
-      return new URL(value);
+      return new URL(input);
     } catch {
       throw new TypoError(
         new TypoText(
           new TypoString(`Unable to parse: `),
-          new TypoString(`"${value}"`, typoStyleQuote),
+          new TypoString(`"${input}"`, typoStyleQuote),
         ),
       );
     }
@@ -201,9 +181,7 @@ export const typeUrl: Type<URL> = {
 };
 
 /**
- * A {@link Type} that passes the raw string through unchanged (identity decoder).
- *
- * This is the simplest type and accepts any string value without validation.
+ * Identity decoder — passes the raw string through unchanged.
  *
  * @example
  * ```ts
@@ -213,35 +191,27 @@ export const typeUrl: Type<URL> = {
  */
 export const typeString: Type<string> = {
   content: "String",
-  decoder(value: string) {
-    return value;
+  decoder(input: string) {
+    return input;
   },
 };
 
 /**
- * Creates a new {@link Type} by chaining a `before` type decoder with an `after`
- * transformation.
- *
- * The raw string is first decoded by `before.decoder`; its result is then passed to
- * `after.decoder`. Errors from `before` are wrapped with a "from: <content>" context
- * prefix so that the full decoding path is visible in error messages.
+ * Chains `before`'s decoder with an `after` transformation.
+ * `before` errors are prefixed with `"from: <content>"` for traceability.
  *
- * Use this when an existing type (e.g. {@link typeString}, {@link typeOneOf}) produces
- * an intermediate value that needs a further transformation (e.g. parsing a
- * string-keyed enum into a number).
+ * @typeParam Before - Intermediate type from `before.decoder`.
+ * @typeParam After - Final type from `after.decoder`.
  *
- * @typeParam Before - The intermediate type produced by `before.decoder`.
- * @typeParam After - The final type produced by `after.decoder`.
- *
- * @param before - The base type that decodes the raw CLI string.
- * @param after - The transformation applied to the `Before` value.
- * @param after.content - Human-readable name for the resulting type (shown in errors).
- * @param after.decoder - Function that converts a `Before` value into `After`.
- * @returns A new {@link Type}`<After>` whose `content` is `after.content`.
+ * @param before - Base decoder for the raw string.
+ * @param after - Transformation applied to the decoded value.
+ * @param after.content - Name for the resulting type (shown in errors).
+ * @param after.decoder - Converts a `Before` value to `After`.
+ * @returns A {@link Type}`<After>`.
  *
  * @example
  * ```ts
- * const typePort = typeConverted(typeNumber, {
+ * const typePort = typeMapped(typeNumber, {
  *   content: "Port",
  *   decoder: (n) => {
  *     if (n < 1 || n > 65535) throw new Error("Out of range");
@@ -252,16 +222,16 @@ export const typeString: Type<string> = {
  * // "--port 99999"  →  TypoError: --port: <PORT>: Port: Out of range
  * ```
  */
-export function typeConverted<Before, After>(
+export function typeMapped<Before, After>(
   before: Type<Before>,
   after: { content: string; decoder: (value: Before) => After },
 ): Type<After> {
   return {
     content: after.content,
-    decoder: (value: string) => {
+    decoder: (input: string) => {
       return after.decoder(
         TypoError.tryWithContext(
-          () => before.decoder(value),
+          () => before.decoder(input),
           () =>
             new TypoText(
               new TypoString("from: "),
@@ -274,18 +244,12 @@ export function typeConverted<Before, After>(
 }
 
 /**
- * Creates a {@link Type}`<string>` that only accepts a fixed set of string values.
- *
- * The decoder performs an exact (case-sensitive) lookup in `values`. If the input is
- * not in the set, a {@link TypoError} is thrown listing up to 5 of the valid options.
- *
- * Combine with {@link typeConverted} to map the accepted strings to a richer type.
+ * Creates a {@link Type}`<string>` that only accepts a fixed set of values.
+ * Out-of-set inputs throw {@link TypoError} listing up to 5 valid options.
  *
- * @param content - Human-readable name for this type shown in help text and error
- *   messages (e.g. `"Environment"`, `"LogLevel"`).
- * @param values - The ordered list of accepted string values. The order is preserved in
- *   the error message preview.
- * @returns A {@link Type}`<string>` that validates membership in `values`.
+ * @param content - Name shown in help and errors (e.g. `"Environment"`).
+ * @param values - Ordered list of accepted values.
+ * @returns A {@link Type}`<string>`.
  *
  * @example
  * ```ts
@@ -294,16 +258,17 @@ export function typeConverted<Before, After>(
  * typeEnv.decoder("unknown") // throws TypoError: Invalid value: "unknown" (expected one of: "dev" | "staging" | "prod")
  * ```
  */
-export function typeOneOf(
+export function typeOneOf<const Value extends string>(
   content: string,
-  values: Array<string>,
-): Type<string> {
-  const valuesSet = new Set(values);
+  values: Array<Value>,
+): Type<Value> {
   return {
     content: content,
-    decoder(value: string) {
-      if (valuesSet.has(value)) {
-        return value;
+    decoder(input: string) {
+      for (const value of values) {
+        if (input === value) {
+          return value;
+        }
       }
       const valuesPreview = [];
       for (const value of values) {
@@ -319,7 +284,7 @@ export function typeOneOf(
       throw new TypoError(
         new TypoText(
           new TypoString(`Invalid value: `),
-          new TypoString(`"${value}"`, typoStyleQuote),
+          new TypoString(`"${input}"`, typoStyleQuote),
           new TypoString(` (expected one of: `),
           ...valuesPreview,
           new TypoString(`)`),
@@ -330,23 +295,14 @@ export function typeOneOf(
 }
 
 /**
- * Creates a {@link Type} that decodes a single delimited string into a fixed-length
- * tuple of typed elements.
+ * Splits a delimited string into a typed tuple.
+ * Each part is decoded by the corresponding element type; wrong count or decode failure throws {@link TypoError}.
  *
- * The raw string is split on `separator` into exactly `elementTypes.length` parts.
- * Each part is decoded by its corresponding element type. If the number of splits does
- * not match, or if any element's decoder fails, a {@link TypoError} is thrown with the
- * index and element type context.
+ * @typeParam Elements - Tuple of decoded value types (inferred from `elementTypes`).
  *
- * The resulting `content` is the element types' `content` values joined by `separator`
- * (e.g. `"Number,String"` for a `[number, string]` tuple with `","` separator).
- *
- * @typeParam Elements - The tuple type of decoded element values (inferred from
- *   `elementTypes`).
- *
- * @param elementTypes - An ordered array of {@link Type}s, one per tuple element.
- * @param separator - The string used to split the raw value (default: `","`).
- * @returns A {@link Type}`<Elements>` tuple type.
+ * @param elementTypes - One {@link Type} per tuple element, in order.
+ * @param separator - Delimiter (default `","`).
+ * @returns A {@link Type}`<Elements>`.
  *
  * @example
  * ```ts
@@ -364,14 +320,14 @@ export function typeTuple<const Elements extends Array<any>>(
     content: elementTypes
       .map((elementType) => elementType.content)
       .join(separator),
-    decoder(value: string) {
-      const splits = value.split(separator, elementTypes.length);
+    decoder(input: string) {
+      const splits = input.split(separator, elementTypes.length);
       if (splits.length !== elementTypes.length) {
         throw new TypoError(
           new TypoText(
             new TypoString(`Found ${splits.length} splits: `),
             new TypoString(`Expected ${elementTypes.length} splits from: `),
-            new TypoString(`"${value}"`, typoStyleQuote),
+            new TypoString(`"${input}"`, typoStyleQuote),
           ),
         );
       }
@@ -391,26 +347,14 @@ export function typeTuple<const Elements extends Array<any>>(
 }
 
 /**
- * Creates a {@link Type} that decodes a single delimited string into an array of
- * homogeneous typed elements.
- *
- * The raw string is split on `separator` and each part is decoded by `elementType`.
- * If any element's decoder fails, a {@link TypoError} is thrown with the index and
- * element type context.
- *
- * Unlike {@link typeTuple}, the number of elements is not fixed; the result array
- * length equals the number of `separator`-delimited parts in the input string. To pass
- * an empty array, the user must pass an empty string (`""`), which splits into one
- * empty-string element — consider using {@link optionRepeatable} instead if you want a
- * naturally empty default.
- *
- * The `content` is formatted as `"<elementContent>[<sep><elementContent>]..."` to
- * signal repeatability.
+ * Splits a delimited string into a typed array.
+ * Each part is decoded by `elementType`; failed decodes throw {@link TypoError}.
+ * Note: splitting an empty string yields one empty element — prefer {@link optionRepeatable} for a zero-default.
  *
- * @typeParam Value - The TypeScript element type produced by `elementType.decoder`.
+ * @typeParam Value - Element type produced by `elementType.decoder`.
  *
- * @param elementType - The {@link Type} used to decode each element.
- * @param separator - The string used to split the raw value (default: `","`).
+ * @param elementType - Decoder applied to each element.
+ * @param separator - Delimiter (default `","`).
  * @returns A {@link Type}`<Array<Value>>`.
  *
  * @example
@@ -429,8 +373,8 @@ export function typeList<Value>(
 ): Type<Array<Value>> {
   return {
     content: `${elementType.content}[${separator}${elementType.content}]...`,
-    decoder(value: string) {
-      const splits = value.split(separator);
+    decoder(input: string) {
+      const splits = input.split(separator);
       return splits.map((split, index) =>
         TypoError.tryWithContext(
           () => elementType.decoder(split),