@optique/core 1.2.0-dev.2229 → 1.2.0-dev.2232

package/dist/index.cjs

@@ -34,6 +34,7 @@ exports.createParserContext = require_internal_parser.createParserContext;
 exports.cron = require_valueparser.cron;
 exports.deduplicateDocEntries = require_doc.deduplicateDocEntries;
 exports.deduplicateDocFragments = require_doc.deduplicateDocFragments;
+exports.deferredValue = require_modifiers.deferredValue;
 exports.dependency = require_internal_dependency.dependency;
 exports.deriveFrom = require_internal_dependency.deriveFrom;
 exports.deriveFromAsync = require_internal_dependency.deriveFromAsync;
@@ -67,6 +68,7 @@ exports.integer = require_valueparser.integer;
 exports.ip = require_valueparser.ip;
 exports.ipv4 = require_valueparser.ipv4;
 exports.ipv6 = require_valueparser.ipv6;
+exports.isDeferredValue = require_modifiers.isDeferredValue;
 exports.isDependencySource = require_internal_dependency.isDependencySource;
 exports.isDerivedValueParser = require_internal_dependency.isDerivedValueParser;
 exports.isDocEntryHidden = require_doc.isDocEntryHidden;

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/modifiers.cjs

@@ -845,6 +845,93 @@ function map(parser, transform) {
 	}
 	return fluent(mappedParser);
 }
+const deferredValueBrand = Symbol.for("@optique/core/deferredValue");
+/**
+* Brands a value-producing function as a {@link DeferredValue}.
+*
+* The brand is a hidden, non-enumerable symbol so {@link isDeferredValue} can
+* recognize the value while object inspection only sees `source`.  The `source`
+* property is enumerable but readonly and non-configurable.
+*
+* @param call The value-producing function.
+* @param source The branch that produced the value.
+* @returns The same function decorated as a {@link DeferredValue}.
+*/
+function brandDeferredValue(call, source) {
+	Object.defineProperties(call, {
+		[deferredValueBrand]: {
+			value: true,
+			enumerable: false,
+			writable: false,
+			configurable: false
+		},
+		source: {
+			value: source,
+			enumerable: true,
+			writable: false,
+			configurable: false
+		}
+	});
+	return call;
+}
+/**
+* Builds the `"specified"` branch: a function that returns the parsed value
+* and ignores any handler-time context.
+*/
+function makeSpecifiedDeferredValue(value) {
+	return brandDeferredValue((_ctx) => value, "specified");
+}
+/**
+* Builds the `"fallback"` branch: a function that runs the fallback resolver,
+* optionally memoizing the resolved value or in-flight promise.
+*/
+function makeFallbackDeferredValue(fallback, memoize) {
+	if (!memoize) return brandDeferredValue((ctx) => fallback(ctx), "fallback");
+	let settled = false;
+	let settledValue;
+	let inFlight;
+	const call = (ctx) => {
+		if (settled) return settledValue;
+		if (inFlight != null) return inFlight;
+		const result = fallback(ctx);
+		if (!isPromiseLike(result)) {
+			settled = true;
+			settledValue = result;
+			return result;
+		}
+		const promise = Promise.resolve(result).then((resolved) => {
+			settled = true;
+			settledValue = resolved;
+			inFlight = void 0;
+			return resolved;
+		}, (error) => {
+			inFlight = void 0;
+			throw error;
+		});
+		inFlight = promise;
+		return promise;
+	};
+	return brandDeferredValue(call, "fallback");
+}
+function deferredValue(parser, fallback, options) {
+	const memoize = options?.memoize ?? false;
+	return map(optional(map(parser, (value) => ({ value }))), (matched) => matched === void 0 ? makeFallbackDeferredValue(fallback, memoize) : makeSpecifiedDeferredValue(matched.value));
+}
+/**
+* Checks whether a value is a {@link DeferredValue} produced by
+* {@link deferredValue}.
+*
+* Useful for tests, generic result walkers, and debugging code that only has an
+* `unknown` value.  In ordinary code the static type already indicates whether a
+* field is a {@link DeferredValue}.
+*
+* @param value The value to check.
+* @returns `true` if `value` is a {@link DeferredValue}.
+* @since 1.2.0
+*/
+function isDeferredValue(value) {
+	return typeof value === "function" && value[deferredValueBrand] === true;
+}
 /**
 * Creates a parser that allows multiple occurrences of a given parser.
 * This parser can be used to parse multiple values of the same type,
@@ -1643,6 +1730,13 @@ function fluent(parser) {
 			},
 			configurable: true,
 			enumerable: false
+		},
+		deferredValue: {
+			value(fallback, options) {
+				return deferredValue(parser, fallback, options);
+			},
+			configurable: true,
+			enumerable: false
 		}
 	});
 	return fluentParser;
@@ -1650,7 +1744,9 @@ function fluent(parser) {
 
 //#endregion
 exports.WithDefaultError = WithDefaultError;
+exports.deferredValue = deferredValue;
 exports.fluent = fluent;
+exports.isDeferredValue = isDeferredValue;
 exports.map = map;
 exports.multiple = multiple;
 exports.nonEmpty = nonEmpty;

package/dist/modifiers.d.cts

@@ -180,6 +180,110 @@ declare function withDefault<M extends Mode, TValue, TState, const TDefault = TV
  * ```
  */
 declare function map<M extends Mode, T, U, TState>(parser: Parser<M, T, TState>, transform: (value: T) => U): FluentParser<M, U, TState>;
