cli-kiss 0.1.0 → 0.1.2

package/src/lib/Command.ts

@@ -5,24 +5,29 @@ import { ReaderArgs } from "./Reader";
 import { TypoError, TypoString, typoStyleConstants, TypoText } from "./Typo";
 
 export type Command<Context, Result> = {
-  getDescription(): string | undefined;
-  createRunnerFromArgs(readerArgs: ReaderArgs): CommandRunner<Context, Result>;
+  getInformation(): CommandInformation;
+  createFactory(readerArgs: ReaderArgs): CommandFactory<Context, Result>;
 };
 
-export type CommandRunner<Context, Result> = {
+export type CommandFactory<Context, Result> = {
   generateUsage(): CommandUsage;
+  createInstance(): CommandInstance<Context, Result>;
+};
+
+export type CommandInstance<Context, Result> = {
   executeWithContext(context: Context): Promise<Result>;
 };
 
-export type CommandMetadata = {
+export type CommandInformation = {
   description: string;
+  hint?: string;
   details?: string;
   // TODO - printable examples ?
 };
 
 export type CommandUsage = {
-  metadata: CommandMetadata;
   breadcrumbs: Array<CommandUsageBreadcrumb>;
+  information: CommandInformation;
   positionals: Array<PositionalUsage>;
   subcommands: Array<CommandUsageSubcommand>;
   options: Array<OptionUsage>;
@@ -35,45 +40,51 @@ export type CommandUsageBreadcrumb =
 export type CommandUsageSubcommand = {
   name: string;
   description: string | undefined;
+  hint: string | undefined;
 };
 
 export function command<Context, Result>(
-  metadata: CommandMetadata,
+  information: CommandInformation,
   operation: Operation<Context, Result>,
 ): Command<Context, Result> {
   return {
-    getDescription() {
-      return metadata.description;
+    getInformation() {
+      return information;
     },
-    createRunnerFromArgs(readerArgs: ReaderArgs) {
+    createFactory(readerArgs: ReaderArgs) {
       function generateUsage(): CommandUsage {
         const operationUsage = operation.generateUsage();
         return {
-          metadata,
           breadcrumbs: operationUsage.positionals.map((positional) =>
             breadcrumbPositional(positional.label),
           ),
+          information: information,
           positionals: operationUsage.positionals,
           subcommands: [],
           options: operationUsage.options,
         };
       }
       try {
-        const operationRunner = operation.createRunnerFromArgs(readerArgs);
+        const operationFactory = operation.createFactory(readerArgs);
         const endPositional = readerArgs.consumePositional();
         if (endPositional !== undefined) {
           throw Error(`Unexpected argument: "${endPositional}"`);
         }
         return {
           generateUsage,
-          async executeWithContext(context: Context) {
-            return operationRunner.executeWithContext(context);
+          createInstance() {
+            const operationInstance = operationFactory.createInstance();
+            return {
+              async executeWithContext(context: Context) {
+                return await operationInstance.executeWithContext(context);
+              },
+            };
           },
         };
       } catch (error) {
         return {
           generateUsage,
-          async executeWithContext() {
+          createInstance() {
             throw error;
           },
         };
@@ -83,23 +94,23 @@ export function command<Context, Result>(
 }
 
 export function commandWithSubcommands<Context, Payload, Result>(
-  metadata: CommandMetadata,
+  information: CommandInformation,
   operation: Operation<Context, Payload>,
   subcommands: { [subcommand: Lowercase<string>]: Command<Payload, Result> },
 ): Command<Context, Result> {
   return {
-    getDescription() {
-      return metadata.description;
+    getInformation() {
+      return information;
     },
-    createRunnerFromArgs(readerArgs: ReaderArgs) {
+    createFactory(readerArgs: ReaderArgs) {
       try {
-        const operationRunner = operation.createRunnerFromArgs(readerArgs);
+        const operationFactory = operation.createFactory(readerArgs);
         const subcommandName = readerArgs.consumePositional();
         if (subcommandName === undefined) {
           throw new TypoError(
             new TypoText(
-              new TypoString(`Missing required positional argument: `),
-              new TypoString(`SUBCOMMAND`, typoStyleConstants),
+              new TypoString(`<SUBCOMMAND>`, typoStyleConstants),
+              new TypoString(`: Is required, but was not provided`),
             ),
           );
         }
@@ -108,24 +119,22 @@ export function commandWithSubcommands<Context, Payload, Result>(
         if (subcommandInput === undefined) {
           throw new TypoError(
             new TypoText(
-              new TypoString(`Invalid value for positional argument: `),
-              new TypoString(`SUBCOMMAND`, typoStyleConstants),
-              new TypoString(`: "${subcommandName}"`),
+              new TypoString(`<SUBCOMMAND>`, typoStyleConstants),
+              new TypoString(`: Invalid value: "${subcommandName}"`),
             ),
           );
         }
-        const subcommandRunner =
-          subcommandInput.createRunnerFromArgs(readerArgs);
+        const subcommandFactory = subcommandInput.createFactory(readerArgs);
         return {
           generateUsage() {
             const operationUsage = operation.generateUsage();
-            const subcommandUsage = subcommandRunner.generateUsage();
+            const subcommandUsage = subcommandFactory.generateUsage();
             return {
-              metadata: subcommandUsage.metadata,
               breadcrumbs: operationUsage.positionals
                 .map((positional) => breadcrumbPositional(positional.label))
                 .concat([breadcrumbCommand(subcommandName)])
                 .concat(subcommandUsage.breadcrumbs),
+              information: subcommandUsage.information,
               positionals: operationUsage.positionals.concat(
                 subcommandUsage.positionals,
               ),
@@ -133,10 +142,16 @@ export function commandWithSubcommands<Context, Payload, Result>(
               options: operationUsage.options.concat(subcommandUsage.options),
             };
           },
-          async executeWithContext(context: Context) {
-            return await subcommandRunner.executeWithContext(
-              await operationRunner.executeWithContext(context),
-            );
+          createInstance() {
+            const operationInstance = operationFactory.createInstance();
+            const subcommandInstance = subcommandFactory.createInstance();
+            return {
+              async executeWithContext(context: Context) {
+                return await subcommandInstance.executeWithContext(
+                  await operationInstance.executeWithContext(context),
+                );
+              },
+            };
           },
         };
       } catch (error) {
@@ -144,21 +159,23 @@ export function commandWithSubcommands<Context, Payload, Result>(
           generateUsage() {
             const operationUsage = operation.generateUsage();
             return {
-              metadata,
               breadcrumbs: operationUsage.positionals
                 .map((positional) => breadcrumbPositional(positional.label))
                 .concat([breadcrumbCommand("<SUBCOMMAND>")]),
+              information: information,
               positionals: operationUsage.positionals,
-              subcommands: Object.entries(subcommands).map(
-                ([name, subcommand]) => ({
-                  name,
-                  description: subcommand.getDescription(),
-                }),
-              ),
+              subcommands: Object.entries(subcommands).map((subcommand) => {
+                const metadata = subcommand[1].getInformation();
+                return {
+                  name: subcommand[0],
+                  description: metadata.description,
+                  hint: metadata.hint,
+                };
+              }),
               options: operationUsage.options,
             };
           },
-          async executeWithContext() {
+          createInstance() {
             throw error;
           },
         };
@@ -168,23 +185,23 @@ export function commandWithSubcommands<Context, Payload, Result>(
 }
 
 export function commandChained<Context, Payload, Result>(
-  metadata: CommandMetadata,
+  metadata: CommandInformation,
   operation: Operation<Context, Payload>,
   nextCommand: Command<Payload, Result>,
 ): Command<Context, Result> {
   return {
-    getDescription() {
-      return metadata.description;
+    getInformation() {
+      return metadata;
     },
-    createRunnerFromArgs(readerArgs: ReaderArgs) {
-      const operationRunner = operation.createRunnerFromArgs(readerArgs);
-      const nextCommandRunner = nextCommand.createRunnerFromArgs(readerArgs);
+    createFactory(readerArgs: ReaderArgs) {
+      const operationFactory = operation.createFactory(readerArgs);
+      const nextCommandFactory = nextCommand.createFactory(readerArgs);
       return {
         generateUsage() {
           const operationUsage = operation.generateUsage();
-          const nextCommandUsage = nextCommandRunner.generateUsage();
+          const nextCommandUsage = nextCommandFactory.generateUsage();
           return {
-            metadata: nextCommandUsage.metadata,
+            information: nextCommandUsage.information,
             breadcrumbs: operationUsage.positionals
               .map((positional) => breadcrumbPositional(positional.label))
               .concat(nextCommandUsage.breadcrumbs),
@@ -195,10 +212,16 @@ export function commandChained<Context, Payload, Result>(
             options: operationUsage.options.concat(nextCommandUsage.options),
           };
         },
-        async executeWithContext(context: Context) {
-          return await nextCommandRunner.executeWithContext(
-            await operationRunner.executeWithContext(context),
-          );
+        createInstance() {
+          const operationInstance = operationFactory.createInstance();
+          const nextCommandInstance = nextCommandFactory.createInstance();
+          return {
+            async executeWithContext(context: Context) {
+              return await nextCommandInstance.executeWithContext(
+                await operationInstance.executeWithContext(context),
+              );
+            },
+          };
         },
       };
     },

package/src/lib/Operation.ts

@@ -4,10 +4,14 @@ import { ReaderArgs } from "./Reader";
 
 export type Operation<Input, Output> = {
   generateUsage(): OperationUsage;
-  createRunnerFromArgs(readerArgs: ReaderArgs): OperationRunner<Input, Output>;
+  createFactory(readerArgs: ReaderArgs): OperationFactory<Input, Output>;
 };
 
-export type OperationRunner<Input, Output> = {
+export type OperationFactory<Input, Output> = {
+  createInstance(): OperationInstance<Input, Output>;
+};
+
+export type OperationInstance<Input, Output> = {
   executeWithContext(input: Input): Promise<Output>;
 };
 
@@ -46,7 +50,7 @@ export function operation<
       }
       return { options: optionsUsage, positionals: positionalsUsage };
     },
-    createRunnerFromArgs(readerArgs: ReaderArgs) {
+    createFactory(readerArgs: ReaderArgs) {
       const optionsGetters: any = {};
       for (const optionKey in inputs.options) {
         const optionInput = inputs.options[optionKey]!;
@@ -57,15 +61,19 @@ export function operation<
         positionalsValues.push(positionalInput.consumePositionals(readerArgs));
       }
       return {
-        executeWithContext(context: Context) {
+        createInstance() {
           const optionsValues: any = {};
           for (const optionKey in optionsGetters) {
             optionsValues[optionKey] = optionsGetters[optionKey]!.getValue();
           }
-          return handler(context, {
-            options: optionsValues,
-            positionals: positionalsValues,
-          });
+          return {
+            executeWithContext(context: Context) {
+              return handler(context, {
+                options: optionsValues,
+                positionals: positionalsValues,
+              });
+            },
+          };
         },
       };
     },

package/src/lib/Option.ts

@@ -15,10 +15,10 @@ export type Option<Value> = {
 
 export type OptionUsage = {
   description: string | undefined;
+  hint: string | undefined;
   long: Lowercase<string>; // TODO - better type for long option names ?
   short: string | undefined;
   label: Uppercase<string> | undefined;
-  // TODO - default value for usage ? but it can be dynamic, so maybe not
 };
 
 export type OptionGetter<Value> = {
@@ -29,13 +29,16 @@ export function optionFlag(definition: {
   long: Lowercase<string>;
   short?: string;
   description?: string;
+  hint?: string;
   aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
   default?: () => boolean;
 }): Option<boolean> {
+  const label = `<${typeBoolean.label}>` as Uppercase<string>;
   return {
     generateUsage() {
       return {
         description: definition.description,
+        hint: definition.hint,
         long: definition.long,
         short: definition.short,
         label: undefined,
@@ -52,9 +55,8 @@ export function optionFlag(definition: {
           if (optionValues.length > 1) {
             throw new TypoError(
               new TypoText(
-                new TypoString(`Option value for: `),
                 new TypoString(`--${definition.long}`, typoStyleConstants),
-                new TypoString(`: must not be set multiple times`),
+                new TypoString(`: Must not be set multiple times`),
               ),
             );
           }
@@ -66,8 +68,8 @@ export function optionFlag(definition: {
             } catch (error) {
               throw new TypoError(
                 new TypoText(
-                  new TypoString(`Failed to compute default value for: `),
                   new TypoString(`--${definition.long}`, typoStyleConstants),
+                  new TypoString(`: Failed to compute default value`),
                 ),
                 error,
               );
@@ -80,7 +82,7 @@ export function optionFlag(definition: {
               new TypoText(
                 new TypoString(`--${definition.long}`, typoStyleConstants),
                 new TypoString(`: `),
-                new TypoString(typeBoolean.label, typoStyleUserInput),
+                new TypoString(label, typoStyleUserInput),
               ),
           );
         },
@@ -93,19 +95,21 @@ export function optionSingleValue<Value>(definition: {
   long: Lowercase<string>;
   short?: string;
   description?: string;
+  hint?: string;
   aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
   label?: Uppercase<string>;
   type: Type<Value>;
   default: () => Value;
 }): Option<Value> {
-  const label = definition.label ?? definition.type.label;
+  const label = `<${definition.label ?? definition.type.label}>`;
   return {
     generateUsage() {
       return {
         description: definition.description,
+        hint: definition.hint,
         long: definition.long,
         short: definition.short,
-        label: `<${label}>` as Uppercase<string>,
+        label: label as Uppercase<string>,
       };
     },
     createGetter(readerOptions: ReaderOptions) {
@@ -119,9 +123,8 @@ export function optionSingleValue<Value>(definition: {
           if (optionValues.length > 1) {
             throw new TypoError(
               new TypoText(
-                new TypoString(`Option value for: `),
                 new TypoString(`--${definition.long}`, typoStyleConstants),
-                new TypoString(`: must not be set multiple times`),
+                new TypoString(`: Must not be set multiple times`),
               ),
             );
           }
@@ -132,8 +135,8 @@ export function optionSingleValue<Value>(definition: {
             } catch (error) {
               throw new TypoError(
                 new TypoText(
-                  new TypoString(`Failed to compute default value for: `),
                   new TypoString(`--${definition.long}`, typoStyleConstants),
+                  new TypoString(`: Failed to compute default value`),
                 ),
                 error,
               );
@@ -159,19 +162,21 @@ export function optionRepeatable<Value>(definition: {
   long: Lowercase<string>;
   short?: string;
   description?: string;
+  hint?: string;
   aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
   label?: Uppercase<string>;
   type: Type<Value>;
 }): Option<Array<Value>> {
-  const label = definition.label ?? definition.type.label;
+  const label = `<${definition.label ?? definition.type.label}>`;
   return {
     generateUsage() {
       // TODO - showcase that it can be repeated ?
       return {
         description: definition.description,
+        hint: definition.hint,
         long: definition.long,
         short: definition.short,
-        label: `<${label}>` as Uppercase<string>,
+        label: label as Uppercase<string>,
       };
     },
     createGetter(readerOptions: ReaderOptions) {

package/src/lib/Positional.ts

@@ -9,20 +9,23 @@ export type Positional<Value> = {
 
 export type PositionalUsage = {
   description: string | undefined;
+  hint: string | undefined;
   label: Uppercase<string>;
 };
 
 export function positionalRequired<Value>(definition: {
   description?: string;
+  hint?: string;
   label?: Uppercase<string>;
   type: Type<Value>;
 }): Positional<Value> {
-  const label = definition.label ?? definition.type.label;
+  const label = `<${definition.label ?? definition.type.label}>`;
   return {
     generateUsage() {
       return {
         description: definition.description,
-        label: `<${label}>` as Uppercase<string>,
+        hint: definition.hint,
+        label: label as Uppercase<string>,
       };
     },
     consumePositionals(readerPositionals: ReaderPositionals) {
@@ -30,8 +33,8 @@ export function positionalRequired<Value>(definition: {
       if (positional === undefined) {
         throw new TypoError(
           new TypoText(
-            new TypoString(`Missing required positional argument: `),
             new TypoString(label, typoStyleUserInput),
+            new TypoString(`: Is required, but was not provided`),
           ),
         );
       }
@@ -46,16 +49,18 @@ export function positionalRequired<Value>(definition: {
 
 export function positionalOptional<Value>(definition: {
   description?: string;
+  hint?: string;
   label?: Uppercase<string>;
   type: Type<Value>;
   default: () => Value;
 }): Positional<Value> {
-  const label = definition.label ?? definition.type.label;
+  const label = `[${definition.label ?? definition.type.label}]`;
   return {
     generateUsage() {
       return {
         description: definition.description,
-        label: `[${label}]` as Uppercase<string>,
+        hint: definition.hint,
+        label: label as Uppercase<string>,
       };
     },
     consumePositionals(readerPositionals: ReaderPositionals) {
@@ -66,8 +71,8 @@ export function positionalOptional<Value>(definition: {
         } catch (error) {
           throw new TypoError(
             new TypoText(
-              new TypoString(`Failed to compute default value for: `),
               new TypoString(label, typoStyleUserInput),
+              new TypoString(`: Failed to compute default value`),
             ),
             error,
           );
@@ -85,15 +90,17 @@ export function positionalOptional<Value>(definition: {
 export function positionalVariadics<Value>(definition: {
   endDelimiter?: string;
   description?: string;
+  hint?: string;
   label?: Uppercase<string>;
   type: Type<Value>;
 }): Positional<Array<Value>> {
-  const label = definition.label ?? definition.type.label;
+  const label = `[${definition.label ?? definition.type.label}]`;
   return {
     generateUsage() {
       return {
         description: definition.description,
-        label: (`[${label}]...` +
+        hint: definition.hint,
+        label: (`${label}...` +
           (definition.endDelimiter
             ? `["${definition.endDelimiter}"]`
             : "")) as Uppercase<string>,

package/src/lib/Reader.ts

@@ -146,8 +146,8 @@ export class ReaderArgs {
       }
       throw new TypoError(
         new TypoText(
-          new TypoString(`Unknown option: `),
           new TypoString(`-${arg.slice(shortIndexStart)}`, typoStyleConstants),
+          new TypoString(`: Unexpected unknown option`),
         ),
       );
     }
@@ -169,8 +169,8 @@ export class ReaderArgs {
     }
     throw new TypoError(
       new TypoText(
-        new TypoString(`Unknown option: `),
         new TypoString(constant, typoStyleConstants),
+        new TypoString(`: Unexpected unknown option`),
       ),
     );
   }
@@ -202,7 +202,6 @@ export class ReaderArgs {
     if (arg === null) {
       throw new TypoError(
         new TypoText(
-          new TypoString(`Option parsing: `),
           new TypoString(constant, typoStyleConstants),
           new TypoString(`: requires a value, but got end of input`),
         ),
@@ -211,7 +210,6 @@ export class ReaderArgs {
     if (this.#parsedDouble) {
       throw new TypoError(
         new TypoText(
-          new TypoString(`Option parsing: `),
           new TypoString(constant, typoStyleConstants),
           new TypoString(`: requires a value before "--"`),
         ),
@@ -221,7 +219,6 @@ export class ReaderArgs {
     if (arg.startsWith("-")) {
       throw new TypoError(
         new TypoText(
-          new TypoString(`Option parsing: `),
           new TypoString(constant, typoStyleConstants),
           new TypoString(`: requires a value, but got: "${arg}"`),
         ),