@optique/core 0.8.0-dev.165 → 0.8.0-dev.167

package/dist/constructs.js

@@ -1,6 +1,6 @@
 import { message, optionName, values } from "./message.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames } from "./usage.js";
-import { createErrorWithSuggestions } from "./suggestion.js";
+import { createErrorWithSuggestions, deduplicateSuggestions } from "./suggestion.js";
 
 //#region src/constructs.ts
 /**
@@ -47,6 +47,35 @@ function analyzeNoMatchContext(parsers) {
 	};
 }
 /**
+* Error class thrown when duplicate option names are detected during parser
+* construction. This is a programmer error, not a user error.
+*/
+var DuplicateOptionError = class extends Error {
+	constructor(optionName$1, sources) {
+		super(`Duplicate option name "${optionName$1}" found in fields: ${sources.join(", ")}. Each option name must be unique within a parser combinator.`);
+		this.optionName = optionName$1;
+		this.sources = sources;
+		this.name = "DuplicateOptionError";
+	}
+};
+/**
+* Checks for duplicate option names across parser sources and throws an error
+* if duplicates are found. This should be called at construction time.
+* @param parserSources Array of [source, usage] tuples
+* @throws DuplicateOptionError if duplicate option names are found
+*/
+function checkDuplicateOptionNames(parserSources) {
+	const optionNameSources = /* @__PURE__ */ new Map();
+	for (const [source, usage] of parserSources) {
+		const names = extractOptionNames(usage);
+		for (const name of names) {
+			if (!optionNameSources.has(name)) optionNameSources.set(name, []);
+			optionNameSources.get(name).push(source);
+		}
+	}
+	for (const [name, sources] of optionNameSources) if (sources.length > 1) throw new DuplicateOptionError(name, sources);
+}
+/**
 * Generates a contextual error message based on what types of inputs
 * the parsers expect (options, commands, or arguments).
 * @param context Context about what types of inputs are expected
@@ -63,6 +92,70 @@ function generateNoMatchError(context) {
 	else return message`No matching option, command, or argument found.`;
 }
 /**
+* Creates a complete() method shared by or() and longestMatch().
+* @internal
+*/
+function createExclusiveComplete(parsers, options, noMatchContext) {
+	return (state) => {
+		if (state == null) return {
+			success: false,
+			error: getNoMatchError(options, noMatchContext)
+		};
+		const [i, result] = state;
+		if (result.success) return parsers[i].complete(result.next.state);
+		return {
+			success: false,
+			error: result.error
+		};
+	};
+}
+/**
+* Creates a suggest() method shared by or() and longestMatch().
+* @internal
+*/
+function createExclusiveSuggest(parsers) {
+	return (context, prefix) => {
+		const suggestions = [];
+		if (context.state == null) for (const parser of parsers) {
+			const parserSuggestions = parser.suggest({
+				...context,
+				state: parser.initialState
+			}, prefix);
+			suggestions.push(...parserSuggestions);
+		}
+		else {
+			const [index, parserResult] = context.state;
+			if (parserResult.success) {
+				const parserSuggestions = parsers[index].suggest({
+					...context,
+					state: parserResult.next.state
+				}, prefix);
+				suggestions.push(...parserSuggestions);
+			}
+		}
+		return deduplicateSuggestions(suggestions);
+	};
+}
+/**
+* Gets the no-match error, either from custom options or default.
+* Shared by or() and longestMatch().
+* @internal
+*/
+function getNoMatchError(options, noMatchContext) {
+	const customNoMatch = options?.errors?.noMatch;
+	return customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
+}
+/**
+* Creates default error for parse() method when buffer is not empty.
+* Shared by or() and longestMatch().
+* @internal
+*/
+function createUnexpectedInputError(token, usage, options) {
+	const defaultMsg = message`Unexpected option or subcommand: ${optionName(token)}.`;
+	if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
+	return createErrorWithSuggestions(defaultMsg, token, usage, "both", options?.errors?.suggestions);
+}
+/**
 * @since 0.5.0
 */
 function or(...args) {
@@ -85,34 +178,11 @@ function or(...args) {
 			terms: parsers.map((p) => p.usage)
 		}],
 		initialState: void 0,
