@optique/core 1.0.0-dev.1536 → 1.0.0-dev.1553

package/dist/facade.js

@@ -3,7 +3,7 @@ import { commandLine, formatMessage, lineBreak, message, optionName, text, value
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { dispatchByMode } from "./mode-dispatch.js";
 import { validateCommandNames, validateMetaNameCollisions, validateOptionNames } from "./validate.js";
-import { extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage } from "./usage.js";
+import { extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { group, longestMatch, object } from "./constructs.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
@@ -196,6 +196,8 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 			$stateType: [],
 			priority: 200,
 			usage: helpParsers.helpOption.usage,
+			leadingNames: helpParsers.helpOption.leadingNames,
+			acceptingAnyToken: false,
 			initialState: null,
 			parse(context) {
 				const { buffer, optionsTerminated } = context;
@@ -275,6 +277,8 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 			$stateType: [],
 			priority: 200,
 			usage: versionParsers.versionOption.usage,
+			leadingNames: versionParsers.versionOption.leadingNames,
+			acceptingAnyToken: false,
 			initialState: null,
 			parse(context) {
 				const { buffer, optionsTerminated } = context;
@@ -620,9 +624,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		completionCommandNames
 	]);
 	validateMetaNameCollisions({
-		leadingOptions: extractLeadingOptionNames(parser.usage, true),
-		leadingCommands: extractLeadingCommandNames(parser.usage, true),
-		leadingLiterals: extractLeadingLiteralValues(parser.usage),
+		leadingNames: parser.leadingNames,
 		allOptions: extractOptionNames(parser.usage, true),
 		allCommands: extractCommandNames(parser.usage, true),
 		allLiterals: extractLiteralValues(parser.usage)

package/dist/index.cjs

@@ -53,9 +53,6 @@ exports.ensureNonEmptyString = require_nonempty.ensureNonEmptyString;
 exports.envVar = require_message.envVar;
 exports.extractArgumentMetavars = require_usage.extractArgumentMetavars;
 exports.extractCommandNames = require_usage.extractCommandNames;
-exports.extractLeadingCommandNames = require_usage.extractLeadingCommandNames;
-exports.extractLeadingLiteralValues = require_usage.extractLeadingLiteralValues;
-exports.extractLeadingOptionNames = require_usage.extractLeadingOptionNames;
 exports.extractLiteralValues = require_usage.extractLiteralValues;
 exports.extractOptionNames = require_usage.extractOptionNames;
 exports.fail = require_primitives.fail;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.cjs";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 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, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.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, DeferredMap, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.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";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.js";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 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, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.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, DeferredMap, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.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";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -2,7 +2,7 @@ import { annotationKey, getAnnotations } from "./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 { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
-import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.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 { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -12,4 +12,4 @@ import { argument, command, constant, fail, flag, option, passThrough } from "./
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/modifiers.cjs

@@ -118,7 +118,7 @@ function optional(parser) {
 	const wrappedDependencyMarker = innerHasWrappedDependency ? { [require_dependency.wrappedDependencySourceMarker]: parser[require_dependency.wrappedDependencySourceMarker] } : innerHasDirectDependency ? { [require_dependency.wrappedDependencySourceMarker]: syncParser.initialState } : {};
 	const hasWrappedDependencySource = require_dependency.wrappedDependencySourceMarker in wrappedDependencyMarker;
 	const wrappedPendingState = hasWrappedDependencySource ? wrappedDependencyMarker[require_dependency.wrappedDependencySourceMarker] : void 0;
-	return {
+	const optionalParser = {
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
@@ -128,6 +128,8 @@ function optional(parser) {
 			type: "optional",
 			terms: parser.usage
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: false,
 		initialState: void 0,
 		...wrappedDependencyMarker,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
@@ -173,6 +175,18 @@ function optional(parser) {
 			return syncParser.getDocFragments(innerState, defaultValue);
 		}
 	};
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(optionalParser, "normalizeValue", {
+			value(v) {
+				if (v == null) return v;
+				return innerNormalize(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	return optionalParser;
 }
 /**
 * Error type for structured error messages in {@link withDefault} default value callbacks.
@@ -246,6 +260,8 @@ function withDefault(parser, defaultValue, options) {
 			type: "optional",
 			terms: parser.usage
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: false,
 		initialState: void 0,
 		...wrappedDependencyMarker,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
@@ -253,12 +269,19 @@ function withDefault(parser, defaultValue, options) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
+			function evaluateDefault() {
+				const raw = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+				if (typeof parser.normalizeValue === "function") try {
+					return parser.normalizeValue(raw);
+				} catch {}
+				return raw;
+			}
 			if (!Array.isArray(state)) {
 				if (require_dependency.transformsDependencyValue(parser)) {
 					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
 					const handleInnerResult = (res) => {
 						if (require_dependency.isDependencySourceState(res)) try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return require_dependency.createDependencySourceState({
 								success: true,
 								value
@@ -270,7 +293,7 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 						try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return {
 								success: true,
 								value
@@ -285,7 +308,7 @@ function withDefault(parser, defaultValue, options) {
 					return require_mode_dispatch.mapModeValue(parser.$mode, innerResult, handleInnerResult);
 				}
 				if (require_dependency.isWrappedDependencySource(parser)) try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					const pendingState = parser[require_dependency.wrappedDependencySourceMarker];
 					return require_dependency.createDependencySourceState({
 						success: true,
@@ -302,7 +325,7 @@ function withDefault(parser, defaultValue, options) {
 					return innerResult;
 				}
 				try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					return {
 						success: true,
 						value
@@ -319,7 +342,7 @@ function withDefault(parser, defaultValue, options) {
 					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
 					const handleInnerResult = (res) => {
 						if (require_dependency.isDependencySourceState(res)) try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return require_dependency.createDependencySourceState({
 								success: true,
 								value
@@ -331,7 +354,7 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 						try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return {
 								success: true,
 								value
@@ -346,7 +369,7 @@ function withDefault(parser, defaultValue, options) {
 					return require_mode_dispatch.mapModeValue(parser.$mode, innerResult, handleInnerResult);
 				}
 				try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					return require_dependency.createDependencySourceState({
 						success: true,
 						value
@@ -369,7 +392,11 @@ function withDefault(parser, defaultValue, options) {
 				kind: "available",
 				state: state.state[0]
 			};
-			const fragments = syncParser.getDocFragments(innerState, getDocDefaultValue(upperDefaultValue));
+			let docDefault = getDocDefaultValue(upperDefaultValue);
+			if (docDefault != null && typeof parser.normalizeValue === "function") try {
+				docDefault = parser.normalizeValue(docDefault);
+			} catch {}
+			const fragments = syncParser.getDocFragments(innerState, docDefault);
 			if (options?.message) {
 				const modifiedFragments = fragments.fragments.map((fragment) => {
 					if (fragment.type === "entry") return {
@@ -393,6 +420,20 @@ function withDefault(parser, defaultValue, options) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(withDefaultParser, "normalizeValue", {
+			value(v) {
+				try {
+					return innerNormalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	return withDefaultParser;
 }
 /**
@@ -506,6 +547,7 @@ function map(parser, transform) {
 			return parser.getDocFragments(state, void 0);
 		}
 	};
+	delete mappedParser.normalizeValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
 		get() {
 			try {
@@ -650,6 +692,8 @@ function multiple(parser, options = {}) {
 			terms: parser.usage,
 			min
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: min > 0 && (parser.acceptingAnyToken ?? false),
 		initialState: [],
 		parse(context) {
 			return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
@@ -822,6 +866,27 @@ function multiple(parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(resultParser, "normalizeValue", {
+			value(values) {
+				if (!Array.isArray(values)) return values;
+				let changed = false;
+				const result = values.map((v) => {
+					try {
+						const n = innerNormalize(v);
+						if (n !== v) changed = true;
+						return n;
+					} catch {
+						return v;
+					}
+				});
+				return changed ? result : values;
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	return resultParser;
 }
 /**
@@ -886,6 +951,8 @@ function nonEmpty(parser) {
 		$stateType: parser.$stateType,
 		priority: parser.priority,
 		usage: parser.usage,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
 		parse(context) {
@@ -908,6 +975,11 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(nonEmptyParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return nonEmptyParser;
 }
 

package/dist/modifiers.js

@@ -118,7 +118,7 @@ function optional(parser) {
 	const wrappedDependencyMarker = innerHasWrappedDependency ? { [wrappedDependencySourceMarker]: parser[wrappedDependencySourceMarker] } : innerHasDirectDependency ? { [wrappedDependencySourceMarker]: syncParser.initialState } : {};
 	const hasWrappedDependencySource = wrappedDependencySourceMarker in wrappedDependencyMarker;
 	const wrappedPendingState = hasWrappedDependencySource ? wrappedDependencyMarker[wrappedDependencySourceMarker] : void 0;
-	return {
+	const optionalParser = {
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
@@ -128,6 +128,8 @@ function optional(parser) {
 			type: "optional",
 			terms: parser.usage
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: false,
 		initialState: void 0,
 		...wrappedDependencyMarker,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
@@ -173,6 +175,18 @@ function optional(parser) {
 			return syncParser.getDocFragments(innerState, defaultValue);
 		}
 	};
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(optionalParser, "normalizeValue", {
+			value(v) {
+				if (v == null) return v;
+				return innerNormalize(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	return optionalParser;
 }
 /**
 * Error type for structured error messages in {@link withDefault} default value callbacks.
@@ -246,6 +260,8 @@ function withDefault(parser, defaultValue, options) {
 			type: "optional",
 			terms: parser.usage
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: false,
 		initialState: void 0,
 		...wrappedDependencyMarker,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser)) } : {},
@@ -253,12 +269,19 @@ function withDefault(parser, defaultValue, options) {
 			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
+			function evaluateDefault() {
+				const raw = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+				if (typeof parser.normalizeValue === "function") try {
+					return parser.normalizeValue(raw);
+				} catch {}
+				return raw;
+			}
 			if (!Array.isArray(state)) {
 				if (transformsDependencyValue(parser)) {
 					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
 					const handleInnerResult = (res) => {
 						if (isDependencySourceState(res)) try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return createDependencySourceState({
 								success: true,
 								value
@@ -270,7 +293,7 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 						try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return {
 								success: true,
 								value
@@ -285,7 +308,7 @@ function withDefault(parser, defaultValue, options) {
 					return mapModeValue(parser.$mode, innerResult, handleInnerResult);
 				}
 				if (isWrappedDependencySource(parser)) try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					const pendingState = parser[wrappedDependencySourceMarker];
 					return createDependencySourceState({
 						success: true,
@@ -302,7 +325,7 @@ function withDefault(parser, defaultValue, options) {
 					return innerResult;
 				}
 				try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					return {
 						success: true,
 						value
@@ -319,7 +342,7 @@ function withDefault(parser, defaultValue, options) {
 					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
 					const handleInnerResult = (res) => {
 						if (isDependencySourceState(res)) try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return createDependencySourceState({
 								success: true,
 								value
@@ -331,7 +354,7 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 						try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return {
 								success: true,
 								value
@@ -346,7 +369,7 @@ function withDefault(parser, defaultValue, options) {
 					return mapModeValue(parser.$mode, innerResult, handleInnerResult);
 				}
 				try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					return createDependencySourceState({
 						success: true,
 						value
@@ -369,7 +392,11 @@ function withDefault(parser, defaultValue, options) {
 				kind: "available",
 				state: state.state[0]
 			};
-			const fragments = syncParser.getDocFragments(innerState, getDocDefaultValue(upperDefaultValue));
+			let docDefault = getDocDefaultValue(upperDefaultValue);
+			if (docDefault != null && typeof parser.normalizeValue === "function") try {
+				docDefault = parser.normalizeValue(docDefault);
+			} catch {}
+			const fragments = syncParser.getDocFragments(innerState, docDefault);
 			if (options?.message) {
 				const modifiedFragments = fragments.fragments.map((fragment) => {
 					if (fragment.type === "entry") return {
@@ -393,6 +420,20 @@ function withDefault(parser, defaultValue, options) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(withDefaultParser, "normalizeValue", {
+			value(v) {
+				try {
+					return innerNormalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	return withDefaultParser;
 }
 /**
@@ -506,6 +547,7 @@ function map(parser, transform) {
 			return parser.getDocFragments(state, void 0);
 		}
 	};
+	delete mappedParser.normalizeValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
 		get() {
 			try {
@@ -650,6 +692,8 @@ function multiple(parser, options = {}) {
 			terms: parser.usage,
 			min
 		}],
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: min > 0 && (parser.acceptingAnyToken ?? false),
 		initialState: [],
 		parse(context) {
 			return dispatchByMode(parser.$mode, () => parseSync(context), () => parseAsync(context));
@@ -822,6 +866,27 @@ function multiple(parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(resultParser, "normalizeValue", {
+			value(values) {
+				if (!Array.isArray(values)) return values;
+				let changed = false;
+				const result = values.map((v) => {
+					try {
+						const n = innerNormalize(v);
+						if (n !== v) changed = true;
+						return n;
+					} catch {
+						return v;
+					}
+				});
+				return changed ? result : values;
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	return resultParser;
 }
 /**
@@ -886,6 +951,8 @@ function nonEmpty(parser) {
 		$stateType: parser.$stateType,
 		priority: parser.priority,
 		usage: parser.usage,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
 		parse(context) {
@@ -908,6 +975,11 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(nonEmptyParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return nonEmptyParser;
 }
 

package/dist/parser.d.cts

@@ -105,6 +105,44 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * to use it in command-line interfaces.
    */
   readonly usage: Usage;
+  /**
+   * Names that this parser could match at the first buffer position.
+   * Used by `runParser()` to detect collisions with built-in meta
+   * features (help, version, completion).
+   *
+   * Each built-in combinator computes this from its structural semantics.
+   * Custom parser implementations must include every fixed token that
+   * the parser accepts at `argv[0]` — command names, option names, and
+   * literal values alike.  For example, a parser whose usage declares
+   * `{ type: "literal", value: "serve" }` should include `"serve"` in
+   * this set.  Parsers that accept *any* token (like `argument()`) should
+   * return an empty set and set {@link acceptingAnyToken} to `true`
+   * instead.
+   *
+   * @since 1.0.0
+   */
+  readonly leadingNames: ReadonlySet<string>;
+  /**
+   * Whether this parser unconditionally consumes any positional token at
+   * the first buffer position.  A parser with this flag accepts any
+   * non-option token but may still reject option-like tokens (those
+   * starting with `"-"`).
+   *
+   * In shared-buffer compositions (`tuple()`, `object()`, `merge()`,
+   * `concat()`), a catch-all parser blocks positional names (command
+   * names) from lower-priority siblings but does not block option-like
+   * names.  In `conditional()`, option-like names from the default
+   * branch remain reachable even when the discriminator is a catch-all.
+   *
+   * Only `argument()` is inherently accepting-any-token; combinators
+   * like `or()` and `map()` propagate this from their children.
+   * Wrappers that can succeed without consuming (`optional()`,
+   * `withDefault()`, `multiple()` with `min = 0`) always set this
+   * to `false`.
+   *
+   * @since 1.0.0
+   */
+  readonly acceptingAnyToken: boolean;
   /**
    * The initial state for this parser.  This is used to initialize the
    * state when parsing starts.
@@ -187,6 +225,26 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   shouldDeferCompletion?(state: TState): boolean;
+  /**
+   * Normalizes a parsed value according to the underlying value parser's
+   * configuration.  When present, {@link withDefault} calls this method
+   * on default values so that runtime defaults match the representation
+   * that the value parser's `parse()` would produce.
+   *
+   * Primitive parsers ({@link option}, {@link argument}) implement this
+   * by delegating to {@link ValueParser.normalize}.  Combinator wrappers
+   * ({@link optional}, {@link withDefault}) forward it from inner parsers.
+   *
+   * Exclusive combinators ({@link or}, `longestMatch()`) and
+   * multi-source combinators (`merge()`) intentionally do *not*
+   * implement this method because the active branch or key ownership
+   * is unknown at default time.
+   *
+   * @param value The value to normalize.
+   * @returns The normalized value.
+   * @since 1.0.0
+   */
+  normalizeValue?(value: TValue): TValue;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.