@optique/core 1.0.0-dev.1596 → 1.0.0-dev.1602

package/dist/dependency-runtime.d.ts

@@ -0,0 +1,123 @@
+import { DependencyRegistryLike } from "./registry-types.js";
+import { ValueParserResult } from "./valueparser.js";
+
+//#region src/dependency-runtime.d.ts
+
+/**
+ * The origin of a dependency source value.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+type DependencyValueOrigin = "cli" | "default" | "config" | "env" | "prompt" | "derived-precomplete";
+/**
+ * A request to resolve one or more dependency values.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface DependencyRequest {
+  /** The dependency source IDs to resolve. */
+  readonly dependencyIds: readonly symbol[];
+  /** Optional default values (one per ID) for missing sources. */
+  readonly defaultValues?: readonly unknown[];
+}
+/**
+ * The result of a dependency resolution request.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface DependencyResolution {
+  /**
+   * - `"resolved"`: all dependency values are available.
+   * - `"partial"`: some are available, some are missing.
+   * - `"missing"`: none are available.
+   */
+  readonly kind: "resolved" | "partial" | "missing";
+  /** The resolved values (one per requested ID, `undefined` for missing). */
+  readonly values: readonly unknown[];
+  /** For each position, whether the value came from a default. */
+  readonly usedDefaults: readonly boolean[];
+}
+/**
+ * A failure that occurred while evaluating a missing-source default.
+ * Returned by `fillMissingSourceDefaults()` so the caller can propagate
+ * the error instead of silently treating the source as absent.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+
+/**
+ * A key for caching replayed parse results.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface ReplayKey {
+  /** Path from root to the parser node. */
+  readonly path: readonly PropertyKey[];
+  /** The raw input string that was parsed. */
+  readonly rawInput: string;
+  /** A stable fingerprint of the dependency values used. */
+  readonly dependencyFingerprint: string;
+  /**
+   * A per-parser identity string that disambiguates different derived
+   * parsers sharing the same path (e.g., alternative branches).
+   * @since 1.0.0
+   */
+  readonly parserFingerprint: string;
+}
+/**
+ * A runtime node representing a child parser's position, metadata, and state.
+ * Used as input to the shared runtime helpers.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+
+/**
+ * Dependency runtime context for centralized dependency resolution.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface DependencyRuntimeContext {
+  /** The underlying registry (for bridge interop). */
+  readonly registry: DependencyRegistryLike;
+  /** Register a source value with its origin. */
+  registerSource(sourceId: symbol, value: unknown, origin: DependencyValueOrigin): void;
+  /** Check if a source has been registered. */
+  hasSource(sourceId: symbol): boolean;
+  /** Get a registered source value. */
+  getSource(sourceId: symbol): unknown;
+  /** Resolve dependency values for a request. */
+  resolveDependencies(request: DependencyRequest): DependencyResolution;
+  /** Get a cached replay result. */
+  getReplayResult(key: ReplayKey): ValueParserResult<unknown> | undefined;
+  /** Cache a replay result. */
+  setReplayResult(key: ReplayKey, result: ValueParserResult<unknown>): void;
+  /**
+   * Mark a source as explicitly failed (user provided input that did
+   * not pass validation).  Derived parsers should not fall back to
+   * defaults for failed sources.
+   */
+  markSourceFailed(sourceId: symbol): void;
+  /**
+   * Check if a source was explicitly attempted but failed validation.
+   */
+  isSourceFailed(sourceId: symbol): boolean;
+  /** Resolve dependencies for suggestions (same semantics as resolve). */
+  getSuggestionDependencies(request: DependencyRequest): DependencyResolution;
+}
+/**
+ * Creates a new {@link DependencyRuntimeContext}.
+ *
+ * @param registry Optional existing registry to wrap for bridge interop.
+ * @returns A new runtime context.
+ * @internal
+ * @since 1.0.0
+ */
+//#endregion
+export { DependencyRuntimeContext };

package/dist/dependency.cjs

@@ -33,6 +33,16 @@ const dependencyIds = Symbol.for("@optique/core/dependency/dependencyIds");
 */
 const defaultValues = Symbol.for("@optique/core/dependency/defaultValues");
 /**
+* A unique symbol used to store the single default value thunk on derived
+* parsers created by {@link DependencySource.derive}.  Unlike
+* {@link defaultValues} (which `createDeferredParseState` reads eagerly),
+* this symbol is only read by the dependency-metadata bridge so that
+* single-source defaults are accessible without double evaluation.
+* @internal
+* @since 1.0.0
+*/
+const singleDefaultValue = Symbol.for("@optique/core/dependency/singleDefaultValue");
+/**
 * A unique symbol used to access the parseWithDependency method on derived parsers.
 * @since 0.10.0
 */
