cli-kiss 0.2.1 → 0.2.3

package/src/lib/Operation.ts

@@ -1,114 +1,89 @@
-import { Option, OptionUsage } from "./Option";
-import { Positional, PositionalUsage } from "./Positional";
+import { Option, OptionDecoder, OptionUsage } from "./Option";
+import { Positional, PositionalDecoder, PositionalUsage } from "./Positional";
 import { ReaderArgs } from "./Reader";
 
 /**
- * Describes an operation — the combination of options, positional arguments, and an
- * async execution handler that together form the core logic of a CLI command.
+ * Options, positionals, and an async handler that together form the logic of a CLI command.
  *
- * An `OperationDescriptor` is created with {@link operation} and passed to
- * {@link command}, {@link commandWithSubcommands}, or {@link commandChained} to build
- * a full {@link CommandDescriptor}.
+ * Created with {@link operation} and passed to {@link command},
+ * {@link commandWithSubcommands}, or {@link commandChained}.
  *
- * @typeParam Input - The context value the handler receives at execution time (forwarded
- *   from the parent command's context or from a preceding chained operation).
- * @typeParam Output - The value the handler produces. For leaf operations this is
- *   typically `void`; for intermediate stages it is the payload forwarded to the next
- *   command in a chain.
+ * @typeParam Context - Injected at execution time; forwarded to handlers. Use to inject dependencies.
+ * @typeParam Result - Value produced on execution; typically `void` for leaf commands.
  */
