@optique/core 1.2.0-dev.2240 → 1.2.0-dev.2242

package/dist/suggestion.cjs

@@ -251,6 +251,46 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 	] : baseError;
 }
 /**
+* Appends a "Did you mean …?" hint to a base error message when the input
+* is close to one of the candidate values.
+*
+* This helper is meant for closed-set value parsers (e.g. `choice()`) that
+* want to surface near-match suggestions without re-implementing distance
+* logic themselves.  It wraps {@link findSimilar} and
+* {@link createSuggestionMessage} and returns the `base` message unchanged
+* when no candidates are close enough.
+*
+* @param base The base error message to display.
+* @param input The invalid input the user typed.
+* @param candidates The list of valid candidate strings to suggest from.
+* @param options Optional thresholds; defaults to
+*   {@link DEFAULT_FIND_SIMILAR_OPTIONS}.
+* @returns `base` with a "Did you mean …?" line appended when a close
+*   candidate is found, or `base` unchanged when none are found.
+*
+* @example
+* ```typescript
+* const base = message`Invalid color: ${input}.`;
+* appendValueHint(base, input, ["red", "green", "blue"]);
+* // → "Invalid color: redd.\n\nDid you mean `red`?"
+* ```
+*
+* @since 1.2.0
+*/
+function appendValueHint(base, input, candidates, options) {
+	const suggestions = findSimilar(input, candidates, options != null ? {
+		...DEFAULT_FIND_SIMILAR_OPTIONS,
+		...options
+	} : void 0);
+	const suggestionMsg = createSuggestionMessage(suggestions);
+	return suggestionMsg.length > 0 ? [
+		...base,
+		require_message.lineBreak(),
+		require_message.lineBreak(),
+		...suggestionMsg
+	] : base;
+}
+/**
 * Creates a unique key for a suggestion to enable deduplication.
 *
 * For literal suggestions, the text itself is used as the key.
@@ -313,6 +353,7 @@ function deduplicateSuggestions(suggestions) {
 
 //#endregion
 exports.DEFAULT_FIND_SIMILAR_OPTIONS = DEFAULT_FIND_SIMILAR_OPTIONS;
+exports.appendValueHint = appendValueHint;
 exports.createErrorWithSuggestions = createErrorWithSuggestions;
 exports.createSuggestionMessage = createSuggestionMessage;
 exports.deduplicateSuggestions = deduplicateSuggestions;

package/dist/suggestion.d.cts

@@ -154,6 +154,34 @@ declare function expandCommandAliasSuggestions(usage: Usage, suggestions: readon
  * @since 0.7.0
  */
 declare function createErrorWithSuggestions(baseError: Message, invalidInput: string, usage: Usage, type?: "option" | "command" | "both", customFormatter?: (suggestions: readonly string[]) => Message): Message;
+/**
+ * Appends a "Did you mean …?" hint to a base error message when the input
+ * is close to one of the candidate values.
+ *
+ * This helper is meant for closed-set value parsers (e.g. `choice()`) that
+ * want to surface near-match suggestions without re-implementing distance
+ * logic themselves.  It wraps {@link findSimilar} and
+ * {@link createSuggestionMessage} and returns the `base` message unchanged
+ * when no candidates are close enough.
+ *
+ * @param base The base error message to display.
+ * @param input The invalid input the user typed.
+ * @param candidates The list of valid candidate strings to suggest from.
+ * @param options Optional thresholds; defaults to
+ *   {@link DEFAULT_FIND_SIMILAR_OPTIONS}.
+ * @returns `base` with a "Did you mean …?" line appended when a close
+ *   candidate is found, or `base` unchanged when none are found.
+ *
+ * @example
+ * ```typescript
+ * const base = message`Invalid color: ${input}.`;
+ * appendValueHint(base, input, ["red", "green", "blue"]);
+ * // → "Invalid color: redd.\n\nDid you mean `red`?"
+ * ```
+ *
+ * @since 1.2.0
+ */
+declare function appendValueHint(base: Message, input: string, candidates: readonly string[], options?: Readonly<Pick<FindSimilarOptions, "maxDistance" | "maxSuggestions">>): Message;
 /**
  * Removes duplicate suggestions from an array while preserving order.
  *
@@ -185,4 +213,4 @@ declare function createErrorWithSuggestions(baseError: Message, invalidInput: st
  */
 declare function deduplicateSuggestions(suggestions: readonly Suggestion[]): Suggestion[];
 //#endregion