@@ -504,6 +514,7 @@ function createSyncDerivedParser(sourceId, options) {
 		},
 		[derivedValueParserMarker]: true,
 		[dependencyId]: sourceId,
+		[singleDefaultValue]: options.defaultValue,
 		parse(input) {
 			let derivedParser;
 			try {
@@ -596,6 +607,7 @@ function createAsyncDerivedParserFromAsyncFactory(sourceId, options) {
 		},
 		[derivedValueParserMarker]: true,
 		[dependencyId]: sourceId,
+		[singleDefaultValue]: options.defaultValue,
 		parse(input) {
 			let derivedParser;
 			try {
@@ -675,6 +687,7 @@ function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
 		},
 		[derivedValueParserMarker]: true,
 		[dependencyId]: sourceId,
+		[singleDefaultValue]: options.defaultValue,
 		parse(input) {
 			let derivedParser;
 			try {
@@ -999,6 +1012,7 @@ exports.isPendingDependencySourceState = isPendingDependencySourceState;
 exports.isWrappedDependencySource = isWrappedDependencySource;
 exports.parseWithDependency = parseWithDependency;
 exports.pendingDependencySourceStateMarker = pendingDependencySourceStateMarker;
+exports.singleDefaultValue = singleDefaultValue;
 exports.suggestWithDependency = suggestWithDependency;
 exports.transformsDependencyValue = transformsDependencyValue;
 exports.transformsDependencyValueMarker = transformsDependencyValueMarker;

package/dist/dependency.d.cts

@@ -37,6 +37,16 @@ declare const dependencyIds: unique symbol;
  * @since 0.10.0
  */
 declare const defaultValues: unique symbol;
+/**
+ * A unique symbol used to store the single default value thunk on derived
+ * parsers created by {@link DependencySource.derive}.  Unlike
+ * {@link defaultValues} (which `createDeferredParseState` reads eagerly),
+ * this symbol is only read by the dependency-metadata bridge so that
+ * single-source defaults are accessible without double evaluation.
+ * @internal
+ * @since 1.0.0
+ */
+declare const singleDefaultValue: unique symbol;
 /**
  * A unique symbol used to access the parseWithDependency method on derived parsers.
  * @since 0.10.0
@@ -363,6 +373,14 @@ interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown>
    * @internal
    */
   readonly [defaultValues]?: () => readonly unknown[];
+  /**
+   * The single default value thunk for single-source derived parsers.
+   * Read by the dependency-metadata bridge; not consumed by
+   * `createDeferredParseState()`.
+   * @internal
+   * @since 1.0.0
+   */
+  readonly [singleDefaultValue]?: () => S;
   /**
    * Parses the input using the actual dependency value instead of the default.
    * This method is used during dependency resolution in `complete()`.
@@ -791,4 +809,4 @@ type DependencyError = {
  */
 declare function formatDependencyError(error: DependencyError): Message;
 //#endregion
-export { 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 };
+export { 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, singleDefaultValue, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };

package/dist/dependency.d.ts

@@ -37,6 +37,16 @@ declare const dependencyIds: unique symbol;
  * @since 0.10.0
  */
 declare const defaultValues: unique symbol;
+/**
+ * A unique symbol used to store the single default value thunk on derived
+ * parsers created by {@link DependencySource.derive}.  Unlike
+ * {@link defaultValues} (which `createDeferredParseState` reads eagerly),
+ * this symbol is only read by the dependency-metadata bridge so that
+ * single-source defaults are accessible without double evaluation.
+ * @internal
+ * @since 1.0.0
+ */
+declare const singleDefaultValue: unique symbol;
 /**
  * A unique symbol used to access the parseWithDependency method on derived parsers.
  * @since 0.10.0
@@ -363,6 +373,14 @@ interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown>
    * @internal
    */
   readonly [defaultValues]?: () => readonly unknown[];
+  /**
+   * The single default value thunk for single-source derived parsers.
+   * Read by the dependency-metadata bridge; not consumed by
+   * `createDeferredParseState()`.
+   * @internal
+   * @since 1.0.0
+   */
+  readonly [singleDefaultValue]?: () => S;
   /**
    * Parses the input using the actual dependency value instead of the default.
    * This method is used during dependency resolution in `complete()`.
@@ -791,4 +809,4 @@ type DependencyError = {
  */
 declare function formatDependencyError(error: DependencyError): Message;
 //#endregion
-export { 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 };
+export { 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, singleDefaultValue, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };

package/dist/dependency.js

@@ -33,6 +33,16 @@ const dependencyIds = Symbol.for("@optique/core/dependency/dependencyIds");
 */
 const defaultValues = Symbol.for("@optique/core/dependency/defaultValues");
 /**
+* A unique symbol used to store the single default value thunk on derived
+* parsers created by {@link DependencySource.derive}.  Unlike
+* {@link defaultValues} (which `createDeferredParseState` reads eagerly),
+* this symbol is only read by the dependency-metadata bridge so that
+* single-source defaults are accessible without double evaluation.
+* @internal
+* @since 1.0.0
+*/
+const singleDefaultValue = Symbol.for("@optique/core/dependency/singleDefaultValue");
+/**
 * A unique symbol used to access the parseWithDependency method on derived parsers.
 * @since 0.10.0
 */
@@ -504,6 +514,7 @@ function createSyncDerivedParser(sourceId, options) {
 		},
 		[derivedValueParserMarker]: true,
 		[dependencyId]: sourceId,
+		[singleDefaultValue]: options.defaultValue,
 		parse(input) {
 			let derivedParser;
 			try {
@@ -596,6 +607,7 @@ function createAsyncDerivedParserFromAsyncFactory(sourceId, options) {
 		},
 		[derivedValueParserMarker]: true,
 		[dependencyId]: sourceId,
+		[singleDefaultValue]: options.defaultValue,
 		parse(input) {
 			let derivedParser;
 			try {
@@ -675,6 +687,7 @@ function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
 		},
 		[derivedValueParserMarker]: true,
 		[dependencyId]: sourceId,
+		[singleDefaultValue]: options.defaultValue,
 		parse(input) {
 			let derivedParser;
 			try {
@@ -973,4 +986,4 @@ function formatDependencyError(error) {
 }
 
 //#endregion
-export { 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 };
+export { 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, singleDefaultValue, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };

package/dist/index.cjs

@@ -124,6 +124,7 @@ exports.runParserSync = require_facade.runParserSync;
 exports.runWith = require_facade.runWith;
 exports.runWithAsync = require_facade.runWithAsync;
 exports.runWithSync = require_facade.runWithSync;
+exports.singleDefaultValue = require_dependency.singleDefaultValue;
 exports.socketAddress = require_valueparser.socketAddress;
 exports.string = require_valueparser.string;
 exports.suggest = require_parser.suggest;

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/modifiers.cjs

@@ -2,6 +2,7 @@ const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_dependency = require('./dependency.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_dependency_metadata = require('./dependency-metadata.cjs');
 
 //#region src/modifiers.ts
 /**
@@ -186,6 +187,10 @@ function optional(parser) {
 			enumerable: false
 		});
 	}
+	if (parser.dependencyMetadata != null) {
+		const composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "optional");
+		if (composed != null) optionalParser.dependencyMetadata = composed;
+	}
 	return optionalParser;
 }
 /**
@@ -434,6 +439,28 @@ function withDefault(parser, defaultValue, options) {
 			enumerable: false
 		});
 	}
+	if (parser.dependencyMetadata != null) {
+		const composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "withDefault", { defaultValue: () => {
+			let v;
+			try {
+				v = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+			} catch (e) {
+				const error = e instanceof WithDefaultError ? e.errorMessage : require_message.message`${e instanceof Error ? e.message : String(e)}`;
+				return {
+					success: false,
+					error
+				};
+			}
+			if (typeof parser.normalizeValue === "function") try {
+				v = parser.normalizeValue(v);
+			} catch {}
+			return {
+				success: true,
+				value: v
+			};
+		} });
+		if (composed != null) withDefaultParser.dependencyMetadata = composed;
+	}
 	return withDefaultParser;
 }
 /**
@@ -559,6 +586,43 @@ function map(parser, transform) {
 		configurable: true,
 		enumerable: false
 	});
+	if (parser.dependencyMetadata != null) {
+		let composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "map");
+		if (composed?.derived != null) {
+			const innerReplay = composed.derived.replayParse;
+			const applyMappedReplay = (r) => {
+				if (!r.success) return r;
+				if (r.deferred) try {
+					return {
+						success: true,
+						value: transform(r.value),
+						deferred: true
+					};
+				} catch {
+					return {
+						success: true,
+						value: void 0,
+						deferred: true
+					};
+				}
+				return {
+					success: true,
+					value: transform(r.value)
+				};
+			};
+			composed = {
+				...composed,
+				derived: {
+					...composed.derived,
+					replayParse: (rawInput, depValues) => {
+						const result = innerReplay(rawInput, depValues);
+						return result instanceof Promise ? result.then(applyMappedReplay) : applyMappedReplay(result);
+					}
+				}
+			};
+		}
+		if (composed != null) mappedParser.dependencyMetadata = composed;
+	}
 	return mappedParser;
 }
 /**

package/dist/modifiers.js

@@ -2,6 +2,7 @@ import { annotateFreshArray, getAnnotations, inheritAnnotations, isInjectedAnnot
 import { formatMessage, message, text } from "./message.js";
 import { createDependencySourceState, dependencyId, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue } from "./mode-dispatch.js";
+import { composeDependencyMetadata } from "./dependency-metadata.js";
 
 //#region src/modifiers.ts
 /**
@@ -186,6 +187,10 @@ function optional(parser) {
 			enumerable: false
 		});
 	}
+	if (parser.dependencyMetadata != null) {
+		const composed = composeDependencyMetadata(parser.dependencyMetadata, "optional");
+		if (composed != null) optionalParser.dependencyMetadata = composed;
+	}
 	return optionalParser;
 }
 /**
@@ -434,6 +439,28 @@ function withDefault(parser, defaultValue, options) {
 			enumerable: false
 		});
 	}
+	if (parser.dependencyMetadata != null) {
+		const composed = composeDependencyMetadata(parser.dependencyMetadata, "withDefault", { defaultValue: () => {
+			let v;
+			try {
+				v = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+			} catch (e) {
+				const error = e instanceof WithDefaultError ? e.errorMessage : message`${e instanceof Error ? e.message : String(e)}`;
+				return {
+					success: false,
+					error
+				};
+			}
+			if (typeof parser.normalizeValue === "function") try {
+				v = parser.normalizeValue(v);
+			} catch {}
+			return {
+				success: true,
+				value: v
+			};
+		} });
+		if (composed != null) withDefaultParser.dependencyMetadata = composed;
+	}
 	return withDefaultParser;
 }
 /**
@@ -559,6 +586,43 @@ function map(parser, transform) {
 		configurable: true,
 		enumerable: false
 	});
+	if (parser.dependencyMetadata != null) {
+		let composed = composeDependencyMetadata(parser.dependencyMetadata, "map");
+		if (composed?.derived != null) {
+			const innerReplay = composed.derived.replayParse;
+			const applyMappedReplay = (r) => {
+				if (!r.success) return r;
+				if (r.deferred) try {
+					return {
+						success: true,
+						value: transform(r.value),
+						deferred: true
+					};
+				} catch {
+					return {
+						success: true,
+						value: void 0,
+						deferred: true
+					};
+				}
+				return {
+					success: true,
+					value: transform(r.value)
+				};
+			};
+			composed = {
+				...composed,
+				derived: {
+					...composed.derived,
+					replayParse: (rawInput, depValues) => {
+						const result = innerReplay(rawInput, depValues);
+						return result instanceof Promise ? result.then(applyMappedReplay) : applyMappedReplay(result);
+					}
+				}
+			};
+		}
+		if (composed != null) mappedParser.dependencyMetadata = composed;
+	}
 	return mappedParser;
 }
 /**

package/dist/parser.d.cts

@@ -4,6 +4,8 @@ import { Usage } from "./usage.cjs";
 import { DocFragments, DocPage } from "./doc.cjs";
 import { DependencyRegistryLike } from "./registry-types.cjs";
 import { DeferredMap, ValueParserResult } from "./valueparser.cjs";
+import { ParserDependencyMetadata } from "./dependency-metadata.cjs";
+import { DependencyRuntimeContext } from "./dependency-runtime.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.cjs";
@@ -251,6 +253,14 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   normalizeValue?(value: TValue): TValue;
+  /**
+   * Internal dependency metadata describing this parser's dependency
+   * capabilities.  Used by the dependency runtime to resolve dependencies
+   * without relying on state-shape protocols.
+   * @internal
+   * @since 1.0.0
+   */
+  readonly dependencyMetadata?: ParserDependencyMetadata;
 }
 /**
  * Parser-local frame data containing the input buffer and parser state.
@@ -308,6 +318,13 @@ interface ExecutionContext {
    * @since 0.10.0
    */
   readonly dependencyRegistry?: DependencyRegistryLike;
+  /**
+   * The dependency runtime context for dependency resolution.
+   * Coexists with `dependencyRegistry` during the transition period.
+   * @internal
+   * @since 1.0.0
+   */
+  readonly dependencyRuntime?: DependencyRuntimeContext;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.