+/**
+ * Identifies which branch a {@link DeferredValue} resolved from.
+ *
+ *  -  `"specified"` means the wrapped parser produced a value, whether from
+ *     CLI input or another source such as `bindEnv()`/`bindConfig()`.
+ *  -  `"fallback"` means {@link deferredValue} selected the fallback resolver.
+ *
+ * @since 1.2.0
+ */
+type DeferredValueSource = "specified" | "fallback";
+/**
+ * A handler-time value produced by {@link deferredValue}.
+ *
+ * It is a value-producing function rather than a scalar value.  When the
+ * wrapped parser produced a value, calling it returns that value.  Otherwise
+ * calling it runs the fallback resolver.  The {@link DeferredValue.source}
+ * property tells which branch was selected without invoking the function.
+ *
+ * The call signature returns `T | Promise<T>` regardless of the wrapped
+ * parser's mode, so a synchronous parser may still pair with an asynchronous
+ * fallback resolver.
+ *
+ * @template T The resolved value type.
+ * @template C The handler-time context type passed to the fallback resolver.
+ * @since 1.2.0
+ */
+type DeferredValue<T, C = void> = ([C] extends [void] ? (() => T | Promise<T>) : [undefined] extends [C] ? ((ctx?: C) => T | Promise<T>) : ((ctx: C) => T | Promise<T>)) & {
+  /**
+   * Which branch produced this value: `"specified"` when the wrapped parser
+   * produced a value, `"fallback"` when the fallback resolver was selected.
+   */
+  readonly source: DeferredValueSource;
+};
+/**
+ * Options for {@link deferredValue}.
+ * @since 1.2.0
+ */
+interface DeferredValueOptions {
+  /**
+   * When `true`, a fallback-backed {@link DeferredValue} caches its first
+   * resolved value (or in-flight promise) and reuses it on later calls.
+   * A rejected fallback is not cached, so the next call retries it.  Defaults
+   * to `false`, meaning every call re-runs the fallback resolver.
+   */
+  readonly memoize?: boolean;
+}
+/**
+ * Wraps a parser so its value is resolved by the command handler instead of
+ * during parsing.
+ *
+ * The parsed field becomes a {@link DeferredValue}: a value-producing function.
+ * When the wrapped parser produced a value, calling the function returns that
+ * value and {@link DeferredValue.source} is `"specified"`.  When the wrapped
+ * parser did not produce a value, calling the function runs `fallback` and
+ * `source` is `"fallback"`.  The fallback runs at handler time, so its errors
+ * are handler errors rather than parser errors.  A value that is specified but
+ * invalid still fails during parsing.
+ *
+ * Like {@link optional}, the wrapped parser keeps its place in usage and help;
+ * only the result type changes.  The fallback context type `C` is inferred from
+ * the `fallback` parameter.
+ *
+ * @example
+ * ```typescript
+ * const parser = object({
+ *   serviceName: option("--service-name", string()),
+ *   apiToken: deferredValue(
+ *     option("--api-token", string()),
+ *     ({ serviceName }: { readonly serviceName: string }) =>
+ *       promptForApiToken(serviceName),
+ *   ),
+ * });
+ *
+ * const parsed = parse(parser, argv);
+ * // The prompt only runs if this branch is reached.
+ * const apiToken = await parsed.apiToken({
+ *   serviceName: parsed.serviceName,
+ * });
+ * ```
+ *
+ * @template M The execution mode of the wrapped parser.
+ * @template T The resolved value type.
+ * @template S The state type of the wrapped parser.
+ * @param parser The parser that reads the CLI value.
+ * @param fallback A resolver run at handler time when no value was specified.
+ * @param options Optional {@link DeferredValueOptions}.
+ * @returns A parser whose value is a {@link DeferredValue}.
+ * @since 1.2.0
+ */
+declare function deferredValue<M extends Mode, T, S>(parser: Parser<M, T, S>, fallback: () => T | Promise<T>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<T>, [S] | undefined>;
+declare function deferredValue<M extends Mode, T, S, C>(parser: Parser<M, T, S>, fallback: (ctx: C) => T | Promise<T>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<T, C>, [S] | undefined>;
+/**
+ * Checks whether a value is a {@link DeferredValue} produced by
+ * {@link deferredValue}.
+ *
+ * Useful for tests, generic result walkers, and debugging code that only has an
+ * `unknown` value.  In ordinary code the static type already indicates whether a
+ * field is a {@link DeferredValue}.
+ *
+ * @param value The value to check.
+ * @returns `true` if `value` is a {@link DeferredValue}.
+ * @since 1.2.0
+ */
+declare function isDeferredValue(value: unknown): value is DeferredValue<unknown>;
 /**
  * Options for the {@link multiple} parser.
  */
@@ -306,6 +410,15 @@ interface ParserModifiers<M extends Mode = "sync", TValue = unknown, TState = un
    * @returns A parser that produces this parser's value or the default value.
    */
   withDefault<const TDefault = TValue>(defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): FluentParser<M, TValue | TDefault, [TState] | undefined>;
+  /**
+   * Defers this parser's value so the command handler resolves it.
+   *
+   * @param fallback A resolver run at handler time when no value was specified.
+   * @param options Optional {@link DeferredValueOptions}.
+   * @returns A parser whose value is a {@link DeferredValue}.
+   */
+  deferredValue(fallback: () => TValue | Promise<TValue>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<TValue>, [TState] | undefined>;
+  deferredValue<C>(fallback: (ctx: C) => TValue | Promise<TValue>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<TValue, C>, [TState] | undefined>;
   /**
    * Allows this parser to match multiple times.
    *
@@ -343,4 +456,4 @@ type FluentParser<M extends Mode = "sync", TValue = unknown, TState = unknown> =
  */
 declare function fluent<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>): FluentParser<M, TValue, TState>;
 //#endregion
-export { FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, fluent, map, multiple, nonEmpty, optional, withDefault };
+export { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault };

package/dist/modifiers.d.ts

@@ -180,6 +180,110 @@ declare function withDefault<M extends Mode, TValue, TState, const TDefault = TV
  * ```
  */
 declare function map<M extends Mode, T, U, TState>(parser: Parser<M, T, TState>, transform: (value: T) => U): FluentParser<M, U, TState>;
+/**
+ * Identifies which branch a {@link DeferredValue} resolved from.
+ *
+ *  -  `"specified"` means the wrapped parser produced a value, whether from
+ *     CLI input or another source such as `bindEnv()`/`bindConfig()`.
+ *  -  `"fallback"` means {@link deferredValue} selected the fallback resolver.
+ *
+ * @since 1.2.0
+ */
+type DeferredValueSource = "specified" | "fallback";
+/**
+ * A handler-time value produced by {@link deferredValue}.
+ *
+ * It is a value-producing function rather than a scalar value.  When the
+ * wrapped parser produced a value, calling it returns that value.  Otherwise
+ * calling it runs the fallback resolver.  The {@link DeferredValue.source}
+ * property tells which branch was selected without invoking the function.
+ *
+ * The call signature returns `T | Promise<T>` regardless of the wrapped
+ * parser's mode, so a synchronous parser may still pair with an asynchronous
+ * fallback resolver.
+ *
+ * @template T The resolved value type.
+ * @template C The handler-time context type passed to the fallback resolver.
+ * @since 1.2.0
+ */
+type DeferredValue<T, C = void> = ([C] extends [void] ? (() => T | Promise<T>) : [undefined] extends [C] ? ((ctx?: C) => T | Promise<T>) : ((ctx: C) => T | Promise<T>)) & {
+  /**
+   * Which branch produced this value: `"specified"` when the wrapped parser
+   * produced a value, `"fallback"` when the fallback resolver was selected.
+   */
+  readonly source: DeferredValueSource;
+};
+/**
+ * Options for {@link deferredValue}.
+ * @since 1.2.0
+ */
+interface DeferredValueOptions {
+  /**
+   * When `true`, a fallback-backed {@link DeferredValue} caches its first
+   * resolved value (or in-flight promise) and reuses it on later calls.
+   * A rejected fallback is not cached, so the next call retries it.  Defaults
+   * to `false`, meaning every call re-runs the fallback resolver.
+   */
+  readonly memoize?: boolean;
+}
+/**
+ * Wraps a parser so its value is resolved by the command handler instead of
+ * during parsing.
+ *
+ * The parsed field becomes a {@link DeferredValue}: a value-producing function.
+ * When the wrapped parser produced a value, calling the function returns that
+ * value and {@link DeferredValue.source} is `"specified"`.  When the wrapped
+ * parser did not produce a value, calling the function runs `fallback` and
+ * `source` is `"fallback"`.  The fallback runs at handler time, so its errors
+ * are handler errors rather than parser errors.  A value that is specified but
+ * invalid still fails during parsing.
+ *
+ * Like {@link optional}, the wrapped parser keeps its place in usage and help;
+ * only the result type changes.  The fallback context type `C` is inferred from
+ * the `fallback` parameter.
+ *
+ * @example
+ * ```typescript
+ * const parser = object({
+ *   serviceName: option("--service-name", string()),
+ *   apiToken: deferredValue(
+ *     option("--api-token", string()),
+ *     ({ serviceName }: { readonly serviceName: string }) =>
+ *       promptForApiToken(serviceName),
+ *   ),
+ * });
+ *
+ * const parsed = parse(parser, argv);
+ * // The prompt only runs if this branch is reached.
+ * const apiToken = await parsed.apiToken({
+ *   serviceName: parsed.serviceName,
+ * });
+ * ```
+ *
+ * @template M The execution mode of the wrapped parser.
+ * @template T The resolved value type.
+ * @template S The state type of the wrapped parser.
+ * @param parser The parser that reads the CLI value.
+ * @param fallback A resolver run at handler time when no value was specified.
+ * @param options Optional {@link DeferredValueOptions}.
+ * @returns A parser whose value is a {@link DeferredValue}.
+ * @since 1.2.0
+ */
+declare function deferredValue<M extends Mode, T, S>(parser: Parser<M, T, S>, fallback: () => T | Promise<T>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<T>, [S] | undefined>;
+declare function deferredValue<M extends Mode, T, S, C>(parser: Parser<M, T, S>, fallback: (ctx: C) => T | Promise<T>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<T, C>, [S] | undefined>;
+/**
+ * Checks whether a value is a {@link DeferredValue} produced by
+ * {@link deferredValue}.
+ *
+ * Useful for tests, generic result walkers, and debugging code that only has an
+ * `unknown` value.  In ordinary code the static type already indicates whether a
+ * field is a {@link DeferredValue}.
+ *
+ * @param value The value to check.
+ * @returns `true` if `value` is a {@link DeferredValue}.
+ * @since 1.2.0
+ */
+declare function isDeferredValue(value: unknown): value is DeferredValue<unknown>;
 /**
  * Options for the {@link multiple} parser.
  */
@@ -306,6 +410,15 @@ interface ParserModifiers<M extends Mode = "sync", TValue = unknown, TState = un
    * @returns A parser that produces this parser's value or the default value.
    */
   withDefault<const TDefault = TValue>(defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): FluentParser<M, TValue | TDefault, [TState] | undefined>;
+  /**
+   * Defers this parser's value so the command handler resolves it.
+   *
+   * @param fallback A resolver run at handler time when no value was specified.
+   * @param options Optional {@link DeferredValueOptions}.
+   * @returns A parser whose value is a {@link DeferredValue}.
+   */
+  deferredValue(fallback: () => TValue | Promise<TValue>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<TValue>, [TState] | undefined>;
+  deferredValue<C>(fallback: (ctx: C) => TValue | Promise<TValue>, options?: DeferredValueOptions): FluentParser<M, DeferredValue<TValue, C>, [TState] | undefined>;
   /**
    * Allows this parser to match multiple times.
    *
@@ -343,4 +456,4 @@ type FluentParser<M extends Mode = "sync", TValue = unknown, TState = unknown> =
  */
 declare function fluent<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>): FluentParser<M, TValue, TState>;
 //#endregion
-export { FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, fluent, map, multiple, nonEmpty, optional, withDefault };
+export { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault };

package/dist/modifiers.js

@@ -845,6 +845,93 @@ function map(parser, transform) {
 	}
 	return fluent(mappedParser);
 }
+const deferredValueBrand = Symbol.for("@optique/core/deferredValue");
+/**
+* Brands a value-producing function as a {@link DeferredValue}.
+*
+* The brand is a hidden, non-enumerable symbol so {@link isDeferredValue} can
+* recognize the value while object inspection only sees `source`.  The `source`
+* property is enumerable but readonly and non-configurable.
+*
+* @param call The value-producing function.
+* @param source The branch that produced the value.
+* @returns The same function decorated as a {@link DeferredValue}.
+*/
+function brandDeferredValue(call, source) {
+	Object.defineProperties(call, {
+		[deferredValueBrand]: {
+			value: true,
+			enumerable: false,
+			writable: false,
+			configurable: false
+		},
+		source: {
+			value: source,
+			enumerable: true,
+			writable: false,
+			configurable: false
+		}
+	});
+	return call;
+}
+/**
+* Builds the `"specified"` branch: a function that returns the parsed value
+* and ignores any handler-time context.
+*/
+function makeSpecifiedDeferredValue(value) {
+	return brandDeferredValue((_ctx) => value, "specified");
+}
+/**
+* Builds the `"fallback"` branch: a function that runs the fallback resolver,
+* optionally memoizing the resolved value or in-flight promise.
+*/
+function makeFallbackDeferredValue(fallback, memoize) {
+	if (!memoize) return brandDeferredValue((ctx) => fallback(ctx), "fallback");
+	let settled = false;
+	let settledValue;
+	let inFlight;
+	const call = (ctx) => {
+		if (settled) return settledValue;
+		if (inFlight != null) return inFlight;
+		const result = fallback(ctx);
+		if (!isPromiseLike(result)) {
+			settled = true;
+			settledValue = result;
+			return result;
+		}
+		const promise = Promise.resolve(result).then((resolved) => {
+			settled = true;
+			settledValue = resolved;
+			inFlight = void 0;
+			return resolved;
+		}, (error) => {
+			inFlight = void 0;
+			throw error;
+		});
+		inFlight = promise;
+		return promise;
+	};
+	return brandDeferredValue(call, "fallback");
+}
+function deferredValue(parser, fallback, options) {
+	const memoize = options?.memoize ?? false;
+	return map(optional(map(parser, (value) => ({ value }))), (matched) => matched === void 0 ? makeFallbackDeferredValue(fallback, memoize) : makeSpecifiedDeferredValue(matched.value));
+}
+/**
+* Checks whether a value is a {@link DeferredValue} produced by
+* {@link deferredValue}.
+*
+* Useful for tests, generic result walkers, and debugging code that only has an
+* `unknown` value.  In ordinary code the static type already indicates whether a
+* field is a {@link DeferredValue}.
+*
+* @param value The value to check.
+* @returns `true` if `value` is a {@link DeferredValue}.
+* @since 1.2.0
+*/
+function isDeferredValue(value) {
+	return typeof value === "function" && value[deferredValueBrand] === true;
+}
 /**
 * Creates a parser that allows multiple occurrences of a given parser.
 * This parser can be used to parse multiple values of the same type,
@@ -1643,10 +1730,17 @@ function fluent(parser) {
 			},
 			configurable: true,
 			enumerable: false
+		},
+		deferredValue: {
+			value(fallback, options) {
+				return deferredValue(parser, fallback, options);
+			},
+			configurable: true,
+			enumerable: false
 		}
 	});
 	return fluentParser;
 }
 
 //#endregion
-export { WithDefaultError, fluent, map, multiple, nonEmpty, optional, withDefault };
+export { WithDefaultError, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.2.0-dev.2229",
+  "version": "1.2.0-dev.2232",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -208,7 +208,7 @@
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
-    "@optique/env": "1.2.0-dev.2229+c0eb0d92"
+    "@optique/env": "1.2.0-dev.2232+9fc28f44"
   },
   "scripts": {
     "build": "tsdown",