cli-kiss 0.2.2 → 0.2.4

package/src/lib/Positional.ts

@@ -7,85 +7,52 @@ import {
   typoStyleUserInput,
   TypoText,
 } from "./Typo";
+import { UsagePositional } from "./Usage";
 
 /**
- * Describes a single positional argument — a bare (non-option) token on the command
- * line — together with its parsing and usage-generation logic.
+ * A positional argument. Created with {@link positionalRequired}, {@link positionalOptional},
+ * or {@link positionalVariadics}.
  *
- * 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.
- *
- * @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. */
-  generateUsage(): PositionalUsage;
   /**
-   * Consumes the positional from `readerPositionals` and then returns a parser that produces the final decoded value.
-   *
-   * The parser is created during {@link Operation.createFactory} and may throw a
-   * {@link TypoError} if the positional is missing (when required) or if decoding fails.
-   * @param readerPositionals - The source of positional arguments to be consumed.
+   * Returns metadata for the `Positionals:` section.
    */
-  createParser(readerPositionals: ReaderPositionals): PositionalParser<Value>;
-};
-
-/**
- * Retrieves the parsed value for a positional argument after parsing is complete.
- *
- * Returned by {@link Positional.createParser} and called by {@link OperationFactory.createInstance}.
- *
- * @typeParam Value - The TypeScript type of the parsed value.
- */
-export type PositionalParser<Value> = {
+  generateUsage(): UsagePositional;
   /**
-   * Returns the fully decoded and validated value for the positional
-   *
-   * @throws {@link TypoError} if the positional was missing (when required) or if decoding failed.
+   * Consumes the next positional token from `readerPositionals`.
+   * Returns a decoder that produces the final value.
    */
-  parseValue(): Value;
+  consumeAndMakeDecoder(
+    readerPositionals: ReaderPositionals,
+  ): PositionalDecoder<Value>;
 };
 
 /**
- * Human-readable metadata for a single positional argument, used to render the
- * `Positionals:` section of the help output produced by {@link usageToStyledLines}.
+ * Produced by {@link Positional.consumeAndMakeDecoder}.
+ *
+ * @typeParam Value - Decoded value type.
  */
-export type PositionalUsage = {
-  /** Short description of what the positional represents. */
-  description: string | undefined;
+export type PositionalDecoder<Value> = {
   /**
-   * Optional supplementary note shown in parentheses next to the description.
-   * Suitable for short caveats such as `"defaults to 'world'"`.
-   */
-  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]..."`).
+   * Returns the decoded positional value.
+   *
+   * @throws {@link TypoError} if decoding failed.
    */
-  label: Uppercase<string>;
+  decodeValue(): Value;
 };
 
 /**
- * Creates a required positional argument — one that must be present on the command line.
- *
- * 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 Operation.createFactory}).
- *
- * The label displayed in the usage line defaults to the uppercased `type.content`
- * wrapped in angle brackets (e.g. `<STRING>`). Supply `label` to override.
+ * Creates a required positional — missing token throws {@link TypoError}.
+ * Label defaults to uppercased `type.content` in angle brackets (e.g. `<STRING>`).
  *
- * @typeParam Value - The TypeScript type produced by the type decoder.
+ * @typeParam Value - Type produced by the 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.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
@@ -113,7 +80,7 @@ export function positionalRequired<Value>(definition: {
         label: label as Uppercase<string>,
       };
     },
-    createParser(readerPositionals: ReaderPositionals) {
+    consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positional = readerPositionals.consumePositional();
       if (positional === undefined) {
         throw new TypoError(
@@ -124,7 +91,7 @@ export function positionalRequired<Value>(definition: {
         );
       }
       return {
-        parseValue() {
+        decodeValue() {
           return decodeValue(label, definition.type, positional);
         },
       };
@@ -133,26 +100,16 @@ export function positionalRequired<Value>(definition: {
 }
 
 /**
- * Creates an optional positional argument — one that may or may not appear on the
- * command line.
+ * Creates an optional positional — absent token falls back to `default()`.
+ * Label defaults to uppercased `type.content` in square brackets (e.g. `[STRING]`).
  *
- * 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.
+ * @typeParam Value - Type produced by the decoder (or the default).
  *
- * 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 - 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.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
@@ -183,10 +140,10 @@ export function positionalOptional<Value>(definition: {
         label: label as Uppercase<string>,
       };
     },
-    createParser(readerPositionals: ReaderPositionals) {
+    consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positional = readerPositionals.consumePositional();
       return {
-        parseValue() {
+        decodeValue() {
           if (positional === undefined) {
             try {
               return definition.default();
@@ -208,31 +165,16 @@ export function positionalOptional<Value>(definition: {
 }
 
 /**
- * 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 `[]`.
- *
- * 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.
+ * Creates a variadic positional that collects zero or more remaining tokens into an array.
+ * Stops at `endDelimiter` (consumed, not included). Label: `[TYPE]...` notation.
  *
- * @typeParam Value - The TypeScript type produced by the type decoder for each token.
+ * @typeParam Value - Type produced by the 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.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
@@ -261,11 +203,11 @@ export function positionalVariadics<Value>(definition: {
         hint: definition.hint,
         label: (`${label}...` +
           (definition.endDelimiter
-            ? `["${definition.endDelimiter}"]`
+            ? ` ["${definition.endDelimiter}"]`
             : "")) as Uppercase<string>,
       };
     },
-    createParser(readerPositionals: ReaderPositionals) {
+    consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positionals = new Array<string>();
       while (true) {
         const positional = readerPositionals.consumePositional();
@@ -278,10 +220,10 @@ export function positionalVariadics<Value>(definition: {
         positionals.push(positional);
       }
       return {
-        parseValue() {
-          return positionals.map((positional) => {
-            return decodeValue(label, definition.type, positional);
-          });
+        decodeValue() {
+          return positionals.map((positional) =>
+            decodeValue(label, definition.type, positional),
+          );
         },
       };
     },
@@ -291,10 +233,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),