cli-kiss 0.2.2 → 0.2.4

package/src/lib/Operation.ts

@@ -1,113 +1,73 @@
-import { Option, OptionParser, OptionUsage } from "./Option";
-import { Positional, PositionalParser, PositionalUsage } from "./Positional";
+import { Option, OptionDecoder } from "./Option";
+import { Positional, PositionalDecoder } from "./Positional";
 import { ReaderArgs } from "./Reader";
+import { UsageOperation, UsageOption, UsagePositional } from "./Usage";
 
 /**
- * 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 `Operation` is created with {@link operation} and passed to
- * {@link command}, {@link commandWithSubcommands}, or {@link commandChained} to build
- * a full {@link Command}.
+ * 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; forwarded to handlers.
+ * @typeParam Result - Value produced on execution; typically `void`.
  */
-export type Operation<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;
+  generateUsage(): UsageOperation;
   /**
-   * 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 Operation.createFactory} after argument parsing.
- * Instantiating it finalises value extraction and produces an {@link OperationInstance}.
+ * Produced by {@link Operation.consumeAndMakeDecoder}.
  *
- * @typeParam Input - operation instance input type {@link Operation}.
- * @typeParam Output - operation instance output type {@link Operation}.
+ * @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 Operation.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>;
-};
-
-/**
- * Collected usage metadata produced by {@link Operation.generateUsage}.
- * Consumed by the parent command factory when building {@link CommandUsage}.
- */
-export type OperationUsage = {
-  /** Usage descriptors for all options registered by this operation. */
-  options: Array<OptionUsage>;
-  /** Usage descriptors for all positionals declared by this operation, in order. */
-  positionals: Array<PositionalUsage>;
+  executeWithContext(context: Context): Promise<Result>;
 };
 
 /**
- * Creates an {@link Operation} 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.
- * - `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 `context` and `inputs` with decoded `options` and `positionals`.
  *
- * @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 Operation} 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}.
  *
  * @example
  * ```ts
@@ -120,7 +80,7 @@ export type OperationUsage = {
  *       positionalRequired({ type: typeString, label: "NAME", description: "Name to greet" }),
  *     ],
  *   },
- *   async (_ctx, { options: { loud }, positionals: [name] }) => {
+ *   async function (_ctx, { options: { loud }, positionals: [name] }) {
  *     const message = `Hello, ${name}!`;
  *     console.log(loud ? message.toUpperCase() : message);
  *   },
@@ -147,38 +107,40 @@ export function operation<
 ): Operation<Context, Result> {
   return {
     generateUsage() {
-      const optionsUsage = new Array<OptionUsage>();
+      const optionsUsage = new Array<UsageOption>();
       for (const optionKey in inputs.options) {
         const optionInput = inputs.options[optionKey]!;
-        if (optionInput) {
-          optionsUsage.push(optionInput.generateUsage());
-        }
+        optionsUsage.push(optionInput.generateUsage());
       }
-      const positionalsUsage = new Array<PositionalUsage>();
+      const positionalsUsage = new Array<UsagePositional>();
       for (const positionalInput of inputs.positionals) {
         positionalsUsage.push(positionalInput.generateUsage());
       }
       return { options: optionsUsage, positionals: positionalsUsage };
     },
-    createFactory(readerArgs: ReaderArgs) {
-      const optionsGetters: Record<string, OptionParser<any>> = {};
+    consumeAndMakeDecoder(readerArgs: ReaderArgs) {
+      const optionsDecoders: Record<string, OptionDecoder<any>> = {};
       for (const optionKey in inputs.options) {
         const optionInput = inputs.options[optionKey]!;
-        optionsGetters[optionKey] = optionInput.createParser(readerArgs);
+        optionsDecoders[optionKey] =
+          optionInput.registerAndMakeDecoder(readerArgs);
       }
-      const positionalsParsers: Array<PositionalParser<any>> = [];
+      const positionalsDecoders: Array<PositionalDecoder<any>> = [];
       for (const positionalInput of inputs.positionals) {
-        positionalsParsers.push(positionalInput.createParser(readerArgs));
+        positionalsDecoders.push(
+          positionalInput.consumeAndMakeDecoder(readerArgs),
+        );
       }
       return {
-        createInstance() {
+        decodeAndMakeInterpreter() {
           const optionsValues: any = {};
-          for (const optionKey in optionsGetters) {
-            optionsValues[optionKey] = optionsGetters[optionKey]!.parseValue();
+          for (const optionKey in optionsDecoders) {
+            optionsValues[optionKey] =
+              optionsDecoders[optionKey]!.getAndDecodeValue();
           }
           const positionalsValues: any = [];
-          for (const positionalParser of positionalsParsers) {
-            positionalsValues.push(positionalParser.parseValue());
+          for (const positionalDecoder of positionalsDecoders) {
+            positionalsValues.push(positionalDecoder.decodeValue());
           }
           return {
             executeWithContext(context: Context) {