@optique/core 0.7.0-dev.127 → 0.7.0-dev.129

package/README.md

@@ -16,7 +16,7 @@ you usually won't use it directly in browsers.
 
 
 When to use @optique/core
-------------------------
+-------------------------
 
 Use *@optique/core* instead when:
 

package/dist/constructs.cjs

@@ -1,5 +1,6 @@
 const require_message = require('./message.cjs');
 const require_usage = require('./usage.cjs');
+const require_suggestion = require('./suggestion.cjs');
 
 //#region src/constructs.ts
 /**
@@ -42,7 +43,8 @@ function or(...args) {
 				error: context.buffer.length < 1 ? options?.errors?.noMatch ?? require_message.message`No matching option or command found.` : (() => {
 					const token = context.buffer[0];
 					const defaultMsg = require_message.message`Unexpected option or subcommand: ${require_message.optionName(token)}.`;
-					return options?.errors?.unexpectedInput != null ? typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput : defaultMsg;
+					if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
+					return require_suggestion.createErrorWithSuggestions(defaultMsg, token, context.usage, "both", options?.errors?.suggestions);
 				})()
 			};
 			const orderedParsers = parsers.map((p, i) => [p, i]);
@@ -177,7 +179,8 @@ function longestMatch(...args) {
 				error: context.buffer.length < 1 ? options?.errors?.noMatch ?? require_message.message`No matching option or command found.` : (() => {
 					const token = context.buffer[0];
 					const defaultMsg = require_message.message`Unexpected option or subcommand: ${require_message.optionName(token)}.`;
-					return options?.errors?.unexpectedInput != null ? typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput : defaultMsg;
+					if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
+					return require_suggestion.createErrorWithSuggestions(defaultMsg, token, context.usage, "both", options?.errors?.suggestions);
 				})()
 			};
 			for (let i = 0; i < parsers.length; i++) {
@@ -299,7 +302,9 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				error: context.buffer.length > 0 ? (() => {
 					const token = context.buffer[0];
 					const customMessage = options.errors?.unexpectedInput;
-					return customMessage ? typeof customMessage === "function" ? customMessage(token) : customMessage : require_message.message`Unexpected option or argument: ${token}.`;
+					if (customMessage) return typeof customMessage === "function" ? customMessage(token) : customMessage;
+					const baseError = require_message.message`Unexpected option or argument: ${token}.`;
+					return require_suggestion.createErrorWithSuggestions(baseError, token, context.usage, "both", options.errors?.suggestions);
 				})() : options.errors?.endOfInput ?? require_message.message`Expected an option or argument, but got end of input.`
 			};
 			let currentContext = context;

package/dist/constructs.d.cts

@@ -27,6 +27,17 @@ interface OrErrorOptions {
    * Can be a static message or a function that receives the unexpected token.
    */
   unexpectedInput?: Message | ((token: string) => Message);
+  /**
+   * Custom function to format suggestion messages.
+   * If provided, this will be used instead of the default "Did you mean?"
+   * formatting. The function receives an array of similar valid options/commands
+   * and should return a formatted message to append to the error.
+   *
+   * @param suggestions Array of similar valid option/command names
+   * @returns Formatted message to append to the error (can be empty array for no suggestions)
+   * @since 0.7.0
+   */
+  suggestions?: (suggestions: readonly string[]) => Message;
 }
 /**
  * Creates a parser that combines two mutually exclusive parsers into one.
@@ -302,6 +313,17 @@ interface LongestMatchErrorOptions {
    * Can be a static message or a function that receives the unexpected token.
    */
   unexpectedInput?: Message | ((token: string) => Message);
+  /**
+   * Custom function to format suggestion messages.
+   * If provided, this will be used instead of the default "Did you mean?"
+   * formatting. The function receives an array of similar valid options/commands
+   * and should return a formatted message to append to the error.
+   *
+   * @param suggestions Array of similar valid option/command names
+   * @returns Formatted message to append to the error (can be empty array for no suggestions)
+   * @since 0.7.0
+   */
+  suggestions?: (suggestions: readonly string[]) => Message;
 }
 /**
  * Creates a parser that combines two mutually exclusive parsers into one,
@@ -427,6 +449,17 @@ interface ObjectErrorOptions {
    * Error message when end of input is reached unexpectedly.
    */
   readonly endOfInput?: Message;
+  /**
+   * Custom function to format suggestion messages.
+   * If provided, this will be used instead of the default "Did you mean?"
+   * formatting. The function receives an array of similar valid options/commands
+   * and should return a formatted message to append to the error.
+   *
+   * @param suggestions Array of similar valid option/command names
+   * @returns Formatted message to append to the error (can be empty array for no suggestions)
+   * @since 0.7.0
+   */
+  readonly suggestions?: (suggestions: readonly string[]) => Message;
 }
 /**
  * Creates a parser that combines multiple parsers into a single object parser.

package/dist/constructs.d.ts

@@ -27,6 +27,17 @@ interface OrErrorOptions {
    * Can be a static message or a function that receives the unexpected token.
    */
   unexpectedInput?: Message | ((token: string) => Message);
+  /**
+   * Custom function to format suggestion messages.
+   * If provided, this will be used instead of the default "Did you mean?"
+   * formatting. The function receives an array of similar valid options/commands
+   * and should return a formatted message to append to the error.
+   *
+   * @param suggestions Array of similar valid option/command names
+   * @returns Formatted message to append to the error (can be empty array for no suggestions)
+   * @since 0.7.0
+   */
+  suggestions?: (suggestions: readonly string[]) => Message;
 }
 /**
  * Creates a parser that combines two mutually exclusive parsers into one.
@@ -302,6 +313,17 @@ interface LongestMatchErrorOptions {
    * Can be a static message or a function that receives the unexpected token.
    */
   unexpectedInput?: Message | ((token: string) => Message);
