@optique/core 1.0.0-dev.1692 → 1.0.0-dev.1693

package/dist/index.cjs

@@ -117,6 +117,7 @@ exports.option = require_primitives.option;
 exports.optionName = require_message.optionName;
 exports.optionNames = require_message.optionNames;
 exports.optional = require_modifiers.optional;
+exports.optionalStyleWrapperKey = require_modifiers.optionalStyleWrapperKey;
 exports.or = require_constructs.or;
 exports.parse = require_parser.parse;
 exports.parseAsync = require_parser.parseAsync;

package/dist/index.d.cts

@@ -5,11 +5,11 @@ import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, Usa
 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";
-import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
+import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.cjs";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker } from "./parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.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, ExecutionContext, ExecutionPhase, 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, ParseFrame, 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, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, 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, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, 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, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, 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, ExecutionContext, ExecutionPhase, 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, ParseFrame, 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, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, 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, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, 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, optionalStyleWrapperKey, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -5,11 +5,11 @@ import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, Usa
 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";
-import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
+import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.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, ExecutionContext, ExecutionPhase, 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, ParseFrame, 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, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, 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, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, 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, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, 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, ExecutionContext, ExecutionPhase, 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, ParseFrame, 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, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, 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, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, 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, optionalStyleWrapperKey, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -4,7 +4,7 @@ import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.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 { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
+import { WithDefaultError, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { 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 { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
@@ -12,4 +12,4 @@ import { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, 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, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, 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, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, annotationWrapperRequiresSourceBindingKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, composeWrappedSourceMetadata, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createParserContext, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, 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, getDelegatingSuggestRuntimeNodes, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, getSnapshottedDefaultDependencyValues, group, hostname, inheritParentAnnotationsKey, 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, optionalStyleWrapperKey, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, singleDefaultValue, snapshotDefaultDependencyValues, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, unmatchedNonCliDependencySourceStateMarker, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/modifiers.cjs

@@ -5,6 +5,15 @@ const require_dependency_metadata = require('./dependency-metadata.cjs');
 const require_parser = require('./parser.cjs');
 
 //#region src/modifiers.ts
+/**
+* Internal marker for optional-style wrappers (`optional()`, `withDefault()`).
+* Used by `object()`'s zero-consumption pass to skip these parsers, since they
+* should return `undefined`/default when the user provides no input rather than
+* running the inner parser.
+*
+* @internal
+*/
+const optionalStyleWrapperKey = Symbol.for("@optique/core/optionalStyleWrapper");
 function withChildExecPath(exec, segment) {
 	if (exec == null) return void 0;
 	return {
@@ -115,6 +124,7 @@ function processOptionalStyleResult(result, innerState, context) {
 	if (result.success) {
 		if (result.next.state !== innerState || result.consumed.length === 0) return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: [result.next.state]
@@ -123,6 +133,7 @@ function processOptionalStyleResult(result, innerState, context) {
 		};
 		return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: context.state
@@ -202,6 +213,7 @@ function optional(parser) {
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
+		[optionalStyleWrapperKey]: true,
 		placeholder: void 0,
 		priority: parser.priority,
 		usage: [{
@@ -349,6 +361,7 @@ function withDefault(parser, defaultValue, options) {
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
+		[optionalStyleWrapperKey]: true,
 		priority: parser.priority,
 		usage: [{
 			type: "optional",
@@ -762,6 +775,7 @@ function multiple(parser, options = {}) {
 		const itemAnnotationSource = added ? context.state : currentItemStateWithAnnotations;
 		if (result.next.state === currentItemStateWithAnnotations && result.consumed.length > 0 && (!added || result.next.optionsTerminated !== context.optionsTerminated)) return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: context.state,
@@ -776,6 +790,7 @@ function multiple(parser, options = {}) {
 		const nextItemState = require_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: require_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
@@ -825,6 +840,7 @@ function multiple(parser, options = {}) {
 		const itemAnnotationSource = added ? context.state : currentItemStateWithAnnotations;
 		if (result.next.state === currentItemStateWithAnnotations && result.consumed.length > 0 && (!added || result.next.optionsTerminated !== context.optionsTerminated)) return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: context.state,
@@ -839,6 +855,7 @@ function multiple(parser, options = {}) {
 		const nextItemState = require_annotations.inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: require_annotations.annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
@@ -1204,4 +1221,5 @@ exports.map = map;
 exports.multiple = multiple;
 exports.nonEmpty = nonEmpty;
 exports.optional = optional;
+exports.optionalStyleWrapperKey = optionalStyleWrapperKey;
 exports.withDefault = withDefault;

package/dist/modifiers.d.cts

@@ -3,6 +3,15 @@ import { Mode, Parser } from "./parser.cjs";
 
 //#region src/modifiers.d.ts
 
+/**
+ * Internal marker for optional-style wrappers (`optional()`, `withDefault()`).
+ * Used by `object()`'s zero-consumption pass to skip these parsers, since they
+ * should return `undefined`/default when the user provides no input rather than
+ * running the inner parser.
+ *
+ * @internal
+ */
+declare const optionalStyleWrapperKey: unique symbol;
 /**
  * Creates a parser that makes another parser optional, allowing it to succeed
  * without consuming input if the wrapped parser fails to match.
@@ -273,4 +282,4 @@ declare function multiple<M extends Mode, TValue, TState>(parser: Parser<M, TVal
  */
 declare function nonEmpty<M extends Mode, T, TState>(parser: Parser<M, T, TState>): Parser<M, T, TState>;
 //#endregion
-export { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault };
+export { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault };

package/dist/modifiers.d.ts

@@ -3,6 +3,15 @@ import { Mode, Parser } from "./parser.js";
 
 //#region src/modifiers.d.ts
 
+/**
+ * Internal marker for optional-style wrappers (`optional()`, `withDefault()`).
+ * Used by `object()`'s zero-consumption pass to skip these parsers, since they
+ * should return `undefined`/default when the user provides no input rather than
+ * running the inner parser.
+ *
+ * @internal
+ */
+declare const optionalStyleWrapperKey: unique symbol;
 /**
  * Creates a parser that makes another parser optional, allowing it to succeed
  * without consuming input if the wrapped parser fails to match.
@@ -273,4 +282,4 @@ declare function multiple<M extends Mode, TValue, TState>(parser: Parser<M, TVal
  */
 declare function nonEmpty<M extends Mode, T, TState>(parser: Parser<M, T, TState>): Parser<M, T, TState>;
 //#endregion
-export { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault };
+export { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault };

package/dist/modifiers.js

@@ -5,6 +5,15 @@ import { composeDependencyMetadata } from "./dependency-metadata.js";
 import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser } from "./parser.js";
 
 //#region src/modifiers.ts
+/**
+* Internal marker for optional-style wrappers (`optional()`, `withDefault()`).
+* Used by `object()`'s zero-consumption pass to skip these parsers, since they
+* should return `undefined`/default when the user provides no input rather than
+* running the inner parser.
+*
+* @internal
+*/
+const optionalStyleWrapperKey = Symbol.for("@optique/core/optionalStyleWrapper");
 function withChildExecPath(exec, segment) {
 	if (exec == null) return void 0;
 	return {
@@ -115,6 +124,7 @@ function processOptionalStyleResult(result, innerState, context) {
 	if (result.success) {
 		if (result.next.state !== innerState || result.consumed.length === 0) return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: [result.next.state]
@@ -123,6 +133,7 @@ function processOptionalStyleResult(result, innerState, context) {
 		};
 		return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: context.state
@@ -202,6 +213,7 @@ function optional(parser) {
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
+		[optionalStyleWrapperKey]: true,
 		placeholder: void 0,
 		priority: parser.priority,
 		usage: [{
@@ -349,6 +361,7 @@ function withDefault(parser, defaultValue, options) {
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
+		[optionalStyleWrapperKey]: true,
 		priority: parser.priority,
 		usage: [{
 			type: "optional",
@@ -762,6 +775,7 @@ function multiple(parser, options = {}) {
 		const itemAnnotationSource = added ? context.state : currentItemStateWithAnnotations;
 		if (result.next.state === currentItemStateWithAnnotations && result.consumed.length > 0 && (!added || result.next.optionsTerminated !== context.optionsTerminated)) return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: context.state,
@@ -776,6 +790,7 @@ function multiple(parser, options = {}) {
 		const nextItemState = inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
@@ -825,6 +840,7 @@ function multiple(parser, options = {}) {
 		const itemAnnotationSource = added ? context.state : currentItemStateWithAnnotations;
 		if (result.next.state === currentItemStateWithAnnotations && result.consumed.length > 0 && (!added || result.next.optionsTerminated !== context.optionsTerminated)) return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: context.state,
@@ -839,6 +855,7 @@ function multiple(parser, options = {}) {
 		const nextItemState = inheritAnnotations(itemAnnotationSource, result.next.state);
 		return {
 			success: true,
+			...result.provisional ? { provisional: true } : {},
 			next: {
 				...result.next,
 				state: annotateFreshArray(context.state, [...added ? context.state : context.state.slice(0, -1), nextItemState]),
@@ -1199,4 +1216,4 @@ function nonEmpty(parser) {
 }
 
 //#endregion
-export { WithDefaultError, map, multiple, nonEmpty, optional, withDefault };
+export { WithDefaultError, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault };

package/dist/parser.cjs

@@ -731,6 +731,7 @@ exports.nonEmpty = require_modifiers.nonEmpty;
 exports.object = require_constructs.object;
 exports.option = require_primitives.option;
 exports.optional = require_modifiers.optional;
+exports.optionalStyleWrapperKey = require_modifiers.optionalStyleWrapperKey;
 exports.or = require_constructs.or;
 exports.parse = parse;
 exports.parseAsync = parseAsync;

package/dist/parser.d.cts

@@ -8,7 +8,7 @@ import { ParserDependencyMetadata } from "./dependency-metadata.cjs";
 import { DependencyRuntimeContext, RuntimeNode } from "./dependency-runtime.cjs";
 import { InputTrace } from "./input-trace.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
-import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
+import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.cjs";
 
 //#region src/parser.d.ts
@@ -558,6 +558,16 @@ type ParserResult<TState> = {
    * The input elements consumed by the parser during this operation.
    */
   readonly consumed: readonly string[];
+  /**
+   * When `true`, indicates that this success is tentative: the parser
+   * matched something (e.g., a zero-consuming discriminator resolved to
+   * a branch key) but the selected sub-parser has not consumed any input
+   * yet.  Outer combinators like {@link or} should not treat provisional
+   * successes as definitive zero-consumed fallback candidates.
+   *
+   * @since 1.0.0
+   */
+  readonly provisional?: true;
 } | {
   /**
    * Indicates that the parsing operation failed.
@@ -909,4 +919,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, optionalStyleWrapperKey, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };

package/dist/parser.d.ts

@@ -8,7 +8,7 @@ import { ParserDependencyMetadata } from "./dependency-metadata.js";
 import { DependencyRuntimeContext, RuntimeNode } from "./dependency-runtime.js";
 import { InputTrace } from "./input-trace.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
-import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
+import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 
 //#region src/parser.d.ts
@@ -558,6 +558,16 @@ type ParserResult<TState> = {
    * The input elements consumed by the parser during this operation.
    */
   readonly consumed: readonly string[];
+  /**
+   * When `true`, indicates that this success is tentative: the parser
+   * matched something (e.g., a zero-consuming discriminator resolved to
+   * a branch key) but the selected sub-parser has not consumed any input
+   * yet.  Outer combinators like {@link or} should not treat provisional
+   * successes as definitive zero-consumed fallback candidates.
+   *
+   * @since 1.0.0
+   */
+  readonly provisional?: true;
 } | {
   /**
    * Indicates that the parsing operation failed.
@@ -909,4 +919,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, optionalStyleWrapperKey, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };

package/dist/parser.js

@@ -4,7 +4,7 @@ import { cloneUsage, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, isDocEntryHidden } from "./doc.js";
 import { dispatchByMode } from "./mode-dispatch.js";
 import { createInputTrace } from "./input-trace.js";
-import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
+import { WithDefaultError, map, multiple, nonEmpty, optional, optionalStyleWrapperKey, withDefault } from "./modifiers.js";
 import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
@@ -702,4 +702,4 @@ function buildDocPage(parser, context, args) {
 }
 
 //#endregion
-export { DuplicateOptionError, WithDefaultError, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };
+export { DuplicateOptionError, WithDefaultError, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, optionalStyleWrapperKey, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1692+5c265bd4",
+  "version": "1.0.0-dev.1693+e2748d7a",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",