@optique/core 1.1.0-dev.2087 → 1.1.0-dev.2146

package/dist/facade.cjs

@@ -1,13 +1,14 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
-const require_completion = require('./completion.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_input_trace = require('./input-trace.cjs');
-const require_parser = require('./internal/parser.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
+const require_completion = require('./completion.cjs');
+const require_command_alias = require('./internal/command-alias.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_constructs = require('./constructs.cjs');
 const require_modifiers = require('./modifiers.cjs');
@@ -15,6 +16,14 @@ const require_valueparser = require('./valueparser.cjs');
 const require_primitives = require('./primitives.cjs');
 
 //#region src/facade.ts
+/**
+* Combines built-in meta commands while intentionally bypassing duplicate
+* leading command name validation in `createLongestMatch()`.
+*/
+function longestMatchForMetaCommands(...parsers) {
+	const options = { [require_command_alias.allowDuplicateLeadingCommandNamesKey]: true };
+	return require_constructs.longestMatch(...parsers, options);
+}
 const SuppressedErrorCtor = typeof SuppressedError === "function" ? SuppressedError : (() => {
 	class SuppressedErrorPolyfill extends Error {
 		error;
@@ -119,9 +128,9 @@ function createCompleteExec(exec, context) {
 	};
 }
 function attemptParseSync(parser, args, mode = "complete") {
-	const shouldUnwrapAnnotatedValue = require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = require_internal_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = createParseExec(parser);
-	let context = require_parser.createParserContext({
+	let context = require_internal_parser.createParserContext({
 		buffer: args,
 		state: parser.initialState,
 		optionsTerminated: false
@@ -168,13 +177,13 @@ function attemptParseSync(parser, args, mode = "complete") {
 	};
 	return {
 		kind: "success",
-		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
+		value: shouldUnwrapAnnotatedValue ? require_internal_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	};
 }
 async function attemptParseAsync(parser, args, mode = "complete") {
-	const shouldUnwrapAnnotatedValue = require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = require_internal_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = createParseExec(parser);
-	let context = require_parser.createParserContext({
+	let context = require_internal_parser.createParserContext({
 		buffer: args,
 		state: parser.initialState,
 		optionsTerminated: false
@@ -221,7 +230,7 @@ async function attemptParseAsync(parser, args, mode = "complete") {
 	};
 	return {
 		kind: "success",
-		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
+		value: shouldUnwrapAnnotatedValue ? require_internal_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	};
 }
 function createPhase2SeedExec(parser, context) {
@@ -250,7 +259,7 @@ function createPhase2SeedContext(parser, args) {
 		commandPath: [],
 		trace: require_input_trace.createInputTrace()
 	};
-	return require_parser.createParserContext({
+	return require_internal_parser.createParserContext({
 		buffer: args,
 		state: parser.initialState,
 		optionsTerminated: false
@@ -278,6 +287,10 @@ async function extractPhase2SeedAsync(parser, args) {
 	} while (context.buffer.length > 0);
 	return await require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
 }
+function getMetaCommandAliases(names) {
+	const [, firstAlias, ...restAliases] = names;
+	return firstAlias == null ? void 0 : [firstAlias, ...restAliases];
+}
 /**
 * Creates help parsers based on the sub-config.
 */
@@ -287,12 +300,12 @@ function createHelpParser(commandConfig, optionConfig) {
 	if (commandConfig) {
 		const names = commandConfig.names ?? ["help"];
 		const innerParser = require_modifiers.multiple(require_primitives.argument(require_valueparser.string({ metavar: "COMMAND" }), { description: require_message.message`Command name to show help for.` }));
-		const commandParsers = [];
-		for (let i = 0; i < names.length; i++) commandParsers.push(require_primitives.command(names[i], innerParser, {
+		const aliases = getMetaCommandAliases(names);
+		helpCommand = require_primitives.command(names[0], innerParser, {
 			description: require_message.message`Show help information.`,
-			hidden: i === 0 ? commandConfig.hidden : true
-		}));
-		helpCommand = commandParsers.length === 1 ? commandParsers[0] : require_constructs.longestMatch(...commandParsers);
+			...aliases != null ? { [require_command_alias.hiddenCommandAliasesKey]: aliases } : {},
+			hidden: commandConfig.hidden
+		});
 	}
 	if (optionConfig) {
 		const names = optionConfig.names ?? ["--help"];
@@ -315,12 +328,12 @@ function createVersionParser(commandConfig, optionConfig) {
 	if (commandConfig) {
 		const names = commandConfig.names ?? ["version"];
 		const innerParser = require_constructs.object({});
-		const commandParsers = [];
-		for (let i = 0; i < names.length; i++) commandParsers.push(require_primitives.command(names[i], innerParser, {
+		const aliases = getMetaCommandAliases(names);
+		versionCommand = require_primitives.command(names[0], innerParser, {
 			description: require_message.message`Show version information.`,
-			hidden: i === 0 ? commandConfig.hidden : true
-		}));
-		versionCommand = commandParsers.length === 1 ? commandParsers[0] : require_constructs.longestMatch(...commandParsers);
+			...aliases != null ? { [require_command_alias.hiddenCommandAliasesKey]: aliases } : {},
+			hidden: commandConfig.hidden
+		});
 	}
 	if (optionConfig) {
 		const names = optionConfig.names ?? ["--version"];
@@ -358,12 +371,12 @@ function createCompletionParser(programName, availableShells, commandConfig, opt
 			description: require_message.message`Generate shell completion script or provide completions.`,
 			footer: require_message.message`Examples:${require_message.lineBreak()}  Bash:       ${require_message.commandLine(`eval "$(${programName} ${displayName} bash)"`)}${require_message.lineBreak()}  zsh:        ${require_message.commandLine(`eval "$(${programName} ${displayName} zsh)"`)}${require_message.lineBreak()}  fish:       ${require_message.commandLine(`eval "$(${programName} ${displayName} fish)"`)}${require_message.lineBreak()}  PowerShell: ${require_message.commandLine(`${programName} ${displayName} pwsh > ${programName}-completion.ps1; . ./${programName}-completion.ps1`)}${require_message.lineBreak()}  Nushell:    ${require_message.commandLine(`${programName} ${displayName} nu | save ${programName}-completion.nu; source ./${programName}-completion.nu`)}`
 		};
-		const commandParsers = [];
-		for (let i = 0; i < names.length; i++) commandParsers.push(require_primitives.command(names[i], completionInner, {
+		const aliases = getMetaCommandAliases(names);
+		completionCommand = require_primitives.command(names[0], completionInner, {
 			...completionCommandConfig,
-			hidden: i === 0 ? commandConfig.hidden : true
-		}));
-		completionCommand = commandParsers.length === 1 ? commandParsers[0] : require_constructs.longestMatch(...commandParsers);
+			...aliases != null ? { [require_command_alias.hiddenCommandAliasesKey]: aliases } : {},
+			hidden: commandConfig.hidden
+		});
 	}
 	if (optionConfig) {
 		const names = optionConfig.names ?? ["--completion"];
@@ -463,9 +476,7 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 	}));
 	const mainParserIndex = parsers.length - 1;
 	if (parsers.length === 1) return parsers[0];
-	let combined;
-	if (parsers.length === 2) combined = require_constructs.longestMatch(parsers[0], parsers[1]);
-	else combined = require_constructs.longestMatch(...parsers);
+	let combined = longestMatchForMetaCommands(...parsers);
 	const topUsage = combined.usage[0];
 	if (topUsage?.type === "exclusive" && mainParserIndex > 0) {
 		const terms = [...topUsage.terms];
@@ -606,7 +617,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 		stderr("Error: Missing shell name for completion.\n");
 		if (completionParser) {
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
-			const doc = require_parser.getDocPage(completionParser, [displayName]);
+			const doc = require_internal_parser.getDocPage(completionParser, [displayName]);
 			if (doc) stderr(require_doc.formatDocPage(programName, doc, {
 				colors,
 				maxWidth,
@@ -774,7 +785,7 @@ function getCompletionSuggestRuntimeNodes(parser, state, path) {
 	}];
 }
 function createCompletionArgumentParserContext(parser, args) {
-	return require_parser.createParserContext({
+	return require_internal_parser.createParserContext({
 		buffer: args,
 		state: parser.initialState,
 		optionsTerminated: false
@@ -824,6 +835,7 @@ function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
 			return;
 		case "optional":
 		case "multiple":
+		case "sequence":
 			collectRootOptionNames(term.terms, names, rootLeadingNames);
 			return;
 		case "exclusive":
@@ -849,7 +861,7 @@ function collectActiveOptionNames(usage, commandPath, names, fromExclusive, incl
 			if (rest.length === 0) collectOptionNamesAtCurrentCommandDepth(remainingUsage, names, !fromExclusive && includeDirectAfterCommandOptions);
 			else collectActiveOptionNames(remainingUsage, rest, names, fromExclusive, includeDirectAfterCommandOptions);
 		} else if (term.type === "exclusive") for (const branch of term.terms) collectActiveOptionNames(branch, commandPath, names, true, includeDirectAfterCommandOptions);
-		else if (term.type === "optional" || term.type === "multiple") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
+		else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
 	}
 }
 function isRootOptionToken(token, rootOptionSuggestions) {
@@ -867,6 +879,7 @@ function collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatch
 			return false;
 		case "optional":
 		case "multiple":
+		case "sequence":
 			collectOptionNamesAtCurrentCommandDepth(term.terms, names, afterMatchedCommand);
 			return false;
 		case "exclusive":
@@ -1078,8 +1091,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					for (const [label, optParsers] of Object.entries(groupedMetaOptions)) if (optParsers.length === 1) commandParsers.push(require_constructs.group(label, optParsers[0]));
 					else commandParsers.push(require_constructs.group(label, require_constructs.longestMatch(...optParsers)));
 					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
-					else if (commandParsers.length === 2) helpGeneratorParser = require_constructs.longestMatch(commandParsers[0], commandParsers[1]);
-					else helpGeneratorParser = require_constructs.longestMatch(...commandParsers);
+					else helpGeneratorParser = longestMatchForMetaCommands(...commandParsers);
 				}
 				const reportInvalidHelpCommand = (validationError) => {
 					stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
@@ -1150,7 +1162,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 									res = processStep(resolved);
 								}
 								if (res != null) return reportInvalidHelpCommand(res);
-								const docOrPromise$1 = require_parser.getDocPage(helpGeneratorParser, classified.commands);
+								const docOrPromise$1 = require_internal_parser.getDocPage(helpGeneratorParser, classified.commands);
 								return docOrPromise$1 instanceof Promise ? docOrPromise$1.then(displayHelp) : displayHelp(docOrPromise$1);
 							};
 							return stepResult.then(asyncValidate);
@@ -1159,7 +1171,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					}
 					if (validationResult != null) return reportInvalidHelpCommand(validationResult);
 				}
-				const docOrPromise = require_parser.getDocPage(helpGeneratorParser, classified.commands);
+				const docOrPromise = require_internal_parser.getDocPage(helpGeneratorParser, classified.commands);
 				if (docOrPromise instanceof Promise) return docOrPromise.then(displayHelp);
 				return displayHelp(docOrPromise);
 			}
@@ -1198,7 +1210,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				};
 				if (aboveError === "help") {
 					const parserForDoc = args.length < 1 ? augmentedParser : parser;
-					const docOrPromise = require_parser.getDocPage(parserForDoc, args);
+					const docOrPromise = require_internal_parser.getDocPage(parserForDoc, args);
 					if (docOrPromise instanceof Promise) return docOrPromise.then((doc) => displayError(doc, aboveError));
 					return displayError(docOrPromise, aboveError);
 				}
@@ -1732,7 +1744,7 @@ function runWithAsync(parser, programName, contexts, options) {
 * @returns A new parser with annotations in its initial state.
 */
 function injectAnnotationsIntoParser(parser, annotations) {
-	const newInitialState = require_annotations.injectAnnotations(parser.initialState, annotations);
+	const newInitialState = require_internal_annotations.injectAnnotations(parser.initialState, annotations);
 	const descriptors = { ...Object.getOwnPropertyDescriptors(parser) };
 	const initialState = descriptors.initialState;
 	descriptors.initialState = initialState == null ? {

package/dist/facade.js

@@ -1,6 +1,5 @@
 import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
-import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { validateCommandNames, validateContextIds, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
 import { formatUsage, isSuggestionHidden } from "./usage.js";
 import { formatDocPage } from "./doc.js";
@@ -8,6 +7,8 @@ import { dispatchByMode } from "./internal/mode-dispatch.js";
 import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
 import { createInputTrace } from "./input-trace.js";
 import { createParserContext, getDocPage } from "./internal/parser.js";
+import { bash, fish, nu, pwsh, zsh } from "./completion.js";
+import { allowDuplicateLeadingCommandNamesKey, hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { completeOrExtractPhase2Seed } from "./phase2-seed.js";
 import { group, longestMatch, object } from "./constructs.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
@@ -15,6 +16,14 @@ import { string } from "./valueparser.js";
 import { argument, command, constant, flag, option } from "./primitives.js";
 
 //#region src/facade.ts
+/**
+* Combines built-in meta commands while intentionally bypassing duplicate
+* leading command name validation in `createLongestMatch()`.
+*/
+function longestMatchForMetaCommands(...parsers) {
+	const options = { [allowDuplicateLeadingCommandNamesKey]: true };
+	return longestMatch(...parsers, options);
+}
 const SuppressedErrorCtor = typeof SuppressedError === "function" ? SuppressedError : (() => {
 	class SuppressedErrorPolyfill extends Error {
 		error;
@@ -278,6 +287,10 @@ async function extractPhase2SeedAsync(parser, args) {
 	} while (context.buffer.length > 0);
 	return await completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
 }
+function getMetaCommandAliases(names) {
+	const [, firstAlias, ...restAliases] = names;
+	return firstAlias == null ? void 0 : [firstAlias, ...restAliases];
+}
 /**
 * Creates help parsers based on the sub-config.
 */
@@ -287,12 +300,12 @@ function createHelpParser(commandConfig, optionConfig) {
 	if (commandConfig) {
 		const names = commandConfig.names ?? ["help"];
 		const innerParser = multiple(argument(string({ metavar: "COMMAND" }), { description: message`Command name to show help for.` }));
-		const commandParsers = [];
-		for (let i = 0; i < names.length; i++) commandParsers.push(command(names[i], innerParser, {
+		const aliases = getMetaCommandAliases(names);
+		helpCommand = command(names[0], innerParser, {
 			description: message`Show help information.`,
-			hidden: i === 0 ? commandConfig.hidden : true
-		}));
-		helpCommand = commandParsers.length === 1 ? commandParsers[0] : longestMatch(...commandParsers);
+			...aliases != null ? { [hiddenCommandAliasesKey]: aliases } : {},
+			hidden: commandConfig.hidden
+		});
 	}
 	if (optionConfig) {
 		const names = optionConfig.names ?? ["--help"];
@@ -315,12 +328,12 @@ function createVersionParser(commandConfig, optionConfig) {
 	if (commandConfig) {
 		const names = commandConfig.names ?? ["version"];
 		const innerParser = object({});
-		const commandParsers = [];
-		for (let i = 0; i < names.length; i++) commandParsers.push(command(names[i], innerParser, {
+		const aliases = getMetaCommandAliases(names);
+		versionCommand = command(names[0], innerParser, {
 			description: message`Show version information.`,
-			hidden: i === 0 ? commandConfig.hidden : true
-		}));
-		versionCommand = commandParsers.length === 1 ? commandParsers[0] : longestMatch(...commandParsers);
+			...aliases != null ? { [hiddenCommandAliasesKey]: aliases } : {},
+			hidden: commandConfig.hidden
+		});
 	}
 	if (optionConfig) {
 		const names = optionConfig.names ?? ["--version"];
@@ -358,12 +371,12 @@ function createCompletionParser(programName, availableShells, commandConfig, opt
 			description: message`Generate shell completion script or provide completions.`,
 			footer: message`Examples:${lineBreak()}  Bash:       ${commandLine(`eval "$(${programName} ${displayName} bash)"`)}${lineBreak()}  zsh:        ${commandLine(`eval "$(${programName} ${displayName} zsh)"`)}${lineBreak()}  fish:       ${commandLine(`eval "$(${programName} ${displayName} fish)"`)}${lineBreak()}  PowerShell: ${commandLine(`${programName} ${displayName} pwsh > ${programName}-completion.ps1; . ./${programName}-completion.ps1`)}${lineBreak()}  Nushell:    ${commandLine(`${programName} ${displayName} nu | save ${programName}-completion.nu; source ./${programName}-completion.nu`)}`
 		};
-		const commandParsers = [];
-		for (let i = 0; i < names.length; i++) commandParsers.push(command(names[i], completionInner, {
+		const aliases = getMetaCommandAliases(names);
+		completionCommand = command(names[0], completionInner, {
 			...completionCommandConfig,
-			hidden: i === 0 ? commandConfig.hidden : true
-		}));
-		completionCommand = commandParsers.length === 1 ? commandParsers[0] : longestMatch(...commandParsers);
+			...aliases != null ? { [hiddenCommandAliasesKey]: aliases } : {},
+			hidden: commandConfig.hidden
+		});
 	}
 	if (optionConfig) {
 		const names = optionConfig.names ?? ["--completion"];
@@ -463,9 +476,7 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 	}));
 	const mainParserIndex = parsers.length - 1;
 	if (parsers.length === 1) return parsers[0];
-	let combined;
-	if (parsers.length === 2) combined = longestMatch(parsers[0], parsers[1]);
-	else combined = longestMatch(...parsers);
+	let combined = longestMatchForMetaCommands(...parsers);
 	const topUsage = combined.usage[0];
 	if (topUsage?.type === "exclusive" && mainParserIndex > 0) {
 		const terms = [...topUsage.terms];
@@ -824,6 +835,7 @@ function collectRootOptionNamesFromTerm(term, names, rootLeadingNames) {
 			return;
 		case "optional":
 		case "multiple":
+		case "sequence":
 			collectRootOptionNames(term.terms, names, rootLeadingNames);
 			return;
 		case "exclusive":
@@ -849,7 +861,7 @@ function collectActiveOptionNames(usage, commandPath, names, fromExclusive, incl
 			if (rest.length === 0) collectOptionNamesAtCurrentCommandDepth(remainingUsage, names, !fromExclusive && includeDirectAfterCommandOptions);
 			else collectActiveOptionNames(remainingUsage, rest, names, fromExclusive, includeDirectAfterCommandOptions);
 		} else if (term.type === "exclusive") for (const branch of term.terms) collectActiveOptionNames(branch, commandPath, names, true, includeDirectAfterCommandOptions);
-		else if (term.type === "optional" || term.type === "multiple") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
+		else if (term.type === "optional" || term.type === "multiple" || term.type === "sequence") collectActiveOptionNames(term.terms, commandPath, names, fromExclusive, includeDirectAfterCommandOptions);
 	}
 }
 function isRootOptionToken(token, rootOptionSuggestions) {
@@ -867,6 +879,7 @@ function collectOptionNamesAtCurrentCommandDepthFromTerm(term, names, afterMatch
 			return false;
 		case "optional":
 		case "multiple":
+		case "sequence":
 			collectOptionNamesAtCurrentCommandDepth(term.terms, names, afterMatchedCommand);
 			return false;
 		case "exclusive":
@@ -1078,8 +1091,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					for (const [label, optParsers] of Object.entries(groupedMetaOptions)) if (optParsers.length === 1) commandParsers.push(group(label, optParsers[0]));
 					else commandParsers.push(group(label, longestMatch(...optParsers)));
 					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
-					else if (commandParsers.length === 2) helpGeneratorParser = longestMatch(commandParsers[0], commandParsers[1]);
-					else helpGeneratorParser = longestMatch(...commandParsers);
+					else helpGeneratorParser = longestMatchForMetaCommands(...commandParsers);
 				}
 				const reportInvalidHelpCommand = (validationError) => {
 					stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {

package/dist/index.cjs

@@ -1,10 +1,10 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
-const require_completion = require('./completion.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
-const require_dependency = require('./internal/dependency.cjs');
-const require_parser = require('./internal/parser.cjs');
+const require_internal_dependency = require('./internal/dependency.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
+const require_completion = require('./completion.cjs');
 const require_constructs = require('./constructs.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_nonempty = require('./nonempty.cjs');
@@ -30,13 +30,13 @@ exports.commandLine = require_message.commandLine;
 exports.concat = require_constructs.concat;
 exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
-exports.createParserContext = require_parser.createParserContext;
+exports.createParserContext = require_internal_parser.createParserContext;
 exports.deduplicateDocEntries = require_doc.deduplicateDocEntries;
 exports.deduplicateDocFragments = require_doc.deduplicateDocFragments;
-exports.dependency = require_dependency.dependency;
-exports.deriveFrom = require_dependency.deriveFrom;
-exports.deriveFromAsync = require_dependency.deriveFromAsync;
-exports.deriveFromSync = require_dependency.deriveFromSync;
+exports.dependency = require_internal_dependency.dependency;
+exports.deriveFrom = require_internal_dependency.deriveFrom;
+exports.deriveFromAsync = require_internal_dependency.deriveFromAsync;
+exports.deriveFromSync = require_internal_dependency.deriveFromSync;
 exports.domain = require_valueparser.domain;
 exports.email = require_valueparser.email;
 exports.ensureNonEmptyString = require_nonempty.ensureNonEmptyString;
@@ -47,6 +47,7 @@ exports.extractLiteralValues = require_usage.extractLiteralValues;
 exports.extractOptionNames = require_usage.extractOptionNames;
 exports.fail = require_primitives.fail;
 exports.fileSize = require_valueparser.fileSize;
+exports.firstOf = require_valueparser.firstOf;
 exports.fish = require_completion.fish;
 exports.flag = require_primitives.flag;
 exports.float = require_valueparser.float;
@@ -54,18 +55,18 @@ exports.formatDocPage = require_doc.formatDocPage;
 exports.formatMessage = require_message.formatMessage;
 exports.formatUsage = require_usage.formatUsage;
 exports.formatUsageTerm = require_usage.formatUsageTerm;
-exports.getAnnotations = require_annotations.getAnnotations;
-exports.getDocPage = require_parser.getDocPage;
-exports.getDocPageAsync = require_parser.getDocPageAsync;
-exports.getDocPageSync = require_parser.getDocPageSync;
+exports.getAnnotations = require_internal_annotations.getAnnotations;
+exports.getDocPage = require_internal_parser.getDocPage;
+exports.getDocPageAsync = require_internal_parser.getDocPageAsync;
+exports.getDocPageSync = require_internal_parser.getDocPageSync;
 exports.group = require_constructs.group;
 exports.hostname = require_valueparser.hostname;
 exports.integer = require_valueparser.integer;
 exports.ip = require_valueparser.ip;
 exports.ipv4 = require_valueparser.ipv4;
 exports.ipv6 = require_valueparser.ipv6;
-exports.isDependencySource = require_dependency.isDependencySource;
-exports.isDerivedValueParser = require_dependency.isDerivedValueParser;
+exports.isDependencySource = require_internal_dependency.isDependencySource;
+exports.isDerivedValueParser = require_internal_dependency.isDerivedValueParser;
 exports.isDocEntryHidden = require_doc.isDocEntryHidden;
 exports.isDocHidden = require_usage.isDocHidden;
 exports.isNonEmptyString = require_nonempty.isNonEmptyString;
@@ -94,9 +95,9 @@ exports.optionName = require_message.optionName;
 exports.optionNames = require_message.optionNames;
 exports.optional = require_modifiers.optional;
 exports.or = require_constructs.or;
-exports.parse = require_parser.parse;
-exports.parseAsync = require_parser.parseAsync;
-exports.parseSync = require_parser.parseSync;
+exports.parse = require_internal_parser.parse;
+exports.parseAsync = require_internal_parser.parseAsync;
+exports.parseSync = require_internal_parser.parseSync;
 exports.passThrough = require_primitives.passThrough;
 exports.port = require_valueparser.port;
 exports.portRange = require_valueparser.portRange;
@@ -108,11 +109,12 @@ exports.runWith = require_facade.runWith;
 exports.runWithAsync = require_facade.runWithAsync;
 exports.runWithSync = require_facade.runWithSync;
 exports.semVer = require_valueparser.semVer;
+exports.seq = require_constructs.seq;
 exports.socketAddress = require_valueparser.socketAddress;
 exports.string = require_valueparser.string;
-exports.suggest = require_parser.suggest;
-exports.suggestAsync = require_parser.suggestAsync;
-exports.suggestSync = require_parser.suggestSync;
+exports.suggest = require_internal_parser.suggest;
+exports.suggestAsync = require_internal_parser.suggestAsync;
+exports.suggestSync = require_internal_parser.suggestSync;
 exports.text = require_message.text;
 exports.tuple = require_constructs.tuple;
 exports.url = require_valueparser.url;

package/dist/index.d.cts

@@ -3,13 +3,13 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.cjs";
-import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.cjs";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.cjs";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
-import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
+import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.cjs";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.cjs";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -3,13 +3,13 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
-import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
-import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.js

@@ -1,15 +1,15 @@
 import { getAnnotations } from "./internal/annotations.js";
 import { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
-import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
-import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { bash, fish, nu, pwsh, zsh } from "./completion.js";
+import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
-import { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
+import { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
 import { argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/input-trace.d.cts

@@ -73,5 +73,6 @@ interface InputTrace {
  * @internal
  * @since 1.0.0
  */
+declare function createInputTrace(): InputTrace;
 //#endregion
-export { InputTrace };
+export { InputTrace, TraceEntry, createInputTrace };

package/dist/input-trace.d.ts

@@ -73,5 +73,6 @@ interface InputTrace {
  * @internal
  * @since 1.0.0
  */
+declare function createInputTrace(): InputTrace;
 //#endregion
-export { InputTrace };
+export { InputTrace, TraceEntry, createInputTrace };

package/dist/internal/annotations.cjs

@@ -306,6 +306,9 @@ function unwrapInjectedAnnotationState(value) {
 //#endregion
 exports.annotateFreshArray = annotateFreshArray;
 exports.annotationKey = annotationKey;
+exports.annotationStateValueKey = annotationStateValueKey;
+exports.annotationWrapperKey = annotationWrapperKey;
+exports.firstPassAnnotationKey = firstPassAnnotationKey;
 exports.getAnnotations = getAnnotations;
 exports.hasMeaningfulAnnotations = hasMeaningfulAnnotations;
 exports.inheritAnnotations = inheritAnnotations;