-export { DEFAULT_FIND_SIMILAR_OPTIONS, FindSimilarOptions, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };
+export { DEFAULT_FIND_SIMILAR_OPTIONS, FindSimilarOptions, appendValueHint, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };

package/dist/suggestion.d.ts

@@ -154,6 +154,34 @@ declare function expandCommandAliasSuggestions(usage: Usage, suggestions: readon
  * @since 0.7.0
  */
 declare function createErrorWithSuggestions(baseError: Message, invalidInput: string, usage: Usage, type?: "option" | "command" | "both", customFormatter?: (suggestions: readonly string[]) => Message): Message;
+/**
+ * Appends a "Did you mean …?" hint to a base error message when the input
+ * is close to one of the candidate values.
+ *
+ * This helper is meant for closed-set value parsers (e.g. `choice()`) that
+ * want to surface near-match suggestions without re-implementing distance
+ * logic themselves.  It wraps {@link findSimilar} and
+ * {@link createSuggestionMessage} and returns the `base` message unchanged
+ * when no candidates are close enough.
+ *
+ * @param base The base error message to display.
+ * @param input The invalid input the user typed.
+ * @param candidates The list of valid candidate strings to suggest from.
+ * @param options Optional thresholds; defaults to
+ *   {@link DEFAULT_FIND_SIMILAR_OPTIONS}.
+ * @returns `base` with a "Did you mean …?" line appended when a close
+ *   candidate is found, or `base` unchanged when none are found.
+ *
+ * @example
+ * ```typescript
+ * const base = message`Invalid color: ${input}.`;
+ * appendValueHint(base, input, ["red", "green", "blue"]);
+ * // → "Invalid color: redd.\n\nDid you mean `red`?"
+ * ```
+ *
+ * @since 1.2.0
+ */
+declare function appendValueHint(base: Message, input: string, candidates: readonly string[], options?: Readonly<Pick<FindSimilarOptions, "maxDistance" | "maxSuggestions">>): Message;
 /**
  * Removes duplicate suggestions from an array while preserving order.
  *
@@ -185,4 +213,4 @@ declare function createErrorWithSuggestions(baseError: Message, invalidInput: st
  */
 declare function deduplicateSuggestions(suggestions: readonly Suggestion[]): Suggestion[];
 //#endregion
-export { DEFAULT_FIND_SIMILAR_OPTIONS, FindSimilarOptions, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };
+export { DEFAULT_FIND_SIMILAR_OPTIONS, FindSimilarOptions, appendValueHint, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };

package/dist/suggestion.js

@@ -1,4 +1,4 @@
-import { message, optionName, text } from "./message.js";
+import { lineBreak, message, optionName, text } from "./message.js";
 import { extractCommandNames, extractOptionNames, isSuggestionHidden } from "./usage.js";
 
 //#region src/suggestion.ts
@@ -251,6 +251,46 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 	] : baseError;
 }
 /**
+* Appends a "Did you mean …?" hint to a base error message when the input
+* is close to one of the candidate values.
+*
+* This helper is meant for closed-set value parsers (e.g. `choice()`) that
+* want to surface near-match suggestions without re-implementing distance
+* logic themselves.  It wraps {@link findSimilar} and
+* {@link createSuggestionMessage} and returns the `base` message unchanged
+* when no candidates are close enough.
+*
+* @param base The base error message to display.
+* @param input The invalid input the user typed.
+* @param candidates The list of valid candidate strings to suggest from.
+* @param options Optional thresholds; defaults to
+*   {@link DEFAULT_FIND_SIMILAR_OPTIONS}.
+* @returns `base` with a "Did you mean …?" line appended when a close
+*   candidate is found, or `base` unchanged when none are found.
+*
+* @example
+* ```typescript
+* const base = message`Invalid color: ${input}.`;
+* appendValueHint(base, input, ["red", "green", "blue"]);
+* // → "Invalid color: redd.\n\nDid you mean `red`?"
+* ```
+*
+* @since 1.2.0
+*/
+function appendValueHint(base, input, candidates, options) {
+	const suggestions = findSimilar(input, candidates, options != null ? {
+		...DEFAULT_FIND_SIMILAR_OPTIONS,
+		...options
+	} : void 0);
+	const suggestionMsg = createSuggestionMessage(suggestions);
+	return suggestionMsg.length > 0 ? [
+		...base,
+		lineBreak(),
+		lineBreak(),
+		...suggestionMsg
+	] : base;
+}
+/**
 * Creates a unique key for a suggestion to enable deduplication.
 *
 * For literal suggestions, the text itself is used as the key.
@@ -312,4 +352,4 @@ function deduplicateSuggestions(suggestions) {
 }
 
 //#endregion
-export { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };
+export { DEFAULT_FIND_SIMILAR_OPTIONS, appendValueHint, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };

package/dist/valueparser.cjs

@@ -139,6 +139,13 @@ function choice(choices, options = {}) {
 		}
 	}
 	const stringInvalidChoice = stringOptions.errors?.invalidChoice;
+	const stringSuggest = stringOptions.suggest;
+	if (stringSuggest !== void 0) {
+		const isValidString = stringSuggest === "nearest" || stringSuggest === "never";
+		const isValidObject = typeof stringSuggest === "object" && stringSuggest !== null;
+		const isValidFunction = typeof stringSuggest === "function";
+		if (!isValidString && !isValidObject && !isValidFunction) throw new TypeError(`Expected suggest to be "nearest", "never", an object, or a function, but got ${typeof stringSuggest}: ${String(stringSuggest)}.`);
+	}
 	return {
 		mode: "sync",
 		metavar: metavar$1,
@@ -149,7 +156,7 @@ function choice(choices, options = {}) {
 			const index = normalizedValues.indexOf(normalizedInput);
 			if (index < 0) return {
 				success: false,
-				error: formatStringChoiceError(input, stringChoices, stringInvalidChoice)
+				error: formatStringChoiceError(input, stringChoices, stringInvalidChoice, stringSuggest)
 			};
 			return {
 				success: true,
@@ -256,9 +263,22 @@ function normalizeDecimal(s) {
 /**
 * Formats error message for string choice parser.
 */