+  /**
+   * Custom function to format suggestion messages.
+   * If provided, this will be used instead of the default "Did you mean?"
+   * formatting. The function receives an array of similar valid options/commands
+   * and should return a formatted message to append to the error.
+   *
+   * @param suggestions Array of similar valid option/command names
+   * @returns Formatted message to append to the error (can be empty array for no suggestions)
+   * @since 0.7.0
+   */
+  suggestions?: (suggestions: readonly string[]) => Message;
 }
 /**
  * Creates a parser that combines two mutually exclusive parsers into one,
@@ -427,6 +449,17 @@ interface ObjectErrorOptions {
    * Error message when end of input is reached unexpectedly.
    */
   readonly endOfInput?: Message;
+  /**
+   * Custom function to format suggestion messages.
+   * If provided, this will be used instead of the default "Did you mean?"
+   * formatting. The function receives an array of similar valid options/commands
+   * and should return a formatted message to append to the error.
+   *
+   * @param suggestions Array of similar valid option/command names
+   * @returns Formatted message to append to the error (can be empty array for no suggestions)
+   * @since 0.7.0
+   */
+  readonly suggestions?: (suggestions: readonly string[]) => Message;
 }
 /**
  * Creates a parser that combines multiple parsers into a single object parser.

package/dist/constructs.js

@@ -1,5 +1,6 @@
 import { message, optionName, values } from "./message.js";
 import { extractOptionNames } from "./usage.js";
+import { createErrorWithSuggestions } from "./suggestion.js";
 
 //#region src/constructs.ts
 /**
@@ -42,7 +43,8 @@ function or(...args) {
 				error: context.buffer.length < 1 ? options?.errors?.noMatch ?? message`No matching option or command found.` : (() => {
 					const token = context.buffer[0];
 					const defaultMsg = message`Unexpected option or subcommand: ${optionName(token)}.`;
-					return options?.errors?.unexpectedInput != null ? typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput : defaultMsg;
+					if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
+					return createErrorWithSuggestions(defaultMsg, token, context.usage, "both", options?.errors?.suggestions);
 				})()
 			};
 			const orderedParsers = parsers.map((p, i) => [p, i]);
@@ -177,7 +179,8 @@ function longestMatch(...args) {
 				error: context.buffer.length < 1 ? options?.errors?.noMatch ?? message`No matching option or command found.` : (() => {
 					const token = context.buffer[0];
 					const defaultMsg = message`Unexpected option or subcommand: ${optionName(token)}.`;
-					return options?.errors?.unexpectedInput != null ? typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput : defaultMsg;
+					if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
+					return createErrorWithSuggestions(defaultMsg, token, context.usage, "both", options?.errors?.suggestions);
 				})()
 			};
 			for (let i = 0; i < parsers.length; i++) {
@@ -299,7 +302,9 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				error: context.buffer.length > 0 ? (() => {
 					const token = context.buffer[0];
 					const customMessage = options.errors?.unexpectedInput;
-					return customMessage ? typeof customMessage === "function" ? customMessage(token) : customMessage : message`Unexpected option or argument: ${token}.`;
+					if (customMessage) return typeof customMessage === "function" ? customMessage(token) : customMessage;
+					const baseError = message`Unexpected option or argument: ${token}.`;
+					return createErrorWithSuggestions(baseError, token, context.usage, "both", options.errors?.suggestions);
 				})() : options.errors?.endOfInput ?? message`Expected an option or argument, but got end of input.`
 			};
 			let currentContext = context;

package/dist/index.cjs

@@ -19,6 +19,7 @@ exports.commandLine = require_message.commandLine;
 exports.concat = require_constructs.concat;
 exports.constant = require_primitives.constant;
 exports.envVar = require_message.envVar;
+exports.extractCommandNames = require_usage.extractCommandNames;
 exports.extractOptionNames = require_usage.extractOptionNames;
 exports.fish = require_completion.fish;
 exports.flag = require_primitives.flag;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Message, MessageFormatOptions, MessageTerm, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.cjs";
-import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
+import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.cjs";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.cjs";
@@ -8,4 +8,4 @@ import { DocState, InferValue, Parser, ParserContext, ParserResult, Result, Sugg
 import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { RunError, RunOptions, run } from "./facade.cjs";
-export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, constant, envVar, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, constant, envVar, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Message, MessageFormatOptions, MessageTerm, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
-import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
+import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.js";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.js";
@@ -8,4 +8,4 @@ import { DocState, InferValue, Parser, ParserContext, ParserResult, Result, Sugg
 import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { RunError, RunOptions, run } from "./facade.js";
-export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, constant, envVar, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, constant, envVar, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
-import { extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
+import { extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { formatDocPage } from "./doc.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
@@ -9,4 +9,4 @@ import { argument, command, constant, flag, option } from "./primitives.js";
 import { getDocPage, parse, suggest } from "./parser.js";
 import { RunError, run } from "./facade.js";
 
-export { RunError, WithDefaultError, argument, bash, choice, command, commandLine, concat, constant, envVar, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { RunError, WithDefaultError, argument, bash, choice, command, commandLine, concat, constant, envVar, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/message.cjs

@@ -155,13 +155,41 @@ function formatMessage(msg, options = {}) {
 	const resetSequence = `\x1b[0m${resetSuffix}`;
 	function* stream() {
 		const wordPattern = /\s*\S+\s*/g;
