@optique/core 1.2.0-dev.2246 → 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,7 +302,7 @@ 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
@@ -283,20 +313,7 @@ function appendValueHint(base, input, candidates, options) {
 		maxDistanceRatio: DEFAULT_FIND_SIMILAR_OPTIONS.maxDistanceRatio,
 		maxSuggestions: options.maxSuggestions ?? DEFAULT_FIND_SIMILAR_OPTIONS.maxSuggestions
 	} : void 0);
-	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.text("\n  "), require_message.value(suggestion));
-		suggestionMsg = parts;
-	}
-	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.
@@ -362,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

@@ -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,7 +302,7 @@ 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
@@ -283,20 +313,7 @@ function appendValueHint(base, input, candidates, options) {
 		maxDistanceRatio: DEFAULT_FIND_SIMILAR_OPTIONS.maxDistanceRatio,
 		maxSuggestions: options.maxSuggestions ?? DEFAULT_FIND_SIMILAR_OPTIONS.maxSuggestions
 	} : void 0);
-	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(text("\n  "), value(suggestion));
-		suggestionMsg = parts;
-	}
-	return base.length > 0 ? [
-		...base,
-		lineBreak(),
-		lineBreak(),
-		...suggestionMsg
-	] : suggestionMsg;
+	return appendValueSuggestions(base, suggestions);
 }
 /**
 * Creates a unique key for a suggestion to enable deduplication.
@@ -360,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 };