-export type OperationDescriptor<Input, Output> = {
+export type Operation<Context, Result> = {
   /**
-   * Returns usage metadata (options and positionals) without consuming any arguments.
-   * Called by the parent command factory when building the help/usage output.
+   * Returns usage metadata without consuming any arguments.
    */
   generateUsage(): OperationUsage;
   /**
-   * Parses options and positionals from `readerArgs` and returns an
-   * {@link OperationFactory} that can create a ready-to-execute
-   * {@link OperationInstance}.
-   *
-   * Any parse error (unknown option, type mismatch, etc.) is captured and re-thrown
-   * when {@link OperationFactory.createInstance} is called.
-   *
-   * @param readerArgs - The shared argument reader. Options are registered on it and
-   *   positionals are consumed in declaration order.
+   * Consumes args from `readerArgs` and returns an {@link OperationDecoder}.
    */
-  createFactory(readerArgs: ReaderArgs): OperationFactory<Input, Output>;
+  consumeAndMakeDecoder(
+    readerArgs: ReaderArgs,
+  ): OperationDecoder<Context, Result>;
 };
 
 /**
- * Produced by {@link OperationDescriptor.createFactory} after argument parsing.
- * Instantiating it finalises value extraction and produces an {@link OperationInstance}.
+ * Produced by {@link Operation.consumeAndMakeDecoder}.
  *
- * @typeParam Input - Forwarded from the parent {@link OperationDescriptor}.
- * @typeParam Output - Forwarded from the parent {@link OperationDescriptor}.
+ * @typeParam Context - See {@link Operation}.
+ * @typeParam Result - See {@link Operation}.
  */
-export type OperationFactory<Input, Output> = {
+export type OperationDecoder<Context, Result> = {
   /**
-   * Extracts the final parsed values for all options and returns an
-   * {@link OperationInstance} ready for execution.
+   * Creates a ready-to-execute {@link OperationInterpreter}.
    *
-   * @throws {@link TypoError} if any option or positional validation failed during
-   *   {@link OperationDescriptor.createFactory}.
+   * @throws {@link TypoError} if parsing or decoding failed.
    */
-  createInstance(): OperationInstance<Input, Output>;
+  decodeAndMakeInterpreter(): OperationInterpreter<Context, Result>;
 };
 
 /**
- * A fully parsed, ready-to-execute operation.
+ * A fully parsed, decoded and ready-to-execute operation.
  *
- * @typeParam Input - The value the caller must supply as context.
- * @typeParam Output - The value produced on successful execution.
+ * @typeParam Context - Caller-supplied context.
+ * @typeParam Result - Value produced on success.
  */
-export type OperationInstance<Input, Output> = {
+export type OperationInterpreter<Context, Result> = {
   /**
-   * Runs the operation handler with the provided input context and the parsed
-   * option/positional values.
-   *
-   * @param input - Context from the parent command (or the root context supplied to
-   *   {@link runAndExit}).
-   * @returns A promise resolving to the handler's return value.
+   * Executes with the provided context.
    */
-  executeWithContext(input: Input): Promise<Output>;
+  executeWithContext(context: Context): Promise<Result>;
 };
 
 /**
- * Collected usage metadata produced by {@link OperationDescriptor.generateUsage}.
- * Consumed by the parent command factory when building {@link CommandUsage}.
+ * Usage metadata produced by {@link Operation.generateUsage}.
+ * Consumed when building {@link CommandUsage}.
  */
 export type OperationUsage = {
-  /** Usage descriptors for all options registered by this operation. */
+  /**
+   * Usage descriptors for all registered options.
+   */
   options: Array<OptionUsage>;
-  /** Usage descriptors for all positionals declared by this operation, in order. */
+  /**
+   * Usage descriptors for all declared positionals, in order.
+   */
   positionals: Array<PositionalUsage>;
 };
 
 /**
- * Creates an {@link OperationDescriptor} from a set of options, positionals, and an
- * async handler function.
+ * Creates an {@link Operation} from options, positionals, and an async handler.
  *
- * The `handler` receives:
- * - `context` — the value passed down from the parent command (or from
- *   {@link runAndExit}).
- * - `inputs.options` — an object whose keys match those declared in `inputs.options` and whose values are
- *   the parsed option values.
- * - `inputs.positionals` — a tuple whose elements match `inputs.positionals` and whose
- *   values are the parsed positional values, in declaration order.
+ * The `handler` receives the parent `context` and an `inputs` object with
+ * `options` (keyed by the same names declared in `inputs.options`) and
+ * `positionals` (a tuple in declaration order).
  *
- * @typeParam Context - The context type accepted by the handler.
- * @typeParam Result - The return type of the handler.
- * @typeParam Options - Object type mapping option keys to their parsed value types.
- * @typeParam Positionals - Tuple type of parsed positional value types, in order.
+ * @typeParam Context - Context type accepted by the handler.
+ * @typeParam Result - Return type of the handler.
+ * @typeParam Options - Map of option keys to parsed value types.
+ * @typeParam Positionals - Tuple of parsed positional value types, in order.
  *
- * @param inputs - Declares the options and positionals this operation accepts.
- * @param inputs.options - A map from arbitrary keys to {@link Option} descriptors.
- *   The same keys appear in `handler`'s `inputs.options` argument.
- * @param inputs.positionals - An ordered array of {@link Positional} descriptors.
- *   Their parsed values appear in `handler`'s `inputs.positionals` argument, in the
- *   same order.
- * @param handler - The async function that implements the command logic. Receives the
- *   execution context and all parsed inputs.
- * @returns An {@link OperationDescriptor} ready to be composed into a command.
+ * @param inputs - Options and positionals this operation accepts.
+ * @param inputs.options - Map of keys to {@link Option} descriptors.
+ * @param inputs.positionals - Ordered array of {@link Positional} descriptors.
+ * @param handler - Async function implementing the command logic.
+ * @returns An {@link Operation} ready to be composed into a command.
  *
  * @example
  * ```ts
@@ -140,9 +115,12 @@ export function operation<
   },
   handler: (
     context: Context,
-    inputs: { options: Options; positionals: Positionals },
+    inputs: {
+      options: Options;
+      positionals: Positionals;
+    },
   ) => Promise<Result>,
-): OperationDescriptor<Context, Result> {
+): Operation<Context, Result> {
   return {
     generateUsage() {
       const optionsUsage = new Array<OptionUsage>();
@@ -158,21 +136,29 @@ export function operation<
       }
       return { options: optionsUsage, positionals: positionalsUsage };
     },
-    createFactory(readerArgs: ReaderArgs) {
-      const optionsGetters: any = {};
+    consumeAndMakeDecoder(readerArgs: ReaderArgs) {
+      const optionsDecoders: Record<string, OptionDecoder<any>> = {};
       for (const optionKey in inputs.options) {
         const optionInput = inputs.options[optionKey]!;
-        optionsGetters[optionKey] = optionInput.createGetter(readerArgs);
+        optionsDecoders[optionKey] =
+          optionInput.registerAndMakeDecoder(readerArgs);
       }
-      const positionalsValues: any = [];
+      const positionalsDecoders: Array<PositionalDecoder<any>> = [];
       for (const positionalInput of inputs.positionals) {
-        positionalsValues.push(positionalInput.consumePositionals(readerArgs));
+        positionalsDecoders.push(
+          positionalInput.consumeAndMakeDecoder(readerArgs),
+        );
       }
       return {
-        createInstance() {
+        decodeAndMakeInterpreter() {
           const optionsValues: any = {};
-          for (const optionKey in optionsGetters) {
-            optionsValues[optionKey] = optionsGetters[optionKey]!.getValue();
+          for (const optionKey in optionsDecoders) {
+            optionsValues[optionKey] =
+              optionsDecoders[optionKey]!.getAndDecodeValue();
+          }
+          const positionalsValues: any = [];
+          for (const positionalDecoder of positionalsDecoders) {
+            positionalsValues.push(positionalDecoder.decodeValue());
           }
           return {
             executeWithContext(context: Context) {

package/src/lib/Option.ts

@@ -10,95 +10,78 @@ import {
 } from "./Typo";
 
 /**
- * Describes a single CLI option (a flag or a valued option) together with its parsing
- * and usage-generation logic.
+ * A CLI option (flag or valued) with its parsing and usage-generation logic.
  *
- * Options are created with {@link optionFlag}, {@link optionSingleValue}, or
- * {@link optionRepeatable} and are passed via the `options` map of {@link operation}.
+ * Created with {@link optionFlag}, {@link optionSingleValue}, or
+ * {@link optionRepeatable} and passed via the `options` map of {@link operation}.
  *
- * @typeParam Value - The TypeScript type of the parsed option value.
- *   - `boolean` for flags created with {@link optionFlag}.
- *   - `T` for single-value options created with {@link optionSingleValue}.
- *   - `Array<T>` for repeatable options created with {@link optionRepeatable}.
+ * @typeParam Value - Decoded value type.
  */
 export type Option<Value> = {
-  /** Returns human-readable metadata used to render the `Options:` section of help. */
+  /**
+   * Returns metadata used to render the `Options:` section of help.
+   */
   generateUsage(): OptionUsage;
   /**
-   * Registers the option on `readerOptions` so the argument reader recognises it, and
-   * returns an {@link OptionGetter} that can later retrieve the parsed value(s).
+   * Registers the option on `readerOptions` and returns an {@link OptionDecoder}.
+   */
+  registerAndMakeDecoder(readerOptions: ReaderOptions): OptionDecoder<Value>;
+};
+
+/**
+ * Produced by {@link Option.registerAndMakeDecoder}.
+ *
+ * @typeParam Value - Decoded value type.
+ */
+export type OptionDecoder<Value> = {
+  /**
+   * Returns the decoded option value.
    *
-   * @param readerOptions - The shared {@link ReaderArgs} that will parse the raw
-   *   command-line tokens.
+   * @throws {@link TypoError} if decoding failed.
    */
-  createGetter(readerOptions: ReaderOptions): OptionGetter<Value>;
+  getAndDecodeValue(): Value;
 };
 
 /**
- * Human-readable metadata for a single CLI option, used to render the `Options:` section
+ * Human-readable metadata for a single option, used to render the `Options:` section
  * of the help output produced by {@link usageToStyledLines}.
  */
 export type OptionUsage = {
-  /** Short description of what the option does. */
-  description: string | undefined;
   /**
-   * Optional supplementary note shown in parentheses next to the description.
-   * Suitable for short caveats such as `"required"` or `"defaults to 42"`.
+   * Long-form name without `--` (e.g. `"verbose"`).
    */
-  hint: string | undefined;
+  long: Lowercase<string>;
   /**
-   * The primary long-form name of the option, without the `--` prefix (e.g. `"verbose"`).
-   * The user passes this as `--verbose` on the command line.
+   * Short-form name without `-` (e.g. `"v"`).
    */
-  long: Lowercase<string>; // TODO - better type for long option names ?
+  short: string | undefined;
   /**
-   * The optional short-form name of the option, without the `-` prefix (e.g. `"v"`).
-   * The user passes this as `-v` on the command line.
+   * Help text in usage.
    */
-  short: string | undefined;
+  description: string | undefined;
   /**
-   * The value placeholder label shown after the long option name in the help output
-   * (e.g. `"<FILE>"`). `undefined` for flags that take no value.
+   * Short note shown in parentheses.
    */
-  label: Uppercase<string> | undefined;
-};
-
-/**
- * Retrieves the parsed value for a registered option after argument parsing is complete.
- *
- * Returned by {@link Option.createGetter} and called by {@link OperationFactory.createInstance}.
- *
- * @typeParam Value - The TypeScript type of the parsed value.
- */
-export type OptionGetter<Value> = {
+  hint: string | undefined;
   /**
-   * Returns the fully decoded and validated value for the option.
-   *
-   * @throws {@link TypoError} if the option appeared more times than allowed, the value
-   *   failed type decoding, or a required default could not be computed.
+   * Value placeholder in help (e.g. `"<FILE>"`). `undefined` for flags.
    */
-  getValue(): Value;
+  label: Uppercase<string> | undefined;
 };
 
 /**
- * Creates a boolean flag option — an option that the user passes without a value (e.g.
- * `--verbose`) to signal `true`, or can explicitly set with `--flag=true` / `--flag=no`.
+ * Creates a boolean flag option (`--verbose`, optionally `--flag=no`).
  *
- * **Parsing rules:**
- * - Absent → `false` (or the return value of `default()` when provided).
- * - `--flag` / `--flag=true` / `--flag=yes` → `true`.
- * - `--flag=false` / `--flag=no` → `false`.
- * - Specified more than once → {@link TypoError} ("Must not be set multiple times").
+ * Parsing: absent → `false`; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
+ * specified more than once → {@link TypoError}.
  *
- * @param definition - Configuration for the flag.
- * @param definition.long - Primary long-form name (without `--`). Must be lowercase.
- * @param definition.short - Optional short-form name (without `-`).
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.aliases - Additional long/short names that the parser also
- *   recognises as this flag.
- * @param definition.default - Factory for the default value when the flag is absent.
- *   Defaults to `() => false` when omitted.
+ * @param definition - Flag configuration.
+ * @param definition.long - Long-form name (without `--`).
+ * @param definition.short - Short-form name (without `-`).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.aliases - Additional names.
+ * @param definition.default - Default when absent. Defaults to `() => false`.
  * @returns An {@link Option}`<boolean>`.
  *
  * @example
@@ -129,13 +112,13 @@ export function optionFlag(definition: {
         label: undefined,
       };
     },
-    createGetter(readerOptions: ReaderOptions) {
+    registerAndMakeDecoder(readerOptions: ReaderOptions) {
       const key = registerOption(readerOptions, {
         ...definition,
         valued: false,
       });
       return {
-        getValue() {
+        getAndDecodeValue() {
           const optionValues = readerOptions.getOptionValues(key);
           if (optionValues.length > 1) {
             throw new TypoError(
@@ -159,7 +142,13 @@ export function optionFlag(definition: {
               );
             }
           }
-          return decodeValue(definition.long, label, typeBoolean, optionValue);
+          return decodeValue({
+            long: definition.long,
+            short: definition.short,
+            label,
+            type: typeBoolean,
+            input: optionValue,
+          });
         },
       };
     },
@@ -167,32 +156,22 @@ export function optionFlag(definition: {
 }
 
 /**
- * Creates an option that accepts exactly one value (e.g. `--output dist/` or
- * `--output=dist/`).
+ * Creates an option that accepts exactly one value (e.g. `--output dist/`).
  *
- * **Parsing rules:**
- * - Absent → `definition.default()` is called. If the default factory throws, a
- *   {@link TypoError} is produced.
- * - Specified once → the value is decoded with `definition.type`.
- * - Specified more than once → {@link TypoError} ("Requires a single value, but got
- *   multiple").
+ * Parsing: absent → `default()`; once → decoded with `type`; more than once → {@link TypoError}.
+ * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
  *
- * **Value syntax:** `--long value`, `--long=value`, or (if `short` is set) `-s value`,
- * `-s=value`, or `-svalue`.
+ * @typeParam Value - Type produced by the decoder.
  *
- * @typeParam Value - The TypeScript type produced by the type decoder.
- *
- * @param definition - Configuration for the option.
- * @param definition.long - Primary long-form name (without `--`). Must be lowercase.
- * @param definition.short - Optional short-form name (without `-`).
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.aliases - Additional long/short names the parser also recognises.
- * @param definition.label - Custom label shown in the help output (e.g. `"FILE"`).
- *   Defaults to the uppercased `type.content`.
- * @param definition.type - The {@link Type} used to decode the raw string value.
- * @param definition.default - Factory for the default value when the option is absent.
- *   Throw an error from this factory to make the option effectively required.
+ * @param definition - Option configuration.
+ * @param definition.long - Long-form name (without `--`).
+ * @param definition.short - Short-form name (without `-`).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.aliases - Additional names.
+ * @param definition.label - Value placeholder in help. Defaults to uppercased `type.content`.
+ * @param definition.type - Decoder for the raw string value.
+ * @param definition.default - Default when absent. Throw to make the option required.
  * @returns An {@link Option}`<Value>`.
  *
  * @example
@@ -228,13 +207,13 @@ export function optionSingleValue<Value>(definition: {
         label: label as Uppercase<string>,
       };
     },
-    createGetter(readerOptions: ReaderOptions) {
+    registerAndMakeDecoder(readerOptions: ReaderOptions) {
       const key = registerOption(readerOptions, {
         ...definition,
         valued: true,
       });
       return {
-        getValue() {
+        getAndDecodeValue() {
           const optionValues = readerOptions.getOptionValues(key);
           if (optionValues.length > 1) {
             throw new TypoError(
@@ -258,12 +237,13 @@ export function optionSingleValue<Value>(definition: {
               );
             }
           }
-          return decodeValue(
-            definition.long,
+          return decodeValue({
+            long: definition.long,
+            short: definition.short,
             label,
-            definition.type,
-            optionValue,
-          );
+            type: definition.type,
+            input: optionValue,
+          });
         },
       };
     },
@@ -271,30 +251,21 @@ export function optionSingleValue<Value>(definition: {
 }
 
 /**
- * Creates an option that can be specified any number of times, collecting all provided
- * values into an array (e.g. `--file a.ts --file b.ts`).
+ * Creates an option that collects every occurrence into an array (e.g. `--file a.ts --file b.ts`).
  *
- * **Parsing rules:**
- * - Absent → empty array `[]`.
- * - Specified N times → array of N decoded values, in the order they appear on the
- *   command line.
- * - Each occurrence is decoded independently with `definition.type`.
+ * Parsing: absent → `[]`; N occurrences → array of N decoded values in order.
+ * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
  *
- * **Value syntax:** `--long value`, `--long=value`, or (if `short` is set) `-s value`,
- * `-s=value`, or `-svalue`.
+ * @typeParam Value - Type produced by the decoder for each occurrence.
  *
- * @typeParam Value - The TypeScript type produced by the type decoder for each
- *   occurrence.
- *
- * @param definition - Configuration for the option.
- * @param definition.long - Primary long-form name (without `--`). Must be lowercase.
- * @param definition.short - Optional short-form name (without `-`).
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.aliases - Additional long/short names the parser also recognises.
- * @param definition.label - Custom label shown in the help output (e.g. `"FILE"`).
- *   Defaults to the uppercased `type.content`.
- * @param definition.type - The {@link Type} used to decode each raw string value.
+ * @param definition - Option configuration.
+ * @param definition.long - Long-form name (without `--`).
+ * @param definition.short - Short-form name (without `-`).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.aliases - Additional names.
+ * @param definition.label - Value placeholder in help. Defaults to uppercased `type.content`.
+ * @param definition.type - Decoder applied to each raw string value.
  * @returns An {@link Option}`<Array<Value>>`.
  *
  * @example
@@ -330,16 +301,22 @@ export function optionRepeatable<Value>(definition: {
         label: label as Uppercase<string>,
       };
     },
-    createGetter(readerOptions: ReaderOptions) {
+    registerAndMakeDecoder(readerOptions: ReaderOptions) {
       const key = registerOption(readerOptions, {
         ...definition,
         valued: true,
       });
       return {
-        getValue() {
+        getAndDecodeValue() {
           const optionValues = readerOptions.getOptionValues(key);
           return optionValues.map((optionValue) =>
-            decodeValue(definition.long, label, definition.type, optionValue),
+            decodeValue({
+              long: definition.long,
+              short: definition.short,
+              label,
+              type: definition.type,
+              input: optionValue,
+            }),
           );
         },
       };
@@ -347,22 +324,28 @@ export function optionRepeatable<Value>(definition: {
   };
 }
 
-function decodeValue<Value>(
-  long: string,
-  label: string,
-  type: Type<Value>,
-  value: string,
-): Value {
+function decodeValue<Value>(params: {
+  long: string;
+  short: string | undefined;
+  label: string;
+  type: Type<Value>;
+  input: string;
+}): Value {
   return TypoError.tryWithContext(
-    () => type.decoder(value),
-    () =>
-      new TypoText(
-        new TypoString(`--${long}`, typoStyleConstants),
-        new TypoString(`: `),
-        new TypoString(label, typoStyleUserInput),
-        new TypoString(`: `),
-        new TypoString(type.content, typoStyleLogic),
-      ),
+    () => params.type.decoder(params.input),
+    () => {
+      const text = new TypoText();
+      if (params.short) {
+        text.pushString(new TypoString(`-${params.short}`, typoStyleConstants));
+        text.pushString(new TypoString(`, `));
+      }
+      text.pushString(new TypoString(`--${params.long}`, typoStyleConstants));
+      text.pushString(new TypoString(`: `));
+      text.pushString(new TypoString(params.label, typoStyleUserInput));
+      text.pushString(new TypoString(`: `));
+      text.pushString(new TypoString(params.type.content, typoStyleLogic));
+      return text;
+    },
   );
 }