-		for (const term of msg) if (term.type === "text") while (true) {
-			const match = wordPattern.exec(term.text);
-			if (match == null) break;
-			yield {
-				text: match[0],
-				width: match[0].length
+		for (const term of msg) if (term.type === "text") if (term.text.includes("\n\n")) {
+			const paragraphs = term.text.split(/\n\n+/);
+			for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
+				if (paragraphIndex > 0) yield {
+					text: "\n",
+					width: -1
+				};
+				const paragraph = paragraphs[paragraphIndex].replace(/\n/g, " ");
+				wordPattern.lastIndex = 0;
+				while (true) {
+					const match = wordPattern.exec(paragraph);
+					if (match == null) break;
+					yield {
+						text: match[0],
+						width: match[0].length
+					};
+				}
+			}
+		} else {
+			const normalizedText = term.text.replace(/\n/g, " ");
+			if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
+				text: " ",
+				width: 1
 			};
+			else {
+				wordPattern.lastIndex = 0;
+				while (true) {
+					const match = wordPattern.exec(normalizedText);
+					if (match == null) break;
+					yield {
+						text: match[0],
+						width: match[0].length
+					};
+				}
+			}
 		}
 		else if (term.type === "optionName") {
 			const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
@@ -223,6 +251,11 @@ function formatMessage(msg, options = {}) {
 	let output = "";
 	let totalWidth = 0;
 	for (const { text: text$1, width } of stream()) {
+		if (width === -1) {
+			output += text$1;
+			totalWidth = 0;
+			continue;
+		}
 		if (options.maxWidth != null && totalWidth + width > options.maxWidth) {
 			output += "\n";
 			totalWidth = 0;

package/dist/message.js

@@ -154,13 +154,41 @@ function formatMessage(msg, options = {}) {
 	const resetSequence = `\x1b[0m${resetSuffix}`;
 	function* stream() {
 		const wordPattern = /\s*\S+\s*/g;
-		for (const term of msg) if (term.type === "text") while (true) {
-			const match = wordPattern.exec(term.text);
-			if (match == null) break;
-			yield {
-				text: match[0],
-				width: match[0].length
+		for (const term of msg) if (term.type === "text") if (term.text.includes("\n\n")) {
+			const paragraphs = term.text.split(/\n\n+/);
+			for (let paragraphIndex = 0; paragraphIndex < paragraphs.length; paragraphIndex++) {
+				if (paragraphIndex > 0) yield {
+					text: "\n",
+					width: -1
+				};
+				const paragraph = paragraphs[paragraphIndex].replace(/\n/g, " ");
+				wordPattern.lastIndex = 0;
+				while (true) {
+					const match = wordPattern.exec(paragraph);
+					if (match == null) break;
+					yield {
+						text: match[0],
+						width: match[0].length
+					};
+				}
+			}
+		} else {
+			const normalizedText = term.text.replace(/\n/g, " ");
+			if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
+				text: " ",
+				width: 1
 			};
+			else {
+				wordPattern.lastIndex = 0;
+				while (true) {
+					const match = wordPattern.exec(normalizedText);
+					if (match == null) break;
+					yield {
+						text: match[0],
+						width: match[0].length
+					};
+				}
+			}
 		}
 		else if (term.type === "optionName") {
 			const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
@@ -222,6 +250,11 @@ function formatMessage(msg, options = {}) {
 	let output = "";
 	let totalWidth = 0;
 	for (const { text: text$1, width } of stream()) {
+		if (width === -1) {
+			output += text$1;
+			totalWidth = 0;
+			continue;
+		}
 		if (options.maxWidth != null && totalWidth + width > options.maxWidth) {
 			output += "\n";
 			totalWidth = 0;

package/dist/parser.cjs

@@ -23,7 +23,8 @@ function parse(parser, args) {
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState
+		state: parser.initialState,
+		usage: parser.usage
 	};
 	do {
 		const result = parser.parse(context);
@@ -81,7 +82,8 @@ function suggest(parser, args) {
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
-		state: parser.initialState
+		state: parser.initialState,
+		usage: parser.usage
 	};
 	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
@@ -129,7 +131,8 @@ function getDocPage(parser, args = []) {
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState
+		state: parser.initialState,
+		usage: parser.usage
 	};
 	do {
 		const result = parser.parse(context);

package/dist/parser.d.cts

@@ -125,6 +125,14 @@ interface ParserContext<TState> {
    * that no further options should be processed.
    */
   readonly optionsTerminated: boolean;
+  /**
+   * Usage information for the entire parser tree.
+   * Used to provide better error messages with suggestions for typos.
+   * When a parser encounters an invalid option or command, it can use
+   * this information to suggest similar valid options.
+   * @since 0.7.0
+   */
+  readonly usage: Usage;
 }
 /**
  * Represents a suggestion for command-line completion or guidance.

package/dist/parser.d.ts

@@ -125,6 +125,14 @@ interface ParserContext<TState> {
    * that no further options should be processed.
    */
   readonly optionsTerminated: boolean;
+  /**
+   * Usage information for the entire parser tree.
+   * Used to provide better error messages with suggestions for typos.
+   * When a parser encounters an invalid option or command, it can use
+   * this information to suggest similar valid options.
+   * @since 0.7.0
+   */
+  readonly usage: Usage;
 }
 /**
  * Represents a suggestion for command-line completion or guidance.

package/dist/parser.js

@@ -23,7 +23,8 @@ function parse(parser, args) {
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState
+		state: parser.initialState,
+		usage: parser.usage
 	};
 	do {
 		const result = parser.parse(context);
@@ -81,7 +82,8 @@ function suggest(parser, args) {
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
-		state: parser.initialState
+		state: parser.initialState,
+		usage: parser.usage
 	};
 	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
@@ -129,7 +131,8 @@ function getDocPage(parser, args = []) {
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState
+		state: parser.initialState,
+		usage: parser.usage
 	};
 	do {
 		const result = parser.parse(context);

package/dist/primitives.cjs

@@ -1,4 +1,6 @@
 const require_message = require('./message.cjs');
+const require_usage = require('./usage.cjs');
+const require_suggestion = require('./suggestion.cjs');
 const require_valueparser = require('./valueparser.cjs');
 
 //#region src/primitives.ts
@@ -182,10 +184,23 @@ function option(...args) {
 					};
 				}
 			}
+			const invalidOption = context.buffer[0];
+			if (options.errors?.noMatch) {
+				const candidates = /* @__PURE__ */ new Set();
+				for (const name of require_usage.extractOptionNames(context.usage)) candidates.add(name);
+				const suggestions = require_suggestion.findSimilar(invalidOption, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS);
+				const errorMessage = typeof options.errors.noMatch === "function" ? options.errors.noMatch(invalidOption, suggestions) : options.errors.noMatch;
+				return {
+					success: false,
+					consumed: 0,
+					error: errorMessage
+				};
+			}
+			const baseError = require_message.message`No matched option for ${require_message.optionName(invalidOption)}.`;
 			return {
 				success: false,
 				consumed: 0,
-				error: require_message.message`No matched option for ${require_message.optionName(context.buffer[0])}.`
+				error: require_suggestion.createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
 			};
 		},
 		complete(state) {
@@ -386,10 +401,23 @@ function flag(...args) {
 					consumed: [context.buffer[0].slice(0, 2)]
 				};
 			}
+			const invalidOption = context.buffer[0];
+			if (options.errors?.noMatch) {
+				const candidates = /* @__PURE__ */ new Set();
+				for (const name of require_usage.extractOptionNames(context.usage)) candidates.add(name);
+				const suggestions = require_suggestion.findSimilar(invalidOption, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS);
+				const errorMessage = typeof options.errors.noMatch === "function" ? options.errors.noMatch(invalidOption, suggestions) : options.errors.noMatch;
+				return {
+					success: false,
+					consumed: 0,
+					error: errorMessage
+				};
+			}
+			const baseError = require_message.message`No matched option for ${require_message.optionName(invalidOption)}.`;
 			return {
 				success: false,
 				consumed: 0,
-				error: require_message.message`No matched option for ${require_message.optionName(context.buffer[0])}.`
+				error: require_suggestion.createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
 			};
 		},
 		complete(state) {
@@ -565,11 +593,27 @@ function command(name, parser, options = {}) {
 			if (context.state === void 0) {
 				if (context.buffer.length < 1 || context.buffer[0] !== name) {
 					const actual = context.buffer.length > 0 ? context.buffer[0] : null;
-					const errorMessage = options.errors?.notMatched ?? require_message.message`Expected command ${require_message.optionName(name)}, but got ${actual ?? "end of input"}.`;
+					if (options.errors?.notMatched) {
+						const errorMessage = options.errors.notMatched;
+						const candidates = /* @__PURE__ */ new Set();
+						for (const cmdName of require_usage.extractCommandNames(context.usage)) candidates.add(cmdName);
+						const suggestions = actual ? require_suggestion.findSimilar(actual, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS) : [];
+						return {
+							success: false,
+							consumed: 0,
+							error: typeof errorMessage === "function" ? errorMessage(name, actual, suggestions) : errorMessage
+						};
+					}
+					if (actual == null) return {
+						success: false,
+						consumed: 0,
+						error: require_message.message`Expected command ${require_message.optionName(name)}, but got end of input.`
+					};
+					const baseError = require_message.message`Expected command ${require_message.optionName(name)}, but got ${actual}.`;
 					return {
 						success: false,
 						consumed: 0,
-						error: typeof errorMessage === "function" ? errorMessage(name, actual) : errorMessage
+						error: require_suggestion.createErrorWithSuggestions(baseError, actual, context.usage, "command")
 					};
 				}
 				return {

package/dist/primitives.d.cts

@@ -58,6 +58,15 @@ interface OptionErrorOptions {
    * Can be a static message or a function that receives the value.
    */
   unexpectedValue?: Message | ((value: string) => Message);
+  /**
+   * Custom error message when no matching option is found.
+   * Can be a static message or a function that receives:
+   * - invalidOption: The invalid option name that was provided
+   * - suggestions: Array of similar valid option names (can be empty)
+   *
+   * @since 0.7.0
+   */
+  noMatch?: Message | ((invalidOption: string, suggestions: readonly string[]) => Message);
 }
 /**
  * Creates a parser for various styles of command-line options that take an
@@ -138,6 +147,15 @@ interface FlagErrorOptions {
    * Can be a static message or a function that receives the token.
    */
   duplicate?: Message | ((token: string) => Message);
+  /**
+   * Custom error message when no matching flag is found.
+   * Can be a static message or a function that receives:
+   * - invalidOption: The invalid option name that was provided
+   * - suggestions: Array of similar valid option names (can be empty)
+   *
+   * @since 0.7.0
+   */
+  noMatch?: Message | ((invalidOption: string, suggestions: readonly string[]) => Message);
 }
 /**
  * Creates a parser for command-line flags that must be explicitly provided.
@@ -255,8 +273,12 @@ interface CommandOptions {
 interface CommandErrorOptions {
   /**
    * Error message when command is expected but not found.
+   * Since version 0.7.0, the function signature now includes suggestions:
+   * - expected: The expected command name
+   * - actual: The actual input (or null if no input)
+   * - suggestions: Array of similar valid command names (can be empty)
    */
-  readonly notMatched?: Message | ((expected: string, actual: string | null) => Message);
+  readonly notMatched?: Message | ((expected: string, actual: string | null, suggestions?: readonly string[]) => Message);
   /**
    * Error message when command was not matched during completion.
    */

package/dist/primitives.d.ts

@@ -58,6 +58,15 @@ interface OptionErrorOptions {
    * Can be a static message or a function that receives the value.
    */
   unexpectedValue?: Message | ((value: string) => Message);
+  /**
+   * Custom error message when no matching option is found.
+   * Can be a static message or a function that receives:
+   * - invalidOption: The invalid option name that was provided
+   * - suggestions: Array of similar valid option names (can be empty)
+   *
+   * @since 0.7.0
+   */
+  noMatch?: Message | ((invalidOption: string, suggestions: readonly string[]) => Message);
 }
 /**
  * Creates a parser for various styles of command-line options that take an
@@ -138,6 +147,15 @@ interface FlagErrorOptions {
    * Can be a static message or a function that receives the token.
    */
   duplicate?: Message | ((token: string) => Message);
+  /**
+   * Custom error message when no matching flag is found.
+   * Can be a static message or a function that receives:
+   * - invalidOption: The invalid option name that was provided
+   * - suggestions: Array of similar valid option names (can be empty)
+   *
+   * @since 0.7.0
+   */
+  noMatch?: Message | ((invalidOption: string, suggestions: readonly string[]) => Message);
 }
 /**
  * Creates a parser for command-line flags that must be explicitly provided.
@@ -255,8 +273,12 @@ interface CommandOptions {
 interface CommandErrorOptions {
   /**
    * Error message when command is expected but not found.
+   * Since version 0.7.0, the function signature now includes suggestions:
+   * - expected: The expected command name
+   * - actual: The actual input (or null if no input)
+   * - suggestions: Array of similar valid command names (can be empty)
    */
-  readonly notMatched?: Message | ((expected: string, actual: string | null) => Message);
+  readonly notMatched?: Message | ((expected: string, actual: string | null, suggestions?: readonly string[]) => Message);
   /**
    * Error message when command was not matched during completion.
    */

package/dist/primitives.js

@@ -1,4 +1,6 @@
 import { message, metavar, optionName, optionNames } from "./message.js";
+import { extractCommandNames, extractOptionNames } from "./usage.js";
+import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, findSimilar } from "./suggestion.js";
 import { isValueParser } from "./valueparser.js";
 
 //#region src/primitives.ts
@@ -182,10 +184,23 @@ function option(...args) {
 					};
 				}
 			}
+			const invalidOption = context.buffer[0];
+			if (options.errors?.noMatch) {
+				const candidates = /* @__PURE__ */ new Set();
+				for (const name of extractOptionNames(context.usage)) candidates.add(name);
+				const suggestions = findSimilar(invalidOption, candidates, DEFAULT_FIND_SIMILAR_OPTIONS);
+				const errorMessage = typeof options.errors.noMatch === "function" ? options.errors.noMatch(invalidOption, suggestions) : options.errors.noMatch;
+				return {
+					success: false,
+					consumed: 0,
+					error: errorMessage
+				};
+			}
+			const baseError = message`No matched option for ${optionName(invalidOption)}.`;
 			return {
 				success: false,
 				consumed: 0,
-				error: message`No matched option for ${optionName(context.buffer[0])}.`
+				error: createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
 			};
 		},
 		complete(state) {
@@ -386,10 +401,23 @@ function flag(...args) {
 					consumed: [context.buffer[0].slice(0, 2)]
 				};
 			}
+			const invalidOption = context.buffer[0];
+			if (options.errors?.noMatch) {
+				const candidates = /* @__PURE__ */ new Set();
+				for (const name of extractOptionNames(context.usage)) candidates.add(name);
+				const suggestions = findSimilar(invalidOption, candidates, DEFAULT_FIND_SIMILAR_OPTIONS);
+				const errorMessage = typeof options.errors.noMatch === "function" ? options.errors.noMatch(invalidOption, suggestions) : options.errors.noMatch;
+				return {
+					success: false,
+					consumed: 0,
+					error: errorMessage
+				};
+			}
+			const baseError = message`No matched option for ${optionName(invalidOption)}.`;
 			return {
 				success: false,
 				consumed: 0,
-				error: message`No matched option for ${optionName(context.buffer[0])}.`
+				error: createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
 			};
 		},
 		complete(state) {
@@ -565,11 +593,27 @@ function command(name, parser, options = {}) {
 			if (context.state === void 0) {
 				if (context.buffer.length < 1 || context.buffer[0] !== name) {
 					const actual = context.buffer.length > 0 ? context.buffer[0] : null;
-					const errorMessage = options.errors?.notMatched ?? message`Expected command ${optionName(name)}, but got ${actual ?? "end of input"}.`;
+					if (options.errors?.notMatched) {
+						const errorMessage = options.errors.notMatched;
+						const candidates = /* @__PURE__ */ new Set();
+						for (const cmdName of extractCommandNames(context.usage)) candidates.add(cmdName);
+						const suggestions = actual ? findSimilar(actual, candidates, DEFAULT_FIND_SIMILAR_OPTIONS) : [];
+						return {
+							success: false,
+							consumed: 0,
+							error: typeof errorMessage === "function" ? errorMessage(name, actual, suggestions) : errorMessage
+						};
+					}
+					if (actual == null) return {
+						success: false,
+						consumed: 0,
+						error: message`Expected command ${optionName(name)}, but got end of input.`
+					};
+					const baseError = message`Expected command ${optionName(name)}, but got ${actual}.`;
 					return {
 						success: false,
 						consumed: 0,
-						error: typeof errorMessage === "function" ? errorMessage(name, actual) : errorMessage
+						error: createErrorWithSuggestions(baseError, actual, context.usage, "command")
 					};
 				}
 				return {

package/dist/suggestion.cjs

@@ -0,0 +1,186 @@
+const require_message = require('./message.cjs');
+const require_usage = require('./usage.cjs');
+
+//#region src/suggestion.ts
+/**
+* Calculates the Levenshtein distance between two strings.
+*
+* The Levenshtein distance is the minimum number of single-character edits
+* (insertions, deletions, or substitutions) required to transform one string
+* into another.
+*
+* @param source The source string
+* @param target The target string
+* @returns The edit distance (number of insertions, deletions, substitutions)
+*
+* @example
+* ```typescript
+* levenshteinDistance("kitten", "sitting"); // returns 3
+* levenshteinDistance("--verbos", "--verbose"); // returns 1
+* levenshteinDistance("hello", "hello"); // returns 0
+* ```
+*/
+function levenshteinDistance(source, target) {
+	if (source.length === 0) return target.length;
+	if (target.length === 0) return source.length;
+	if (source.length > target.length) [source, target] = [target, source];
+	let previousRow = new Array(source.length + 1);
+	let currentRow = new Array(source.length + 1);
+	for (let i = 0; i <= source.length; i++) previousRow[i] = i;
+	for (let j = 1; j <= target.length; j++) {
+		currentRow[0] = j;
+		for (let i = 1; i <= source.length; i++) {
+			const cost = source[i - 1] === target[j - 1] ? 0 : 1;
+			currentRow[i] = Math.min(currentRow[i - 1] + 1, previousRow[i] + 1, previousRow[i - 1] + cost);
+		}
+		[previousRow, currentRow] = [currentRow, previousRow];
+	}
+	return previousRow[source.length];
+}
+/**
+* Default options for finding similar strings.
+* These values are optimized for command-line option/command name suggestions.
+*
+* @since 0.7.0
+*/
+const DEFAULT_FIND_SIMILAR_OPTIONS = {
+	maxDistance: 3,
+	maxDistanceRatio: .5,
+	maxSuggestions: 3,
+	caseSensitive: false
+};
+/**
+* Finds similar strings from a list of candidates.
+*
+* This function uses Levenshtein distance to find strings that are similar
+* to the input string. Results are sorted by similarity (most similar first).
+*
+* @param input The input string to find matches for
+* @param candidates List of candidate strings to compare against
+* @param options Configuration options
+* @returns Array of similar strings, sorted by similarity (most similar first)
+*
+* @example
+* ```typescript
+* const candidates = ["--verbose", "--version", "--verify", "--help"];
+* findSimilar("--verbos", candidates);
+* // returns ["--verbose"]
+*
+* findSimilar("--ver", candidates, { maxDistance: 5 });
+* // returns ["--verify", "--version", "--verbose"]
+*
+* findSimilar("--xyz", candidates);
+* // returns [] (no similar matches)
+* ```
+*/
+function findSimilar(input, candidates, options = {}) {
+	const maxDistance = options.maxDistance ?? DEFAULT_FIND_SIMILAR_OPTIONS.maxDistance;
+	const maxDistanceRatio = options.maxDistanceRatio ?? DEFAULT_FIND_SIMILAR_OPTIONS.maxDistanceRatio;
+	const maxSuggestions = options.maxSuggestions ?? DEFAULT_FIND_SIMILAR_OPTIONS.maxSuggestions;
+	const caseSensitive = options.caseSensitive ?? DEFAULT_FIND_SIMILAR_OPTIONS.caseSensitive;
+	if (input.length === 0) return [];
+	const normalizedInput = caseSensitive ? input : input.toLowerCase();
+	const matches = [];
+	for (const candidate of candidates) {
+		const normalizedCandidate = caseSensitive ? candidate : candidate.toLowerCase();
+		const distance = levenshteinDistance(normalizedInput, normalizedCandidate);
+		if (distance === 0) return [candidate];
+		const distanceRatio = distance / input.length;
+		if (distance <= maxDistance && distanceRatio <= maxDistanceRatio) matches.push({
+			candidate,
+			distance
+		});
+	}
+	matches.sort((a, b) => {
+		if (a.distance !== b.distance) return a.distance - b.distance;
+		const lengthDiffA = Math.abs(a.candidate.length - input.length);
+		const lengthDiffB = Math.abs(b.candidate.length - input.length);
+		if (lengthDiffA !== lengthDiffB) return lengthDiffA - lengthDiffB;
+		return a.candidate.localeCompare(b.candidate);
+	});
+	return matches.slice(0, maxSuggestions).map((m) => m.candidate);
+}
+/**
+* Creates a suggestion message for a mismatched option/command.
+*
+* This function formats suggestions in a user-friendly way:
+* - No suggestions: returns empty message
+* - One suggestion: "Did you mean `option`?"
+* - Multiple suggestions: "Did you mean one of these?\n  option1\n  option2"
+*
+* @param suggestions List of similar valid options/commands
+* @returns A Message array with suggestion text
+*
+* @example
+* ```typescript
+* createSuggestionMessage(["--verbose", "--version"]);
+* // returns message parts for:
+* // "Did you mean one of these?
+* //   --verbose
+* //   --version"
+*
+* createSuggestionMessage(["--verbose"]);
+* // returns message parts for:
+* // "Did you mean `--verbose`?"
+*
+* createSuggestionMessage([]);
+* // returns []
+* ```
+*/
+function createSuggestionMessage(suggestions) {
+	if (suggestions.length === 0) return [];
+	if (suggestions.length === 1) return require_message.message`Did you mean ${require_message.optionName(suggestions[0])}?`;
+	const messageParts = [require_message.text("Did you mean one of these?")];
+	for (const suggestion of suggestions) {
+		messageParts.push(require_message.text("\n  "));
+		messageParts.push(require_message.optionName(suggestion));
+	}
+	return messageParts;
+}
+/**
+* Creates an error message with suggestions for similar options or commands.
+*
+* This is a convenience function that combines the functionality of
+* `findSimilar()` and `createSuggestionMessage()` to generate user-friendly
+* error messages with "Did you mean?" suggestions.
+*
+* @param baseError The base error message to display
+* @param invalidInput The invalid option or command name that the user typed
+* @param usage The usage information to extract available options/commands from
+* @param type What type of names to suggest ("option", "command", or "both")
+* @param customFormatter Optional custom function to format suggestions instead
+*                        of using the default "Did you mean?" formatting
+* @returns A message combining the base error with suggestions, or just the
+*          base error if no similar names are found
+*
+* @example
+* ```typescript
+* const baseError = message`No matched option for ${optionName("--verbos")}.`;
+* const error = createErrorWithSuggestions(
+*   baseError,
+*   "--verbos",
+*   context.usage,
+*   "option"
+* );
+* // Returns: "No matched option for `--verbos`.\nDid you mean `--verbose`?"
+* ```
+*
+* @since 0.7.0
+*/
+function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both", customFormatter) {
+	const candidates = /* @__PURE__ */ new Set();
+	if (type === "option" || type === "both") for (const name of require_usage.extractOptionNames(usage)) candidates.add(name);
+	if (type === "command" || type === "both") for (const name of require_usage.extractCommandNames(usage)) candidates.add(name);
+	const suggestions = findSimilar(invalidInput, candidates, DEFAULT_FIND_SIMILAR_OPTIONS);
+	const suggestionMsg = customFormatter ? customFormatter(suggestions) : createSuggestionMessage(suggestions);
+	return suggestionMsg.length > 0 ? [
+		...baseError,
+		require_message.text("\n\n"),
+		...suggestionMsg
+	] : baseError;
+}
+
+//#endregion
+exports.DEFAULT_FIND_SIMILAR_OPTIONS = DEFAULT_FIND_SIMILAR_OPTIONS;
+exports.createErrorWithSuggestions = createErrorWithSuggestions;
+exports.findSimilar = findSimilar;

package/dist/suggestion.js

@@ -0,0 +1,184 @@
+import { message, optionName, text } from "./message.js";
+import { extractCommandNames, extractOptionNames } from "./usage.js";
+
+//#region src/suggestion.ts
+/**
+* Calculates the Levenshtein distance between two strings.
+*
+* The Levenshtein distance is the minimum number of single-character edits
+* (insertions, deletions, or substitutions) required to transform one string
+* into another.
+*
+* @param source The source string
+* @param target The target string
+* @returns The edit distance (number of insertions, deletions, substitutions)
+*
+* @example
+* ```typescript
+* levenshteinDistance("kitten", "sitting"); // returns 3
+* levenshteinDistance("--verbos", "--verbose"); // returns 1
+* levenshteinDistance("hello", "hello"); // returns 0
+* ```
+*/
+function levenshteinDistance(source, target) {
+	if (source.length === 0) return target.length;
+	if (target.length === 0) return source.length;
+	if (source.length > target.length) [source, target] = [target, source];
+	let previousRow = new Array(source.length + 1);
+	let currentRow = new Array(source.length + 1);
+	for (let i = 0; i <= source.length; i++) previousRow[i] = i;
+	for (let j = 1; j <= target.length; j++) {
+		currentRow[0] = j;
+		for (let i = 1; i <= source.length; i++) {
+			const cost = source[i - 1] === target[j - 1] ? 0 : 1;
+			currentRow[i] = Math.min(currentRow[i - 1] + 1, previousRow[i] + 1, previousRow[i - 1] + cost);
+		}
+		[previousRow, currentRow] = [currentRow, previousRow];
+	}
+	return previousRow[source.length];
+}
+/**
+* Default options for finding similar strings.
+* These values are optimized for command-line option/command name suggestions.
+*
+* @since 0.7.0
+*/
+const DEFAULT_FIND_SIMILAR_OPTIONS = {
+	maxDistance: 3,
+	maxDistanceRatio: .5,
+	maxSuggestions: 3,
+	caseSensitive: false
+};
+/**
+* Finds similar strings from a list of candidates.
+*
+* This function uses Levenshtein distance to find strings that are similar
+* to the input string. Results are sorted by similarity (most similar first).
+*
+* @param input The input string to find matches for
+* @param candidates List of candidate strings to compare against
+* @param options Configuration options
+* @returns Array of similar strings, sorted by similarity (most similar first)
+*
+* @example
+* ```typescript
+* const candidates = ["--verbose", "--version", "--verify", "--help"];
+* findSimilar("--verbos", candidates);
+* // returns ["--verbose"]
+*
+* findSimilar("--ver", candidates, { maxDistance: 5 });
+* // returns ["--verify", "--version", "--verbose"]
+*
+* findSimilar("--xyz", candidates);
+* // returns [] (no similar matches)
+* ```
+*/
+function findSimilar(input, candidates, options = {}) {
+	const maxDistance = options.maxDistance ?? DEFAULT_FIND_SIMILAR_OPTIONS.maxDistance;
+	const maxDistanceRatio = options.maxDistanceRatio ?? DEFAULT_FIND_SIMILAR_OPTIONS.maxDistanceRatio;
+	const maxSuggestions = options.maxSuggestions ?? DEFAULT_FIND_SIMILAR_OPTIONS.maxSuggestions;
+	const caseSensitive = options.caseSensitive ?? DEFAULT_FIND_SIMILAR_OPTIONS.caseSensitive;
+	if (input.length === 0) return [];
+	const normalizedInput = caseSensitive ? input : input.toLowerCase();
+	const matches = [];
+	for (const candidate of candidates) {
+		const normalizedCandidate = caseSensitive ? candidate : candidate.toLowerCase();
+		const distance = levenshteinDistance(normalizedInput, normalizedCandidate);
+		if (distance === 0) return [candidate];
+		const distanceRatio = distance / input.length;
+		if (distance <= maxDistance && distanceRatio <= maxDistanceRatio) matches.push({
+			candidate,
+			distance
+		});
+	}
+	matches.sort((a, b) => {
+		if (a.distance !== b.distance) return a.distance - b.distance;
+		const lengthDiffA = Math.abs(a.candidate.length - input.length);
+		const lengthDiffB = Math.abs(b.candidate.length - input.length);
+		if (lengthDiffA !== lengthDiffB) return lengthDiffA - lengthDiffB;
+		return a.candidate.localeCompare(b.candidate);
+	});
+	return matches.slice(0, maxSuggestions).map((m) => m.candidate);
+}
+/**
+* Creates a suggestion message for a mismatched option/command.
+*
+* This function formats suggestions in a user-friendly way:
+* - No suggestions: returns empty message
+* - One suggestion: "Did you mean `option`?"
+* - Multiple suggestions: "Did you mean one of these?\n  option1\n  option2"
+*
+* @param suggestions List of similar valid options/commands
+* @returns A Message array with suggestion text
+*
+* @example
+* ```typescript
+* createSuggestionMessage(["--verbose", "--version"]);
+* // returns message parts for:
+* // "Did you mean one of these?
+* //   --verbose
+* //   --version"
+*
+* createSuggestionMessage(["--verbose"]);
+* // returns message parts for:
+* // "Did you mean `--verbose`?"
+*
+* createSuggestionMessage([]);
+* // returns []
+* ```
+*/
+function createSuggestionMessage(suggestions) {
+	if (suggestions.length === 0) return [];
+	if (suggestions.length === 1) return message`Did you mean ${optionName(suggestions[0])}?`;
+	const messageParts = [text("Did you mean one of these?")];
+	for (const suggestion of suggestions) {
+		messageParts.push(text("\n  "));
+		messageParts.push(optionName(suggestion));
+	}
+	return messageParts;
+}
+/**
+* Creates an error message with suggestions for similar options or commands.
+*
+* This is a convenience function that combines the functionality of
+* `findSimilar()` and `createSuggestionMessage()` to generate user-friendly
+* error messages with "Did you mean?" suggestions.
+*
+* @param baseError The base error message to display
+* @param invalidInput The invalid option or command name that the user typed
+* @param usage The usage information to extract available options/commands from
+* @param type What type of names to suggest ("option", "command", or "both")
+* @param customFormatter Optional custom function to format suggestions instead
+*                        of using the default "Did you mean?" formatting
+* @returns A message combining the base error with suggestions, or just the
+*          base error if no similar names are found
+*
+* @example
+* ```typescript
+* const baseError = message`No matched option for ${optionName("--verbos")}.`;
+* const error = createErrorWithSuggestions(
+*   baseError,
+*   "--verbos",
+*   context.usage,
+*   "option"
+* );
+* // Returns: "No matched option for `--verbos`.\nDid you mean `--verbose`?"
+* ```
+*
+* @since 0.7.0
+*/
+function createErrorWithSuggestions(baseError, invalidInput, usage, type = "both", customFormatter) {
+	const candidates = /* @__PURE__ */ new Set();
+	if (type === "option" || type === "both") for (const name of extractOptionNames(usage)) candidates.add(name);
+	if (type === "command" || type === "both") for (const name of extractCommandNames(usage)) candidates.add(name);
+	const suggestions = findSimilar(invalidInput, candidates, DEFAULT_FIND_SIMILAR_OPTIONS);
+	const suggestionMsg = customFormatter ? customFormatter(suggestions) : createSuggestionMessage(suggestions);
+	return suggestionMsg.length > 0 ? [
+		...baseError,
+		text("\n\n"),
+		...suggestionMsg
+	] : baseError;
+}
+
+//#endregion
+export { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, findSimilar };

package/dist/usage.cjs

@@ -23,6 +23,7 @@
 function extractOptionNames(usage) {
 	const names = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
+		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "option") for (const name of term.names) names.add(name);
 		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -31,6 +32,37 @@ function extractOptionNames(usage) {
 	return names;
 }
 /**
+* Extracts all command names from a Usage array.
+*
+* This function recursively traverses the usage structure and collects
+* all command names, similar to {@link extractOptionNames}.
+*
+* @param usage The usage structure to extract command names from
+* @returns A Set of all command names found in the usage structure
+*
+* @example
+* ```typescript
+* const usage: Usage = [
+*   { type: "command", name: "build" },
+*   { type: "command", name: "test" },
+* ];
+* const names = extractCommandNames(usage);
+* // names = Set(["build", "test"])
+* ```
+* @since 0.7.0
+*/
+function extractCommandNames(usage) {
+	const names = /* @__PURE__ */ new Set();
+	function traverseUsage(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) if (term.type === "command") names.add(term.name);
+		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
+	}
+	traverseUsage(usage);
+	return names;
+}
+/**
 * Formats a usage description into a human-readable string representation
 * suitable for command-line help text.
 *
@@ -267,6 +299,7 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
+exports.extractCommandNames = extractCommandNames;
 exports.extractOptionNames = extractOptionNames;
 exports.formatUsage = formatUsage;
 exports.formatUsageTerm = formatUsageTerm;

package/dist/usage.d.cts

@@ -137,6 +137,27 @@ type Usage = readonly UsageTerm[];
  * ```
  */
 declare function extractOptionNames(usage: Usage): Set<string>;
+/**
+ * Extracts all command names from a Usage array.
+ *
+ * This function recursively traverses the usage structure and collects
+ * all command names, similar to {@link extractOptionNames}.
+ *
+ * @param usage The usage structure to extract command names from
+ * @returns A Set of all command names found in the usage structure
+ *
+ * @example
+ * ```typescript
+ * const usage: Usage = [
+ *   { type: "command", name: "build" },
+ *   { type: "command", name: "test" },
+ * ];
+ * const names = extractCommandNames(usage);
+ * // names = Set(["build", "test"])
+ * ```
+ * @since 0.7.0
+ */
+declare function extractCommandNames(usage: Usage): Set<string>;
 /**
  * Options for formatting usage descriptions.
  */
@@ -235,4 +256,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };
+export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };

package/dist/usage.d.ts

@@ -137,6 +137,27 @@ type Usage = readonly UsageTerm[];
  * ```
  */
 declare function extractOptionNames(usage: Usage): Set<string>;
+/**
+ * Extracts all command names from a Usage array.
+ *
+ * This function recursively traverses the usage structure and collects
+ * all command names, similar to {@link extractOptionNames}.
+ *
+ * @param usage The usage structure to extract command names from
+ * @returns A Set of all command names found in the usage structure
+ *
+ * @example
+ * ```typescript
+ * const usage: Usage = [
+ *   { type: "command", name: "build" },
+ *   { type: "command", name: "test" },
+ * ];
+ * const names = extractCommandNames(usage);
+ * // names = Set(["build", "test"])
+ * ```
+ * @since 0.7.0
+ */
+declare function extractCommandNames(usage: Usage): Set<string>;
 /**
  * Options for formatting usage descriptions.
  */
@@ -235,4 +256,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };
+export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };

package/dist/usage.js

@@ -22,6 +22,7 @@
 function extractOptionNames(usage) {
 	const names = /* @__PURE__ */ new Set();
 	function traverseUsage(terms) {
+		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "option") for (const name of term.names) names.add(name);
 		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -30,6 +31,37 @@ function extractOptionNames(usage) {
 	return names;
 }
 /**
+* Extracts all command names from a Usage array.
+*
+* This function recursively traverses the usage structure and collects
+* all command names, similar to {@link extractOptionNames}.
+*
+* @param usage The usage structure to extract command names from
+* @returns A Set of all command names found in the usage structure
+*
+* @example
+* ```typescript
+* const usage: Usage = [
+*   { type: "command", name: "build" },
+*   { type: "command", name: "test" },
+* ];
+* const names = extractCommandNames(usage);
+* // names = Set(["build", "test"])
+* ```
+* @since 0.7.0
+*/
+function extractCommandNames(usage) {
+	const names = /* @__PURE__ */ new Set();
+	function traverseUsage(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) if (term.type === "command") names.add(term.name);
+		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
+	}
+	traverseUsage(usage);
+	return names;
+}
+/**
 * Formats a usage description into a human-readable string representation
 * suitable for command-line help text.
 *
@@ -266,4 +298,4 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
-export { extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };
+export { extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.7.0-dev.127+2f66c91d",
+  "version": "0.7.0-dev.129+a07ddbd0",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",