cli-kiss 0.2.5 → 0.2.7

package/docs/.vitepress/config.mts

@@ -28,8 +28,8 @@ export default defineConfig({
           { text: "Commands", link: "/guide/02_commands" },
           { text: "Options", link: "/guide/03_options" },
           { text: "Positionals", link: "/guide/04_positionals" },
-          { text: "Types", link: "/guide/05_types" },
-          { text: "Running your CLI", link: "/guide/06_run" },
+          { text: "Input Types", link: "/guide/05_input_types" },
+          { text: "Running your CLI", link: "/guide/06_run_as_cli" },
         ],
       },
     ],

package/docs/.vitepress/theme/style.css

@@ -1,4 +1,8 @@
 :root {
-  --vp-home-hero-image-background-image: linear-gradient( -50deg, #ff003cff 0%, #00000000 50%, #459900ff 100% );
-  --vp-home-hero-image-filter: blur(150px);
+  /*
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: linear-gradient(-50deg, #ff003caa 30%, #459900aa 70%);
+  */
+  --vp-home-hero-image-background-image: linear-gradient( -50deg, #ff003c88 25%, #008732aa 60% );
+  --vp-home-hero-image-filter: blur(60px);
 }

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/{05_types.md → 05_input_types.md}

@@ -1,23 +1,26 @@
-# Types
+# Input Types
 
 A `Type<Value>` converts a raw CLI string into a typed value:
 
 - Contains a `content` label about the type of data being decoded
 - Paired with a `decoder` function that throws if the value is invalid.
 
+A `Type<Value>` can then be used as a value for an `Option` or `Positional`
+
 ## Built-in types
 
-All type factories accept an optional `name` parameter that overrides the label shown in help/errors.
+All type factories accept an optional `name` parameter that overrides the label
+shown in help/errors.
 
-| Type factory   | Content type | Accepts                                                                      |
-| -------------- | ------------ | ---------------------------------------------------------------------------- |
-| `type`         | `string`     | Any string                                                                   |
-| `typeBoolean`  | `boolean`    | `true/yes/on/1/y/t` → true, `false/no/off/0/n/f` → false (case-insensitive) |
-| `typeNumber`   | `number`     | Integers, floats, scientific notation                                        |
-| `typeInteger`  | `bigint`     | Integer strings only                                                         |
-| `typeDatetime` | `Date`       | Any format accepted by `Date.parse` (ISO 8601 recommended)                   |
-| `typeUrl`      | `URL`        | Absolute URLs                                                                |
-| `typePath`     | `string`     | Non-empty path strings; optional sync existence check                        |
+| Type factory   | Content type | Accepts                                                             |
+| -------------- | ------------ | ------------------------------------------------------------------- |
+| `type`         | `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                                                |
+| `typeDatetime` | `Date`       | Any format accepted by `Date.parse` (ISO 8601 recommended)          |
+| `typeUrl`      | `URL`        | Absolute URLs                                                       |
+| `typePath`     | `string`     | Non-empty path strings; optional sync existence check               |
 
 ```ts
 type("greeting").decoder("hello"); // → "hello"
@@ -32,8 +35,8 @@ typePath().decoder("/usr/bin"); // → "/usr/bin"
 `typePath` also accepts a second argument for existence checks:
 
 ```ts
-typePath("config", { checkSyncExistAs: "file" });     // throws if not a file
-typePath("dir",    { checkSyncExistAs: "directory" }); // throws if not a directory
+typePath("config", { checkSyncExistAs: "file" }); // throws if not a file
+typePath("dir", { checkSyncExistAs: "directory" }); // throws if not a directory
 ```
 
 ## `typeChoice` — string enum
@@ -101,7 +104,7 @@ const typePort = typeConverted("port", typeNumber(), (n) => {
   return n;
 });
 // "--port 8080"   →  8080
-// "--port 99999"  →  TypoError
+// "--port 99999"  →  throws
 ```
 
 ## `typeRenamed` — rename a type
@@ -109,8 +112,7 @@ const typePort = typeConverted("port", typeNumber(), (n) => {
 Wraps a type with a different label for clearer errors:
 
 ```ts
-const typeId = typeRenamed(typeInteger(), "user-id");
-// errors show "user-id" instead of "integer"
+const typeUserId = typeRenamed(typeInteger("u64"), "user-id");
 ```
 
 ## Custom types
@@ -124,7 +126,7 @@ const typeHexColor: Type<string> = {
     if (/^#[0-9a-fA-F]{6}$/.test(value)) {
       return value;
     }
-    throw new Error(`Not a valid color: "${value}"`);
+    throw new Error(`Not a valid hex color: "${value}"`);
   },
 };
 // "#ff0000"  →  "#ff0000"

package/docs/guide/{06_run.md → 06_run_as_cli.md}

@@ -18,14 +18,14 @@ await runAndExit(cliName, cliArgs, context, command, options?);
 
 ### Options
 
-| Option         | Type                                        | Default        | Description                                                                                 |
-| -------------- | ------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------- |
-| `buildVersion` | `string?`                                   | —              | Enables `--version` flag; prints `<cliName> <buildVersion>`                                 |
-| `usageOnHelp`  | `boolean?`                                  | `true`         | Enables `--help` flag                                                                       |
-| `usageOnError` | `boolean?`                                  | `true`         | Prints usage to stderr when parsing fails                                                   |
-| `colorSetup`   | `"flag"\|"env"\|"always"\|"never"\|"mock"?` | `"flag"`       | Color mode: `"flag"` adds a `--color` option; `"env"` reads env vars; others force the mode |
-| `onError`      | `(error: unknown) => void`                  | —              | Custom handler for parse and execution errors                                               |
-| `onExit`       | `(code: number) => never`                   | `process.exit` | Override for testing                                                                        |
+| Option         | Type                                | Default        | Description                                                                                 |
+| -------------- | ----------------------------------- | -------------- | ------------------------------------------------------------------------------------------- |
+| `buildVersion` | `string?`                           | —              | Enables `--version` flag; prints `<cliName> <buildVersion>`                                 |
+| `usageOnHelp`  | `boolean?`                          | `true`         | Enables `--help` flag                                                                       |
+| `usageOnError` | `boolean?`                          | `true`         | Prints usage to stderr when parsing fails                                                   |
+| `colorSetup`   | `flag` / `env` / `always` / `never` | `"flag"`       | Color mode: `"flag"` adds a `--color` option; `"env"` reads env vars; others force the mode |
+| `onError`      | `(error: unknown) => void`          | —              | Custom handler for parse and execution errors                                               |
+| `onExit`       | `(code: number) => never`           | `process.exit` | Override for testing                                                                        |
 
 ### Exit codes
 
@@ -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: [],
@@ -118,17 +118,12 @@ Colors are auto-detected by default (`colorSetup: "flag"` adds a `--color`
 option). Override:
 
 ```ts
+// Read from env vars (FORCE_COLOR, NO_COLOR), same as `--color=auto`
+await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "env" });
 // Force colors on
 await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "always" });