-		complete(state) {
-			if (state == null) {
-				const customNoMatch = options?.errors?.noMatch;
-				const error = customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
-				return {
-					success: false,
-					error
-				};
-			}
-			const [i, result] = state;
-			if (result.success) return parsers[i].complete(result.next.state);
-			return {
-				success: false,
-				error: result.error
-			};
-		},
+		complete: createExclusiveComplete(parsers, options, noMatchContext),
 		parse(context) {
 			let error = {
 				consumed: 0,
-				error: context.buffer.length < 1 ? (() => {
-					const customNoMatch = options?.errors?.noMatch;
-					return customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
-				})() : (() => {
-					const token = context.buffer[0];
-					const defaultMsg = message`Unexpected option or subcommand: ${optionName(token)}.`;
-					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);
-				})()
+				error: context.buffer.length < 1 ? getNoMatchError(options, noMatchContext) : createUnexpectedInputError(context.buffer[0], context.usage, options)
 			};
 			const orderedParsers = parsers.map((p, i) => [p, i]);
 			orderedParsers.sort(([_, a], [__, b]) => context.state?.[0] === a ? -1 : context.state?.[0] === b ? 1 : a - b);
@@ -144,33 +214,7 @@ function or(...args) {
 				success: false
 			};
 		},
-		suggest(context, prefix) {
-			const suggestions = [];
-			if (context.state == null) for (const parser of parsers) {
-				const parserSuggestions = parser.suggest({
-					...context,
-					state: parser.initialState
-				}, prefix);
-				suggestions.push(...parserSuggestions);
-			}
-			else {
-				const [index, parserResult] = context.state;
-				if (parserResult.success) {
-					const parserSuggestions = parsers[index].suggest({
-						...context,
-						state: parserResult.next.state
-					}, prefix);
-					suggestions.push(...parserSuggestions);
-				}
-			}
-			const seen = /* @__PURE__ */ new Set();
-			return suggestions.filter((suggestion) => {
-				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}:${suggestion.pattern}`;
-				if (seen.has(key)) return false;
-				seen.add(key);
-				return true;
-			});
-		},
+		suggest: createExclusiveSuggest(parsers),
 		getDocFragments(state, _defaultValue) {
 			let description;
 			let fragments;
@@ -228,35 +272,12 @@ function longestMatch(...args) {
 			terms: parsers.map((p) => p.usage)
 		}],
 		initialState: void 0,
-		complete(state) {
-			if (state == null) {
-				const customNoMatch = options?.errors?.noMatch;
-				const error = customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
-				return {
-					success: false,
-					error
-				};
-			}
-			const [i, result] = state;
-			if (result.success) return parsers[i].complete(result.next.state);
-			return {
-				success: false,
-				error: result.error
-			};
-		},
+		complete: createExclusiveComplete(parsers, options, noMatchContext),
 		parse(context) {
 			let bestMatch = null;
 			let error = {
 				consumed: 0,
-				error: context.buffer.length < 1 ? (() => {
-					const customNoMatch = options?.errors?.noMatch;
-					return customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
-				})() : (() => {
-					const token = context.buffer[0];
-					const defaultMsg = message`Unexpected option or subcommand: ${optionName(token)}.`;
-					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);
-				})()
+				error: context.buffer.length < 1 ? getNoMatchError(options, noMatchContext) : createUnexpectedInputError(context.buffer[0], context.usage, options)
 			};
 			for (let i = 0; i < parsers.length; i++) {
 				const parser = parsers[i];
@@ -288,33 +309,7 @@ function longestMatch(...args) {
 				success: false
 			};
 		},
-		suggest(context, prefix) {
-			const suggestions = [];
-			if (context.state == null) for (const parser of parsers) {
-				const parserSuggestions = parser.suggest({
-					...context,
-					state: parser.initialState
-				}, prefix);
-				suggestions.push(...parserSuggestions);
-			}
-			else {
-				const [index, parserResult] = context.state;
-				if (parserResult.success) {
-					const parserSuggestions = parsers[index].suggest({
-						...context,
-						state: parserResult.next.state
-					}, prefix);
-					suggestions.push(...parserSuggestions);
-				}
-			}
-			const seen = /* @__PURE__ */ new Set();
-			return suggestions.filter((suggestion) => {
-				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}:${suggestion.pattern}`;
-				if (seen.has(key)) return false;
-				seen.add(key);
-				return true;
-			});
-		},
+		suggest: createExclusiveSuggest(parsers),
 		getDocFragments(state, _defaultValue) {
 			let description;
 			let footer;
@@ -353,6 +348,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	}
 	const parserPairs = Object.entries(parsers);
 	parserPairs.sort(([_, parserA], [__, parserB]) => parserB.priority - parserA.priority);
