cli-kiss 0.2.1 → 0.2.3

package/src/lib/Positional.ts

@@ -9,28 +9,40 @@ import {
 } from "./Typo";
 
 /**
- * Describes a single positional argument — a bare (non-option) token on the command
- * line — together with its parsing and usage-generation logic.
+ * A bare (non-option) positional argument with its parsing and usage-generation logic.
  *
- * Positionals are created with {@link positionalRequired}, {@link positionalOptional}, or
- * {@link positionalVariadics} and are passed via the `positionals` array of
- * {@link operation}, where they are consumed in declaration order.
+ * Created with {@link positionalRequired}, {@link positionalOptional}, or
+ * {@link positionalVariadics} and passed via the `positionals` array of
+ * {@link operation}, consumed in declaration order.
  *
- * @typeParam Value - The TypeScript type of the parsed positional value.
+ * @typeParam Value - Decoded value type.
  */
 export type Positional<Value> = {
-  /** Returns human-readable metadata used to render the `Positionals:` section of help. */
+  /**
+   * Returns metadata used to render the `Positionals:` section of help.
+   */
   generateUsage(): PositionalUsage;
   /**
-   * Consumes the next positional token(s) from `readerPositionals` and returns the
-   * decoded value.
+   * Consumes the next positional token from `readerPositionals`.
+   * Returns a decoder that produces the final value.
+   */
+  consumeAndMakeDecoder(
+    readerPositionals: ReaderPositionals,
+  ): PositionalDecoder<Value>;
+};
+
+/**
+ * Produced by {@link Positional.consumeAndMakeDecoder}.
+ *
+ * @typeParam Value - Decoded value type.
+ */
+export type PositionalDecoder<Value> = {
+  /**
+   * Returns the decoded positional value.
    *
-   * @param readerPositionals - The shared {@link ReaderArgs} that manages the queue of
-   *   remaining positional tokens.
-   * @throws {@link TypoError} if the positional is required but absent, or if the raw
-   *   value fails type decoding.
+   * @throws {@link TypoError} if decoding failed.
    */
-  consumePositionals(readerPositionals: ReaderPositionals): Value;
+  decodeValue(): Value;
 };
 
 /**
@@ -38,40 +50,32 @@ export type Positional<Value> = {
  * `Positionals:` section of the help output produced by {@link usageToStyledLines}.
  */
 export type PositionalUsage = {
-  /** Short description of what the positional represents. */
+  /**
+   * Help text.
+   */
   description: string | undefined;
   /**
-   * Optional supplementary note shown in parentheses next to the description.
-   * Suitable for short caveats such as `"defaults to 'world'"`.
+   * Short note shown in parentheses.
    */
   hint: string | undefined;
   /**
-   * The placeholder label shown in the usage line and the `Positionals:` section.
-   * Required positionals use angle-bracket notation (e.g. `"<NAME>"`); optional ones
-   * use square-bracket notation (e.g. `"[FILE]"`); variadic ones append `...`
-   * (e.g. `"[ITEM]..."`).
+   * Placeholder label shown in the usage line and the `Positionals:` section.
+   * Required: `<NAME>`, optional: `[NAME]`, variadic: `[NAME]...`.
    */
   label: Uppercase<string>;
 };
 
 /**
- * Creates a required positional argument — one that must be present on the command line.
+ * Creates a required positional — missing token throws {@link TypoError}.
+ * Label defaults to uppercased `type.content` in angle brackets (e.g. `<STRING>`).
  *
- * The parser consumes the next available positional token and decodes it with
- * `definition.type`. If no token is available, a {@link TypoError} is thrown immediately
- * during parsing (i.e. inside {@link OperationDescriptor.createFactory}).
+ * @typeParam Value - Type produced by the decoder.
  *
- * The label displayed in the usage line defaults to the uppercased `type.content`
- * wrapped in angle brackets (e.g. `<STRING>`). Supply `label` to override.
- *
- * @typeParam Value - The TypeScript type produced by the type decoder.
- *
- * @param definition - Configuration for the positional.
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.label - Custom label shown in the usage line (without angle brackets).
- *   Defaults to the uppercased `type.content`.
- * @param definition.type - The {@link Type} used to decode the raw string token.
+ * @param definition - Positional configuration.
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
+ * @param definition.type - Decoder for the raw token.
  * @returns A {@link Positional}`<Value>`.
  *
  * @example
@@ -99,7 +103,7 @@ export function positionalRequired<Value>(definition: {
         label: label as Uppercase<string>,
       };
     },
-    consumePositionals(readerPositionals: ReaderPositionals) {
+    consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positional = readerPositionals.consumePositional();
       if (positional === undefined) {
         throw new TypoError(
@@ -109,32 +113,27 @@ export function positionalRequired<Value>(definition: {
           ),
         );
       }
-      return decodeValue(label, definition.type, positional);
+      return {
+        decodeValue() {
+          return decodeValue(label, definition.type, positional);
+        },
+      };
     },
   };
 }
 
 /**
- * Creates an optional positional argument — one that may or may not appear on the
- * command line.
- *
- * The parser consumes the next available positional token. If no token is available,
- * `definition.default()` is called to supply the fallback value. If the default factory
- * throws, a {@link TypoError} is produced.
+ * Creates an optional positional — absent token falls back to `default()`.
+ * Label defaults to uppercased `type.content` in square brackets (e.g. `[STRING]`).
  *
- * The label displayed in the usage line defaults to the uppercased `type.content`
- * wrapped in square brackets (e.g. `[STRING]`). Supply `label` to override.
+ * @typeParam Value - Type produced by the decoder (or the default).
  *
- * @typeParam Value - The TypeScript type produced by the type decoder (or the default).
- *
- * @param definition - Configuration for the positional.
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.label - Custom label shown in the usage line (without square brackets).
- *   Defaults to the uppercased `type.content`.
- * @param definition.type - The {@link Type} used to decode the raw string token.
- * @param definition.default - Factory called when the positional is absent to supply the
- *   default value. Throw from this factory to make omission an error.
+ * @param definition - Positional configuration.
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
+ * @param definition.type - Decoder for the raw token.
+ * @param definition.default - Value when absent. Throw to make it required.
  * @returns A {@link Positional}`<Value>`.
  *
  * @example
@@ -165,52 +164,42 @@ export function positionalOptional<Value>(definition: {
         label: label as Uppercase<string>,
       };
     },
-    consumePositionals(readerPositionals: ReaderPositionals) {
+    consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positional = readerPositionals.consumePositional();
-      if (positional === undefined) {
-        try {
-          return definition.default();
-        } catch (error) {
-          throw new TypoError(
-            new TypoText(
-              new TypoString(label, typoStyleUserInput),
-              new TypoString(`: Failed to get default value`),
-            ),
-            error,
-          );
-        }
-      }
-      return decodeValue(label, definition.type, positional);
+      return {
+        decodeValue() {
+          if (positional === undefined) {
+            try {
+              return definition.default();
+            } catch (error) {
+              throw new TypoError(
+                new TypoText(
+                  new TypoString(label, typoStyleUserInput),
+                  new TypoString(`: Failed to get default value`),
+                ),
+                error,
+              );
+            }
+          }
+          return decodeValue(label, definition.type, positional);
+        },
+      };
     },
   };
 }
 
 /**
- * Creates a variadic positional argument — one that collects zero or more remaining
- * positional tokens into an array.
- *
- * The parser greedily consumes tokens until either there are no more tokens or it
- * encounters the optional `endDelimiter` sentinel string, which is consumed but not
- * included in the result. Each token is decoded independently with `definition.type`.
- *
- * If absent entirely, the result is an empty array `[]`.
+ * Creates a variadic positional that collects zero or more remaining tokens into an array.
+ * Stops at `endDelimiter` (consumed, not included). Label: `[TYPE]...` notation.
  *
- * The label displayed in the usage line defaults to the uppercased `type.content`
- * wrapped in square brackets followed by `...` (e.g. `[STRING]...`). When an
- * `endDelimiter` is configured, the delimiter is also shown (e.g. `[STRING]...["--"]`).
- * Supply `label` to override the base label.
+ * @typeParam Value - Type produced by the decoder for each token.
  *
- * @typeParam Value - The TypeScript type produced by the type decoder for each token.
- *
- * @param definition - Configuration for the variadic positional.
- * @param definition.endDelimiter - Optional sentinel string that signals the end of
- *   the variadic sequence (e.g. `"--"`). When encountered it is consumed but not
- *   included in the result array.
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.label - Custom label shown in the usage line (without brackets).
- *   Defaults to the uppercased `type.content`.
- * @param definition.type - The {@link Type} used to decode each raw string token.
+ * @param definition - Positional configuration.
+ * @param definition.endDelimiter - Sentinel token that stops collection (consumed, not included).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
+ * @param definition.type - Decoder applied to each token.
  * @returns A {@link Positional}`<Array<Value>>`.
  *
  * @example
@@ -243,8 +232,8 @@ export function positionalVariadics<Value>(definition: {
             : "")) as Uppercase<string>,
       };
     },
-    consumePositionals(readerPositionals: ReaderPositionals) {
-      const positionals: Array<Value> = [];
+    consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
+      const positionals = new Array<string>();
       while (true) {
         const positional = readerPositionals.consumePositional();
         if (
@@ -253,9 +242,15 @@ export function positionalVariadics<Value>(definition: {
         ) {
           break;
         }
-        positionals.push(decodeValue(label, definition.type, positional));
+        positionals.push(positional);
       }
-      return positionals;
+      return {
+        decodeValue() {
+          return positionals.map((positional) => {
+            return decodeValue(label, definition.type, positional);
+          });
+        },
+      };
     },
   };
 }
@@ -263,10 +258,10 @@ export function positionalVariadics<Value>(definition: {
 function decodeValue<Value>(
   label: string,
   type: Type<Value>,
-  value: string,
+  input: string,
 ): Value {
   return TypoError.tryWithContext(
-    () => type.decoder(value),
+    () => type.decoder(input),
     () =>
       new TypoText(
         new TypoString(label, typoStyleUserInput),

package/src/lib/Reader.ts

@@ -7,35 +7,26 @@ import {
 } from "./Typo";
 
 /**
- * An opaque key that uniquely identifies a registered CLI option within a
- * {@link ReaderArgs} instance.
- *
- * Keys are returned by {@link ReaderArgs.registerOption} and passed back to
- * {@link ReaderArgs.getOptionValues} to retrieve the parsed values. The internal
- * representation is intentionally opaque — treat it as a handle, not a string.
+ * Opaque key identifying a registered option within a {@link ReaderArgs} instance.
+ * Returned by {@link ReaderArgs.registerOption}; passed to {@link ReaderArgs.getOptionValues}.
  */
 export type ReaderOptionKey = (string | { __brand: "ReaderOptionKey" }) & {
   __brand: "ReaderOptionKey";
 };
 
 /**
- * Interface for registering and querying CLI options during argument parsing.
- *
- * {@link ReaderArgs} implements both `ReaderOptions` and {@link ReaderPositionals}.
- * The two interfaces are exposed separately so that option and positional parsing logic
- * can depend only on the capability they need.
+ * Option registration and query interface, implemented by {@link ReaderArgs}.
+ * Exposed separately from {@link ReaderPositionals} so parsers depend only on what they need.
  */
 export type ReaderOptions = {
   /**
-   * Registers a new option so the parser can recognise it when scanning argument tokens.
+   * Registers an option so the parser can recognise it.
    *
-   * @param definition.longs - The long-form names (without `--`) for this option.
-   * @param definition.shorts - The short-form names (without `-`) for this option.
-   * @param definition.valued - When `true`, the option consumes the following token as
-   *   its value. When `false`, the option is a boolean flag.
-   * @returns An opaque {@link ReaderOptionKey} used to retrieve parsed values later.
-   * @throws `Error` if any of the given names has already been registered, or if a
-   *   short name overlaps (is a prefix of, or has as a prefix, another registered short).
+   * @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.
+   * @returns A {@link ReaderOptionKey} for later retrieval.
+   * @throws `Error` if a name is already registered or short names overlap.
    */
   registerOption(definition: {
     longs: Array<string>;
@@ -45,48 +36,34 @@ export type ReaderOptions = {
   /**
    * Returns all values collected for the option identified by `key`.
    *
-   * @param key - The key returned by a prior {@link ReaderOptions.registerOption} call.
-   * @returns An array of raw string values, one per occurrence of the option on the
-   *   command line. Empty if the option was never provided.
-   * @throws `Error` if `key` was not previously registered on this instance.
+   * @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.
    */
   getOptionValues(key: ReaderOptionKey): Array<string>;
 };
 
 /**
- * Interface for consuming positional (non-option) argument tokens during parsing.
- *
- * {@link ReaderArgs} implements both {@link ReaderOptions} and `ReaderPositionals`.
+ * Positional token consumption interface, implemented by {@link ReaderArgs}.
  */
 export type ReaderPositionals = {
   /**
-   * Consumes and returns the next positional token from the argument list, skipping
-   * any option tokens (which are parsed as side-effects).
+   * Returns the next positional token, parsing intervening options as side-effects.
    *
-   * @returns The next positional string value, or `undefined` if no more positionals
-   *   are available.
-   * @throws {@link TypoError} if an unrecognised option token is encountered while
-   *   scanning for the next positional.
+   * @returns The next positional, or `undefined` when exhausted.
+   * @throws {@link TypoError} on an unrecognised option.
    */
   consumePositional(): string | undefined;
 };
 
 /**
- * The core argument parser for `cli-kiss`. Parses a flat array of raw CLI tokens into
- * named options and positional values.
+ * Core argument parser: converts raw CLI tokens into named options and positionals.
+ * Options must be registered before {@link ReaderArgs.consumePositional} is called.
  *
- * Options must be registered with {@link ReaderArgs.registerOption} **before**
- * {@link ReaderArgs.consumePositional} is called, because the parser needs to know
- * whether each token is an option name, an option value, or a bare positional.
+ * Supported syntax: `--name`, `--name value`, `--name=value`,
+ * `-n`, `-n value`, `-nvalue`, `-abc` (stacked), `--` (end-of-options).
  *
- * **Supported argument syntax:**
- * - Long options: `--name`, `--name value`, `--name=value`
- * - Short options: `-n`, `-n value`, `-n=value`, `-nvalue`, `-abc` (stacked flags)
- * - End-of-options separator: `--` — all subsequent tokens are treated as positionals.
- *
- * In most cases you do not need to use `ReaderArgs` directly; it is created internally
- * by {@link runAndExit}. It is exposed for advanced use cases such as building
- * custom runners.
+ * Created internally by {@link runAndExit}; exposed for advanced / custom runners.
  */
 export class ReaderArgs {
   #args: ReadonlyArray<string>;
@@ -98,8 +75,7 @@ export class ReaderArgs {
   #resultByKey: Map<ReaderOptionKey, Array<string>>;
 
   /**
-   * @param args - The raw command-line tokens to parse. Typically `process.argv.slice(2)`.
-   *   The array is not modified; a read cursor is maintained internally.
+   * @param args - Raw CLI tokens (e.g. `process.argv.slice(2)`). Not mutated.
    */
   constructor(args: ReadonlyArray<string>) {
     this.#args = args;
@@ -112,22 +88,15 @@ export class ReaderArgs {
   }
 
   /**
-   * Registers a CLI option so the parser can recognise it.
-   *
-   * All `longs` and `shorts` are associated with the same returned key. Calling
-   * `getOptionValues(key)` after parsing will return values collected under any of the
-   * registered names.
-   *
-   * Short names support stacking (e.g. `-abc` is parsed as `-a -b -c`) and inline
-   * values (e.g. `-nvalue`). Short names must not be a prefix of, nor have as a prefix,
-   * any other registered short name — the parser uses prefix matching to parse stacked
-   * shorts, so overlapping prefixes would be ambiguous.
+   * 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.
    *
    * @param definition.longs - Long-form names (without `--`).
    * @param definition.shorts - Short-form names (without `-`).
-   * @param definition.valued - `true` if the option consumes a value; `false` for flags.
-   * @returns An opaque {@link ReaderOptionKey} to pass to {@link ReaderArgs.getOptionValues}.
-   * @throws `Error` if any name is already registered or if two short names overlap.
+   * @param definition.valued - `true` if the option takes a value; `false` for flags.
+   * @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>;
@@ -139,12 +108,17 @@ export class ReaderArgs {
       ...definition.shorts.map((short) => `-${short}`),
     ].join(", ") as ReaderOptionKey;
     for (const long of definition.longs) {
+      if (!this.#isValidOptionName(long)) {
+        throw new Error(`Invalid option name: --${long}`);
+      }
       if (this.#keyByLong.has(long)) {
         throw new Error(`Option already registered: --${long}`);
       }
-      this.#keyByLong.set(long, key);
     }
     for (const short of definition.shorts) {
+      if (!this.#isValidOptionName(short)) {
+        throw new Error(`Invalid option name: -${short}`);
+      }
       if (this.#keyByShort.has(short)) {
         throw new Error(`Option already registered: -${short}`);
       }
@@ -163,6 +137,11 @@ export class ReaderArgs {
           );
         }
       }
+    }
+    for (const long of definition.longs) {
+      this.#keyByLong.set(long, key);
+    }
+    for (const short of definition.shorts) {
       this.#keyByShort.set(short, key);
     }
     this.#valuedByKey.set(key, definition.valued);
@@ -171,13 +150,11 @@ export class ReaderArgs {
   }
 
   /**
-   * Returns all raw string values collected for the given option key.
+   * Returns all values collected for the option key.
    *
-   * @param key - A key previously returned by {@link ReaderArgs.registerOption}.
-   * @returns An array of string values, one per occurrence on the command line. For
-   *   flags this will be `["true"]` per occurrence; for valued options it will be the
-   *   literal value strings.
-   * @throws `Error` if `key` was not registered on this instance.
+   * @param key - Key from {@link ReaderArgs.registerOption}.
+   * @returns String values, one per occurrence.
+   * @throws `Error` if `key` was not registered.
    */
   getOptionValues(key: ReaderOptionKey): Array<string> {
     const optionResult = this.#resultByKey.get(key);
@@ -188,18 +165,12 @@ export class ReaderArgs {
   }
 
   /**
-   * Scans forward through the argument list and returns the next bare positional token,
-   * consuming and parsing any intervening option tokens as side-effects.
-   *
-   * Option tokens encountered during the scan are recorded in the internal results map
-   * (equivalent to recording their values against their key). Any unrecognised option token
-   * causes a {@link TypoError} to be thrown immediately.
-   *
-   * After `--` is encountered, all remaining tokens are treated as positionals.
+   * Returns the next bare positional token.
+   * Parse intervening options as side-effects.
+   * All tokens after `--` are treated as positionals.
    *
-   * @returns The next positional string, or `undefined` when the argument list is
-   *   exhausted.
-   * @throws {@link TypoError} if an unrecognised option (long or short) is encountered.
+   * @returns The next positional, or `undefined` when exhausted.
+   * @throws {@link TypoError} on an unrecognised option.
    */
   consumePositional(): string | undefined {
     while (true) {
@@ -348,4 +319,8 @@ export class ReaderArgs {
   #acknowledgeOption(key: ReaderOptionKey, value: string) {
     this.getOptionValues(key).push(value);
   }
+
+  #isValidOptionName(name: string): boolean {
+    return name.length > 0 && !name.includes("=");
+  }
 }