cli-kiss 0.2.3 → 0.2.4

package/src/lib/Reader.ts

@@ -7,44 +7,58 @@ import {
 } from "./Typo";
 
 /**
- * Opaque key identifying a registered option within a {@link ReaderArgs} instance.
- * Returned by {@link ReaderArgs.registerOption}; passed to {@link ReaderArgs.getOptionValues}.
+ * Opaque key returned by {@link ReaderArgs.registerOption}.
  */
 export type ReaderOptionKey = (string | { __brand: "ReaderOptionKey" }) & {
   __brand: "ReaderOptionKey";
 };
 
 /**
- * Option registration and query interface, implemented by {@link ReaderArgs}.
- * Exposed separately from {@link ReaderPositionals} so parsers depend only on what they need.
+ * Parsing behaviour for a registered option, passed to {@link ReaderArgs.registerOption}.
+ */
+export type ReaderOptionParsing = {
+  consumeShortGroup: boolean;
+  consumeNextArg: (
+    inlined: string | null,
+    separated: Array<string>,
+    next: string | undefined,
+  ) => boolean;
+};
+
+/**
+ * Result of parsing an option, including its inlined value and any following separated values.
+ */
+export type ReaderOptionValue = {
+  inlined: string | null;
+  separated: Array<string>;
+};
+
+/**
+ * Option registration/query interface. Subset of {@link ReaderArgs}.
  */
 export type ReaderOptions = {
   /**
-   * Registers an option so the parser can recognise it.
+   * Registers an option; all `longs` and `shorts` share the same key.
    *
    * @param definition.longs - Long-form names (without `--`).
    * @param definition.shorts - Short-form names (without `-`).
-   * @param definition.valued - `true` if the option takes a value; `false` for flags.
+   * @param definition.parsing - Parsing behaviour.
    * @returns A {@link ReaderOptionKey} for later retrieval.
    * @throws `Error` if a name is already registered or short names overlap.
    */
   registerOption(definition: {
     longs: Array<string>;
     shorts: Array<string>;
-    valued: boolean;
+    parsing: ReaderOptionParsing;
   }): ReaderOptionKey;
   /**
-   * Returns all values collected for the option identified by `key`.
-   *
-   * @param key - Key from {@link ReaderOptions.registerOption}.
-   * @returns Raw string values, one per occurrence; empty if never provided.
-   * @throws `Error` if `key` was not registered.
+   * Returns all values collected for `key`.
    */
-  getOptionValues(key: ReaderOptionKey): Array<string>;
+  getOptionValues(key: ReaderOptionKey): Array<ReaderOptionValue>;
 };
 
 /**
- * Positional token consumption interface, implemented by {@link ReaderArgs}.
+ * Positional consumption interface. Subset of {@link ReaderArgs}.
  */
 export type ReaderPositionals = {
   /**
@@ -69,10 +83,9 @@ export class ReaderArgs {
   #args: ReadonlyArray<string>;
   #parsedIndex: number;
   #parsedDouble: boolean;
-  #keyByLong: Map<string, ReaderOptionKey>;
-  #keyByShort: Map<string, ReaderOptionKey>;
-  #valuedByKey: Map<ReaderOptionKey, boolean>;
-  #resultByKey: Map<ReaderOptionKey, Array<string>>;
+  #optionContextByLong: Map<string, ReaderOptionContext>;
+  #optionContextByShort: Map<string, ReaderOptionContext>;
+  #optionContextByKey: Map<ReaderOptionKey, ReaderOptionContext>;
 
   /**
    * @param args - Raw CLI tokens (e.g. `process.argv.slice(2)`). Not mutated.
@@ -81,27 +94,25 @@ export class ReaderArgs {
     this.#args = args;
     this.#parsedIndex = 0;
     this.#parsedDouble = false;
-    this.#keyByLong = new Map();
-    this.#keyByShort = new Map();
-    this.#valuedByKey = new Map();
-    this.#resultByKey = new Map();
+    this.#optionContextByLong = new Map();
+    this.#optionContextByShort = new Map();
+    this.#optionContextByKey = new Map();
   }
 
   /**
    * Registers an option; all `longs` and `shorts` share the same key.
-   * Short names support stacking (e.g. `-abc`) and inline values (e.g. `-nvalue`),
-   * but must not be prefixes of one another.
+   * Short names must not be prefixes of one another.
    *
    * @param definition.longs - Long-form names (without `--`).
    * @param definition.shorts - Short-form names (without `-`).
-   * @param definition.valued - `true` if the option takes a value; `false` for flags.
+   * @param definition.parsing - Parsing behaviour.
    * @returns A {@link ReaderOptionKey} for {@link ReaderArgs.getOptionValues}.
    * @throws `Error` if any name is already registered or short names overlap.
    */
   registerOption(definition: {
     longs: Array<string>;
     shorts: Array<string>;
-    valued: boolean;
+    parsing: ReaderOptionParsing;
   }) {
     const key = [
       ...definition.longs.map((long) => `--${long}`),
@@ -111,7 +122,7 @@ export class ReaderArgs {
       if (!this.#isValidOptionName(long)) {
         throw new Error(`Invalid option name: --${long}`);
       }
-      if (this.#keyByLong.has(long)) {
+      if (this.#optionContextByLong.has(long)) {
         throw new Error(`Option already registered: --${long}`);
       }
     }
@@ -119,18 +130,18 @@ export class ReaderArgs {
       if (!this.#isValidOptionName(short)) {
         throw new Error(`Invalid option name: -${short}`);
       }
-      if (this.#keyByShort.has(short)) {
+      if (this.#optionContextByShort.has(short)) {
         throw new Error(`Option already registered: -${short}`);
       }
       for (let i = 0; i < short.length; i++) {
         const shortSlice = short.slice(0, i);
-        if (this.#keyByShort.has(shortSlice)) {
+        if (this.#optionContextByShort.has(shortSlice)) {
           throw new Error(
             `Option -${short} overlap with shorter option: -${shortSlice}`,
           );
         }
       }
-      for (const shortOther of this.#keyByShort.keys()) {
+      for (const shortOther of this.#optionContextByShort.keys()) {
         if (shortOther.startsWith(short)) {
           throw new Error(
             `Option -${short} overlap with longer option: -${shortOther}`,
@@ -138,35 +149,37 @@ export class ReaderArgs {
         }
       }
     }
+    const optionContext = {
+      parsing: definition.parsing,
+      results: new Array<ReaderOptionValue>(),
+    };
     for (const long of definition.longs) {
-      this.#keyByLong.set(long, key);
+      this.#optionContextByLong.set(long, optionContext);
     }
     for (const short of definition.shorts) {
-      this.#keyByShort.set(short, key);
+      this.#optionContextByShort.set(short, optionContext);
     }
-    this.#valuedByKey.set(key, definition.valued);
-    this.#resultByKey.set(key, new Array<string>());
+    this.#optionContextByKey.set(key, optionContext);
     return key;
   }
 
   /**
-   * Returns all values collected for the option key.
+   * Returns all values collected for `key`.
    *
    * @param key - Key from {@link ReaderArgs.registerOption}.
-   * @returns String values, one per occurrence.
+   * @returns One entry per occurrence.
    * @throws `Error` if `key` was not registered.
    */
-  getOptionValues(key: ReaderOptionKey): Array<string> {
-    const optionResult = this.#resultByKey.get(key);
-    if (optionResult === undefined) {
+  getOptionValues(key: ReaderOptionKey): Array<ReaderOptionValue> {
+    const optionContext = this.#optionContextByKey.get(key);
+    if (optionContext === undefined) {
       throw new Error(`Unregistered option: ${key}`);
     }
-    return optionResult;
+    return optionContext.results;
   }
 
   /**
-   * Returns the next bare positional token.
-   * Parse intervening options as side-effects.
+   * Returns the next positional token; parses intervening options as a side-effect.
    * All tokens after `--` are treated as positionals.
    *
    * @returns The next positional, or `undefined` when exhausted.
@@ -175,19 +188,19 @@ export class ReaderArgs {
   consumePositional(): string | undefined {
     while (true) {
       const arg = this.#consumeArg();
-      if (arg === null) {
+      if (arg === undefined) {
         return undefined;
       }
-      if (this.#processedAsPositional(arg)) {
+      if (!this.#tryConsumeAsOption(arg)) {
         return arg;
       }
     }
   }
 
-  #consumeArg(): string | null {
+  #consumeArg(): string | undefined {
     const arg = this.#args[this.#parsedIndex];
     if (arg === undefined) {
-      return null;
+      return undefined;
     }
     this.#parsedIndex++;
     if (!this.#parsedDouble) {
@@ -199,9 +212,9 @@ export class ReaderArgs {
     return arg;
   }
 
-  #processedAsPositional(arg: string): boolean {
+  #tryConsumeAsOption(arg: string): boolean {
     if (this.#parsedDouble) {
-      return true;
+      return false;
     }
     if (arg.startsWith("--")) {
       const valueIndexStart = arg.indexOf("=");
@@ -213,80 +226,90 @@ export class ReaderArgs {
           arg.slice(valueIndexStart + 1),
         );
       }
-      return false;
+      return true;
     }
     if (arg.startsWith("-")) {
       let shortIndexStart = 1;
       let shortIndexEnd = 2;
       while (shortIndexEnd <= arg.length) {
-        const result = this.#tryConsumeOptionShort(
-          arg.slice(shortIndexStart, shortIndexEnd),
-          arg.slice(shortIndexEnd),
-        );
-        if (result === true) {
-          return false;
-        }
-        if (result === false) {
+        const short = arg.slice(shortIndexStart, shortIndexEnd);
+        const optionContext = this.#optionContextByShort.get(short);
+        if (optionContext !== undefined) {
+          const rest = arg.slice(shortIndexEnd);
+          if (this.#tryConsumeOptionShort(optionContext, short, rest)) {
+            return true;
+          }
           shortIndexStart = shortIndexEnd;
         }
         shortIndexEnd++;
       }
       throw new TypoError(
         new TypoText(
-          new TypoString(`-${arg.slice(shortIndexStart)}`, typoStyleConstants),
-          new TypoString(`: Unexpected unknown option`),
+          new TypoString(`Unexpected unknown option(s): `),
+          new TypoString(`-${arg.slice(shortIndexStart)}`, typoStyleQuote),
         ),
       );
     }
-    return true;
+    return false;
   }
 
-  #consumeOptionLong(long: string, direct: string | null): void {
+  #consumeOptionLong(long: string, inlined: string | null): void {
     const constant = `--${long}`;
-    const key = this.#keyByLong.get(long);
-    if (key !== undefined) {
-      if (direct !== null) {
-        return this.#acknowledgeOption(key, direct);
-      }
-      const valued = this.#valuedByKey.get(key);
-      if (valued) {
-        return this.#acknowledgeOption(key, this.#consumeOptionValue(constant));
-      }
-      return this.#acknowledgeOption(key, "true");
+    const optionContext = this.#optionContextByLong.get(long);
+    if (optionContext !== undefined) {
+      return this.#consumeOptionValues(optionContext, constant, inlined);
     }
     throw new TypoError(
       new TypoText(
-        new TypoString(constant, typoStyleConstants),
-        new TypoString(`: Unexpected unknown option`),
+        new TypoString(`Unexpected unknown option: `),
+        new TypoString(constant, typoStyleQuote),
       ),
     );
   }
 
-  #tryConsumeOptionShort(short: string, rest: string): boolean | null {
-    const key = this.#keyByShort.get(short);
-    if (key !== undefined) {
-      if (rest.startsWith("=")) {
-        this.#acknowledgeOption(key, rest.slice(1));
-        return true;
-      }
-      const valued = this.#valuedByKey.get(key);
-      if (valued) {
-        if (rest === "") {
-          this.#acknowledgeOption(key, this.#consumeOptionValue(`-${short}`));
-        } else {
-          this.#acknowledgeOption(key, rest);
-        }
-        return true;
-      }
-      this.#acknowledgeOption(key, "true");
-      return rest === "";
+  #tryConsumeOptionShort(
+    optionContext: ReaderOptionContext,
+    short: string,
+    rest: string,
+  ): boolean {
+    const constant = `-${short}`;
+    if (rest.startsWith("=")) {
+      this.#consumeOptionValues(optionContext, constant, rest.slice(1));
+      return true;
+    }
+    if (rest.length === 0) {
+      this.#consumeOptionValues(optionContext, constant, null);
+      return true;
+    }
+    if (optionContext.parsing.consumeShortGroup) {
+      this.#consumeOptionValues(optionContext, constant, rest);
+      return true;
     }
-    return null;
+    this.#consumeOptionValues(optionContext, constant, null);
+    return false;
   }
 
-  #consumeOptionValue(constant: string) {
+  #consumeOptionValues(
+    optionContext: ReaderOptionContext,
+    constant: string,
+    inlined: string | null,
+  ) {
+    const separated = new Array<string>();
+    while (
+      optionContext.parsing.consumeNextArg(
+        inlined,
+        separated,
+        this.#args[this.#parsedIndex],
+      )
+    ) {
+      separated.push(this.#consumeOptionValue(constant));
+    }
+    optionContext.results.push({ inlined, separated });
+  }
+
+  #consumeOptionValue(constant: string): string {
     const arg = this.#consumeArg();
-    if (arg === null) {
+    if (arg === undefined) {
       throw new TypoError(
         new TypoText(
           new TypoString(constant, typoStyleConstants),
@@ -316,11 +339,12 @@ export class ReaderArgs {
     return arg;
   }
 
-  #acknowledgeOption(key: ReaderOptionKey, value: string) {
-    this.getOptionValues(key).push(value);
-  }
-
   #isValidOptionName(name: string): boolean {
     return name.length > 0 && !name.includes("=");
   }
 }
+
+type ReaderOptionContext = {
+  parsing: ReaderOptionParsing;
+  results: Array<ReaderOptionValue>;
+};

package/src/lib/Run.ts

@@ -7,15 +7,16 @@ import { usageToStyledLines } from "./Usage";
  * Main entry point: parses CLI arguments, executes the matched command, and exits.
  * Handles `--help`, `--version`, usage-on-error, and exit codes.
  *
- * Exit codes: `0` on success / `--help` / `--version`; `1` on parse or execution error.
+ * Exit codes:
+ *  - `0` on success / `--help` / `--version`
+ *  - `1` on parse error or execution error.
  *
- * @typeParam Context - Passed unchanged to the command handler; use to inject dependencies.
+ * @typeParam Context - Forwarded unchanged to the handler.
  *
  * @param cliName - Program name used in usage and `--version` output.
  * @param cliArgs - Raw arguments, typically `process.argv.slice(2)`.
- * @param context - Forwarded to the command handler, injected dependencies.
+ * @param context - Forwarded to the handler.
  * @param command - Root {@link Command}.
- * @param options - Optional runner configuration.
  * @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`).
@@ -34,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}!`);
  *     },
  *   ),
@@ -51,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;
@@ -65,7 +66,10 @@ export async function runAndExit<Context>(
     readerArgs.registerOption({
       shorts: [],
       longs: ["help"],
-      valued: false,
+      parsing: {
+        consumeShortGroup: false,
+        consumeNextArg: () => false,
+      },
     });
   }
   const buildVersion = options?.buildVersion;
@@ -73,7 +77,10 @@ export async function runAndExit<Context>(
     readerArgs.registerOption({
       shorts: [],
       longs: ["version"],
-      valued: false,
+      parsing: {
+        consumeShortGroup: false,
+        consumeNextArg: () => false,
+      },
     });
   }
   /*
@@ -84,6 +91,7 @@ export async function runAndExit<Context>(
     longs: ["completion"],
   });
   */
+  // TODO - handle color flag ?
   const commandDecoder = command.consumeAndMakeDecoder(readerArgs);
   while (true) {
     try {
@@ -93,15 +101,8 @@ 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, commandDecoder, typoSupport));
@@ -151,7 +152,19 @@ function computeUsageString<Context, Result>(
 ) {
   return usageToStyledLines({
     cliName,
-    commandUsage: commandDecoder.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

@@ -18,11 +18,11 @@ import {
  */
 export type Type<Value> = {
   /**
-   * Human-readable name shown in help and error messages (e.g. `"String"`, `"Number"`).
+   * Human-readable name shown in help and errors (e.g. `"String"`, `"Number"`).
    */
   content: string;
   /**
-   * Converts a raw CLI string into `Value`.
+   * Decodes a raw CLI string into `Value`.
    *
    * @param input - Raw string from the command line.
    * @returns The decoded value.
@@ -32,24 +32,27 @@ export type Type<Value> = {
 };
 
 /**
- * Decodes `"true"` / `"yes"` → `true` and `"false"` / `"no"` → `false` (case-insensitive).
- * Used internally by {@link optionFlag} for the `--flag=<value>` syntax.
+ * 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(input: string) {
     const lower = input.toLowerCase();
-    if (lower === "true" || lower === "yes") {
+    if (booleanValuesTrue.has(lower)) {
       return true;
     }
-    if (lower === "false" || lower === "no") {
+    if (booleanValuesFalse.has(lower)) {
       return false;
     }
     throw new TypoError(
@@ -60,9 +63,11 @@ export const typeBoolean: Type<boolean> = {
     );
   },
 };
+const booleanValuesTrue = new Set(["true", "yes", "on", "1", "y", "t"]);
+const booleanValuesFalse = new Set(["false", "no", "off", "0", "n", "f"]);
 
 /**
- * Parses a date/time string via `Date.parse` into a `Date` object.
+ * Parses a date/time string via `Date.parse`.
  * Accepts any format supported by `Date.parse`, including ISO 8601.
  *
  * @example
@@ -93,8 +98,7 @@ export const typeDate: Type<Date> = {
 };
 
 /**
- * Parses a string into a `number` via `Number()`.
- * Accepts integers, floats, and scientific notation; `NaN` throws a {@link TypoError}.
+ * Parses a string to `number` via `Number()`; `NaN` throws {@link TypoError}.
  *
  * @example
  * ```ts
@@ -124,8 +128,8 @@ export const typeNumber: Type<number> = {
 };
 
 /**
- * Parses an integer string into a `bigint` via `BigInt()`.
- * Floats and non-numeric strings throw a {@link TypoError}.
+ * Parses an integer string to `bigint` via `BigInt()`.
+ * Floats and non-numeric strings throw {@link TypoError}.
  *
  * @example
  * ```ts
@@ -151,8 +155,8 @@ export const typeInteger: Type<bigint> = {
 };
 
 /**
- * Parses an absolute URL string into a `URL` object.
- * Relative or malformed URLs throw a {@link TypoError}.
+ * Parses an absolute URL string to a `URL` object.
+ * Relative or malformed URLs throw {@link TypoError}.
  *
  * @example
  * ```ts
@@ -193,7 +197,7 @@ export const typeString: Type<string> = {
 };
 
 /**
- * Creates a {@link Type} by chaining `before`'s decoder with an `after` transformation.
+ * Chains `before`'s decoder with an `after` transformation.
  * `before` errors are prefixed with `"from: <content>"` for traceability.
  *
  * @typeParam Before - Intermediate type from `before.decoder`.
@@ -240,8 +244,8 @@ export function typeMapped<Before, After>(
 }
 
 /**
- * Creates a {@link Type}`<string>` accepting only a fixed set of string values.
- * Out-of-set inputs throw a {@link TypoError} listing up to 5 valid options.
+ * 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 - Name shown in help and errors (e.g. `"Environment"`).
  * @param values - Ordered list of accepted values.
@@ -291,7 +295,7 @@ export function typeOneOf<const Value extends string>(
 }
 
 /**
- * Splits a delimited string into a fixed-length typed tuple.
+ * 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}.
  *
  * @typeParam Elements - Tuple of decoded value types (inferred from `elementTypes`).
@@ -316,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),
           ),
         );
       }
@@ -343,7 +347,7 @@ export function typeTuple<const Elements extends Array<any>>(
 }
 
 /**
- * Splits a delimited string into a variable-length typed array.
+ * 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.
  *