@optique/core 1.3.0-dev.2486 → 1.3.0-dev.2491

package/dist/facade.cjs

@@ -98,24 +98,6 @@ function prepareParsedForContexts(parsed, deferred, deferredKeys) {
 function isBufferUnchanged(previous, current) {
 	return current.length > 0 && current.length === previous.length && current.every((item, i) => item === previous[i]);
 }
-function getFailureProgress(args, buffer, consumedInStep) {
-	return {
-		remainingArgs: buffer.slice(consumedInStep),
-		consumedCount: args.length - buffer.length + consumedInStep
-	};
-}
-function createParseExec(parser) {
-	return {
-		usage: parser.usage,
-		phase: "parse",
-		path: [],
-		commandPath: [],
-		trace: require_input_trace.createInputTrace()
-	};
-}
-function getCommandPath(exec) {
-	return exec?.commandPath ?? [];
-}
 const effectfulSessionOptionsKey = Symbol("@optique/core/facade/effectfulSessionOptionsKey");
 function getEffectfulSessionOption(options) {
 	return options[effectfulSessionOptionsKey];
@@ -152,124 +134,6 @@ function createRunWithSessions() {
 		finalSession
 	};
 }
-function createCompleteExec(exec, context, session) {
-	const runtime = require_dependency_runtime.createDependencyRuntimeContext();
-	return {
-		...exec,
-		phase: "complete",
-		dependencyRuntime: runtime,
-		dependencyRegistry: runtime.registry,
-		commandPath: getCommandPath(context.exec) ?? exec.commandPath,
-		trace: context.exec?.trace ?? context.trace ?? exec.trace,
-		effectfulCompletionSession: session ?? require_internal_parser.createEffectfulCompletionSession()
-	};
-}
-function attemptParseSync(parser, args, mode = "complete", session) {
-	const shouldUnwrapAnnotatedValue = require_internal_annotations.isInjectedAnnotationWrapper(parser.initialState);
-	const exec = createParseExec(parser);
-	let context = require_internal_parser.createParserContext({
-		buffer: args,
-		state: parser.initialState,
-		optionsTerminated: false
-	}, exec);
-	do {
-		const result = parser.parse(context);
-		if (!result.success) {
-			const progress = getFailureProgress(args, context.buffer, result.consumed);
-			return {
-				kind: "failure",
-				error: result.error,
-				remainingArgs: progress.remainingArgs,
-				consumedCount: progress.consumedCount,
-				optionsTerminated: context.optionsTerminated,
-				commandPath: getCommandPath(context.exec)
-			};
-		}
-		const previousBuffer = context.buffer;
-		context = result.next;
-		if (isBufferUnchanged(previousBuffer, context.buffer)) {
-			const progress = getFailureProgress(args, previousBuffer, result.consumed.length);
-			return {
-				kind: "failure",
-				error: require_message.message`Unexpected option or argument: ${context.buffer[0]}.`,
-				remainingArgs: progress.remainingArgs,
-				consumedCount: progress.consumedCount,
-				optionsTerminated: context.optionsTerminated,
-				commandPath: getCommandPath(context.exec)
-			};
-		}
-	} while (context.buffer.length > 0);
-	if (mode === "parse-only") return {
-		kind: "success",
-		value: void 0
-	};
-	const endResult = parser.complete(context.state, createCompleteExec(exec, context, session));
-	if (!endResult.success) return {
-		kind: "failure",
-		error: endResult.error,
-		remainingArgs: [],
-		consumedCount: args.length,
-		optionsTerminated: context.optionsTerminated,
-		commandPath: getCommandPath(context.exec)
-	};
-	return {
-		kind: "success",
-		value: shouldUnwrapAnnotatedValue ? require_internal_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
-	};
-}
-async function attemptParseAsync(parser, args, mode = "complete", session) {
-	const shouldUnwrapAnnotatedValue = require_internal_annotations.isInjectedAnnotationWrapper(parser.initialState);
-	const exec = createParseExec(parser);
-	let context = require_internal_parser.createParserContext({
-		buffer: args,
-		state: parser.initialState,
-		optionsTerminated: false
-	}, exec);
-	do {
-		const result = await parser.parse(context);
-		if (!result.success) {
-			const progress = getFailureProgress(args, context.buffer, result.consumed);
-			return {
-				kind: "failure",
-				error: result.error,
-				remainingArgs: progress.remainingArgs,
-				consumedCount: progress.consumedCount,
-				optionsTerminated: context.optionsTerminated,
-				commandPath: getCommandPath(context.exec)
-			};
-		}
-		const previousBuffer = context.buffer;
-		context = result.next;
-		if (isBufferUnchanged(previousBuffer, context.buffer)) {
-			const progress = getFailureProgress(args, previousBuffer, result.consumed.length);
-			return {
-				kind: "failure",
-				error: require_message.message`Unexpected option or argument: ${context.buffer[0]}.`,
-				remainingArgs: progress.remainingArgs,
-				consumedCount: progress.consumedCount,
-				optionsTerminated: context.optionsTerminated,
-				commandPath: getCommandPath(context.exec)
-			};
-		}
-	} while (context.buffer.length > 0);
-	if (mode === "parse-only") return {
-		kind: "success",
-		value: void 0
-	};
-	const endResult = await parser.complete(context.state, createCompleteExec(exec, context, session));
-	if (!endResult.success) return {
-		kind: "failure",
-		error: endResult.error,
-		remainingArgs: [],
-		consumedCount: args.length,
-		optionsTerminated: context.optionsTerminated,
-		commandPath: getCommandPath(context.exec)
-	};
-	return {
-		kind: "success",
-		value: shouldUnwrapAnnotatedValue ? require_internal_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
-	};
-}
 function createPhase2SeedExec(parser, context, session) {
 	const exec = {
 		usage: parser.usage,
@@ -284,7 +148,7 @@ function createPhase2SeedExec(parser, context, session) {
 		phase: "complete",
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
-		commandPath: getCommandPath(context.exec),
+		commandPath: context.exec?.commandPath ?? [],
 		trace: context.exec?.trace ?? context.trace ?? exec.trace,
 		effectfulCompletionSession: session ?? require_internal_parser.createEffectfulCompletionSession()
 	};
@@ -1284,19 +1148,25 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	};
 	const parserMode = parser.mode;
 	return require_mode_dispatch.dispatchByMode(parserMode, () => {
-		const attempted = attemptParseSync(parser, args, "complete", getEffectfulSessionOption(options));
+		const attempted = require_internal_parser.attemptParseSync(parser, args, {
+			mode: "complete",
+			session: getEffectfulSessionOption(options)
+		});
 		const classified = attempted.kind === "success" ? {
 			type: "success",
-			value: attempted.value
+			value: attempted.result.value
 		} : classifyParseFailure(attempted, helpOptionConfig ? [...helpOptionNames] : [], helpCommandConfig ? [...helpCommandNames] : [], versionOptionConfig ? [...versionOptionNames] : [], versionCommandConfig ? [...versionCommandNames] : [], completionOptionConfig ? [...completionOptionNames] : [], completionCommandConfig ? [...completionCommandNames] : []);
 		const handled = handleResult(classified);
 		if (handled instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 		return handled;
 	}, async () => {
-		const attempted = await attemptParseAsync(parser, args, "complete", getEffectfulSessionOption(options));
+		const attempted = await require_internal_parser.attemptParseAsync(parser, args, {
+			mode: "complete",
+			session: getEffectfulSessionOption(options)
+		});
 		const classified = attempted.kind === "success" ? {
 			type: "success",
-			value: attempted.value
+			value: attempted.result.value
 		} : classifyParseFailure(attempted, helpOptionConfig ? [...helpOptionNames] : [], helpCommandConfig ? [...helpCommandNames] : [], versionOptionConfig ? [...versionOptionNames] : [], versionCommandConfig ? [...versionCommandNames] : [], completionOptionConfig ? [...completionOptionNames] : [], completionCommandConfig ? [...completionCommandNames] : []);
 		const handled = handleResult(classified);
 		return handled instanceof Promise ? await handled : handled;
@@ -1423,7 +1293,7 @@ function shouldProbeEarlyExit(options, needsTwoPhase) {
 * handled without collecting source-context annotations first.
 */
 function needsEarlyExitSync(parser, args, options) {
-	const attempted = attemptParseSync(parser, args, "parse-only");
+	const attempted = require_internal_parser.attemptParseSync(parser, args, { mode: "parse-only" });
 	if (attempted.kind === "success") return false;
 	return isMetaEarlyExit(classifyEarlyExitFailure(attempted, options));
 }
@@ -1431,7 +1301,7 @@ function needsEarlyExitSync(parser, args, options) {
 * Async variant of {@link needsEarlyExitSync}.
 */
 async function needsEarlyExitAsync(parser, args, options) {
-	const attempted = await attemptParseAsync(parser, args, "parse-only");
+	const attempted = await require_internal_parser.attemptParseAsync(parser, args, { mode: "parse-only" });
 	if (attempted.kind === "success") return false;
 	return isMetaEarlyExit(classifyEarlyExitFailure(attempted, options));
 }

package/dist/facade.js

@@ -1,4 +1,4 @@
-import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
+import { injectAnnotations } from "./internal/annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
 import { validateCommandNames, validateContextIds, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
 import { cloneUsage, formatUsage, isSuggestionHidden, normalizeUsage } from "./usage.js";
@@ -6,7 +6,7 @@ import { formatDocPage } from "./doc.js";
 import { dispatchByMode } from "./internal/mode-dispatch.js";
 import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
 import { createInputTrace } from "./input-trace.js";
-import { createEffectfulCompletionSession, createParserContext, getDocPage } from "./internal/parser.js";
+import { attemptParseAsync, attemptParseSync, createEffectfulCompletionSession, 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";
@@ -98,24 +98,6 @@ function prepareParsedForContexts(parsed, deferred, deferredKeys) {
 function isBufferUnchanged(previous, current) {
 	return current.length > 0 && current.length === previous.length && current.every((item, i) => item === previous[i]);
 }
-function getFailureProgress(args, buffer, consumedInStep) {
-	return {
-		remainingArgs: buffer.slice(consumedInStep),
-		consumedCount: args.length - buffer.length + consumedInStep
-	};
-}
-function createParseExec(parser) {
-	return {
-		usage: parser.usage,
-		phase: "parse",
-		path: [],
-		commandPath: [],
-		trace: createInputTrace()
-	};
-}
-function getCommandPath(exec) {
-	return exec?.commandPath ?? [];
-}
 const effectfulSessionOptionsKey = Symbol("@optique/core/facade/effectfulSessionOptionsKey");
 function getEffectfulSessionOption(options) {
 	return options[effectfulSessionOptionsKey];
@@ -152,124 +134,6 @@ function createRunWithSessions() {
 		finalSession
 	};
 }
-function createCompleteExec(exec, context, session) {
-	const runtime = createDependencyRuntimeContext();
-	return {
-		...exec,
-		phase: "complete",
-		dependencyRuntime: runtime,
-		dependencyRegistry: runtime.registry,
-		commandPath: getCommandPath(context.exec) ?? exec.commandPath,
-		trace: context.exec?.trace ?? context.trace ?? exec.trace,
-		effectfulCompletionSession: session ?? createEffectfulCompletionSession()
-	};
-}
-function attemptParseSync(parser, args, mode = "complete", session) {
-	const shouldUnwrapAnnotatedValue = isInjectedAnnotationWrapper(parser.initialState);
-	const exec = createParseExec(parser);
-	let context = createParserContext({
-		buffer: args,
-		state: parser.initialState,
-		optionsTerminated: false
-	}, exec);
-	do {
-		const result = parser.parse(context);
-		if (!result.success) {
-			const progress = getFailureProgress(args, context.buffer, result.consumed);
-			return {
-				kind: "failure",
-				error: result.error,
-				remainingArgs: progress.remainingArgs,
-				consumedCount: progress.consumedCount,
-				optionsTerminated: context.optionsTerminated,
-				commandPath: getCommandPath(context.exec)
-			};
-		}
-		const previousBuffer = context.buffer;
-		context = result.next;
-		if (isBufferUnchanged(previousBuffer, context.buffer)) {
-			const progress = getFailureProgress(args, previousBuffer, result.consumed.length);
-			return {
-				kind: "failure",
-				error: message`Unexpected option or argument: ${context.buffer[0]}.`,
-				remainingArgs: progress.remainingArgs,
-				consumedCount: progress.consumedCount,
-				optionsTerminated: context.optionsTerminated,
-				commandPath: getCommandPath(context.exec)
-			};
-		}
-	} while (context.buffer.length > 0);
-	if (mode === "parse-only") return {
-		kind: "success",
-		value: void 0
-	};
-	const endResult = parser.complete(context.state, createCompleteExec(exec, context, session));
-	if (!endResult.success) return {
-		kind: "failure",
-		error: endResult.error,
-		remainingArgs: [],
-		consumedCount: args.length,
-		optionsTerminated: context.optionsTerminated,
-		commandPath: getCommandPath(context.exec)
-	};
-	return {
-		kind: "success",
-		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
-	};
-}
-async function attemptParseAsync(parser, args, mode = "complete", session) {
-	const shouldUnwrapAnnotatedValue = isInjectedAnnotationWrapper(parser.initialState);
-	const exec = createParseExec(parser);
-	let context = createParserContext({
-		buffer: args,
-		state: parser.initialState,
-		optionsTerminated: false
-	}, exec);
-	do {
-		const result = await parser.parse(context);
-		if (!result.success) {
-			const progress = getFailureProgress(args, context.buffer, result.consumed);
-			return {
-				kind: "failure",
-				error: result.error,
-				remainingArgs: progress.remainingArgs,
-				consumedCount: progress.consumedCount,
-				optionsTerminated: context.optionsTerminated,
-				commandPath: getCommandPath(context.exec)
-			};
-		}
-		const previousBuffer = context.buffer;
-		context = result.next;
-		if (isBufferUnchanged(previousBuffer, context.buffer)) {
-			const progress = getFailureProgress(args, previousBuffer, result.consumed.length);
-			return {
-				kind: "failure",
-				error: message`Unexpected option or argument: ${context.buffer[0]}.`,
-				remainingArgs: progress.remainingArgs,
-				consumedCount: progress.consumedCount,
-				optionsTerminated: context.optionsTerminated,
-				commandPath: getCommandPath(context.exec)
-			};
-		}
-	} while (context.buffer.length > 0);
-	if (mode === "parse-only") return {
-		kind: "success",
-		value: void 0
-	};
-	const endResult = await parser.complete(context.state, createCompleteExec(exec, context, session));
-	if (!endResult.success) return {
-		kind: "failure",
-		error: endResult.error,
-		remainingArgs: [],
-		consumedCount: args.length,
-		optionsTerminated: context.optionsTerminated,
-		commandPath: getCommandPath(context.exec)
-	};
-	return {
-		kind: "success",
-		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
-	};
-}
 function createPhase2SeedExec(parser, context, session) {
 	const exec = {
 		usage: parser.usage,
@@ -284,7 +148,7 @@ function createPhase2SeedExec(parser, context, session) {
 		phase: "complete",
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
-		commandPath: getCommandPath(context.exec),
+		commandPath: context.exec?.commandPath ?? [],
 		trace: context.exec?.trace ?? context.trace ?? exec.trace,
 		effectfulCompletionSession: session ?? createEffectfulCompletionSession()
 	};
@@ -1284,19 +1148,25 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	};
 	const parserMode = parser.mode;
 	return dispatchByMode(parserMode, () => {
-		const attempted = attemptParseSync(parser, args, "complete", getEffectfulSessionOption(options));
+		const attempted = attemptParseSync(parser, args, {
+			mode: "complete",
+			session: getEffectfulSessionOption(options)
+		});
 		const classified = attempted.kind === "success" ? {
 			type: "success",
-			value: attempted.value
+			value: attempted.result.value
 		} : classifyParseFailure(attempted, helpOptionConfig ? [...helpOptionNames] : [], helpCommandConfig ? [...helpCommandNames] : [], versionOptionConfig ? [...versionOptionNames] : [], versionCommandConfig ? [...versionCommandNames] : [], completionOptionConfig ? [...completionOptionNames] : [], completionCommandConfig ? [...completionCommandNames] : []);
 		const handled = handleResult(classified);
 		if (handled instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 		return handled;
 	}, async () => {
-		const attempted = await attemptParseAsync(parser, args, "complete", getEffectfulSessionOption(options));
+		const attempted = await attemptParseAsync(parser, args, {
+			mode: "complete",
+			session: getEffectfulSessionOption(options)
+		});
 		const classified = attempted.kind === "success" ? {
 			type: "success",
-			value: attempted.value
+			value: attempted.result.value
 		} : classifyParseFailure(attempted, helpOptionConfig ? [...helpOptionNames] : [], helpCommandConfig ? [...helpCommandNames] : [], versionOptionConfig ? [...versionOptionNames] : [], versionCommandConfig ? [...versionCommandNames] : [], completionOptionConfig ? [...completionOptionNames] : [], completionCommandConfig ? [...completionCommandNames] : []);
 		const handled = handleResult(classified);
 		return handled instanceof Promise ? await handled : handled;
@@ -1423,7 +1293,7 @@ function shouldProbeEarlyExit(options, needsTwoPhase) {
 * handled without collecting source-context annotations first.
 */
 function needsEarlyExitSync(parser, args, options) {
-	const attempted = attemptParseSync(parser, args, "parse-only");
+	const attempted = attemptParseSync(parser, args, { mode: "parse-only" });
 	if (attempted.kind === "success") return false;
 	return isMetaEarlyExit(classifyEarlyExitFailure(attempted, options));
 }
@@ -1431,7 +1301,7 @@ function needsEarlyExitSync(parser, args, options) {
 * Async variant of {@link needsEarlyExitSync}.
 */
 async function needsEarlyExitAsync(parser, args, options) {
-	const attempted = await attemptParseAsync(parser, args, "parse-only");
+	const attempted = await attemptParseAsync(parser, args, { mode: "parse-only" });
 	if (attempted.kind === "success") return false;
 	return isMetaEarlyExit(classifyEarlyExitFailure(attempted, options));
 }

package/dist/index.cjs

@@ -104,6 +104,7 @@ exports.optional = require_modifiers.optional;
 exports.or = require_constructs.or;
 exports.parse = require_internal_parser.parse;
 exports.parseAsync = require_internal_parser.parseAsync;
+exports.parseDetailed = require_internal_parser.parseDetailed;
 exports.parseSync = require_internal_parser.parseSync;
 exports.passThrough = require_primitives.passThrough;
 exports.port = require_valueparser.port;

package/dist/index.d.cts

@@ -4,7 +4,7 @@ import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLin
 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, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.cjs";
-import { CombineModes, DocState, EffectfulCompletionSession, 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 { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.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";
@@ -12,4 +12,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.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, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, 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, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, 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, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, 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, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, 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, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLin
 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, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
-import { CombineModes, DocState, EffectfulCompletionSession, 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 { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.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";
@@ -12,4 +12,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.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, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, 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, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, 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, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, 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, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, 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, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.js

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

package/dist/internal/mode-dispatch.cjs

@@ -17,6 +17,24 @@ function dispatchByMode(mode, syncFn, asyncFn) {
 	if (mode === "async") return asyncFn();
 	return syncFn();
 }
+/**
+* Dispatches a parser to a callback narrowed to its runtime mode.
+*
+* TypeScript cannot narrow the generic mode parameter of a {@link Parser}
+* from its `mode` property.  This helper keeps the necessary parser assertions
+* at the mode-dispatch boundary while giving each callback a precise parser
+* type.
+*
+* @param parser The parser whose mode selects the callback.
+* @param syncFn Function to call with a synchronous parser.
+* @param asyncFn Function to call with an asynchronous parser.
+* @returns The callback result with the parser's mode wrapping.
+* @internal
+* @since 1.3.0
+*/
+function dispatchParserByMode(parser, syncFn, asyncFn) {
+	return dispatchByMode(parser.mode, () => syncFn(parser), () => asyncFn(parser));
+}
 function wrapForMode(mode, value) {
 	if (mode === "async") return Promise.resolve(value);
 	if (value instanceof Promise) throw new TypeError("Synchronous mode cannot wrap Promise value.");
@@ -92,6 +110,7 @@ function dispatchIterableByMode(mode, syncFn, asyncFn) {
 //#endregion
 exports.dispatchByMode = dispatchByMode;
 exports.dispatchIterableByMode = dispatchIterableByMode;
+exports.dispatchParserByMode = dispatchParserByMode;
 exports.mapMaybePromiseByMode = mapMaybePromiseByMode;
 exports.mapModeValue = mapModeValue;
 exports.wrapForMode = wrapForMode;

package/dist/internal/mode-dispatch.d.cts

@@ -16,6 +16,22 @@ import { Mode, ModeValue } from "./parser.cjs";
  * @since 0.10.0
  */
 declare function dispatchByMode<M extends Mode, T>(mode: M, syncFn: () => T, asyncFn: () => Promise<T>): ModeValue<M, T>;
+/**
+ * Dispatches a parser to a callback narrowed to its runtime mode.
+ *
+ * TypeScript cannot narrow the generic mode parameter of a {@link Parser}
+ * from its `mode` property.  This helper keeps the necessary parser assertions
+ * at the mode-dispatch boundary while giving each callback a precise parser
+ * type.
+ *
+ * @param parser The parser whose mode selects the callback.
+ * @param syncFn Function to call with a synchronous parser.
+ * @param asyncFn Function to call with an asynchronous parser.
+ * @returns The callback result with the parser's mode wrapping.
+ * @internal
+ * @since 1.3.0
+ */
+
 /**
  * Wraps a value so it matches the parser execution mode.
  *

package/dist/internal/mode-dispatch.d.ts

@@ -16,6 +16,22 @@ import { Mode, ModeValue } from "./parser.js";
  * @since 0.10.0
  */
 declare function dispatchByMode<M extends Mode, T>(mode: M, syncFn: () => T, asyncFn: () => Promise<T>): ModeValue<M, T>;
+/**
+ * Dispatches a parser to a callback narrowed to its runtime mode.
+ *
+ * TypeScript cannot narrow the generic mode parameter of a {@link Parser}
+ * from its `mode` property.  This helper keeps the necessary parser assertions
+ * at the mode-dispatch boundary while giving each callback a precise parser
+ * type.
+ *
+ * @param parser The parser whose mode selects the callback.
+ * @param syncFn Function to call with a synchronous parser.
+ * @param asyncFn Function to call with an asynchronous parser.
+ * @returns The callback result with the parser's mode wrapping.
+ * @internal
+ * @since 1.3.0
+ */
+
 /**
  * Wraps a value so it matches the parser execution mode.
  *

package/dist/internal/mode-dispatch.js

@@ -16,6 +16,24 @@ function dispatchByMode(mode, syncFn, asyncFn) {
 	if (mode === "async") return asyncFn();
 	return syncFn();
 }
+/**
+* Dispatches a parser to a callback narrowed to its runtime mode.
+*
+* TypeScript cannot narrow the generic mode parameter of a {@link Parser}
+* from its `mode` property.  This helper keeps the necessary parser assertions
+* at the mode-dispatch boundary while giving each callback a precise parser
+* type.
+*
+* @param parser The parser whose mode selects the callback.
+* @param syncFn Function to call with a synchronous parser.
+* @param asyncFn Function to call with an asynchronous parser.
+* @returns The callback result with the parser's mode wrapping.
+* @internal
+* @since 1.3.0
+*/
+function dispatchParserByMode(parser, syncFn, asyncFn) {
+	return dispatchByMode(parser.mode, () => syncFn(parser), () => asyncFn(parser));
+}
 function wrapForMode(mode, value) {
 	if (mode === "async") return Promise.resolve(value);
 	if (value instanceof Promise) throw new TypeError("Synchronous mode cannot wrap Promise value.");
@@ -89,4 +107,4 @@ function dispatchIterableByMode(mode, syncFn, asyncFn) {
 }
 
 //#endregion
-export { dispatchByMode, dispatchIterableByMode, mapMaybePromiseByMode, mapModeValue, wrapForMode, wrapIterableForMode };
+export { dispatchByMode, dispatchIterableByMode, dispatchParserByMode, mapMaybePromiseByMode, mapModeValue, wrapForMode, wrapIterableForMode };