-
 // Force colors off (useful in CI)
 await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "never" });
-
-// Read from env vars (FORCE_COLOR, NO_COLOR, MOCK_COLOR)
-await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "env" });
-
-// Deterministic mock output (useful in snapshot tests)
-await runAndExit("my-cli", args, ctx, cmd, { colorSetup: "mock" });
 ```
 
 ## Testing your CLI

package/docs/index.md

@@ -2,11 +2,12 @@
 layout: home
 
 hero:
-  name: CLI-kiss
+  name: CLI-Kiss
   text: CLI for TypeScript.
 
   tagline:
-    No bloat, no dependencies.<br/>Standard behavior users expect.<br/>Keep It Simple and Stupid, it just does the job.
+    No bloat, no dependencies.<br/>Standard behavior users expect.<br/>Keep It
+    Simple and Stupid, it just does the job.
 
   image:
     src: /hero.png

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-kiss",
-  "version": "0.2.5",
+  "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

@@ -5,6 +5,11 @@ import { typeChoice } from "./Type";
 import { TypoSupport } from "./Typo";
 import { usageToStyledLines } from "./Usage";
 
+/**
+ * Color selection modes availables
+ */
+export type RunColorMode = "env" | "always" | "never" | "mock";
+
 /**
  * Main entry point: parses CLI arguments, executes the matched command, and exits.
  * Handles `--help`, `--version`, usage-on-error, and exit codes.
@@ -53,7 +58,7 @@ export async function runAndExit<Context>(
   context: Context,
   command: Command<Context, void>,
   options?: {
-    colorSetup?: "flag" | "env" | "always" | "never" | "mock" | undefined;
+    colorSetup?: "flag" | RunColorMode | undefined;
     usageOnHelp?: boolean | undefined;
     usageOnError?: boolean | undefined;
     buildVersion?: string | undefined;
@@ -68,14 +73,12 @@ export async function runAndExit<Context>(
   let typoSupport = TypoSupport.none();
   const colorSetup = options?.colorSetup ?? "flag";
   if (colorSetup === "flag") {
-    const colorOption = optionSingleValue<"auto" | "always" | "never" | "mock">(
-      {
-        long: "color",
-        type: typeChoice("color-mode", ["auto", "always", "never", "mock"]),
-        defaultWhenNotDefined: () => "auto",
-        defaultWhenNotInlined: () => "always",
-      },
-    ).registerAndMakeDecoder(readerArgs);
+    const colorOption = optionSingleValue<"auto" | RunColorMode>({
+      long: "color",
+      type: typeChoice("color-mode", ["auto", "always", "never", "mock"]),
+      defaultIfNotSpecified: () => "auto",
+      valueIfNothingInlined: () => "always",
+    }).registerAndMakeDecoder(readerArgs);
     preprocessors.push(() => {
       try {
         typoSupport = computeTypoSupport(colorOption.getAndDecodeValue());
@@ -86,11 +89,7 @@ export async function runAndExit<Context>(
       return undefined;
     });
   } else {
-    if (colorSetup === "env") {
-      typoSupport = TypoSupport.inferFromEnv();
-    } else {
-      typoSupport = computeTypoSupport(colorSetup);
-    }
+    typoSupport = computeTypoSupport(colorSetup);
   }
   if (options?.usageOnHelp ?? true) {
     const helpOption = optionFlag({ long: "help" }).registerAndMakeDecoder(
@@ -182,12 +181,12 @@ function computeUsageString<Context, Result>(
   }).join("\n");
 }
 
-function computeTypoSupport(
-  colorMode: "auto" | "always" | "never" | "mock",
-): TypoSupport {
+function computeTypoSupport(colorMode: "auto" | RunColorMode): TypoSupport {
   switch (colorMode) {
     case "auto":
       return TypoSupport.inferFromEnv();
+    case "env":
+      return TypoSupport.inferFromEnv();
     case "always":
       return TypoSupport.tty();
     case "never":

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]!;
+}