cli-kiss 0.2.6 → 0.2.7

package/docs/guide/02_commands.md

@@ -87,7 +87,7 @@ const authenticatedDeploy = commandChained(
           long: "token",
           type: type("secret"),
           description: "API token",
-          defaultWhenNotDefined: function () {
+          defaultIfNotSpecified: function () {
             const t = process.env.API_TOKEN;
             if (!t) throw new Error("API_TOKEN env var is required");
             return t;

package/docs/guide/03_options.md

@@ -44,7 +44,7 @@ const output = optionSingleValue({
   short: "o",
   type: typePath(),
   description: "Output directory",
-  defaultWhenNotDefined: () => "dist/",
+  defaultIfNotSpecified: () => "dist/",
 });
 // --output dist/   →  "dist/"
 // --output=dist/   →  "dist/"
@@ -59,8 +59,8 @@ const output = optionSingleValue({
 | `type`                  | `Type<Value>`         | Decoder for the value                                                        |
 | `description`           | `string?`             | Help text                                                                    |
 | `hint`                  | `string?`             | Short note in parentheses                                                    |
-| `defaultWhenNotDefined` | `() => Value`         | Value when option is absent — **throw** to make it required                  |
-| `defaultWhenNotInlined` | `() => Value?`        | Value when option is present but has no inline value (e.g. `--output` alone) |
+| `defaultIfNotSpecified` | `() => Value`         | Value when option is absent — **throw** to make it required                  |
+| `valueIfNothingInlined` | `() => Value?`        | Value when option is present but has no inline value (e.g. `--output` alone) |
 | `aliases`               | `{ longs?, shorts? }` | Additional names                                                             |
 
 ## `optionRepeatable` — collect multiple values

package/docs/guide/06_run_as_cli.md

@@ -67,7 +67,7 @@ const rootCmd = commandWithSubcommands(
           long: "db",
           type: typeUrl(),
           description: "Database URL",
-          defaultWhenNotDefined: () => new URL("postgres://localhost/mydb"),
+          defaultIfNotSpecified: () => new URL("postgres://localhost/mydb"),
         }),
       },
       positionals: [],

package/package.json

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

package/src/index.ts

@@ -4,6 +4,7 @@ export * from "./lib/Option";
 export * from "./lib/Positional";
 export * from "./lib/Reader";
 export * from "./lib/Run";
+export * from "./lib/Similarity";
 export * from "./lib/Type";
 export * from "./lib/Typo";
 export * from "./lib/Usage";

package/src/lib/Command.ts

@@ -1,8 +1,10 @@
 import { Operation } from "./Operation";
 import { ReaderArgs } from "./Reader";
+import { similaritySort } from "./Similarity";
 import {
   TypoError,
   TypoString,
+  typoStyleConstants,
   typoStyleQuote,
   typoStyleUserInput,
   TypoText,
@@ -194,6 +196,10 @@ export function commandWithSubcommands<Context, Payload, Result>(
   operation: Operation<Context, Payload>,
   subcommands: { [subcommand: string]: Command<Payload, Result> },
 ): Command<Context, Result> {
+  const subcommandNames = Object.keys(subcommands);
+  if (subcommandNames.length === 0) {
+    throw new Error("At least one subcommand is required");
+  }
   return {
     getInformation() {
       return information;
@@ -212,13 +218,21 @@ export function commandWithSubcommands<Context, Payload, Result>(
         }
         const subcommandInput = subcommands[subcommandName];
         if (subcommandInput === undefined) {
-          throw new TypoError(
-            new TypoText(
-              new TypoString(`<subcommand>`, typoStyleUserInput),
-              new TypoString(`: Invalid value: `),
-              new TypoString(`"${subcommandName}"`, typoStyleQuote),
-            ),
-          );
+          const text = new TypoText();
+          text.push(new TypoString(`<subcommand>`, typoStyleUserInput));
+          text.push(new TypoString(`: Unknown name: `));
+          text.push(new TypoString(`"${subcommandName}"`, typoStyleQuote));
+          const suggestions = similaritySort(
+            subcommandName,
+            subcommandNames.map((subcommandName) => ({
+              key: subcommandName,
+              value: new TypoString(subcommandName, typoStyleConstants),
+            })),
+          ).slice(0, 3);
+          text.push(new TypoString(`: did you mean: `));
+          text.push(TypoText.join(suggestions, new TypoString(`, `)));
+          text.push(new TypoString(` ?`));
+          throw new TypoError(text);
         }
         const subcommandDecoder =
           subcommandInput.consumeAndMakeDecoder(readerArgs);

package/src/lib/Operation.ts

@@ -83,7 +83,7 @@ export type OperationInterpreter<Context, Result> = {
  * const greetOperation = operation(
  *   {
  *     options: {
- *       loud: optionFlag({ long: "loud", description: "Print in uppercase", default: false }),
+ *       loud: optionFlag({ long: "loud", description: "Print in uppercase" }),
  *     },
  *     positionals: [
  *       positionalRequired({ type: type("name"), description: "Name to greet" }),

package/src/lib/Option.ts

@@ -77,7 +77,7 @@ export function optionFlag(definition: {
   aliases?: { longs?: Array<string>; shorts?: Array<string> };
   default?: boolean;
 }): Option<boolean> {
-  const type = typeBoolean("value");
+  const typeBool = typeBoolean("value");
   const { long, short, description, hint, aliases } = definition;
   return {
     generateUsage() {
@@ -105,7 +105,7 @@ export function optionFlag(definition: {
           const positiveResult = optionResults[0]!;
           const value =
             positiveResult.inlined === null ? "true" : positiveResult.inlined;
-          return decodeValue({ long, short, type, input: value });
+          return decodeValue({ long, type: typeBool, input: value });
         },
       };
     },
@@ -126,8 +126,8 @@ export function optionFlag(definition: {
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.aliases - Additional names.
  * @param definition.type - Decoder for the raw string value.
- * @param definition.valueWhenNotDefined - Default value when the option is not specified at all.
- * @param definition.valueWhenNotInlined - Default value when the option is specified without an inline value (e.g. `--option` or `-o`).
+ * @param definition.defaultIfNotSpecified - Default value when the option is not specified at all.
+ * @param definition.valueIfNothingInlined - Default value when the option is specified without an inline value (e.g. `--option` or `-o`).
  * @returns An {@link Option}`<Value>`.
  *
  * @example
@@ -137,7 +137,7 @@ export function optionFlag(definition: {
  *   short: "o",
  *   type: typePath(),
  *   description: "Output directory",
- *   valueWhenNotDefined: () => "dist",
+ *   defaultIfNotSpecified: () => "dist",
  * });
  * // Usage:
  * //   my-cli  →  "dist"
@@ -152,8 +152,8 @@ export function optionSingleValue<Value>(definition: {
   hint?: string;
   aliases?: { longs?: Array<string>; shorts?: Array<string> };
   type: Type<Value>;
-  defaultWhenNotDefined: () => Value;
-  defaultWhenNotInlined?: () => Value;
+  defaultIfNotSpecified: () => Value;
+  valueIfNothingInlined?: () => Value;
 }): Option<Value> {
   const { long, short, description, hint, aliases, type } = definition;
   const label = `<${type.content}>`;
@@ -170,7 +170,7 @@ export function optionSingleValue<Value>(definition: {
         parsing: {
           consumeShortGroup: true,
           consumeNextArg(inlined, separated) {
-            if (definition.defaultWhenNotInlined !== undefined) {
+            if (definition.valueIfNothingInlined !== undefined) {
               return false;
             }
             return inlined === null && separated.length === 0;
@@ -186,24 +186,26 @@ export function optionSingleValue<Value>(definition: {
           const optionResult = optionResults[0];
           if (optionResult === undefined) {
             try {
-              return definition.defaultWhenNotDefined();
+              return definition.defaultIfNotSpecified();
             } catch (error) {
-              throwFailedToGetDefaultValueError(long, error, "not set");
+              const context = "Not specified";
+              throwFailedToGetDefaultValueError({ long, error, context });
             }
           }
           if (optionResult.inlined) {
             const inlined = optionResult.inlined;
-            return decodeValue({ long, short, label, type, input: inlined });
+            return decodeValue({ long, label, type, input: inlined });
           }
-          if (definition.defaultWhenNotInlined !== undefined) {
+          if (definition.valueIfNothingInlined !== undefined) {
             try {
-              return definition.defaultWhenNotInlined();
+              return definition.valueIfNothingInlined();
             } catch (error) {
-              throwFailedToGetDefaultValueError(long, error, "not inlined");
+              const context = "Nothing inlined";
+              throwFailedToGetDefaultValueError({ long, error, context });
             }
           }
           const separated = optionResult.separated[0]!;
-          return decodeValue({ long, short, label, type, input: separated });
+          return decodeValue({ long, label, type, input: separated });
         },
       };
     },
@@ -269,7 +271,7 @@ export function optionRepeatable<Value>(definition: {
           const optionResults = readerOptions.getOptionValues(key);
           return optionResults.map((optionResult) => {
             const input = optionResult.inlined ?? optionResult.separated[0]!;
-            return decodeValue({ long, short, label, type, input });
+            return decodeValue({ long, label, type, input });
           });
         },
       };
@@ -279,7 +281,6 @@ export function optionRepeatable<Value>(definition: {
 
 function decodeValue<Value>(params: {
   long: string;
-  short?: string | undefined;
   label?: string | undefined;
   type: Type<Value>;
   input: string;
@@ -288,10 +289,6 @@ function decodeValue<Value>(params: {
     () => params.type.decoder(params.input),
     () => {
       const text = new TypoText();
-      if (params.short) {
-        text.push(new TypoString(`-${params.short}`, typoStyleConstants));
-        text.push(new TypoString(`, `));
-      }
       text.push(new TypoString(`--${params.long}`, typoStyleConstants));
       if (params.label) {
         text.push(new TypoString(`: `));
@@ -336,16 +333,15 @@ function throwSetMultipleTimesError(long: string): never {
   );
 }
 
-function throwFailedToGetDefaultValueError(
-  long: string,
-  error: unknown,
-  context: string,
-): never {
-  throw new TypoError(
-    new TypoText(
-      new TypoString(`--${long}`, typoStyleConstants),
-      new TypoString(`: Failed to get default value (${context})`),
-    ),
-    error,
+function throwFailedToGetDefaultValueError(params: {
+  long: string;
+  error: unknown;
+  context: string;
+}): never {
+  const text = new TypoText();
+  text.push(new TypoString(`--${params.long}`, typoStyleConstants));
+  text.push(
+    new TypoString(`: ${params.context}: Failed to generate default value`),
   );
+  throw new TypoError(text, params.error);
 }

package/src/lib/Positional.ts

@@ -102,7 +102,8 @@ export function positionalRequired<Value>(definition: {
  * ```ts
  * const greeteePositional = positionalOptional({
  *   type: type("name"),
- *   description: "Name to greet (default: world)",
+ *   description: "Name to greet",
+ *   hint: "Defaults to \"world\"",
  *   default: () => "world",
  * });
  * // Usage:

package/src/lib/Reader.ts

@@ -1,3 +1,4 @@
+import { similaritySort } from "./Similarity";
 import {
   TypoError,
   TypoString,
@@ -243,12 +244,7 @@ export class ReaderArgs {
         }
         shortIndexEnd++;
       }
-      throw new TypoError(
-        new TypoText(
-          new TypoString(`Unexpected unknown option(s): `),
-          new TypoString(`-${arg.slice(shortIndexStart)}`, typoStyleQuote),
-        ),
-      );
+      this.#throwUnknownOptionError(`-${arg.slice(shortIndexStart)}`);
     }
     return false;
   }
@@ -259,12 +255,7 @@ export class ReaderArgs {
     if (optionContext !== undefined) {
       return this.#consumeOptionValues(optionContext, constant, inlined);
     }
-    throw new TypoError(
-      new TypoText(
-        new TypoString(`Unexpected unknown option: `),
-        new TypoString(constant, typoStyleQuote),
-      ),
-    );
+    this.#throwUnknownOptionError(constant);
   }
 
   #tryConsumeOptionShort(
@@ -342,6 +333,34 @@ export class ReaderArgs {
   #isValidOptionName(name: string): boolean {
     return name.length > 0 && !name.includes("=") && !name.includes("\0");
   }
+
+  #throwUnknownOptionError(constant: string): never {
+    const candidatesConstants = [];
+    for (const optionLong of this.#optionContextByLong.keys()) {
+      candidatesConstants.push(`--${optionLong}`);
+    }
+    for (const optionShort of this.#optionContextByShort.keys()) {
+      candidatesConstants.push(`-${optionShort}`);
+    }
+    const text = new TypoText();
+    text.push(new TypoString(`Unknown option: `));
+    text.push(new TypoString(`"${constant}"`, typoStyleQuote));
+    if (candidatesConstants.length > 0) {
+      const suggestionsConstants = similaritySort(
+        constant,
+        candidatesConstants.map((candidateConstant) => ({
+          key: candidateConstant,
+          value: new TypoString(candidateConstant, typoStyleConstants),
+        })),
+      ).slice(0, 3);
+      text.push(new TypoString(`: did you mean: `));
+      text.push(TypoText.join(suggestionsConstants, new TypoString(`, `)));
+      text.push(new TypoString(` ?`));
+    } else {
+      text.push(new TypoString(`, no options are registered`));
+    }
+    throw new TypoError(text);
+  }
 }
 
 type ReaderOptionContext = {

package/src/lib/Run.ts

@@ -76,8 +76,8 @@ export async function runAndExit<Context>(
     const colorOption = optionSingleValue<"auto" | RunColorMode>({
       long: "color",
       type: typeChoice("color-mode", ["auto", "always", "never", "mock"]),
-      defaultWhenNotDefined: () => "auto",
-      defaultWhenNotInlined: () => "always",
+      defaultIfNotSpecified: () => "auto",
+      valueIfNothingInlined: () => "always",
     }).registerAndMakeDecoder(readerArgs);
     preprocessors.push(() => {
       try {

package/src/lib/Similarity.ts

@@ -0,0 +1,41 @@
+export function similaritySort<Value>(
+  reference: string,
+  candidates: { [key: string]: Value } | Array<{ key: string; value: Value }>,
+): Array<Value> {
+  let entries = Array.isArray(candidates)
+    ? candidates.map(({ key, value }) => [key, value] as const)
+    : Object.entries(candidates);
+  const ranked = entries.map(([key, value]) => {
+    const score =
+      damerauLevenshtein(reference, key) /
+      Math.max(reference.length, key.length);
+    return { key, value, score };
+  });
+  return ranked.sort((a, b) => a.score - b.score).map((v) => v.value);
+}
+
+function damerauLevenshtein(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array<number>(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) {
+    dp[i]![0] = i;
+  }
+  for (let j = 0; j <= n; j++) {
+    dp[0]![j] = j;
+  }
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i]![j] = Math.min(
+        dp[i - 1]![j]! + 1,
+        dp[i]![j - 1]! + 1,
+        dp[i - 1]![j - 1]! + cost,
+      );
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        dp[i]![j] = Math.min(dp[i]![j]!, dp[i - 2]![j - 2]! + cost);
+      }
+    }
+  }
+  return dp[m]![n]!;
+}

package/src/lib/Type.ts

@@ -1,4 +1,5 @@
 import { statSync } from "fs";
+import { similaritySort } from "./Similarity";
 import {
   TypoError,
   TypoString,
@@ -50,18 +51,17 @@ export function typeBoolean(name?: string): Type<boolean> {
   return {
     content: name ?? "boolean",
     decoder(input: string) {
-      const lower = input.toLowerCase();
-      if (typeBooleanValuesTrue.has(lower)) {
+      const lowerInput = input.toLowerCase();
+      if (typeBooleanValuesTrue.has(lowerInput)) {
         return true;
       }
-      if (typeBooleanValuesFalse.has(lower)) {
+      if (typeBooleanValuesFalse.has(lowerInput)) {
         return false;
       }
       throwInvalidValue("a boolean", input);
     },
   };
 }
-
 export const typeBooleanValuesTrue = new Set(["true", "yes", "on", "y"]);
 export const typeBooleanValuesFalse = new Set(["false", "no", "off", "n"]);
 
@@ -333,38 +333,37 @@ export function typeChoice<const Value extends string>(
   values: Array<Value>,
   caseSensitive: boolean = false,
 ): Type<Value> {
+  if (values.length === 0) {
+    throw new Error("At least one value is required");
+  }
   const normalize = caseSensitive
     ? (s: string) => s
     : (s: string) => s.toLowerCase();
-  const valueMap = new Map(values.map((value) => [normalize(value), value]));
+  const valueByNormalizedKey = new Map(
+    values.map((value) => [normalize(value), value]),
+  );
   return {
     content: name,
     decoder(input: string) {
-      const normalized = normalize(input);
-      const original = valueMap.get(normalized);
-      if (original !== undefined) {
-        return original;
+      const normalizedKey = normalize(input);
+      const value = valueByNormalizedKey.get(normalizedKey);
+      if (value !== undefined) {
+        return value;
       }
-      const valuesPreview = [];
-      for (const value of values) {
-        if (valuesPreview.length >= 5) {
-          valuesPreview.push(new TypoString(`...`));
-          break;
-        }
-        if (valuesPreview.length > 0) {
-          valuesPreview.push(new TypoString(` | `));
-        }
-        valuesPreview.push(new TypoString(`"${value}"`, typoStyleQuote));
-      }
-      throw new TypoError(
-        new TypoText(
-          new TypoString(`Invalid value: `),
-          new TypoString(`"${input}"`, typoStyleQuote),
-          new TypoString(` (expected one of: `),
-          ...valuesPreview,
-          new TypoString(`)`),
-        ),
-      );
+      const text = new TypoText();
+      text.push(new TypoString(`Unknown value: `));
+      text.push(new TypoString(`"${input}"`, typoStyleQuote));
+      const suggestions = similaritySort(
+        normalizedKey,
+        [...valueByNormalizedKey.entries()].map(([normalizedKey, value]) => ({
+          key: normalizedKey,
+          value: new TypoString(`"${value}"`, typoStyleQuote),
+        })),
+      ).slice(0, 3);
+      text.push(new TypoString(`: did you mean: `));
+      text.push(TypoText.join(suggestions, new TypoString(`, `)));
+      text.push(new TypoString(` ?`));
+      throw new TypoError(text);
     },
   };
 }

package/src/lib/Typo.ts

@@ -125,12 +125,12 @@ export const typoStyleRegularWeaker: TypoStyle = {
  */
 export class TypoString {
   #value: string;
-  #typoStyle: TypoStyle;
+  #typoStyle: TypoStyle | undefined;
   /**
    * @param value - Raw text content.
-   * @param typoStyle - Style to apply when rendering. Defaults to `{}` (no style).
+   * @param typoStyle - Style to apply when rendering. Defaults to `undefined` (no style).
    */
-  constructor(value: string, typoStyle: TypoStyle = {}) {
+  constructor(value: string, typoStyle?: TypoStyle) {
     this.#value = value;
     this.#typoStyle = typoStyle;
   }
@@ -150,6 +150,11 @@ export class TypoString {
   }
 }
 
+/**
+ * A segment of styled text, a string, or an array of segments.
+ */
+export type TypoSegment = TypoText | TypoString | string | Array<TypoSegment>;
+
 /**
  * Mutable sequence of {@link TypoString} segments.
  */
@@ -158,12 +163,10 @@ export class TypoText {
   /**
    * @param segments - Initial text segments
    */
-  constructor(
-    ...segments: Array<TypoText | Array<TypoString> | TypoString | string>
-  ) {
+  constructor(...segments: TypoSegment[]) {
     this.#typoStrings = [];
-    for (const typoPart of segments) {
-      this.push(typoPart);
+    for (const segment of segments) {
+      this.push(segment);
     }
   }
   /**
@@ -171,14 +174,14 @@ export class TypoText {
    *
    * @param segment - Text segment(s) to append.
    */
-  push(segment: TypoText | Array<TypoString> | TypoString | string) {
+  push(segment: TypoSegment) {
     if (typeof segment === "string") {
       this.#typoStrings.push(new TypoString(segment));
     } else if (segment instanceof TypoText) {
       this.#typoStrings.push(...segment.#typoStrings);
     } else if (Array.isArray(segment)) {
       for (const typoString of segment) {
-        this.#typoStrings.push(typoString);
+        this.push(typoString);
       }
     } else {
       this.#typoStrings.push(segment);
@@ -211,6 +214,20 @@ export class TypoText {
     }
     return length;
   }
+  /**
+   * Joins multiple segments with a separator.
+   * @returns A new {@link TypoText} containing the joined segments.
+   */
+  static join(segments: Array<TypoSegment>, separator: TypoSegment): TypoText {
+    const result = new TypoText();
+    for (let index = 0; index < segments.length; index++) {
+      if (index > 0) {
+        result.push(separator);
+      }
+      result.push(segments[index]!);
+    }
+    return result;
+  }
 }
 
 /**
@@ -334,8 +351,8 @@ export class TypoError extends Error {
  * Controls ANSI terminal styling. Create via the static factory methods.
  */
 export class TypoSupport {
-  #kind: "none" | "tty" | "mock";
-  private constructor(kind: "none" | "tty" | "mock") {
+  #kind: TypoSupportKind;
+  private constructor(kind: TypoSupportKind) {
     this.#kind = kind;
   }
   /**
@@ -402,7 +419,10 @@ export class TypoSupport {
    * @param typoStyle - Style to apply.
    * @returns Styled string.
    */
-  computeStyledString(value: string, typoStyle: TypoStyle): string {
+  computeStyledString(value: string, typoStyle: TypoStyle | undefined): string {
+    if (typoStyle === undefined) {
+      return value;
+    }
     let styledValue = value;
     if (typoStyle.case === "upper") {
       styledValue = styledValue.toUpperCase();
@@ -516,3 +536,5 @@ function readEnvVar(name: string) {
   }
   return process.env[name];
 }
+
+type TypoSupportKind = "none" | "tty" | "mock";

package/src/lib/Usage.ts

@@ -262,7 +262,7 @@ export function usageToStyledLines(params: {
       for (const commandArg of example.commandArgs) {
         commandLineText.push(textDelimiter(" "));
         if (typeof commandArg === "string") {
-          commandLineText.push(commandArg);
+          commandLineText.push(new TypoString(commandArg));
         } else if ("positional" in commandArg) {
           commandLineText.push(textUserInput(commandArg.positional));
         } else if ("subcommand" in commandArg) {

package/tests/unit.command.execute.ts

@@ -47,7 +47,7 @@ const rootCommand = commandChained(
           string: optionSingleValue({
             long: "string-option",
             type: type(),
-            defaultWhenNotDefined: () => undefined,
+            defaultIfNotSpecified: () => undefined,
           }),
           number: optionRepeatable({
             long: "number-option",

package/tests/unit.command.usage.ts

@@ -39,8 +39,8 @@ const rootCommand = commandChained<any, any, any>(
           long: "choice-option",
           type: typeChoice("choice", ["unset", "empty", "choice1", "choice2"]),
           description: "choice-option description",
-          defaultWhenNotInlined: () => "empty",
-          defaultWhenNotDefined: () => "unset",
+          valueIfNothingInlined: () => "empty",
+          defaultIfNotSpecified: () => "unset",
         }),
         booleanFlag: optionFlag({
           short: "b",
@@ -81,7 +81,7 @@ const rootCommand = commandChained<any, any, any>(
             short: "s",
             long: "string-option",
             type: type("cool-stuff"),
-            defaultWhenNotDefined: () => undefined,
+            defaultIfNotSpecified: () => undefined,
             description: "string-option description",
           }),
           complexOption: optionRepeatable({
@@ -174,7 +174,7 @@ const rootCommand = commandChained<any, any, any>(
               duduValue: optionSingleValue({
                 long: "dudu",
                 type: type("dudu-value"),
-                defaultWhenNotDefined: () => "duduDefault",
+                defaultIfNotSpecified: () => "duduDefault",
                 hint: "Dudu option hint",
                 description: "Dudu option description",
               }),