@optique/core 1.2.0-dev.2244 → 1.2.0-dev.2248

package/dist/suggestion.cjs

@@ -251,14 +251,44 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 	] : baseError;
 }
 /**
+* Appends a "Did you mean …?" hint to a base message from a pre-filtered list
+* of suggestion strings.
+*
+* Unlike {@link appendValueHint}, this function accepts suggestions that have
+* already been selected by the caller—it only handles formatting and
+* appending.  Useful when the caller provides its own distance logic (e.g.,
+* the custom-function form of `choice()`'s `suggest` option).
+*
+* @param base The base error message.
+* @param suggestions The already-filtered suggestion strings to display.
+* @returns `base` with a "Did you mean …?" line appended, or `base` unchanged
+*   when `suggestions` is empty.
+* @since 1.2.0
+*/
+function appendValueSuggestions(base, suggestions) {
+	if (suggestions.length === 0) return base;
+	let suggestionMsg;
+	if (suggestions.length === 1) suggestionMsg = require_message.message`Did you mean ${require_message.value(suggestions[0])}?`;
+	else {
+		const parts = [require_message.text("Did you mean one of these?")];
+		for (const suggestion of suggestions) parts.push(require_message.lineBreak(), require_message.text("  "), require_message.value(suggestion));
+		suggestionMsg = parts;
+	}
+	return base.length > 0 ? [
+		...base,
+		require_message.lineBreak(),
+		require_message.lineBreak(),
+		...suggestionMsg
+	] : suggestionMsg;
+}
+/**
 * 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.
+* logic themselves.  It wraps {@link findSimilar} 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.
@@ -272,24 +302,18 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 * ```typescript
 * const base = message`Invalid color: ${input}.`;
 * appendValueHint(base, input, ["red", "green", "blue"]);
-* // → "Invalid color: redd.\n\nDid you mean `red`?"
+* // → "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
+		maxDistance: options.maxDistance ?? DEFAULT_FIND_SIMILAR_OPTIONS.maxDistance,
+		maxDistanceRatio: DEFAULT_FIND_SIMILAR_OPTIONS.maxDistanceRatio,
+		maxSuggestions: options.maxSuggestions ?? DEFAULT_FIND_SIMILAR_OPTIONS.maxSuggestions
 	} : void 0);
-	const suggestionMsg = createSuggestionMessage(suggestions);
-	if (suggestionMsg.length === 0) return base;
-	return base.length > 0 ? [
-		...base,
-		require_message.lineBreak(),
-		require_message.lineBreak(),
-		...suggestionMsg
-	] : suggestionMsg;
+	return appendValueSuggestions(base, suggestions);
 }
 /**
 * Creates a unique key for a suggestion to enable deduplication.
@@ -355,6 +379,7 @@ function deduplicateSuggestions(suggestions) {
 //#endregion
 exports.DEFAULT_FIND_SIMILAR_OPTIONS = DEFAULT_FIND_SIMILAR_OPTIONS;
 exports.appendValueHint = appendValueHint;
+exports.appendValueSuggestions = appendValueSuggestions;
 exports.createErrorWithSuggestions = createErrorWithSuggestions;
 exports.createSuggestionMessage = createSuggestionMessage;
 exports.deduplicateSuggestions = deduplicateSuggestions;

package/dist/suggestion.d.cts

@@ -154,15 +154,30 @@ 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 message from a pre-filtered list
+ * of suggestion strings.
+ *
+ * Unlike {@link appendValueHint}, this function accepts suggestions that have
+ * already been selected by the caller—it only handles formatting and
+ * appending.  Useful when the caller provides its own distance logic (e.g.,
+ * the custom-function form of `choice()`'s `suggest` option).
+ *
+ * @param base The base error message.
+ * @param suggestions The already-filtered suggestion strings to display.
+ * @returns `base` with a "Did you mean …?" line appended, or `base` unchanged
+ *   when `suggestions` is empty.
+ * @since 1.2.0
+ */
+declare function appendValueSuggestions(base: Message, suggestions: readonly string[]): 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.
+ * logic themselves.  It wraps {@link findSimilar} 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.
@@ -176,7 +191,7 @@ declare function createErrorWithSuggestions(baseError: Message, invalidInput: st
  * ```typescript
  * const base = message`Invalid color: ${input}.`;
  * appendValueHint(base, input, ["red", "green", "blue"]);
- * // → "Invalid color: redd.\n\nDid you mean `red`?"
+ * // → "Invalid color: redd.\n\nDid you mean \"red\"?"
  * ```
  *
  * @since 1.2.0
@@ -213,4 +228,4 @@ declare function appendValueHint(base: Message, input: string, candidates: reado
  */
 declare function deduplicateSuggestions(suggestions: readonly Suggestion[]): Suggestion[];
 //#endregion
-export { DEFAULT_FIND_SIMILAR_OPTIONS, FindSimilarOptions, appendValueHint, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };
+export { DEFAULT_FIND_SIMILAR_OPTIONS, FindSimilarOptions, appendValueHint, appendValueSuggestions, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };

package/dist/suggestion.d.ts

@@ -154,15 +154,30 @@ 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 message from a pre-filtered list
+ * of suggestion strings.
+ *
+ * Unlike {@link appendValueHint}, this function accepts suggestions that have
+ * already been selected by the caller—it only handles formatting and
+ * appending.  Useful when the caller provides its own distance logic (e.g.,
+ * the custom-function form of `choice()`'s `suggest` option).
+ *
+ * @param base The base error message.
+ * @param suggestions The already-filtered suggestion strings to display.
+ * @returns `base` with a "Did you mean …?" line appended, or `base` unchanged
+ *   when `suggestions` is empty.
+ * @since 1.2.0
+ */
+declare function appendValueSuggestions(base: Message, suggestions: readonly string[]): 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.
+ * logic themselves.  It wraps {@link findSimilar} 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.
@@ -176,7 +191,7 @@ declare function createErrorWithSuggestions(baseError: Message, invalidInput: st
  * ```typescript
  * const base = message`Invalid color: ${input}.`;
  * appendValueHint(base, input, ["red", "green", "blue"]);
- * // → "Invalid color: redd.\n\nDid you mean `red`?"
+ * // → "Invalid color: redd.\n\nDid you mean \"red\"?"
  * ```
  *
  * @since 1.2.0
@@ -213,4 +228,4 @@ declare function appendValueHint(base: Message, input: string, candidates: reado
  */
 declare function deduplicateSuggestions(suggestions: readonly Suggestion[]): Suggestion[];
 //#endregion
-export { DEFAULT_FIND_SIMILAR_OPTIONS, FindSimilarOptions, appendValueHint, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };
+export { DEFAULT_FIND_SIMILAR_OPTIONS, FindSimilarOptions, appendValueHint, appendValueSuggestions, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };

package/dist/suggestion.js

@@ -1,4 +1,4 @@
-import { lineBreak, message, optionName, text } from "./message.js";
+import { lineBreak, message, optionName, text, value } from "./message.js";
 import { extractCommandNames, extractOptionNames, isSuggestionHidden } from "./usage.js";
 
 //#region src/suggestion.ts
@@ -251,14 +251,44 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 	] : baseError;
 }
 /**
+* Appends a "Did you mean …?" hint to a base message from a pre-filtered list
+* of suggestion strings.
+*
+* Unlike {@link appendValueHint}, this function accepts suggestions that have
+* already been selected by the caller—it only handles formatting and
+* appending.  Useful when the caller provides its own distance logic (e.g.,
+* the custom-function form of `choice()`'s `suggest` option).
+*
+* @param base The base error message.
+* @param suggestions The already-filtered suggestion strings to display.
+* @returns `base` with a "Did you mean …?" line appended, or `base` unchanged
+*   when `suggestions` is empty.
+* @since 1.2.0
+*/
+function appendValueSuggestions(base, suggestions) {
+	if (suggestions.length === 0) return base;
+	let suggestionMsg;
+	if (suggestions.length === 1) suggestionMsg = message`Did you mean ${value(suggestions[0])}?`;
+	else {
+		const parts = [text("Did you mean one of these?")];
+		for (const suggestion of suggestions) parts.push(lineBreak(), text("  "), value(suggestion));
+		suggestionMsg = parts;
+	}
+	return base.length > 0 ? [
+		...base,
+		lineBreak(),
+		lineBreak(),
+		...suggestionMsg
+	] : suggestionMsg;
+}
+/**
 * 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.
+* logic themselves.  It wraps {@link findSimilar} 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.
@@ -272,24 +302,18 @@ function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both
 * ```typescript
 * const base = message`Invalid color: ${input}.`;
 * appendValueHint(base, input, ["red", "green", "blue"]);
-* // → "Invalid color: redd.\n\nDid you mean `red`?"
+* // → "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
+		maxDistance: options.maxDistance ?? DEFAULT_FIND_SIMILAR_OPTIONS.maxDistance,
+		maxDistanceRatio: DEFAULT_FIND_SIMILAR_OPTIONS.maxDistanceRatio,
+		maxSuggestions: options.maxSuggestions ?? DEFAULT_FIND_SIMILAR_OPTIONS.maxSuggestions
 	} : void 0);
-	const suggestionMsg = createSuggestionMessage(suggestions);
-	if (suggestionMsg.length === 0) return base;
-	return base.length > 0 ? [
-		...base,
-		lineBreak(),
-		lineBreak(),
-		...suggestionMsg
-	] : suggestionMsg;
+	return appendValueSuggestions(base, suggestions);
 }
 /**
 * Creates a unique key for a suggestion to enable deduplication.
@@ -353,4 +377,4 @@ function deduplicateSuggestions(suggestions) {
 }
 
 //#endregion
-export { DEFAULT_FIND_SIMILAR_OPTIONS, appendValueHint, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };
+export { DEFAULT_FIND_SIMILAR_OPTIONS, appendValueHint, appendValueSuggestions, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar, levenshteinDistance };

package/dist/valueparser.cjs

@@ -151,8 +151,8 @@ function choice(choices, options = {}) {
 		}
 		if (isValidObject) {
 			const obj = stringSuggest;
-			if (obj.maxDistance !== void 0 && (typeof obj.maxDistance !== "number" || !isFinite(obj.maxDistance))) throw new TypeError(`Expected suggest.maxDistance to be a finite number, but got ${typeof obj.maxDistance}: ${String(obj.maxDistance)}.`);
-			if (obj.maxSuggestions !== void 0 && (typeof obj.maxSuggestions !== "number" || !isFinite(obj.maxSuggestions))) throw new TypeError(`Expected suggest.maxSuggestions to be a finite number, but got ${typeof obj.maxSuggestions}: ${String(obj.maxSuggestions)}.`);
+			if (obj.maxDistance !== void 0 && (typeof obj.maxDistance !== "number" || !Number.isInteger(obj.maxDistance) || obj.maxDistance < 0)) throw new TypeError(`Expected suggest.maxDistance to be a non-negative integer, but got ${typeof obj.maxDistance}: ${String(obj.maxDistance)}.`);
+			if (obj.maxSuggestions !== void 0 && (typeof obj.maxSuggestions !== "number" || !Number.isInteger(obj.maxSuggestions) || obj.maxSuggestions < 1)) throw new TypeError(`Expected suggest.maxSuggestions to be a positive integer, but got ${typeof obj.maxSuggestions}: ${String(obj.maxSuggestions)}.`);
 		}
 	}
 	return {
@@ -278,14 +278,8 @@ function formatStringChoiceError(input, choices, invalidChoice, suggest) {
 	if (suggest === "nearest") return require_suggestion.appendValueHint(base, input, choices);
 	if (typeof suggest === "function") {
 		const hints = suggest(input, choices);
-		if (!Array.isArray(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;
+		if (!Array.isArray(hints)) return base;
+		return require_suggestion.appendValueSuggestions(base, hints);
 	}
 	return require_suggestion.appendValueHint(base, input, choices, suggest);
 }

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 { appendValueHint, createSuggestionMessage, deduplicateSuggestions } from "./suggestion.js";
+import { appendValueHint, appendValueSuggestions, deduplicateSuggestions } from "./suggestion.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 
 //#region src/valueparser.ts
@@ -151,8 +151,8 @@ function choice(choices, options = {}) {
 		}
 		if (isValidObject) {
 			const obj = stringSuggest;
-			if (obj.maxDistance !== void 0 && (typeof obj.maxDistance !== "number" || !isFinite(obj.maxDistance))) throw new TypeError(`Expected suggest.maxDistance to be a finite number, but got ${typeof obj.maxDistance}: ${String(obj.maxDistance)}.`);
-			if (obj.maxSuggestions !== void 0 && (typeof obj.maxSuggestions !== "number" || !isFinite(obj.maxSuggestions))) throw new TypeError(`Expected suggest.maxSuggestions to be a finite number, but got ${typeof obj.maxSuggestions}: ${String(obj.maxSuggestions)}.`);
+			if (obj.maxDistance !== void 0 && (typeof obj.maxDistance !== "number" || !Number.isInteger(obj.maxDistance) || obj.maxDistance < 0)) throw new TypeError(`Expected suggest.maxDistance to be a non-negative integer, but got ${typeof obj.maxDistance}: ${String(obj.maxDistance)}.`);
+			if (obj.maxSuggestions !== void 0 && (typeof obj.maxSuggestions !== "number" || !Number.isInteger(obj.maxSuggestions) || obj.maxSuggestions < 1)) throw new TypeError(`Expected suggest.maxSuggestions to be a positive integer, but got ${typeof obj.maxSuggestions}: ${String(obj.maxSuggestions)}.`);
 		}
 	}
 	return {
@@ -278,14 +278,8 @@ function formatStringChoiceError(input, choices, invalidChoice, suggest) {
 	if (suggest === "nearest") return appendValueHint(base, input, choices);
 	if (typeof suggest === "function") {
 		const hints = suggest(input, choices);
-		if (!Array.isArray(hints) || hints.length === 0) return base;
-		const suggestionMsg = createSuggestionMessage(hints);
-		return suggestionMsg.length > 0 ? [
-			...base,
-			lineBreak(),
-			lineBreak(),
-			...suggestionMsg
-		] : base;
+		if (!Array.isArray(hints)) return base;
+		return appendValueSuggestions(base, hints);
 	}
 	return appendValueHint(base, input, choices, suggest);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.2.0-dev.2244",
+  "version": "1.2.0-dev.2248",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -216,7 +216,7 @@
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
-    "@optique/env": "1.2.0-dev.2244+b3c70b3c"
+    "@optique/env": "1.2.0-dev.2248+e16654a6"
   },
   "scripts": {
     "build": "tsdown",