@optique/core 1.4.0-dev.2976 → 1.4.0-dev.2979

package/dist/execution-context.cjs

@@ -39,7 +39,8 @@ function withChildContext(context, segment, state, usage) {
 	const exec = withChildExecPath(context.exec, segment);
 	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
 	return {
-		...require_short_option.withOptionScopeChild(context, segment),
+		...context,
+		...require_short_option.getChildOptionScope(context, segment, exec?.path),
 		state,
 		...usage != null ? { usage } : {},
 		...exec != null ? {

package/dist/execution-context.js

@@ -1,5 +1,5 @@
 import { mergeCommandDocPolicy } from "./internal/command-doc-policy.js";
-import { withOptionScopeChild } from "./short-option.js";
+import { getChildOptionScope } from "./short-option.js";
 
 //#region src/execution-context.ts
 /**
@@ -39,7 +39,8 @@ function withChildContext(context, segment, state, usage) {
 	const exec = withChildExecPath(context.exec, segment);
 	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
 	return {
-		...withOptionScopeChild(context, segment),
+		...context,
+		...getChildOptionScope(context, segment, exec?.path),
 		state,
 		...usage != null ? { usage } : {},
 		...exec != null ? {

package/dist/index.cjs

@@ -139,4 +139,5 @@ exports.value = require_message.value;
 exports.valueSet = require_message.valueSet;
 exports.values = require_message.values;
 exports.withDefault = require_modifiers.withDefault;
+exports.withSuggestions = require_valueparser.withSuggestions;
 exports.zsh = require_completion.zsh;

package/dist/index.d.cts

@@ -4,7 +4,7 @@ import { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOption
 import { ErrorLabelTerm, LabelTerm, ProgramNameTerm, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, defaultTerminalTheme } from "./terminal.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, EnvironmentBindingDoc, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.cjs";
-import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, normalizeInput, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.cjs";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, SuggestionInput, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithSuggestionsAsyncOptions, WithSuggestionsOptions, WithSuggestionsOptionsBase, WithSuggestionsSyncOptions, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, normalizeInput, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid, withSuggestions } from "./valueparser.cjs";
 import { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
@@ -13,4 +13,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, EnvironmentBindingDoc, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeInput, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, EnvironmentBindingDoc, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SuggestionInput, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, WithSuggestionsAsyncOptions, WithSuggestionsOptions, WithSuggestionsOptionsBase, WithSuggestionsSyncOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeInput, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, withSuggestions, zsh };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { Message, MessageFormatOptions, MessageFormatter, MessageFormatterOption
 import { ErrorLabelTerm, LabelTerm, ProgramNameTerm, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, defaultTerminalTheme } from "./terminal.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, EnvironmentBindingDoc, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, deriveEnvironmentSection, formatDocPage, isDocEntryHidden } from "./doc.js";
-import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, normalizeInput, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.js";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, SuggestionInput, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithSuggestionsAsyncOptions, WithSuggestionsOptions, WithSuggestionsOptionsBase, WithSuggestionsSyncOptions, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, normalizeInput, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid, withSuggestions } from "./valueparser.js";
 import { CombineModes, DetailedParseResult, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseDetailed, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -13,4 +13,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, getDependencySourceInfo, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, HelpSectionsOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, EnvironmentBindingDoc, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeInput, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencySourceInfo, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DetailedParseResult, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, EnvironmentBindingDoc, ErrorLabelTerm, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HelpSectionsOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LabelTerm, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageFormatter, type MessageFormatterOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, OriginOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ProgramNameTerm, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowAliasesOptions, ShowChoicesOptions, ShowDefaultOptions, ShowEnvironmentOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, SuggestionInput, SyntaxPunctuationTerm, TerminalColor, TerminalFormatContext, TerminalFormatter, TerminalFragment, TerminalStyle, TerminalTerm, TerminalTheme, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, WithSuggestionsAsyncOptions, WithSuggestionsOptions, WithSuggestionsOptionsBase, WithSuggestionsSyncOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createMessageFormatter, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, defaultTerminalTheme, deferredValue, dependency, deriveEnvironmentSection, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDependencySourceInfo, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeInput, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, origin, parse, parseAsync, parseDetailed, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, withSuggestions, zsh };

package/dist/index.js

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

package/dist/short-option.cjs

@@ -18,6 +18,16 @@ function getScopeBindings(selections) {
 	}
 	return bindings;
 }
+function setSelection(selections, source, selected) {
+	if (selections.map.get(source) === selected) return;
+	if (!selections.owned) {
+		const previous = selections.map;
+		selections.map = new Map(previous);
+		scopeBindings.set(selections.map, getScopeBindings(previous));
+		selections.owned = true;
+	}
+	selections.map.set(source, selected);
+}
 function bindScope(source, path, selections) {
 	const boundScopes = getScopeBindings(selections);
 	let node = boundScopes.get(source);
@@ -47,12 +57,9 @@ function bindScope(source, path, selections) {
 function scopePath(context) {
 	return context.exec?.path ?? context[optionPathKey] ?? [];
 }
-/** Tracks child occurrences even for contexts without execution metadata. @internal */
-function withOptionScopeChild(context, segment) {
-	return {
-		...context,
-		[optionPathKey]: [...scopePath(context), segment]
-	};
+/** Supplies child occurrence metadata without copying the parent. @internal */
+function getChildOptionScope(context, segment, path) {
+	return { [optionPathKey]: path ?? [...scopePath(context), segment] };
 }
 const primitiveScopes = /* @__PURE__ */ new WeakMap();
 function parserScope(parser) {
@@ -104,7 +111,7 @@ function selectableOptionScope(initial) {
 		select(context, selected) {
 			const selections = context[optionScopeKey]?.selections;
 			if (selections == null) return;
-			selections.set(bindScope(source, scopePath(context), selections), selected);
+			setSelection(selections, bindScope(source, scopePath(context), selections.map), selected);
 		}
 	};
 }
@@ -135,7 +142,7 @@ function conditionalOptionScope(discriminator, fallback, candidates = []) {
 /** Returns the names reachable in this parse scope. @internal */
 function getOptionScope(context) {
 	const scoped = context[optionScopeKey];
-	const names = scoped == null ? require_usage.extractOptionNames(context.usage, true) : new Set([...scoped.names, ...[...scoped.sources].flatMap((source) => [...source(scoped.selections, void 0, context)])]);
+	const names = scoped == null ? require_usage.extractOptionNames(context.usage, true) : new Set([...scoped.names, ...[...scoped.sources].flatMap((source) => [...source(scoped.selections.map, void 0, context)])]);
 	return names;
 }
 /** Adds reachable names without consulting the flattened help tree. @internal */
@@ -146,19 +153,42 @@ function withOptionScope(context, names) {
 		[optionScopeKey]: {
 			names: new Set([...inherited?.names ?? [], ...names]),
 			sources: inherited?.sources ?? /* @__PURE__ */ new Set(),
-			selections: inherited?.selections ?? /* @__PURE__ */ new Map()
+			selections: inherited?.selections ?? {
+				map: /* @__PURE__ */ new Map(),
+				owned: true
+			}
 		}
 	};
 }
+const scopeUnions = /* @__PURE__ */ new WeakMap();
+function withScopeSource(sources, source) {
+	let unions = scopeUnions.get(sources);
+	if (unions == null) {
+		unions = /* @__PURE__ */ new WeakMap();
+		scopeUnions.set(sources, unions);
+	}
+	let combined = unions.get(source);
+	if (combined == null) {
+		combined = new Set([...sources, source]);
+		unions.set(source, combined);
+	}
+	return combined;
+}
 /** Adds a parser's owned declarations, retaining modifier metadata. @internal */
 function withParserOptionScope(context, parser, segment) {
 	const inherited = context[optionScopeKey];
-	const selections = inherited?.selections ?? /* @__PURE__ */ new Map();
+	const selections = inherited?.selections ?? {
+		map: /* @__PURE__ */ new Map(),
+		owned: true
+	};
+	const source = bindScope(parserScope(parser), segment == null ? scopePath(context) : [...scopePath(context), segment], selections.map);
+	if (inherited?.sources.has(source)) return context;
+	const sources = inherited == null ? new Set([source]) : withScopeSource(inherited.sources, source);
 	return {
 		...context,
 		[optionScopeKey]: {
 			names: inherited?.names ?? /* @__PURE__ */ new Set(),
-			sources: new Set([...inherited?.sources ?? [], bindScope(parserScope(parser), segment == null ? scopePath(context) : [...scopePath(context), segment], selections)]),
+			sources,
 			selections
 		}
 	};
@@ -167,8 +197,11 @@ function withParserOptionScope(context, parser, segment) {
 function forkOptionScope(context) {
 	const scoped = context[optionScopeKey];
 	if (scoped == null) return context;
-	const selections = new Map(scoped.selections);
-	scopeBindings.set(selections, getScopeBindings(scoped.selections));
+	scoped.selections.owned = false;
+	const selections = {
+		map: scoped.selections.map,
+		owned: false
+	};
 	return {
 		...context,
 		[optionScopeKey]: {
@@ -181,7 +214,7 @@ function forkOptionScope(context) {
 function adoptOptionScope(context, next) {
 	const own = context[optionScopeKey];
 	const child = next[optionScopeKey];
-	if (own != null && child != null) for (const [source, selected] of child.selections) own.selections.set(source, selected);
+	if (own != null && child != null && own.selections.map !== child.selections.map) for (const [source, selected] of child.selections.map) setSelection(own.selections, source, selected);
 	return context;
 }
 /** Removes names reserved only for a speculative probe. @internal */
@@ -268,7 +301,7 @@ function attachedValuePrefix(context, prefix, optionNames) {
 	};
 	const scoped = context[optionScopeKey];
 	if (scoped == null) require_usage_internals.collectOptionNamesAtCurrentCommandDepth(context.usage, names, false);
-	else for (const source of scoped.sources) source(scoped.selections, names, context);
+	else for (const source of scoped.sources) source(scoped.selections.map, names, context);
 	for (let index = 1; index < prefix.length;) {
 		const character = String.fromCodePoint(prefix.codePointAt(index));
 		const nextIndex = index + character.length;
@@ -305,6 +338,7 @@ exports.combinedOptionScope = combinedOptionScope;
 exports.conditionalOptionScope = conditionalOptionScope;
 exports.forkOptionScope = forkOptionScope;
 exports.fullNameOwnsToken = fullNameOwnsToken;
+exports.getChildOptionScope = getChildOptionScope;
 exports.inheritOptionScope = inheritOptionScope;
 exports.prefixSuggestion = prefixSuggestion;
 exports.repeatedOptionScope = repeatedOptionScope;
@@ -312,5 +346,4 @@ exports.restoreOptionScope = restoreOptionScope;
 exports.scopeParser = scopeParser;
 exports.selectableOptionScope = selectableOptionScope;
 exports.withOptionScope = withOptionScope;
-exports.withOptionScopeChild = withOptionScopeChild;
 exports.withParserOptionScope = withParserOptionScope;

package/dist/short-option.js

@@ -18,6 +18,16 @@ function getScopeBindings(selections) {
 	}
 	return bindings;
 }
+function setSelection(selections, source, selected) {
+	if (selections.map.get(source) === selected) return;
+	if (!selections.owned) {
+		const previous = selections.map;
+		selections.map = new Map(previous);
+		scopeBindings.set(selections.map, getScopeBindings(previous));
+		selections.owned = true;
+	}
+	selections.map.set(source, selected);
+}
 function bindScope(source, path, selections) {
 	const boundScopes = getScopeBindings(selections);
 	let node = boundScopes.get(source);
@@ -47,12 +57,9 @@ function bindScope(source, path, selections) {
 function scopePath(context) {
 	return context.exec?.path ?? context[optionPathKey] ?? [];
 }
-/** Tracks child occurrences even for contexts without execution metadata. @internal */
-function withOptionScopeChild(context, segment) {
-	return {
-		...context,
-		[optionPathKey]: [...scopePath(context), segment]
-	};
+/** Supplies child occurrence metadata without copying the parent. @internal */
+function getChildOptionScope(context, segment, path) {
+	return { [optionPathKey]: path ?? [...scopePath(context), segment] };
 }
 const primitiveScopes = /* @__PURE__ */ new WeakMap();
 function parserScope(parser) {
@@ -104,7 +111,7 @@ function selectableOptionScope(initial) {
 		select(context, selected) {
 			const selections = context[optionScopeKey]?.selections;
 			if (selections == null) return;
-			selections.set(bindScope(source, scopePath(context), selections), selected);
+			setSelection(selections, bindScope(source, scopePath(context), selections.map), selected);
 		}
 	};
 }
@@ -135,7 +142,7 @@ function conditionalOptionScope(discriminator, fallback, candidates = []) {
 /** Returns the names reachable in this parse scope. @internal */
 function getOptionScope(context) {
 	const scoped = context[optionScopeKey];
-	const names = scoped == null ? extractOptionNames(context.usage, true) : new Set([...scoped.names, ...[...scoped.sources].flatMap((source) => [...source(scoped.selections, void 0, context)])]);
+	const names = scoped == null ? extractOptionNames(context.usage, true) : new Set([...scoped.names, ...[...scoped.sources].flatMap((source) => [...source(scoped.selections.map, void 0, context)])]);
 	return names;
 }
 /** Adds reachable names without consulting the flattened help tree. @internal */
@@ -146,19 +153,42 @@ function withOptionScope(context, names) {
 		[optionScopeKey]: {
 			names: new Set([...inherited?.names ?? [], ...names]),
 			sources: inherited?.sources ?? /* @__PURE__ */ new Set(),
-			selections: inherited?.selections ?? /* @__PURE__ */ new Map()
+			selections: inherited?.selections ?? {
+				map: /* @__PURE__ */ new Map(),
+				owned: true
+			}
 		}
 	};
 }
+const scopeUnions = /* @__PURE__ */ new WeakMap();
+function withScopeSource(sources, source) {
+	let unions = scopeUnions.get(sources);
+	if (unions == null) {
+		unions = /* @__PURE__ */ new WeakMap();
+		scopeUnions.set(sources, unions);
+	}
+	let combined = unions.get(source);
+	if (combined == null) {
+		combined = new Set([...sources, source]);
+		unions.set(source, combined);
+	}
+	return combined;
+}
 /** Adds a parser's owned declarations, retaining modifier metadata. @internal */
 function withParserOptionScope(context, parser, segment) {
 	const inherited = context[optionScopeKey];
-	const selections = inherited?.selections ?? /* @__PURE__ */ new Map();
+	const selections = inherited?.selections ?? {
+		map: /* @__PURE__ */ new Map(),
+		owned: true
+	};
+	const source = bindScope(parserScope(parser), segment == null ? scopePath(context) : [...scopePath(context), segment], selections.map);
+	if (inherited?.sources.has(source)) return context;
+	const sources = inherited == null ? new Set([source]) : withScopeSource(inherited.sources, source);
 	return {
 		...context,
 		[optionScopeKey]: {
 			names: inherited?.names ?? /* @__PURE__ */ new Set(),
-			sources: new Set([...inherited?.sources ?? [], bindScope(parserScope(parser), segment == null ? scopePath(context) : [...scopePath(context), segment], selections)]),
+			sources,
 			selections
 		}
 	};
@@ -167,8 +197,11 @@ function withParserOptionScope(context, parser, segment) {
 function forkOptionScope(context) {
 	const scoped = context[optionScopeKey];
 	if (scoped == null) return context;
-	const selections = new Map(scoped.selections);
-	scopeBindings.set(selections, getScopeBindings(scoped.selections));
+	scoped.selections.owned = false;
+	const selections = {
+		map: scoped.selections.map,
+		owned: false
+	};
 	return {
 		...context,
 		[optionScopeKey]: {
@@ -181,7 +214,7 @@ function forkOptionScope(context) {
 function adoptOptionScope(context, next) {
 	const own = context[optionScopeKey];
 	const child = next[optionScopeKey];
-	if (own != null && child != null) for (const [source, selected] of child.selections) own.selections.set(source, selected);
+	if (own != null && child != null && own.selections.map !== child.selections.map) for (const [source, selected] of child.selections.map) setSelection(own.selections, source, selected);
 	return context;
 }
 /** Removes names reserved only for a speculative probe. @internal */
@@ -268,7 +301,7 @@ function attachedValuePrefix(context, prefix, optionNames) {
 	};
 	const scoped = context[optionScopeKey];
 	if (scoped == null) collectOptionNamesAtCurrentCommandDepth(context.usage, names, false);
-	else for (const source of scoped.sources) source(scoped.selections, names, context);
+	else for (const source of scoped.sources) source(scoped.selections.map, names, context);
 	for (let index = 1; index < prefix.length;) {
 		const character = String.fromCodePoint(prefix.codePointAt(index));
 		const nextIndex = index + character.length;
@@ -299,4 +332,4 @@ function prefixSuggestion(head, suggestion) {
 }
 
 //#endregion
-export { adoptOptionScope, attachedValuePrefix, combinedOptionScope, conditionalOptionScope, forkOptionScope, fullNameOwnsToken, inheritOptionScope, prefixSuggestion, repeatedOptionScope, restoreOptionScope, scopeParser, selectableOptionScope, withOptionScope, withOptionScopeChild, withParserOptionScope };
+export { adoptOptionScope, attachedValuePrefix, combinedOptionScope, conditionalOptionScope, forkOptionScope, fullNameOwnsToken, getChildOptionScope, inheritOptionScope, prefixSuggestion, repeatedOptionScope, restoreOptionScope, scopeParser, selectableOptionScope, withOptionScope, withParserOptionScope };

package/dist/valueparser.cjs

@@ -415,6 +415,275 @@ function preserveNormalizedDerivedMetadata(wrapped, parser, normalize) {
 		});
 	}
 }
+function withSuggestions(parser, options) {
+	if (!isValueParser(parser)) throw new TypeError("Expected parser to be a value parser.");
+	if (options == null || typeof options !== "object") throw new TypeError("Expected options to be an object.");
+	if (typeof options.suggest !== "function") throw new TypeError("Expected suggest to be a function.");
+	checkEnumOption(options, "mode", ["sync", "async"]);
+	checkBooleanOption(options, "includeExisting");
+	checkBooleanOption(options, "filterByPrefix");
+	if (require_internal_dependency.isDependencySource(parser)) throw new TypeError("Cannot attach suggestions to a dependency source directly.");
+	const inner = parser;
+	const providerMode = options.mode ?? "sync";
+	const resultMode = providerMode === "async" ? "async" : inner.mode;
+	const lift = resultMode !== inner.mode;
+	const provider = options.suggest;
+	const includeExisting = options.includeExisting ?? false;
+	const filterByPrefix = options.filterByPrefix ?? true;
+	const existingSuggest = includeExisting ? inner.suggest?.bind(inner) : void 0;
+	const normalizeValue = inner.normalize?.bind(inner);
+	const validate = inner.validate?.bind(inner);
+	const getProviderSource = (prefix) => () => {
+		const source = provider(prefix);
+		return providerMode === "sync" ? checkSyncProviderResult(source) : source;
+	};
+	const suggestFrom = (prefix, existing) => require_mode_dispatch.dispatchIterableByMode(resultMode, () => suggestFromSources(createSuggestionProcessors(prefix, filterByPrefix), existing, getProviderSource(prefix)), () => suggestFromSourcesAsync(createSuggestionProcessors(prefix, filterByPrefix), existing, getProviderSource(prefix)));
+	const wrapped = {
+		mode: resultMode,
+		metavar: inner.metavar,
+		get placeholder() {
+			return inner.placeholder;
+		},
+		...inner.choices == null ? {} : { choices: inner.choices },
+		parse(input) {
+			return lift ? liftToAsync(() => inner.parse(input)) : inner.parse(input);
+		},
+		format(value) {
+			return inner.format(value);
+		},
+		...normalizeValue == null ? {} : { normalize(value) {
+			return normalizeValue(value);
+		} },
+		...validate == null ? {} : { validate(value) {
+			return validate(value);
+		} },
+		suggest(prefix) {
+			return suggestFrom(prefix, existingSuggest == null ? void 0 : () => existingSuggest(prefix));
+		}
+	};
+	const docValue = require_internal_doc_metadata.getDocValue(inner);
+	if (docValue != null) require_internal_doc_metadata.captureDocValue(wrapped, docValue);
+	if (require_internal_dependency.isDerivedValueParser(inner)) preserveSuggestedDerivedMetadata(wrapped, inner, lift, includeExisting, suggestFrom);
+	return wrapped;
+}
+function preserveSuggestedDerivedMetadata(wrapped, parser, lift, includeExisting, suggestFrom) {
+	Object.defineProperties(wrapped, {
+		[require_internal_dependency.derivedValueParserMarker]: {
+			value: true,
+			enumerable: true
+		},
+		[require_internal_dependency.dependencyId]: {
+			value: parser[require_internal_dependency.dependencyId],
+			enumerable: true
+		},
+		[require_internal_dependency.parseWithDependency]: {
+			value(input, dependencyValue) {
+				return lift ? liftToAsync(() => parser[require_internal_dependency.parseWithDependency](input, dependencyValue)) : parser[require_internal_dependency.parseWithDependency](input, dependencyValue);
+			},
+			enumerable: true
+		}
+	});
+	if (require_internal_dependency.dependencyIds in parser && parser[require_internal_dependency.dependencyIds] != null) Object.defineProperty(wrapped, require_internal_dependency.dependencyIds, {
+		value: parser[require_internal_dependency.dependencyIds],
+		enumerable: true
+	});
+	if (require_internal_dependency.defaultValues in parser && parser[require_internal_dependency.defaultValues] != null) Object.defineProperty(wrapped, require_internal_dependency.defaultValues, {
+		value: parser[require_internal_dependency.defaultValues],
+		enumerable: true
+	});
+	if (require_internal_dependency.singleDefaultValue in parser && parser[require_internal_dependency.singleDefaultValue] != null) Object.defineProperty(wrapped, require_internal_dependency.singleDefaultValue, {
+		value: parser[require_internal_dependency.singleDefaultValue],
+		enumerable: true
+	});
+	if (includeExisting && require_internal_dependency.suggestWithDependency in parser && parser[require_internal_dependency.suggestWithDependency] != null) {
+		const existing = parser[require_internal_dependency.suggestWithDependency].bind(parser);
+		Object.defineProperty(wrapped, require_internal_dependency.suggestWithDependency, {
+			value(prefix, dependencyValue) {
+				return suggestFrom(prefix, () => existing(prefix, dependencyValue));
+			},
+			enumerable: true
+		});
+	}
+}
+/**
+* Lifts a synchronous computation to async mode.  It runs inside an async
+* function, so a synchronous throw becomes a rejected promise, and the
+* resolved result object is passed through unchanged.
+*/
+function liftToAsync(compute) {
+	return require_mode_dispatch.dispatchByMode("async", () => require_mode_dispatch.wrapForMode("sync", compute()), async () => await compute());
+}
+function isThenable(value) {
+	return isObjectLike(value) && "then" in value && typeof value.then === "function";
+}
+/**
+* Rejects results a synchronous provider must not return, even when the
+* resulting parser is async.  A thenable gets a rejection handler first so
+* that an invalid async callback cannot cause an unhandled rejection.
+* @throws {TypeError} If the result is not a synchronous iterable.
+*/
+function checkSyncProviderResult(source) {
+	if (isThenable(source)) {
+		Promise.resolve(source).then(void 0, () => {});
+		throw new TypeError("A sync suggestion provider returned a promise.");
+	}
+	return { [Symbol.iterator]: getSyncIteratorMethod(source) };
+}
+function isObjectLike(value) {
+	return value != null && (typeof value === "object" || typeof value === "function");
+}
+/**
+* @throws {TypeError} If the source is not a non-string iterable.
+*/
+function getSyncIteratorMethod(source) {
+	if (!isObjectLike(source) || !(Symbol.iterator in source) || typeof source[Symbol.iterator] !== "function") throw new TypeError("Expected an iterable of suggestions.");
+	const iterable = source;
+	return () => iterable[Symbol.iterator]();
+}
+/**
+* @throws {TypeError} If the source is not a non-string iterable.
+*/
+function getSyncIterator(source) {
+	return getSyncIteratorMethod(source)();
+}
+/**
+* @throws {TypeError} If the source is neither an async iterable nor a
+*   non-string iterable.
+*/
+function getAnyIterator(source) {
+	if (isObjectLike(source) && Symbol.asyncIterator in source && typeof source[Symbol.asyncIterator] === "function") {
+		const iterable = source;
+		return iterable[Symbol.asyncIterator]();
+	}
+	return getSyncIterator(source);
+}
+const fileSuggestionTypes = new Set([
+	"file",
+	"directory",
+	"any"
+]);
+function isOptionalOfType(item, key, check) {
+	const value = Reflect.get(item, key);
+	return value === void 0 || check(value);
+}
+function isString(value) {
+	return typeof value === "string";
+}
+function isStringArray(value) {
+	return Array.isArray(value) && value.every(isString);
+}
+/**
+* Screens a provider item for the `Suggestion` fields that completion encoding
+* relies on: required fields and the types of optional ones.  This is shape
+* checking, not full validation; message terms inside a description are
+* trusted.
+*/
+function screenSuggestionInput(item) {
+	if (typeof item === "string") return {
+		kind: "literal",
+		text: item
+	};
+	if (isThenable(item)) {
+		Promise.resolve(item).then(void 0, () => {});
+		return void 0;
+	}
+	if (item == null || typeof item !== "object" || !("kind" in item)) return void 0;
+	if (!isOptionalOfType(item, "description", Array.isArray)) return void 0;
+	if (item.kind === "literal") return "text" in item && typeof item.text === "string" ? item : void 0;
+	if (item.kind === "file") return "type" in item && fileSuggestionTypes.has(item.type) && isOptionalOfType(item, "pattern", isString) && isOptionalOfType(item, "prefix", isString) && isOptionalOfType(item, "extensions", isStringArray) && isOptionalOfType(item, "includeHidden", (value) => typeof value === "boolean") ? item : void 0;
+	return void 0;
+}
+function createSuggestionProcessors(prefix, filterByPrefix) {
+	const seen = /* @__PURE__ */ new Set();
+	const dedupe = (suggestion) => {
+		if (suggestion.kind !== "literal") return suggestion;
+		if (seen.has(suggestion.text)) return void 0;
+		seen.add(suggestion.text);
+		return suggestion;
+	};
+	return {
+		existing: (item) => dedupe(item),
+		provider(item) {
+			const suggestion = screenSuggestionInput(item);
+			if (suggestion == null || filterByPrefix && suggestion.kind === "literal" && !suggestion.text.startsWith(prefix)) return void 0;
+			return dedupe(suggestion);
+		}
+	};
+}
+function* suggestFromSources(processors, existing, provider) {
+	if (existing != null) yield* guardedSuggestions(existing, processors.existing);
+	yield* guardedSuggestions(provider, processors.provider);
+}
+async function* suggestFromSourcesAsync(processors, existing, provider) {
+	if (existing != null) yield* guardedSuggestionsAsync(existing, processors.existing);
+	yield* guardedSuggestionsAsync(provider, processors.provider);
+}
+/**
+* Yields processed items from one source, ending quietly on any failure.
+* Yields happen outside the guarded regions, so consumer cancellation is never
+* mistaken for a source failure, and the source iterator is closed when the
+* consumer stops early.
+*/
+function* guardedSuggestions(getSource, process) {
+	let iterator;
+	try {
+		iterator = getSyncIterator(getSource());
+	} catch {
+		return;
+	}
+	let finished = false;
+	try {
+		while (true) {
+			let suggestion;
+			try {
+				const step = iterator.next();
+				if (!isObjectLike(step)) return;
+				if (step.done) {
+					finished = true;
+					return;
+				}
+				suggestion = process(step.value);
+			} catch {
+				return;
+			}
+			if (suggestion != null) yield suggestion;
+		}
+	} finally {
+		if (!finished) try {
+			iterator.return?.();
+		} catch {}
+	}
+}
+async function* guardedSuggestionsAsync(getSource, process) {
+	let iterator;
+	try {
+		iterator = getAnyIterator(await getSource());
+	} catch {
+		return;
+	}
+	let finished = false;
+	try {
+		while (true) {
+			let suggestion;
+			try {
+				const step = await iterator.next();
+				if (!isObjectLike(step)) return;
+				if (step.done) {
+					finished = true;
+					return;
+				}
+				suggestion = process(step.value);
+			} catch {
+				return;
+			}
+			if (suggestion != null) yield suggestion;
+		}
+	} finally {
+		if (!finished) try {
+			await iterator.return?.();
+		} catch {}
+	}
+}
 /**
 * Creates a value parser that transforms the result of another value parser.
 *
@@ -7026,4 +7295,5 @@ exports.socketAddress = socketAddress;
 exports.string = string;
 exports.transform = transform;
 exports.url = url;
-exports.uuid = uuid;
+exports.uuid = uuid;
+exports.withSuggestions = withSuggestions;

package/dist/valueparser.d.cts

@@ -459,6 +459,139 @@ declare function biject<const T extends object>(mapping: T): ValueParser<"sync",
  * @since 1.4.0
  */
 declare function normalizeInput<M extends Mode, T>(parser: ValueParser<M, T>, normalize: (input: string) => string): ValueParser<M, T>;
+/**
+ * A completion candidate produced by a {@link withSuggestions} provider.
+ *
+ * A string is shorthand for a literal suggestion with that text.
+ *
+ * @since 1.4.0
+ */
+type SuggestionInput = string | Suggestion;
+/**
+ * Options shared by every {@link withSuggestions} provider mode.
+ *
+ * @since 1.4.0
+ */
+interface WithSuggestionsOptionsBase {
+  /**
+   * Whether to keep the wrapped parser's own suggestions.  When `true`, they
+   * are produced first, followed by the provider's candidates.  Literal
+   * candidates whose text was already produced are skipped.
+   *
+   * @default `false`
+   */
+  readonly includeExisting?: boolean;
+  /**
+   * Whether to drop provider literals whose text does not start with the
+   * completion prefix.  Turn this off when the provider already matches in
+   * its own way, such as case-insensitively or by completing `42` to `#42`,
+   * and returns spellings that differ from the typed prefix.  Suggestions
+   * kept by `includeExisting` are never filtered by this wrapper.
+   *
+   * @default `true`
+   */
+  readonly filterByPrefix?: boolean;
+}
+/**
+ * Options for {@link withSuggestions} with a synchronous provider.
+ *
+ * @since 1.4.0
+ */
+interface WithSuggestionsSyncOptions extends WithSuggestionsOptionsBase {
+  /**
+   * The provider mode.  Synchronous providers keep the wrapped parser's mode.
+   *
+   * @default `"sync"`
+   */
+  readonly mode?: "sync";
+  /**
+   * Returns completion candidates for the given prefix.  This is a shell
+   * completion provider, unrelated to the typo hints configured by
+   * `choice()`'s `suggest` option.  It is called only during completion,
+   * never while parsing.  Failures are swallowed without logging, so log
+   * inside the provider if you need diagnostics.
+   *
+   * Return a collection of candidates, not a bare string: a string result
+   * yields no suggestions rather than one suggestion per character.
+   *
+   * @param prefix The current input prefix to complete.
+   * @returns The completion candidates.
+   */
+  readonly suggest: (prefix: string) => Iterable<SuggestionInput>;
+}
+/**
+ * Options for {@link withSuggestions} with an asynchronous provider.
+ *
+ * @since 1.4.0
+ */
+interface WithSuggestionsAsyncOptions extends WithSuggestionsOptionsBase {
+  /**
+   * The provider mode.  Asynchronous providers make the resulting value
+   * parser asynchronous.
+   */
+  readonly mode: "async";
+  /**
+   * Returns completion candidates for the given prefix.  It may be an async
+   * generator, or return an iterable, an async iterable, or a promise of
+   * either.  This is a shell completion provider, unrelated to the typo hints
+   * configured by `choice()`'s `suggest` option.  It is called only during
+   * completion, never while parsing.  Failures are swallowed without logging,
+   * so log inside the provider if you need diagnostics.  A bare string result
+   * yields no suggestions.
+   *
+   * @param prefix The current input prefix to complete.
+   * @returns The completion candidates.
+   */
+  readonly suggest: (prefix: string) => Iterable<SuggestionInput> | AsyncIterable<SuggestionInput> | Promise<Iterable<SuggestionInput> | AsyncIterable<SuggestionInput>>;
+}
+/**
+ * Options for {@link withSuggestions}.
+ *
+ * @since 1.4.0
+ */
+type WithSuggestionsOptions = WithSuggestionsSyncOptions | WithSuggestionsAsyncOptions;
+/**
+ * Attaches completion candidates to an existing value parser.
+ *
+ * The returned parser accepts the same input and produces the same values as
+ * `parser`: parsing, formatting, `normalize()`, `validate()`, `choices`,
+ * the placeholder, and dependency-derived behavior are all delegated to it.
+ * Only `suggest()` changes.  By default the provider's candidates replace the
+ * wrapped parser's own suggestions; set `includeExisting` to keep them.
+ *
+ * The provider receives the raw completion prefix, so it can filter on the
+ * server side, and literal candidates that do not start with the prefix are
+ * dropped afterwards unless `filterByPrefix` is `false`.  Completion is best-effort: if the provider throws,
+ * rejects, or fails during iteration, candidates produced so far are kept and
+ * the rest are skipped.  Malformed candidates are skipped.
+ *
+ * A synchronous provider keeps the wrapped parser's mode.  An asynchronous
+ * provider (`mode: "async"`) makes the result asynchronous, so `parse()`
+ * returns a promise even when the wrapped parser is synchronous.
+ *
+ * @example
+ * ```typescript
+ * const issue = withSuggestions(integer({ min: 1 }), {
+ *   mode: "async",
+ *   async *suggest(prefix) {
+ *     yield* await listIssueNumbers(prefix);
+ *   },
+ * });
+ * ```
+ *
+ * @template M The mode of the wrapped parser.
+ * @template T The value type produced by the wrapped parser.
+ * @param parser The value parser to attach suggestions to.
+ * @param options The completion provider and its options.
+ * @returns A value parser that accepts the same input as `parser` and uses the
+ *          provider for completion.
+ * @throws {TypeError} If `parser` is not a value parser or is a dependency
+ *   source, or if `options` is invalid.
+ * @since 1.4.0
+ */
+declare function withSuggestions<M extends Mode, T>(parser: ValueParser<M, T>, options: WithSuggestionsSyncOptions): ValueParser<M, T>;
+declare function withSuggestions<M extends Mode, T>(parser: ValueParser<M, T>, options: WithSuggestionsAsyncOptions): ValueParser<"async", T>;
+declare function withSuggestions<M extends Mode, T>(parser: ValueParser<M, T>, options: WithSuggestionsOptions): ValueParser<M | "async", T>;
 /**
  * Creates a value parser that transforms the result of another value parser.
  *
@@ -3457,4 +3590,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, normalizeInput, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, SuggestionInput, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithSuggestionsAsyncOptions, WithSuggestionsOptions, WithSuggestionsOptionsBase, WithSuggestionsSyncOptions, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, normalizeInput, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid, withSuggestions };

package/dist/valueparser.d.ts

@@ -459,6 +459,139 @@ declare function biject<const T extends object>(mapping: T): ValueParser<"sync",
  * @since 1.4.0
  */
 declare function normalizeInput<M extends Mode, T>(parser: ValueParser<M, T>, normalize: (input: string) => string): ValueParser<M, T>;
+/**
+ * A completion candidate produced by a {@link withSuggestions} provider.
+ *
+ * A string is shorthand for a literal suggestion with that text.
+ *
+ * @since 1.4.0
+ */
+type SuggestionInput = string | Suggestion;
+/**
+ * Options shared by every {@link withSuggestions} provider mode.
+ *
+ * @since 1.4.0
+ */
+interface WithSuggestionsOptionsBase {
+  /**
+   * Whether to keep the wrapped parser's own suggestions.  When `true`, they
+   * are produced first, followed by the provider's candidates.  Literal
+   * candidates whose text was already produced are skipped.
+   *
+   * @default `false`
+   */
+  readonly includeExisting?: boolean;
+  /**
+   * Whether to drop provider literals whose text does not start with the
+   * completion prefix.  Turn this off when the provider already matches in
+   * its own way, such as case-insensitively or by completing `42` to `#42`,
+   * and returns spellings that differ from the typed prefix.  Suggestions
+   * kept by `includeExisting` are never filtered by this wrapper.
+   *
+   * @default `true`
+   */
+  readonly filterByPrefix?: boolean;
+}
+/**
+ * Options for {@link withSuggestions} with a synchronous provider.
+ *
+ * @since 1.4.0
+ */
+interface WithSuggestionsSyncOptions extends WithSuggestionsOptionsBase {
+  /**
+   * The provider mode.  Synchronous providers keep the wrapped parser's mode.
+   *
+   * @default `"sync"`
+   */
+  readonly mode?: "sync";
+  /**
+   * Returns completion candidates for the given prefix.  This is a shell
+   * completion provider, unrelated to the typo hints configured by
+   * `choice()`'s `suggest` option.  It is called only during completion,
+   * never while parsing.  Failures are swallowed without logging, so log
+   * inside the provider if you need diagnostics.
+   *
+   * Return a collection of candidates, not a bare string: a string result
+   * yields no suggestions rather than one suggestion per character.
+   *
+   * @param prefix The current input prefix to complete.
+   * @returns The completion candidates.
+   */
+  readonly suggest: (prefix: string) => Iterable<SuggestionInput>;
+}
+/**
+ * Options for {@link withSuggestions} with an asynchronous provider.
+ *
+ * @since 1.4.0
+ */
+interface WithSuggestionsAsyncOptions extends WithSuggestionsOptionsBase {
+  /**
+   * The provider mode.  Asynchronous providers make the resulting value
+   * parser asynchronous.
+   */
+  readonly mode: "async";
+  /**
+   * Returns completion candidates for the given prefix.  It may be an async
+   * generator, or return an iterable, an async iterable, or a promise of
+   * either.  This is a shell completion provider, unrelated to the typo hints
+   * configured by `choice()`'s `suggest` option.  It is called only during
+   * completion, never while parsing.  Failures are swallowed without logging,
+   * so log inside the provider if you need diagnostics.  A bare string result
+   * yields no suggestions.
+   *
+   * @param prefix The current input prefix to complete.
+   * @returns The completion candidates.
+   */
+  readonly suggest: (prefix: string) => Iterable<SuggestionInput> | AsyncIterable<SuggestionInput> | Promise<Iterable<SuggestionInput> | AsyncIterable<SuggestionInput>>;
+}
+/**
+ * Options for {@link withSuggestions}.
+ *
+ * @since 1.4.0
+ */
+type WithSuggestionsOptions = WithSuggestionsSyncOptions | WithSuggestionsAsyncOptions;
+/**
+ * Attaches completion candidates to an existing value parser.
+ *
+ * The returned parser accepts the same input and produces the same values as
+ * `parser`: parsing, formatting, `normalize()`, `validate()`, `choices`,
+ * the placeholder, and dependency-derived behavior are all delegated to it.
+ * Only `suggest()` changes.  By default the provider's candidates replace the
+ * wrapped parser's own suggestions; set `includeExisting` to keep them.
+ *
+ * The provider receives the raw completion prefix, so it can filter on the
+ * server side, and literal candidates that do not start with the prefix are
+ * dropped afterwards unless `filterByPrefix` is `false`.  Completion is best-effort: if the provider throws,
+ * rejects, or fails during iteration, candidates produced so far are kept and
+ * the rest are skipped.  Malformed candidates are skipped.
+ *
+ * A synchronous provider keeps the wrapped parser's mode.  An asynchronous
+ * provider (`mode: "async"`) makes the result asynchronous, so `parse()`
+ * returns a promise even when the wrapped parser is synchronous.
+ *
+ * @example
+ * ```typescript
+ * const issue = withSuggestions(integer({ min: 1 }), {
+ *   mode: "async",
+ *   async *suggest(prefix) {
+ *     yield* await listIssueNumbers(prefix);
+ *   },
+ * });
+ * ```
+ *
+ * @template M The mode of the wrapped parser.
+ * @template T The value type produced by the wrapped parser.
+ * @param parser The value parser to attach suggestions to.
+ * @param options The completion provider and its options.
+ * @returns A value parser that accepts the same input as `parser` and uses the
+ *          provider for completion.
+ * @throws {TypeError} If `parser` is not a value parser or is a dependency
+ *   source, or if `options` is invalid.
+ * @since 1.4.0
+ */
+declare function withSuggestions<M extends Mode, T>(parser: ValueParser<M, T>, options: WithSuggestionsSyncOptions): ValueParser<M, T>;
+declare function withSuggestions<M extends Mode, T>(parser: ValueParser<M, T>, options: WithSuggestionsAsyncOptions): ValueParser<"async", T>;
+declare function withSuggestions<M extends Mode, T>(parser: ValueParser<M, T>, options: WithSuggestionsOptions): ValueParser<M | "async", T>;
 /**
  * Creates a value parser that transforms the result of another value parser.
  *
@@ -3457,4 +3590,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, normalizeInput, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, SuggestionInput, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithSuggestionsAsyncOptions, WithSuggestionsOptions, WithSuggestionsOptionsBase, WithSuggestionsSyncOptions, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, normalizeInput, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid, withSuggestions };

package/dist/valueparser.js

@@ -1,7 +1,7 @@
 import { cloneMessage, lineBreak, message, metavar, text, valueSet } from "./message.js";
-import { mapMaybePromiseByMode, wrapForMode, wrapIterableForMode } from "./internal/mode-dispatch.js";
+import { dispatchByMode, dispatchIterableByMode, mapMaybePromiseByMode, wrapForMode, wrapIterableForMode } from "./internal/mode-dispatch.js";
 import { defaultValues, dependencyId, dependencyIds, derivedValueParserMarker, getSnapshottedDefaultDependencyValues, isDependencySource, isDerivedValueParser, parseWithDependency, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency } from "./internal/dependency.js";
-import { captureDocValue } from "./internal/doc-metadata.js";
+import { captureDocValue, getDocValue } from "./internal/doc-metadata.js";
 import { appendValueHint, appendValueSuggestions, deduplicateSuggestions } from "./suggestion.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 
@@ -415,6 +415,275 @@ function preserveNormalizedDerivedMetadata(wrapped, parser, normalize) {
 		});
 	}
 }
+function withSuggestions(parser, options) {
+	if (!isValueParser(parser)) throw new TypeError("Expected parser to be a value parser.");
+	if (options == null || typeof options !== "object") throw new TypeError("Expected options to be an object.");
+	if (typeof options.suggest !== "function") throw new TypeError("Expected suggest to be a function.");
+	checkEnumOption(options, "mode", ["sync", "async"]);
+	checkBooleanOption(options, "includeExisting");
+	checkBooleanOption(options, "filterByPrefix");
+	if (isDependencySource(parser)) throw new TypeError("Cannot attach suggestions to a dependency source directly.");
+	const inner = parser;
+	const providerMode = options.mode ?? "sync";
+	const resultMode = providerMode === "async" ? "async" : inner.mode;
+	const lift = resultMode !== inner.mode;
+	const provider = options.suggest;
+	const includeExisting = options.includeExisting ?? false;
+	const filterByPrefix = options.filterByPrefix ?? true;
+	const existingSuggest = includeExisting ? inner.suggest?.bind(inner) : void 0;
+	const normalizeValue = inner.normalize?.bind(inner);
+	const validate = inner.validate?.bind(inner);
+	const getProviderSource = (prefix) => () => {
+		const source = provider(prefix);
+		return providerMode === "sync" ? checkSyncProviderResult(source) : source;
+	};
+	const suggestFrom = (prefix, existing) => dispatchIterableByMode(resultMode, () => suggestFromSources(createSuggestionProcessors(prefix, filterByPrefix), existing, getProviderSource(prefix)), () => suggestFromSourcesAsync(createSuggestionProcessors(prefix, filterByPrefix), existing, getProviderSource(prefix)));
+	const wrapped = {
+		mode: resultMode,
+		metavar: inner.metavar,
+		get placeholder() {
+			return inner.placeholder;
+		},
+		...inner.choices == null ? {} : { choices: inner.choices },
+		parse(input) {
+			return lift ? liftToAsync(() => inner.parse(input)) : inner.parse(input);
+		},
+		format(value) {
+			return inner.format(value);
+		},
+		...normalizeValue == null ? {} : { normalize(value) {
+			return normalizeValue(value);
+		} },
+		...validate == null ? {} : { validate(value) {
+			return validate(value);
+		} },
+		suggest(prefix) {
+			return suggestFrom(prefix, existingSuggest == null ? void 0 : () => existingSuggest(prefix));
+		}
+	};
+	const docValue = getDocValue(inner);
+	if (docValue != null) captureDocValue(wrapped, docValue);
+	if (isDerivedValueParser(inner)) preserveSuggestedDerivedMetadata(wrapped, inner, lift, includeExisting, suggestFrom);
+	return wrapped;
+}
+function preserveSuggestedDerivedMetadata(wrapped, parser, lift, includeExisting, suggestFrom) {
+	Object.defineProperties(wrapped, {
+		[derivedValueParserMarker]: {
+			value: true,
+			enumerable: true
+		},
+		[dependencyId]: {
+			value: parser[dependencyId],
+			enumerable: true
+		},
+		[parseWithDependency]: {
+			value(input, dependencyValue) {
+				return lift ? liftToAsync(() => parser[parseWithDependency](input, dependencyValue)) : parser[parseWithDependency](input, dependencyValue);
+			},
+			enumerable: true
+		}
+	});
+	if (dependencyIds in parser && parser[dependencyIds] != null) Object.defineProperty(wrapped, dependencyIds, {
+		value: parser[dependencyIds],
+		enumerable: true
+	});
+	if (defaultValues in parser && parser[defaultValues] != null) Object.defineProperty(wrapped, defaultValues, {
+		value: parser[defaultValues],
+		enumerable: true
+	});
+	if (singleDefaultValue in parser && parser[singleDefaultValue] != null) Object.defineProperty(wrapped, singleDefaultValue, {
+		value: parser[singleDefaultValue],
+		enumerable: true
+	});
+	if (includeExisting && suggestWithDependency in parser && parser[suggestWithDependency] != null) {
+		const existing = parser[suggestWithDependency].bind(parser);
+		Object.defineProperty(wrapped, suggestWithDependency, {
+			value(prefix, dependencyValue) {
+				return suggestFrom(prefix, () => existing(prefix, dependencyValue));
+			},
+			enumerable: true
+		});
+	}
+}
+/**
+* Lifts a synchronous computation to async mode.  It runs inside an async
+* function, so a synchronous throw becomes a rejected promise, and the
+* resolved result object is passed through unchanged.
+*/
+function liftToAsync(compute) {
+	return dispatchByMode("async", () => wrapForMode("sync", compute()), async () => await compute());
+}
+function isThenable(value) {
+	return isObjectLike(value) && "then" in value && typeof value.then === "function";
+}
+/**
+* Rejects results a synchronous provider must not return, even when the
+* resulting parser is async.  A thenable gets a rejection handler first so
+* that an invalid async callback cannot cause an unhandled rejection.
+* @throws {TypeError} If the result is not a synchronous iterable.
+*/
+function checkSyncProviderResult(source) {
+	if (isThenable(source)) {
+		Promise.resolve(source).then(void 0, () => {});
+		throw new TypeError("A sync suggestion provider returned a promise.");
+	}
+	return { [Symbol.iterator]: getSyncIteratorMethod(source) };
+}
+function isObjectLike(value) {
+	return value != null && (typeof value === "object" || typeof value === "function");
+}
+/**
+* @throws {TypeError} If the source is not a non-string iterable.
+*/
+function getSyncIteratorMethod(source) {
+	if (!isObjectLike(source) || !(Symbol.iterator in source) || typeof source[Symbol.iterator] !== "function") throw new TypeError("Expected an iterable of suggestions.");
+	const iterable = source;
+	return () => iterable[Symbol.iterator]();
+}
+/**
+* @throws {TypeError} If the source is not a non-string iterable.
+*/
+function getSyncIterator(source) {
+	return getSyncIteratorMethod(source)();
+}
+/**
+* @throws {TypeError} If the source is neither an async iterable nor a
+*   non-string iterable.
+*/
+function getAnyIterator(source) {
+	if (isObjectLike(source) && Symbol.asyncIterator in source && typeof source[Symbol.asyncIterator] === "function") {
+		const iterable = source;
+		return iterable[Symbol.asyncIterator]();
+	}
+	return getSyncIterator(source);
+}
+const fileSuggestionTypes = new Set([
+	"file",
+	"directory",
+	"any"
+]);
+function isOptionalOfType(item, key, check) {
+	const value = Reflect.get(item, key);
+	return value === void 0 || check(value);
+}
+function isString(value) {
+	return typeof value === "string";
+}
+function isStringArray(value) {
+	return Array.isArray(value) && value.every(isString);
+}
+/**
+* Screens a provider item for the `Suggestion` fields that completion encoding
+* relies on: required fields and the types of optional ones.  This is shape
+* checking, not full validation; message terms inside a description are
+* trusted.
+*/
+function screenSuggestionInput(item) {
+	if (typeof item === "string") return {
+		kind: "literal",
+		text: item
+	};
+	if (isThenable(item)) {
+		Promise.resolve(item).then(void 0, () => {});
+		return void 0;
+	}
+	if (item == null || typeof item !== "object" || !("kind" in item)) return void 0;
+	if (!isOptionalOfType(item, "description", Array.isArray)) return void 0;
+	if (item.kind === "literal") return "text" in item && typeof item.text === "string" ? item : void 0;
+	if (item.kind === "file") return "type" in item && fileSuggestionTypes.has(item.type) && isOptionalOfType(item, "pattern", isString) && isOptionalOfType(item, "prefix", isString) && isOptionalOfType(item, "extensions", isStringArray) && isOptionalOfType(item, "includeHidden", (value) => typeof value === "boolean") ? item : void 0;
+	return void 0;
+}
+function createSuggestionProcessors(prefix, filterByPrefix) {
+	const seen = /* @__PURE__ */ new Set();
+	const dedupe = (suggestion) => {
+		if (suggestion.kind !== "literal") return suggestion;
+		if (seen.has(suggestion.text)) return void 0;
+		seen.add(suggestion.text);
+		return suggestion;
+	};
+	return {
+		existing: (item) => dedupe(item),
+		provider(item) {
+			const suggestion = screenSuggestionInput(item);
+			if (suggestion == null || filterByPrefix && suggestion.kind === "literal" && !suggestion.text.startsWith(prefix)) return void 0;
+			return dedupe(suggestion);
+		}
+	};
+}
+function* suggestFromSources(processors, existing, provider) {
+	if (existing != null) yield* guardedSuggestions(existing, processors.existing);
+	yield* guardedSuggestions(provider, processors.provider);
+}
+async function* suggestFromSourcesAsync(processors, existing, provider) {
+	if (existing != null) yield* guardedSuggestionsAsync(existing, processors.existing);
+	yield* guardedSuggestionsAsync(provider, processors.provider);
+}
+/**
+* Yields processed items from one source, ending quietly on any failure.
+* Yields happen outside the guarded regions, so consumer cancellation is never
+* mistaken for a source failure, and the source iterator is closed when the
+* consumer stops early.
+*/
+function* guardedSuggestions(getSource, process) {
+	let iterator;
+	try {
+		iterator = getSyncIterator(getSource());
+	} catch {
+		return;
+	}
+	let finished = false;
+	try {
+		while (true) {
+			let suggestion;
+			try {
+				const step = iterator.next();
+				if (!isObjectLike(step)) return;
+				if (step.done) {
+					finished = true;
+					return;
+				}
+				suggestion = process(step.value);
+			} catch {
+				return;
+			}
+			if (suggestion != null) yield suggestion;
+		}
+	} finally {
+		if (!finished) try {
+			iterator.return?.();
+		} catch {}
+	}
+}
+async function* guardedSuggestionsAsync(getSource, process) {
+	let iterator;
+	try {
+		iterator = getAnyIterator(await getSource());
+	} catch {
+		return;
+	}
+	let finished = false;
+	try {
+		while (true) {
+			let suggestion;
+			try {
+				const step = await iterator.next();
+				if (!isObjectLike(step)) return;
+				if (step.done) {
+					finished = true;
+					return;
+				}
+				suggestion = process(step.value);
+			} catch {
+				return;
+			}
+			if (suggestion != null) yield suggestion;
+		}
+	} finally {
+		if (!finished) try {
+			await iterator.return?.();
+		} catch {}
+	}
+}
 /**
 * Creates a value parser that transforms the result of another value parser.
 *
@@ -6992,4 +7261,4 @@ function plainObjectsEqual(a, b) {
 }
 
 //#endregion
-export { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, normalizeInput, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };
+export { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, normalizeInput, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid, withSuggestions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.4.0-dev.2976",
+  "version": "1.4.0-dev.2979",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -269,7 +269,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2976+6b99c6c9",
+    "@optique/env": "1.4.0-dev.2979+a175cdb7",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -45,9 +45,9 @@ Core rules
     parsing. Use `regExp({ flags })` for user-supplied sources, `biject()` for
     one-to-one mappings, `transform()` for mapped results, and
     `choice(values, { key })` for custom string matching that returns the
-    declared spelling. Use `normalizeInput()` for raw-string cleanup and
-    `path()` from `@optique/run/valueparser` for file-system paths. Write a
-    custom value parser only when these tools do not cover the domain.
+    declared spelling. Use `normalizeInput()` to clean raw strings,
+    `withSuggestions()` to replace completions, and `path()` (*@optique/run*)
+    for paths. Write a custom value parser only when these do not fit.
  -  Since 1.4.0, `-p8080`/`-vp8080` accept attached values. Values consume
     the literal suffix (`-p=5` gives `"=5"`); full single-dash names win.
  -  Async value parsers like *@optique/git* make containing parsers async.