@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/index.cjs

@@ -1,64 +1,58 @@
-const require_annotations = require('./annotations.cjs');
+const require_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
 const require_completion = require('./completion.cjs');
-const require_dependency = require('./dependency.cjs');
 const require_usage = require('./usage.cjs');
-const require_constructs = require('./constructs.cjs');
 const require_doc = require('./doc.cjs');
+const require_dependency = require('./internal/dependency.cjs');
+const require_parser = require('./internal/parser.cjs');
+const require_constructs = require('./constructs.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_nonempty = require('./nonempty.cjs');
 const require_valueparser = require('./valueparser.cjs');
 const require_primitives = require('./primitives.cjs');
-const require_parser = require('./parser.cjs');
 const require_facade = require('./facade.cjs');
 
-exports.DependencyRegistry = require_dependency.DependencyRegistry;
 exports.DuplicateOptionError = require_constructs.DuplicateOptionError;
 exports.RunParserError = require_facade.RunParserError;
 exports.WithDefaultError = require_modifiers.WithDefaultError;
-exports.annotationKey = require_annotations.annotationKey;
 exports.argument = require_primitives.argument;
 exports.bash = require_completion.bash;
+exports.checkBooleanOption = require_valueparser.checkBooleanOption;
+exports.checkEnumOption = require_valueparser.checkEnumOption;
 exports.choice = require_valueparser.choice;
 exports.cidr = require_valueparser.cidr;
+exports.cloneDocEntry = require_doc.cloneDocEntry;
+exports.cloneUsage = require_usage.cloneUsage;
+exports.cloneUsageTerm = require_usage.cloneUsageTerm;
 exports.command = require_primitives.command;
 exports.commandLine = require_message.commandLine;
 exports.concat = require_constructs.concat;
 exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
-exports.createDeferredParseState = require_dependency.createDeferredParseState;
-exports.createDependencySourceState = require_dependency.createDependencySourceState;
-exports.createPendingDependencySourceState = require_dependency.createPendingDependencySourceState;
-exports.defaultValues = require_dependency.defaultValues;
-exports.deferredParseMarker = require_dependency.deferredParseMarker;
+exports.createParserContext = require_parser.createParserContext;
+exports.deduplicateDocEntries = require_doc.deduplicateDocEntries;
+exports.deduplicateDocFragments = require_doc.deduplicateDocFragments;
 exports.dependency = require_dependency.dependency;
-exports.dependencyId = require_dependency.dependencyId;
-exports.dependencyIds = require_dependency.dependencyIds;
-exports.dependencySourceMarker = require_dependency.dependencySourceMarker;
-exports.dependencySourceStateMarker = require_dependency.dependencySourceStateMarker;
 exports.deriveFrom = require_dependency.deriveFrom;
 exports.deriveFromAsync = require_dependency.deriveFromAsync;
 exports.deriveFromSync = require_dependency.deriveFromSync;
-exports.derivedValueParserMarker = require_dependency.derivedValueParserMarker;
 exports.domain = require_valueparser.domain;
 exports.email = require_valueparser.email;
 exports.ensureNonEmptyString = require_nonempty.ensureNonEmptyString;
 exports.envVar = require_message.envVar;
 exports.extractArgumentMetavars = require_usage.extractArgumentMetavars;
 exports.extractCommandNames = require_usage.extractCommandNames;
+exports.extractLiteralValues = require_usage.extractLiteralValues;
 exports.extractOptionNames = require_usage.extractOptionNames;
 exports.fail = require_primitives.fail;
 exports.fish = require_completion.fish;
 exports.flag = require_primitives.flag;
 exports.float = require_valueparser.float;
-exports.formatDependencyError = require_dependency.formatDependencyError;
 exports.formatDocPage = require_doc.formatDocPage;
 exports.formatMessage = require_message.formatMessage;
 exports.formatUsage = require_usage.formatUsage;
 exports.formatUsageTerm = require_usage.formatUsageTerm;
 exports.getAnnotations = require_annotations.getAnnotations;
-exports.getDefaultValuesFunction = require_dependency.getDefaultValuesFunction;
-exports.getDependencyIds = require_dependency.getDependencyIds;
 exports.getDocPage = require_parser.getDocPage;
 exports.getDocPageAsync = require_parser.getDocPageAsync;
 exports.getDocPageSync = require_parser.getDocPageSync;
@@ -68,17 +62,14 @@ exports.integer = require_valueparser.integer;
 exports.ip = require_valueparser.ip;
 exports.ipv4 = require_valueparser.ipv4;
 exports.ipv6 = require_valueparser.ipv6;
-exports.isDeferredParseState = require_dependency.isDeferredParseState;
 exports.isDependencySource = require_dependency.isDependencySource;
-exports.isDependencySourceState = require_dependency.isDependencySourceState;
 exports.isDerivedValueParser = require_dependency.isDerivedValueParser;
+exports.isDocEntryHidden = require_doc.isDocEntryHidden;
 exports.isDocHidden = require_usage.isDocHidden;
 exports.isNonEmptyString = require_nonempty.isNonEmptyString;
-exports.isPendingDependencySourceState = require_dependency.isPendingDependencySourceState;
 exports.isSuggestionHidden = require_usage.isSuggestionHidden;
 exports.isUsageHidden = require_usage.isUsageHidden;
 exports.isValueParser = require_valueparser.isValueParser;
-exports.isWrappedDependencySource = require_dependency.isWrappedDependencySource;
 exports.lineBreak = require_message.lineBreak;
 exports.link = require_message.link;
 exports.locale = require_valueparser.locale;
@@ -102,9 +93,7 @@ exports.or = require_constructs.or;
 exports.parse = require_parser.parse;
 exports.parseAsync = require_parser.parseAsync;
 exports.parseSync = require_parser.parseSync;
-exports.parseWithDependency = require_dependency.parseWithDependency;
 exports.passThrough = require_primitives.passThrough;
-exports.pendingDependencySourceStateMarker = require_dependency.pendingDependencySourceStateMarker;
 exports.port = require_valueparser.port;
 exports.portRange = require_valueparser.portRange;
 exports.pwsh = require_completion.pwsh;
@@ -119,10 +108,7 @@ exports.string = require_valueparser.string;
 exports.suggest = require_parser.suggest;
 exports.suggestAsync = require_parser.suggestAsync;
 exports.suggestSync = require_parser.suggestSync;
-exports.suggestWithDependency = require_dependency.suggestWithDependency;
 exports.text = require_message.text;
-exports.transformsDependencyValue = require_dependency.transformsDependencyValue;
-exports.transformsDependencyValueMarker = require_dependency.transformsDependencyValueMarker;
 exports.tuple = require_constructs.tuple;
 exports.url = require_valueparser.url;
 exports.uuid = require_valueparser.uuid;
@@ -130,5 +116,4 @@ exports.value = require_message.value;
 exports.valueSet = require_message.valueSet;
 exports.values = require_message.values;
 exports.withDefault = require_modifiers.withDefault;
-exports.wrappedDependencySourceMarker = require_dependency.wrappedDependencySourceMarker;
 exports.zsh = require_completion.zsh;

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/input-trace.cjs

@@ -0,0 +1,56 @@
+
+//#region src/input-trace.ts
+const symbolKeys = /* @__PURE__ */ new WeakMap();
+let symbolCounter = 0;
+/** Length-prefix a raw segment so that no delimiter escaping is needed. */
+function lengthPrefix(s) {
+	return `${s.length}:${s}`;
+}
+function serializeKey(key) {
+	if (typeof key === "string") return lengthPrefix(`s${key}`);
+	if (typeof key === "number") return lengthPrefix(`n${key}`);
+	const registeredKey = Symbol.keyFor(key);
+	if (registeredKey !== void 0) return lengthPrefix(`r${registeredKey}`);
+	let id = symbolKeys.get(key);
+	if (id === void 0) {
+		id = `y${symbolCounter++}`;
+		symbolKeys.set(key, id);
+	}
+	return lengthPrefix(id);
+}
+function serializePath(path) {
+	if (path.length === 0) return "";
+	return path.map(serializeKey).join("");
+}
+var InputTraceImpl = class InputTraceImpl {
+	#entries;
+	constructor(entries) {
+		this.#entries = entries ?? /* @__PURE__ */ new Map();
+	}
+	get(path) {
+		return this.#entries.get(serializePath(path));
+	}
+	set(path, entry) {
+		const copy = new Map(this.#entries);
+		copy.set(serializePath(path), entry);
+		return new InputTraceImpl(copy);
+	}
+	delete(path) {
+		const copy = new Map(this.#entries);
+		copy.delete(serializePath(path));
+		return new InputTraceImpl(copy);
+	}
+};
+/**
+* Creates a new empty {@link InputTrace}.
+*
+* @returns An empty immutable input trace.
+* @internal
+* @since 1.0.0
+*/
+function createInputTrace() {
+	return new InputTraceImpl();
+}
+
+//#endregion
+exports.createInputTrace = createInputTrace;

package/dist/input-trace.d.cts

@@ -0,0 +1,77 @@
+import { ValueParserResult } from "./valueparser.cjs";
+
+//#region src/input-trace.d.ts
+
+/**
+ * A replayable record of raw input consumed by a single parser node.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface TraceEntry {
+  /** The kind of input that was consumed. */
+  readonly kind: "option-value" | "argument-value" | "literal" | "custom";
+  /** The raw input string to be replayed. */
+  readonly rawInput: string;
+  /** The tokens consumed from the buffer. */
+  readonly consumed: readonly string[];
+  /** The preliminary parse result using default dependency values. */
+  readonly preliminaryResult?: ValueParserResult<unknown>;
+  /**
+   * Snapshotted default dependency values captured during parse.
+   *
+   * Present when a derived parser snapshots default dependency values during
+   * parse, including both `derive()` and `deriveFrom()` parsers.
+   * This avoids re-evaluating dynamic default thunks during replay.
+   */
+  readonly defaultDependencyValues?: readonly unknown[];
+  /** The option names that matched (e.g., `["--env", "-e"]`). */
+  readonly optionNames?: readonly string[];
+  /** The metavar of the value parser. */
+  readonly metavar?: string;
+}
+/**
+ * An immutable, path-keyed store of {@link TraceEntry} records.
+ *
+ * Each entry is keyed by a path of `PropertyKey` segments (strings, numbers,
+ * or symbols) corresponding to the position of the parser in the parse tree.
+ *
+ * All mutation methods return a new `InputTrace` instance; the original is
+ * never modified.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface InputTrace {
+  /**
+   * Retrieves the trace entry at the given path.
+   *
+   * @param path The path segments identifying the entry.
+   * @returns The entry, or `undefined` if no entry exists at that path.
+   */
+  get(path: readonly PropertyKey[]): TraceEntry | undefined;
+  /**
+   * Returns a new trace with the entry set at the given path.
+   *
+   * @param path The path segments identifying the entry.
+   * @param entry The trace entry to store.
+   * @returns A new `InputTrace` with the entry stored.
+   */
+  set(path: readonly PropertyKey[], entry: TraceEntry): InputTrace;
+  /**
+   * Returns a new trace with the entry at the given path removed.
+   *
+   * @param path The path segments identifying the entry to remove.
+   * @returns A new `InputTrace` without the entry.
+   */
+  delete(path: readonly PropertyKey[]): InputTrace;
+}
+/**
+ * Creates a new empty {@link InputTrace}.
+ *
+ * @returns An empty immutable input trace.
+ * @internal
+ * @since 1.0.0
+ */
+//#endregion
+export { InputTrace };

package/dist/input-trace.d.ts

@@ -0,0 +1,77 @@
+import { ValueParserResult } from "./valueparser.js";
+
+//#region src/input-trace.d.ts
+
+/**
+ * A replayable record of raw input consumed by a single parser node.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface TraceEntry {
+  /** The kind of input that was consumed. */
+  readonly kind: "option-value" | "argument-value" | "literal" | "custom";
+  /** The raw input string to be replayed. */
+  readonly rawInput: string;
+  /** The tokens consumed from the buffer. */
+  readonly consumed: readonly string[];
+  /** The preliminary parse result using default dependency values. */
+  readonly preliminaryResult?: ValueParserResult<unknown>;
+  /**
+   * Snapshotted default dependency values captured during parse.
+   *
+   * Present when a derived parser snapshots default dependency values during
+   * parse, including both `derive()` and `deriveFrom()` parsers.
+   * This avoids re-evaluating dynamic default thunks during replay.
+   */
+  readonly defaultDependencyValues?: readonly unknown[];
+  /** The option names that matched (e.g., `["--env", "-e"]`). */
+  readonly optionNames?: readonly string[];
+  /** The metavar of the value parser. */
+  readonly metavar?: string;
+}
+/**
+ * An immutable, path-keyed store of {@link TraceEntry} records.
+ *
+ * Each entry is keyed by a path of `PropertyKey` segments (strings, numbers,
+ * or symbols) corresponding to the position of the parser in the parse tree.
+ *
+ * All mutation methods return a new `InputTrace` instance; the original is
+ * never modified.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface InputTrace {
+  /**
+   * Retrieves the trace entry at the given path.
+   *
+   * @param path The path segments identifying the entry.
+   * @returns The entry, or `undefined` if no entry exists at that path.
+   */
+  get(path: readonly PropertyKey[]): TraceEntry | undefined;
+  /**
+   * Returns a new trace with the entry set at the given path.
+   *
+   * @param path The path segments identifying the entry.
+   * @param entry The trace entry to store.
+   * @returns A new `InputTrace` with the entry stored.
+   */
+  set(path: readonly PropertyKey[], entry: TraceEntry): InputTrace;
+  /**
+   * Returns a new trace with the entry at the given path removed.
+   *
+   * @param path The path segments identifying the entry to remove.
+   * @returns A new `InputTrace` without the entry.
+   */
+  delete(path: readonly PropertyKey[]): InputTrace;
+}
+/**
+ * Creates a new empty {@link InputTrace}.
+ *
+ * @returns An empty immutable input trace.
+ * @internal
+ * @since 1.0.0
+ */
+//#endregion
+export { InputTrace };

