cli-kiss 0.2.8 → 0.2.9

package/docs/guide/01_getting_started.md

@@ -20,7 +20,7 @@ import {
   optionFlag,
   positionalRequired,
   runAndExit,
-  type,
+  typeString,
 } from "cli-kiss";
 
 const greetCommand = command(
@@ -32,7 +32,7 @@ const greetCommand = command(
       },
       positionals: [
         positionalRequired({
-          type: type("name"),
+          type: typeString("name"),
           description: "The name of the person to greet",
         }),
       ],

package/docs/guide/02_commands.md

@@ -12,7 +12,7 @@ const greet = command(
   operation(
     {
       options: {},
-      positionals: [positionalRequired({ type: type("name") })],
+      positionals: [positionalRequired({ type: typeString("name") })],
     },
     async function (_ctx, { positionals: [name] }) {
       console.log(`Hello, ${name}!`);
@@ -85,7 +85,7 @@ const authenticatedDeploy = commandChained(
       options: {
         token: optionSingleValue({
           long: "token",
-          type: type("secret"),
+          type: typeString("secret"),
           description: "API token",
           fallbackValueIfAbsent: function () {
             const t = process.env.API_TOKEN;

package/docs/guide/04_positionals.md

@@ -9,7 +9,7 @@ Fails if missing.
 
 ```ts
 const name = positionalRequired({
-  type: type("person"),
+  type: typeString("person"),
   description: "The name of the person to greet",
 });
 // Usage:
@@ -29,7 +29,7 @@ Falls back to a default when absent.
 
 ```ts
 const greeting = positionalOptional({
-  type: type("greeting"),
+  type: typeString("greeting"),
   description: "Custom greeting",
   hint: "default to 'Hello'",
   default: () => "Hello",
@@ -66,7 +66,7 @@ Optionally stop collecting at a specific sentinel token:
 
 ```ts
 const args = positionalVariadics({
-  type: type("argument"),
+  type: typeString("argument"),
   endDelimiter: "STOP",
   description: "Arguments (end with STOP)",
 });
@@ -90,10 +90,10 @@ operation(
   {
     options: {},
     positionals: [
-      positionalRequired({ type: type("src") }),
-      positionalRequired({ type: type("dst") }),
-      positionalOptional({ type: type("tag"), default: () => "latest" }),
-      positionalVariadics({ type: type("extra") }),
+      positionalRequired({ type: typeString("src") }),
+      positionalRequired({ type: typeString("dst") }),
+      positionalOptional({ type: typeString("tag"), default: () => "latest" }),
+      positionalVariadics({ type: typeString("extra") }),
     ],
   },
   async function (_ctx, { positionals: [src, dst, tag, extras] }) {
@@ -101,6 +101,6 @@ operation(
   },
 );
 // Usage:
-//   my-cli in out  →  src="in", src="out", tag="latest", extras=[]
-//   my-cli in out v2 a b c  →  src="in", src="out", tag="v2", extras=["a","b","c"]
+//   my-cli in out  →  src="in", dst="out", tag="latest", extras=[]
+//   my-cli in out v2 a b c  →  src="in", dst="out", tag="v2", extras=["a","b","c"]
 ```

package/docs/guide/05_input_types.md

@@ -14,7 +14,7 @@ shown in help/errors.
 
 | Type factory   | Content type | Accepts                                                             |
 | -------------- | ------------ | ------------------------------------------------------------------- |
-| `type`         | `string`     | Any string                                                          |
+| `typeString`   | `string`     | Any string                                                          |
 | `typeBoolean`  | `boolean`    | `true/yes/on/y` → true, `false/no/off/n` → false (case-insensitive) |
 | `typeNumber`   | `number`     | Integers, floats, scientific notation                               |
 | `typeInteger`  | `bigint`     | Integer strings only                                                |
@@ -23,7 +23,7 @@ shown in help/errors.
 | `typePath`     | `string`     | Non-empty path strings; optional sync existence check               |
 
 ```ts
-type("greeting").decoder("hello"); // → "hello"
+typeString("greeting").decoder("hello"); // → "hello"
 typeBoolean("flag").decoder("yes"); // → true
 typeNumber("pi").decoder("3.14"); // → 3.14
 typeInteger("id").decoder("9007199254740993"); // → 9007199254740993n
@@ -65,7 +65,7 @@ typePoint.decoder("x,2"); // → Error: at 0: a: Unable to parse: "x"
 The default separator is `","`. Pass a second argument to change it:
 
 ```ts
-typeTuple([type("name"), typeNumber()], ":");
+typeTuple([typeString("name"), typeNumber()], ":");
 // "foo:42"  →  ["foo", 42]
 ```
 
@@ -93,13 +93,15 @@ over `typeList` when users should pass multiple values as separate flags
 
 :::
 
-## `typeConverted` — transform decoded value
+## `typeMapped` — transformed decoded value
 
 Chains a base type with a transformation function:
 
 ```ts
-const typePort = typeConverted("port", typeNumber(), (n) => {
-  if (n < 1 || n > 65535) throw new Error("Out of range");
+const typePort = typeMapped("port", typeNumber(), (n) => {
+  if (n < 1 || n > 65535) {
+    throw new Error("Out of range");
+  }
   return n;
 });
 typePort.decoder("8080"); // → 8080

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-kiss",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "devDependencies": {

package/src/lib/Command.ts

@@ -17,7 +17,7 @@ import { UsageCommand } from "./Usage";
  * @typeParam Context - Injected at execution; forwarded to handlers.
  * @typeParam Result - Produced on execution; typically `void`.
  */
-export type Command<Context, Result> = {
+export type Command<Context, Result = void> = {
   /**
    * Returns static metadata.
    */
@@ -197,11 +197,15 @@ export function commandWithSubcommands<Context, Payload, Result = void>(
   operation: Operation<Context, Payload>,
   subcommands: { [subcommand: string]: Command<Payload, Result> },
 ): Command<Context, Result> {
-  // TODO - forbid subcommands that start with a "-" ?
   const subcommandNames = Object.keys(subcommands);
   if (subcommandNames.length === 0) {
     throw new Error("At least one subcommand is required");
   }
+  for (const name of subcommandNames) {
+    if (name.startsWith("-")) {
+      throw new Error(`Subcommand name "${name}" cannot start with "-".`);
+    }
+  }
   return {
     getInformation() {
       return information;
@@ -212,8 +216,9 @@ export function commandWithSubcommands<Context, Payload, Result = void>(
         const subcommandName = readerArgs.consumePositional();
         if (subcommandName === undefined) {
           const errorText = new TypoText();
+          errorText.push(new TypoString(`Missing argument: `));
           errorText.push(new TypoString(`<subcommand>`, typoStyleUserInput));
-          errorText.push(new TypoString(`: Missing argument.`));
+          errorText.push(new TypoString(`.`));
           suggestSubcommandNames(errorText, "", subcommandNames);
           throw new TypoError(errorText);
         }

package/src/lib/Operation.ts

@@ -12,7 +12,7 @@ import { UsageOption, UsagePositional } from "./Usage";
  * @typeParam Context - Injected at execution; forwarded to handlers.
  * @typeParam Result - Value produced on execution; typically `void`.
  */
-export type Operation<Context, Result> = {
+export type Operation<Context, Result = void> = {
   /**
    * Returns usage metadata without consuming any arguments.
    */
@@ -132,7 +132,9 @@ export function operation<
       return { options: optionsUsage, positionals: positionalsUsage };
     },
     consumeAndMakeDecoder(readerArgs: ReaderArgs) {
-      const optionsDecoders: Record<string, OptionDecoder<any>> = {};
+      const optionsDecoders = {} as {
+        [K in keyof Options]: OptionDecoder<Options[K]>;
+      };
       if (inputs.options !== undefined) {
         for (const optionKey in inputs.options) {
           const optionInput = inputs.options[optionKey]!;
@@ -140,7 +142,9 @@ export function operation<
             optionInput.registerAndMakeDecoder(readerArgs);
         }
       }
-      const positionalsDecoders: Array<PositionalDecoder<any>> = [];
+      const positionalsDecoders = [] as {
+        [K in keyof Positionals]: PositionalDecoder<Positionals[K]>;
+      };
       if (inputs.positionals !== undefined) {
         for (const positionalInput of inputs.positionals) {
           positionalsDecoders.push(
@@ -150,12 +154,16 @@ export function operation<
       }
       return {
         decodeAndMakeInterpreter() {
-          const optionsValues: any = {};
+          const optionsValues = {} as {
+            [K in keyof Options]: Options[K];
+          };
           for (const optionKey in optionsDecoders) {
             optionsValues[optionKey] =
               optionsDecoders[optionKey]!.getAndDecodeValue();
           }
-          const positionalsValues: any = [];
+          const positionalsValues = [] as {
+            [K in keyof Positionals]: Positionals[K];
+          };
           for (const positionalDecoder of positionalsDecoders) {
             positionalsValues.push(positionalDecoder.decodeValue());
           }

package/src/lib/Option.ts

@@ -1,7 +1,6 @@
 import {
   ReaderOptionGetter,
   ReaderOptionNextGuard,
-  ReaderOptionRestGuard,
   ReaderOptions,
   ReaderOptionValue,
 } from "./Reader";
@@ -94,8 +93,8 @@ export function optionFlag(definition: {
         shortKey: short,
         aliasLongKeys: aliases?.longs,
         aliasShortKeys: aliases?.shorts,
-        restGuard: () => false,
         nextGuard: () => false,
+        consumeGroupRestAsValue: false,
       });
       return {
         getAndDecodeValue() {
@@ -180,12 +179,6 @@ export function optionSingleValue<Value>(definition: {
         shortKey: short,
         aliasLongKeys: aliases?.longs,
         aliasShortKeys: aliases?.shorts,
-        restGuard: () => {
-          if (definition.impliedValueIfNotInlined !== undefined) {
-            return false;
-          }
-          return true;
-        },
         nextGuard: (value) => {
           if (definition.impliedValueIfNotInlined !== undefined) {
             return false;
@@ -198,6 +191,8 @@ export function optionSingleValue<Value>(definition: {
           }
           return true;
         },
+        consumeGroupRestAsValue:
+          definition.impliedValueIfNotInlined === undefined,
       });
       return {
         getAndDecodeValue() {
@@ -292,7 +287,6 @@ export function optionRepeatable<Value>(definition: {
         shortKey: short,
         aliasLongKeys: aliases?.longs,
         aliasShortKeys: aliases?.shorts,
-        restGuard: () => true,
         nextGuard: (value) => {
           if (value.inlined !== null) {
             return false;
@@ -302,6 +296,7 @@ export function optionRepeatable<Value>(definition: {
           }
           return true;
         },
+        consumeGroupRestAsValue: true,
       });
       return {
         getAndDecodeValue() {
@@ -353,8 +348,8 @@ function setupOptionAliased(
     shortKey: string | undefined;
     aliasLongKeys: Array<string> | undefined;
     aliasShortKeys: Array<string> | undefined;
-    restGuard: ReaderOptionRestGuard;
     nextGuard: ReaderOptionNextGuard;
+    consumeGroupRestAsValue: boolean;
   },
 ): () => Array<{ identifier: string; value: ReaderOptionValue }> {
   const { longKey, shortKey, aliasLongKeys, aliasShortKeys } = params;
@@ -369,8 +364,8 @@ function setupOptionAliased(
   return setupOptionMany(readerOptions, {
     longKeys,
     shortKeys,
-    restGuard: params.restGuard,
     nextGuard: params.nextGuard,
+    consumeGroupRestAsValue: params.consumeGroupRestAsValue,
   });
 }
 
@@ -379,25 +374,32 @@ function setupOptionMany(
   params: {
     longKeys: Array<string>;
     shortKeys: Array<string>;
-    restGuard: ReaderOptionRestGuard;
     nextGuard: ReaderOptionNextGuard;
+    consumeGroupRestAsValue: boolean;
   },
 ): () => Array<{ identifier: string; value: ReaderOptionValue }> {
-  const { longKeys, shortKeys, restGuard, nextGuard } = params;
-  const getters = new Array<ReaderOptionGetter>();
+  const { longKeys, shortKeys, nextGuard, consumeGroupRestAsValue } = params;
+  const getters = new Map<string, ReaderOptionGetter>();
   for (const key of longKeys) {
-    getters.push(readerOptions.registerOptionLong({ key, nextGuard }));
+    getters.set(
+      `--${key}`,
+      readerOptions.registerOptionLong({ key, nextGuard }),
+    );
   }
   for (const key of shortKeys) {
-    getters.push(
-      readerOptions.registerOptionShort({ key, restGuard, nextGuard }),
+    getters.set(
+      `-${key}`,
+      readerOptions.registerOptionShort({
+        key,
+        nextGuard,
+        consumeGroupRestAsValue,
+      }),
     );
   }
   return () => {
     const results = new Array();
-    for (const getter of getters) {
-      const { identifier, values } = getter();
-      for (const value of values) {
+    for (const [identifier, getter] of getters.entries()) {
+      for (const value of getter()) {
         results.push({ identifier, value });
       }
     }

package/src/lib/Positional.ts

@@ -81,12 +81,17 @@ export function positionalRequired<Value>(definition: {
     consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positional = readerPositionals.consumePositional();
       if (positional === undefined) {
-        const errorText = makeErrorText(label);
-        errorText.push(new TypoString(`: Is required, but was not provided.`));
+        const errorText = makeErrorTextLabel("Missing argument", label);
         if (description !== undefined) {
-          // TODO - should there be a dedicated hint here ?
           errorText.push(
-            new TypoString(` (${description})`, typoStyleRegularWeaker),
+            new TypoString(`: `),
+            new TypoString(`${description}`),
+          );
+        }
+        if (hint !== undefined) {
+          errorText.push(
+            new TypoString(` `),
+            new TypoString(`(${hint})`, typoStyleRegularWeaker),
           );
         }
         throw new TypoError(errorText);
@@ -146,7 +151,12 @@ export function positionalOptional<Value>(definition: {
             try {
               return definition.default();
             } catch (error) {
-              throwsWhenFailedToGetDefault(label);
+              const errorText = makeErrorTextLabel(
+                "Failed to get default value",
+                label,
+              );
+              errorText.push(new TypoString("."));
+              throw new TypoError(errorText, error);
             }
           }
           return decodeValue(label, definition.type, positional);
@@ -231,14 +241,9 @@ function decodeValue<Value>(
   );
 }
 
-function makeErrorText(label: string): TypoText {
+function makeErrorTextLabel(message: string, label: string): TypoText {
   const errorText = new TypoText();
+  errorText.push(new TypoString(`${message}: `));
   errorText.push(new TypoString(label, typoStyleUserInput));
   return errorText;
 }
-
-function throwsWhenFailedToGetDefault(label: string): never {
-  const errorText = makeErrorText(label);
-  errorText.push(new TypoString(`: Failed to get default value.`));
-  throw new TypoError(errorText);
-}

package/src/lib/Reader.ts

@@ -8,6 +8,7 @@ import {
 } from "./Typo";
 
 /**
+ * Represents the parsing specification for a long option
  */
 export type ReaderOptionLongSpec = {
   key: string;
@@ -15,18 +16,14 @@ export type ReaderOptionLongSpec = {
 };
 
 /**
+ * Represents the parsing specification for a short option
  */
-export type ReaderOptionShortSpec = {
-  key: string;
-  restGuard: ReaderOptionRestGuard;
-  nextGuard: ReaderOptionNextGuard;
+export type ReaderOptionShortSpec = ReaderOptionLongSpec & {
+  consumeGroupRestAsValue: boolean;
 };
 
 /**
- */
-export type ReaderOptionRestGuard = (rest: string) => boolean;
-
-/**
+ * Determines whether the next token is valid for a given option.
  */
 export type ReaderOptionNextGuard = (
   value: ReaderOptionValue,
@@ -34,13 +31,7 @@ export type ReaderOptionNextGuard = (
 ) => boolean;
 
 /**
- */
-export type ReaderOptionResult = {
-  identifier: string;
-  values: ReadonlyArray<ReaderOptionValue>;
-};
-
-/**
+ * Represents the values parsed for an option.
  */
 export type ReaderOptionValue = {
   inlined: string | null;
@@ -48,8 +39,9 @@ export type ReaderOptionValue = {
 };
 
 /**
+ * Returns the parsed values for a registered option.
  */
-export type ReaderOptionGetter = () => ReaderOptionResult;
+export type ReaderOptionGetter = () => ReadonlyArray<ReaderOptionValue>;
 
 /**
  * Option registration/query interface. Subset of {@link ReaderArgs}.
@@ -100,9 +92,10 @@ export class ReaderArgs {
   }
 
   /**
+   * Registers a long option and returns a getter for its parsed values.
    */
   registerOptionLong(longSpec: ReaderOptionLongSpec): ReaderOptionGetter {
-    const identifier = `--${longSpec.key}`;
+    const identifier = `--${longSpec.key}`; // TODO - is this necessary ?
     if (!isValidOptionKey(longSpec.key)) {
       throw new Error(`Option identifier is invalid: ${identifier}.`);
     }
@@ -115,10 +108,11 @@ export class ReaderArgs {
       spec: longSpec,
       values,
     });
-    return () => ({ identifier, values });
+    return () => values;
   }
 
   /**
+   * Registers a short option and returns a getter for its parsed values.
    */
   registerOptionShort(shortSpec: ReaderOptionShortSpec): ReaderOptionGetter {
     const identifier = `-${shortSpec.key}`;
@@ -149,7 +143,7 @@ export class ReaderArgs {
       spec: shortSpec,
       values,
     });
-    return () => ({ identifier, values });
+    return () => values;
   }
 
   /**
@@ -243,7 +237,7 @@ export class ReaderArgs {
       this.#consumeOptionValues(shortContext, null);
       return true;
     }
-    if (shortContext.spec.restGuard(tokenRest)) {
+    if (shortContext.spec.consumeGroupRestAsValue) {
       this.#consumeOptionValues(shortContext, tokenRest);
       return true;
     }

package/src/lib/Run.ts

@@ -116,9 +116,9 @@ export async function runAndExit<Context>(
     });
   }
   // TODO - the lifecycle of this function should be improved
-  // TODO - how to pass the color information to the command logic ?
+  // TODO - how to pass the color TypoSupport to the command logic ?
+  // TODO - handle completions generators ?
   /*
-  // TODO - handle completions ?
   readerArgs.registerFlag({
     key: "completion",
     shorts: [],