-function formatStringChoiceError(input, choices, invalidChoice) {
-	if (invalidChoice) return typeof invalidChoice === "function" ? invalidChoice(input, choices) : invalidChoice;
-	return formatDefaultChoiceError(input, choices);
+function formatStringChoiceError(input, choices, invalidChoice, suggest) {
+	const base = invalidChoice ? typeof invalidChoice === "function" ? invalidChoice(input, choices) : invalidChoice : formatDefaultChoiceError(input, choices);
+	if (suggest == null || suggest === "never") return base;
+	if (suggest === "nearest") return require_suggestion.appendValueHint(base, input, choices);
+	if (typeof suggest === "function") {
+		const hints = suggest(input, choices);
+		if (!hints || hints.length === 0) return base;
+		const suggestionMsg = require_suggestion.createSuggestionMessage(hints);
+		return suggestionMsg.length > 0 ? [
+			...base,
+			require_message.lineBreak(),
+			require_message.lineBreak(),
+			...suggestionMsg
+		] : base;
+	}
+	return require_suggestion.appendValueHint(base, input, choices, suggest);
 }
 /**
 * Formats error message for number choice parser.

package/dist/valueparser.d.cts

@@ -1,5 +1,6 @@
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 import { Message } from "./message.cjs";
+import { FindSimilarOptions } from "./suggestion.cjs";
 import { Mode, ModeIterable, ModeValue, Suggestion } from "./internal/parser.cjs";
 
 //#region src/valueparser.d.ts
@@ -101,9 +102,20 @@ interface ValueParser<M extends Mode = "sync", T = unknown> {
    * Provides completion suggestions for values of this type.
    * This is optional and used for shell completion functionality.
    *
-   * @param prefix The current input prefix to complete.
-   * @returns An iterable of suggestion objects.
-   *          In async mode, returns an AsyncIterable.
+   * In `"sync"` mode, returns an `Iterable<Suggestion>`.  In `"async"`
+   * mode, returns an `AsyncIterable<Suggestion>`; the runtime consumes
+   * it with `for await`.  Sleeping or yielding in multiple batches is
+   * acceptable.
+   *
+   * For async suggesters, failures must be swallowed and logged rather
+   * than propagated as exceptions, because completion is best-effort.
+   * An exception that escapes the generator will surface as broken
+   * completion in the user's shell.
+   *
+   * @param prefix The current input prefix to complete.  Only yield
+   *   items whose `text` starts with this prefix.
+   * @returns An iterable (or async iterable in async mode) of
+   *   suggestion objects.
    * @since 0.6.0
    */
   suggest?(prefix: string): ModeIterable<M, Suggestion>;
@@ -258,6 +270,25 @@ interface ChoiceOptionsString extends ChoiceOptionsBase {
    * @default `false`
    */
   readonly caseInsensitive?: boolean;
+  /**
+   * Controls whether the error message for an invalid value includes a
+   * "Did you mean …?" hint based on Levenshtein distance.
+   *
+   * - `"nearest"`: append a hint with the closest valid choice(s) using
+   *   default distance thresholds.  Recommended for small-to-medium
+   *   enumeration sets.
+   * - `{ maxDistance?, maxSuggestions? }`: same as `"nearest"` but with
+   *   custom thresholds.
+   * - `"never"`: disable hints; emit the plain "not one of" error message
+   *   unchanged.
+   * - A function `(input, choices) => readonly string[] | undefined`:
+   *   custom suggestion logic.  Return `undefined` to suppress the hint,
+   *   or a non-empty array of strings to display as suggestions.
+   *
+   * @default `"never"` (backward-compatible: no hint is appended)
+   * @since 1.2.0
+   */
+  readonly suggest?: "nearest" | "never" | Readonly<Pick<FindSimilarOptions, "maxDistance" | "maxSuggestions">> | ((input: string, choices: readonly string[]) => readonly string[] | undefined);
   /**
    * Custom error messages for choice parsing failures.
    * @since 0.5.0

package/dist/valueparser.d.ts

@@ -1,5 +1,6 @@
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { Message } from "./message.js";
+import { FindSimilarOptions } from "./suggestion.js";
 import { Mode, ModeIterable, ModeValue, Suggestion } from "./internal/parser.js";
 
 //#region src/valueparser.d.ts
@@ -101,9 +102,20 @@ interface ValueParser<M extends Mode = "sync", T = unknown> {
    * Provides completion suggestions for values of this type.
    * This is optional and used for shell completion functionality.
    *
-   * @param prefix The current input prefix to complete.
-   * @returns An iterable of suggestion objects.
-   *          In async mode, returns an AsyncIterable.
+   * In `"sync"` mode, returns an `Iterable<Suggestion>`.  In `"async"`
+   * mode, returns an `AsyncIterable<Suggestion>`; the runtime consumes
+   * it with `for await`.  Sleeping or yielding in multiple batches is
+   * acceptable.
+   *
+   * For async suggesters, failures must be swallowed and logged rather
+   * than propagated as exceptions, because completion is best-effort.
+   * An exception that escapes the generator will surface as broken
+   * completion in the user's shell.
+   *
+   * @param prefix The current input prefix to complete.  Only yield
+   *   items whose `text` starts with this prefix.
+   * @returns An iterable (or async iterable in async mode) of
+   *   suggestion objects.
    * @since 0.6.0
    */
   suggest?(prefix: string): ModeIterable<M, Suggestion>;
@@ -258,6 +270,25 @@ interface ChoiceOptionsString extends ChoiceOptionsBase {
    * @default `false`
    */
   readonly caseInsensitive?: boolean;
+  /**
+   * Controls whether the error message for an invalid value includes a
+   * "Did you mean …?" hint based on Levenshtein distance.
+   *
+   * - `"nearest"`: append a hint with the closest valid choice(s) using
+   *   default distance thresholds.  Recommended for small-to-medium
+   *   enumeration sets.
+   * - `{ maxDistance?, maxSuggestions? }`: same as `"nearest"` but with
+   *   custom thresholds.
+   * - `"never"`: disable hints; emit the plain "not one of" error message
+   *   unchanged.
+   * - A function `(input, choices) => readonly string[] | undefined`:
+   *   custom suggestion logic.  Return `undefined` to suppress the hint,
+   *   or a non-empty array of strings to display as suggestions.
+   *
+   * @default `"never"` (backward-compatible: no hint is appended)
+   * @since 1.2.0
+   */
+  readonly suggest?: "nearest" | "never" | Readonly<Pick<FindSimilarOptions, "maxDistance" | "maxSuggestions">> | ((input: string, choices: readonly string[]) => readonly string[] | undefined);
   /**
    * Custom error messages for choice parsing failures.
    * @since 0.5.0

package/dist/valueparser.js

@@ -1,6 +1,6 @@
 import { cloneMessage, lineBreak, message, metavar, text, valueSet } from "./message.js";
 import { isDerivedValueParser } from "./internal/dependency.js";
-import { deduplicateSuggestions } from "./suggestion.js";
+import { appendValueHint, createSuggestionMessage, deduplicateSuggestions } from "./suggestion.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 
 //#region src/valueparser.ts
@@ -139,6 +139,13 @@ function choice(choices, options = {}) {
 		}
 	}
 	const stringInvalidChoice = stringOptions.errors?.invalidChoice;
+	const stringSuggest = stringOptions.suggest;
+	if (stringSuggest !== void 0) {
+		const isValidString = stringSuggest === "nearest" || stringSuggest === "never";
+		const isValidObject = typeof stringSuggest === "object" && stringSuggest !== null;
+		const isValidFunction = typeof stringSuggest === "function";
+		if (!isValidString && !isValidObject && !isValidFunction) throw new TypeError(`Expected suggest to be "nearest", "never", an object, or a function, but got ${typeof stringSuggest}: ${String(stringSuggest)}.`);
+	}
 	return {
 		mode: "sync",
 		metavar: metavar$1,
@@ -149,7 +156,7 @@ function choice(choices, options = {}) {
 			const index = normalizedValues.indexOf(normalizedInput);
 			if (index < 0) return {
 				success: false,
-				error: formatStringChoiceError(input, stringChoices, stringInvalidChoice)
+				error: formatStringChoiceError(input, stringChoices, stringInvalidChoice, stringSuggest)
 			};
 			return {
 				success: true,
@@ -256,9 +263,22 @@ function normalizeDecimal(s) {
 /**
 * Formats error message for string choice parser.
 */
-function formatStringChoiceError(input, choices, invalidChoice) {
-	if (invalidChoice) return typeof invalidChoice === "function" ? invalidChoice(input, choices) : invalidChoice;
-	return formatDefaultChoiceError(input, choices);
+function formatStringChoiceError(input, choices, invalidChoice, suggest) {
+	const base = invalidChoice ? typeof invalidChoice === "function" ? invalidChoice(input, choices) : invalidChoice : formatDefaultChoiceError(input, choices);
+	if (suggest == null || suggest === "never") return base;
+	if (suggest === "nearest") return appendValueHint(base, input, choices);
+	if (typeof suggest === "function") {
+		const hints = suggest(input, choices);
+		if (!hints || hints.length === 0) return base;
+		const suggestionMsg = createSuggestionMessage(hints);
+		return suggestionMsg.length > 0 ? [
+			...base,
+			lineBreak(),
+			lineBreak(),
+			...suggestionMsg
+		] : base;
+	}
+	return appendValueHint(base, input, choices, suggest);
 }
 /**
 * Formats error message for number choice parser.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.2.0-dev.2240",
+  "version": "1.2.0-dev.2242",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -179,6 +179,14 @@
       "import": "./dist/program.js",
       "require": "./dist/program.cjs"
     },
+    "./suggestion": {
+      "types": {
+        "import": "./dist/suggestion.d.ts",
+        "require": "./dist/suggestion.d.cts"
+      },
+      "import": "./dist/suggestion.js",
+      "require": "./dist/suggestion.cjs"
+    },
     "./usage": {
       "types": {
         "import": "./dist/usage.d.ts",
@@ -208,7 +216,7 @@
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
-    "@optique/env": "1.2.0-dev.2240+70c4e017"
+    "@optique/env": "1.2.0-dev.2242+4f7a5e89"
   },
   "scripts": {
     "build": "tsdown",