package/dist/input-trace.js

@@ -0,0 +1,55 @@
+//#region src/input-trace.ts
+const symbolKeys = /* @__PURE__ */ new WeakMap();
+let symbolCounter = 0;
+/** Length-prefix a raw segment so that no delimiter escaping is needed. */
+function lengthPrefix(s) {
+	return `${s.length}:${s}`;
+}
+function serializeKey(key) {
+	if (typeof key === "string") return lengthPrefix(`s${key}`);
+	if (typeof key === "number") return lengthPrefix(`n${key}`);
+	const registeredKey = Symbol.keyFor(key);
+	if (registeredKey !== void 0) return lengthPrefix(`r${registeredKey}`);
+	let id = symbolKeys.get(key);
+	if (id === void 0) {
+		id = `y${symbolCounter++}`;
+		symbolKeys.set(key, id);
+	}
+	return lengthPrefix(id);
+}
+function serializePath(path) {
+	if (path.length === 0) return "";
+	return path.map(serializeKey).join("");
+}
+var InputTraceImpl = class InputTraceImpl {
+	#entries;
+	constructor(entries) {
+		this.#entries = entries ?? /* @__PURE__ */ new Map();
+	}
+	get(path) {
+		return this.#entries.get(serializePath(path));
+	}
+	set(path, entry) {
+		const copy = new Map(this.#entries);
+		copy.set(serializePath(path), entry);
+		return new InputTraceImpl(copy);
+	}
+	delete(path) {
+		const copy = new Map(this.#entries);
+		copy.delete(serializePath(path));
+		return new InputTraceImpl(copy);
+	}
+};
+/**
+* Creates a new empty {@link InputTrace}.
+*
+* @returns An empty immutable input trace.
+* @internal
+* @since 1.0.0
+*/
+function createInputTrace() {
+	return new InputTraceImpl();
+}
+
+//#endregion
+export { createInputTrace };