+	if (!options.allowDuplicates) checkDuplicateOptionNames(parserPairs.map(([field, parser]) => [field, parser.usage]));
 	const noMatchContext = analyzeNoMatchContext(Object.values(parsers));
 	return {
 		$valueType: [],
@@ -361,21 +357,6 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		usage: parserPairs.flatMap(([_, p]) => p.usage),
 		initialState: Object.fromEntries(Object.entries(parsers).map(([key, parser]) => [key, parser.initialState])),
 		parse(context) {
-			if (!options.allowDuplicates) {
-				const optionNameSources = /* @__PURE__ */ new Map();
-				for (const [field, parser] of parserPairs) {
-					const names = extractOptionNames(parser.usage);
-					for (const name of names) {
-						if (!optionNameSources.has(name)) optionNameSources.set(name, []);
-						optionNameSources.get(name).push(field);
-					}
-				}
-				for (const [name, sources] of optionNameSources) if (sources.length > 1) return {
-					success: false,
-					consumed: 0,
-					error: message`Duplicate option name ${optionName(name)} found in fields: ${values(sources)}. Each option name must be unique within a parser combinator.`
-				};
-			}
 			let error = {
 				consumed: 0,
 				error: context.buffer.length > 0 ? (() => {
@@ -469,13 +450,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				}, prefix);
 				suggestions.push(...fieldSuggestions);
 			}
-			const seen = /* @__PURE__ */ new Set();
-			return suggestions.filter((suggestion) => {
-				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}:${suggestion.pattern}`;
-				if (seen.has(key)) return false;
-				seen.add(key);
-				return true;
-			});
+			return deduplicateSuggestions(suggestions);
 		},
 		getDocFragments(state, defaultValue) {
 			const fragments = parserPairs.flatMap(([field, p]) => {
@@ -515,6 +490,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		parsers = labelOrParsers;
 		options = maybeParsersOrOptions ?? {};
 	}
+	if (!options.allowDuplicates) checkDuplicateOptionNames(parsers.map((parser, index) => [String(index), parser.usage]));
 	return {
 		$valueType: [],
 		$stateType: [],
@@ -522,21 +498,6 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
 		initialState: parsers.map((parser) => parser.initialState),
 		parse(context) {
-			if (!options.allowDuplicates) {
-				const optionNameSources = /* @__PURE__ */ new Map();
-				for (let i = 0; i < parsers.length; i++) {
-					const names = extractOptionNames(parsers[i].usage);
-					for (const name of names) {
-						if (!optionNameSources.has(name)) optionNameSources.set(name, []);
-						optionNameSources.get(name).push(i);
-					}
-				}
-				for (const [name, indices] of optionNameSources) if (indices.length > 1) return {
-					success: false,
-					consumed: 0,
-					error: message`Duplicate option name ${optionName(name)} found at positions: ${values(indices.map(String))}. Each option name must be unique within a parser combinator.`
-				};
-			}
 			let currentContext = context;
 			const allConsumed = [];
 			const matchedParsers = /* @__PURE__ */ new Set();
@@ -621,13 +582,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				}, prefix);
 				suggestions.push(...parserSuggestions);
 			}
-			const seen = /* @__PURE__ */ new Set();
-			return suggestions.filter((suggestion) => {
-				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}:${suggestion.pattern}`;
-				if (seen.has(key)) return false;
-				seen.add(key);
-				return true;
-			});
+			return deduplicateSuggestions(suggestions);
 		},
 		getDocFragments(state, defaultValue) {
 			const fragments = parsers.flatMap((p, i) => {
@@ -670,6 +625,7 @@ function merge(...args) {
 	const withIndex = rawParsers.map((p, i) => [p, i]);
 	const sorted = withIndex.toSorted(([a], [b]) => b.priority - a.priority);
 	const parsers = sorted.map(([p]) => p);
+	if (!options.allowDuplicates) checkDuplicateOptionNames(sorted.map(([parser, originalIndex]) => [String(originalIndex), parser.usage]));
 	const initialState = {};
 	for (const parser of parsers) if (parser.initialState && typeof parser.initialState === "object") for (const field in parser.initialState) initialState[field] = parser.initialState[field];
 	return {
@@ -679,21 +635,6 @@ function merge(...args) {
 		usage: parsers.flatMap((p) => p.usage),
 		initialState,
 		parse(context) {
-			if (!options.allowDuplicates) {
-				const optionNameSources = /* @__PURE__ */ new Map();
-				for (const [parser, originalIndex] of sorted) {
-					const names = extractOptionNames(parser.usage);
-					for (const name of names) {
-						if (!optionNameSources.has(name)) optionNameSources.set(name, []);
-						optionNameSources.get(name).push(originalIndex);
-					}
-				}
-				for (const [name, indices] of optionNameSources) if (indices.length > 1) return {
-					success: false,
-					consumed: 0,
-					error: message`Duplicate option name ${optionName(name)} found in merged parsers at positions: ${values(indices.map(String))}. Each option name must be unique within a parser combinator.`
-				};
-			}
 			for (let i = 0; i < parsers.length; i++) {
 				const parser = parsers[i];
 				let parserState;
@@ -782,13 +723,7 @@ function merge(...args) {
 				}, prefix);
 				suggestions.push(...parserSuggestions);
 			}
-			const seen = /* @__PURE__ */ new Set();
-			return suggestions.filter((suggestion) => {
-				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}:${suggestion.pattern}`;
-				if (seen.has(key)) return false;
-				seen.add(key);
-				return true;
-			});
+			return deduplicateSuggestions(suggestions);
 		},
 		getDocFragments(state, _defaultValue) {
 			const fragments = parsers.flatMap((p) => {
@@ -919,13 +854,7 @@ function concat(...parsers) {
 				}, prefix);
 				suggestions.push(...parserSuggestions);
 			}
-			const seen = /* @__PURE__ */ new Set();
-			return suggestions.filter((suggestion) => {
-				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}:${suggestion.pattern}`;
-				if (seen.has(key)) return false;
-				seen.add(key);
-				return true;
-			});
+			return deduplicateSuggestions(suggestions);
 		},
 		getDocFragments(state, _defaultValue) {
 			const fragments = parsers.flatMap((p, index) => {
@@ -1257,13 +1186,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					state: state.branchState
 				}, prefix));
 			}
-			const seen = /* @__PURE__ */ new Set();
-			return suggestions.filter((suggestion) => {
-				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}`;
-				if (seen.has(key)) return false;
-				seen.add(key);
-				return true;
-			});
+			return deduplicateSuggestions(suggestions);
 		},
 		getDocFragments(_state, _defaultValue) {
 			const fragments = [];
@@ -1295,4 +1218,4 @@ function conditional(discriminator, branches, defaultBranch, options) {
 }
 
 //#endregion
-export { concat, conditional, group, longestMatch, merge, object, or, tuple };
+export { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple };

package/dist/index.cjs

@@ -9,6 +9,7 @@ const require_primitives = require('./primitives.cjs');
 const require_parser = require('./parser.cjs');
 const require_facade = require('./facade.cjs');
 
+exports.DuplicateOptionError = require_constructs.DuplicateOptionError;
 exports.RunError = require_facade.RunError;
 exports.WithDefaultError = require_modifiers.WithDefaultError;
 exports.argument = require_primitives.argument;

package/dist/index.d.cts

@@ -5,7 +5,7 @@ import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.cjs";
 import { DocState, InferValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, parse, suggest } from "./parser.cjs";
-import { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
+import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, 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, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, 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, conditional, constant, envVar, extractArgumentMetavars, 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, passThrough, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, 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, conditional, constant, envVar, extractArgumentMetavars, 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, passThrough, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, PassThroughFormat, PassThroughOptions, argument, command, constant, flag, option, passThrough } from "./primitives.js";
 import { DocState, InferValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, parse, suggest } from "./parser.js";
-import { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, 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, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, 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, conditional, constant, envVar, extractArgumentMetavars, 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, passThrough, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, 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, conditional, constant, envVar, extractArgumentMetavars, 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, passThrough, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
-import { concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { formatDocPage } from "./doc.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { WithDefaultError, map, multiple, optional, withDefault } from "./modifiers.js";
@@ -9,4 +9,4 @@ import { argument, command, constant, flag, option, passThrough } from "./primit
 import { getDocPage, parse, suggest } from "./parser.js";
 import { RunError, run } from "./facade.js";
 
-export { RunError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, 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, passThrough, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { DuplicateOptionError, RunError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, 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, passThrough, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/modifiers.cjs

@@ -2,6 +2,45 @@ const require_message = require('./message.cjs');
 
 //#region src/modifiers.ts
 /**
+* Internal helper for optional-style parsing logic shared by optional()
+* and withDefault(). Handles the common pattern of:
+* - Unwrapping optional state to inner parser state
+* - Detecting if inner parser actually matched (state changed or no consumption)
+* - Returning success with undefined state when inner parser fails without consuming
+* @internal
+*/
+function parseOptionalStyle(context, parser) {
+	const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+	const result = parser.parse({
+		...context,
+		state: innerState
+	});
+	if (result.success) {
+		if (result.next.state !== innerState || result.consumed.length === 0) return {
+			success: true,
+			next: {
+				...result.next,
+				state: [result.next.state]
+			},
+			consumed: result.consumed
+		};
+		return {
+			success: true,
+			next: {
+				...result.next,
+				state: context.state
+			},
+			consumed: result.consumed
+		};
+	}
+	if (result.consumed === 0) return {
+		success: true,
+		next: context,
+		consumed: []
+	};
+	return result;
+}
+/**
 * Creates a parser that makes another parser optional, allowing it to succeed
 * without consuming input if the wrapped parser fails to match.
 * If the wrapped parser succeeds, this returns its value.
@@ -23,35 +62,7 @@ function optional(parser) {
 		}],
 		initialState: void 0,
 		parse(context) {
-			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
-			const result = parser.parse({
-				...context,
-				state: innerState
-			});
-			if (result.success) {
-				if (result.next.state !== innerState || result.consumed.length === 0) return {
-					success: true,
-					next: {
-						...result.next,
-						state: [result.next.state]
-					},
-					consumed: result.consumed
-				};
-				return {
-					success: true,
-					next: {
-						...result.next,
-						state: context.state
-					},
-					consumed: result.consumed
-				};
-			}
-			if (result.consumed === 0) return {
-				success: true,
-				next: context,
-				consumed: []
-			};
-			return result;
+			return parseOptionalStyle(context, parser);
 		},
 		complete(state) {
 			if (typeof state === "undefined") return {
@@ -121,35 +132,7 @@ function withDefault(parser, defaultValue, options) {
 		}],
 		initialState: void 0,
 		parse(context) {
-			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
-			const result = parser.parse({
-				...context,
-				state: innerState
-			});
-			if (result.success) {
-				if (result.next.state !== innerState || result.consumed.length === 0) return {
-					success: true,
-					next: {
-						...result.next,
-						state: [result.next.state]
-					},
-					consumed: result.consumed
-				};
-				return {
-					success: true,
-					next: {
-						...result.next,
-						state: context.state
-					},
-					consumed: result.consumed
-				};
-			}
-			if (result.consumed === 0) return {
-				success: true,
-				next: context,
-				consumed: []
-			};
-			return result;
+			return parseOptionalStyle(context, parser);
 		},
 		complete(state) {
 			if (typeof state === "undefined") try {