@optique/core 1.1.0-dev.2087 → 1.1.0-dev.2146

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/dist/annotation-state.cjs +26 -26
  2. package/dist/annotation-state.d.cts +133 -1
  3. package/dist/annotation-state.d.ts +133 -1
  4. package/dist/annotations.cjs +2 -2
  5. package/dist/constructs.cjs +873 -73
  6. package/dist/constructs.d.cts +72 -1
  7. package/dist/constructs.d.ts +72 -1
  8. package/dist/constructs.js +808 -9
  9. package/dist/dependency-metadata.cjs +12 -12
  10. package/dist/dependency-metadata.d.cts +34 -3
  11. package/dist/dependency-metadata.d.ts +34 -3
  12. package/dist/dependency-runtime.cjs +37 -13
  13. package/dist/dependency-runtime.d.cts +197 -2
  14. package/dist/dependency-runtime.d.ts +197 -2
  15. package/dist/dependency-runtime.js +22 -1
  16. package/dist/dependency.cjs +7 -7
  17. package/dist/displaywidth.d.cts +12 -0
  18. package/dist/displaywidth.d.ts +12 -0
  19. package/dist/doc.cjs +3 -0
  20. package/dist/doc.js +3 -0
  21. package/dist/execution-context.d.cts +23 -0
  22. package/dist/execution-context.d.ts +23 -0
  23. package/dist/extension.cjs +14 -14
  24. package/dist/facade.cjs +49 -37
  25. package/dist/facade.js +34 -22
  26. package/dist/index.cjs +23 -21
  27. package/dist/index.d.cts +3 -3
  28. package/dist/index.d.ts +3 -3
  29. package/dist/index.js +4 -4
  30. package/dist/input-trace.d.cts +2 -1
  31. package/dist/input-trace.d.ts +2 -1
  32. package/dist/internal/annotations.cjs +3 -0
  33. package/dist/internal/annotations.d.cts +47 -5
  34. package/dist/internal/annotations.d.ts +47 -5
  35. package/dist/internal/annotations.js +1 -1
  36. package/dist/internal/command-alias.cjs +16 -0
  37. package/dist/internal/command-alias.js +14 -0
  38. package/dist/internal/dependency.cjs +131 -0
  39. package/dist/internal/dependency.d.cts +311 -2
  40. package/dist/internal/dependency.d.ts +311 -2
  41. package/dist/internal/dependency.js +119 -1
  42. package/dist/internal/parser.cjs +108 -23
  43. package/dist/internal/parser.d.cts +58 -3
  44. package/dist/internal/parser.d.ts +58 -3
  45. package/dist/internal/parser.js +101 -16
  46. package/dist/modifiers.cjs +74 -44
  47. package/dist/modifiers.js +34 -4
  48. package/dist/parser.cjs +11 -11
  49. package/dist/phase2-seed.cjs +2 -2
  50. package/dist/phase2-seed.d.cts +50 -0
  51. package/dist/phase2-seed.d.ts +50 -0
  52. package/dist/primitives.cjs +104 -33
  53. package/dist/primitives.d.cts +10 -0
  54. package/dist/primitives.d.ts +10 -0
  55. package/dist/primitives.js +84 -13
  56. package/dist/suggestion.cjs +72 -2
  57. package/dist/suggestion.d.cts +188 -0
  58. package/dist/suggestion.d.ts +188 -0
  59. package/dist/suggestion.js +71 -3
  60. package/dist/usage-internals.cjs +14 -6
  61. package/dist/usage-internals.js +14 -6
  62. package/dist/usage.cjs +33 -8
  63. package/dist/usage.d.cts +31 -0
  64. package/dist/usage.d.ts +31 -0
  65. package/dist/usage.js +33 -8
  66. package/dist/validate.cjs +1 -0
  67. package/dist/validate.d.cts +99 -0
  68. package/dist/validate.d.ts +99 -0
  69. package/dist/validate.js +1 -1
  70. package/dist/valueparser.cjs +333 -79
  71. package/dist/valueparser.d.cts +197 -1
  72. package/dist/valueparser.d.ts +197 -1
  73. package/dist/valueparser.js +334 -81
  74. package/package.json +19 -4
@@ -1,4 +1,4 @@
1
- const require_dependency = require('./internal/dependency.cjs');
1
+ const require_internal_dependency = require('./internal/dependency.cjs');
2
2
 
3
3
  //#region src/dependency-metadata.ts
4
4
  /**
@@ -14,27 +14,27 @@ const require_dependency = require('./internal/dependency.cjs');
14
14
  * @since 1.0.0
15
15
  */
16
16
  function extractDependencyMetadata(valueParser) {
17
- if (require_dependency.isDependencySource(valueParser)) return { source: {
17
+ if (require_internal_dependency.isDependencySource(valueParser)) return { source: {
18
18
  kind: "source",
19
- sourceId: valueParser[require_dependency.dependencyId],
19
+ sourceId: valueParser[require_internal_dependency.dependencyId],
20
20
  extractSourceValue: extractFromBareState,
21
21
  preservesSourceValue: true
22
22
  } };
23
- if (require_dependency.isDerivedValueParser(valueParser)) {
24
- const isMultiSource = require_dependency.dependencyIds in valueParser && valueParser[require_dependency.dependencyIds] != null;
25
- const allIds = isMultiSource ? valueParser[require_dependency.dependencyIds] : [valueParser[require_dependency.dependencyId]];
23
+ if (require_internal_dependency.isDerivedValueParser(valueParser)) {
24
+ const isMultiSource = require_internal_dependency.dependencyIds in valueParser && valueParser[require_internal_dependency.dependencyIds] != null;
25
+ const allIds = isMultiSource ? valueParser[require_internal_dependency.dependencyIds] : [valueParser[require_internal_dependency.dependencyId]];
26
26
  let defaultValuesFn;
27
- if (require_dependency.defaultValues in valueParser && valueParser[require_dependency.defaultValues] != null) defaultValuesFn = valueParser[require_dependency.defaultValues];
28
- else if (require_dependency.singleDefaultValue in valueParser && valueParser[require_dependency.singleDefaultValue] != null) {
29
- const singleFn = valueParser[require_dependency.singleDefaultValue];
27
+ if (require_internal_dependency.defaultValues in valueParser && valueParser[require_internal_dependency.defaultValues] != null) defaultValuesFn = valueParser[require_internal_dependency.defaultValues];
28
+ else if (require_internal_dependency.singleDefaultValue in valueParser && valueParser[require_internal_dependency.singleDefaultValue] != null) {
29
+ const singleFn = valueParser[require_internal_dependency.singleDefaultValue];
30
30
  defaultValuesFn = () => [singleFn()];
31
31
  }
32
32
  const parser = valueParser;
33
33
  const replayParse = (rawInput, depValues) => {
34
34
  const depArg = isMultiSource ? depValues : depValues[0];
35
- return parser[require_dependency.parseWithDependency](rawInput, depArg);
35
+ return parser[require_internal_dependency.parseWithDependency](rawInput, depArg);
36
36
  };
37
- const suggestFn = require_dependency.suggestWithDependency in parser ? parser[require_dependency.suggestWithDependency] : void 0;
37
+ const suggestFn = require_internal_dependency.suggestWithDependency in parser ? parser[require_internal_dependency.suggestWithDependency] : void 0;
38
38
  const replaySuggest = suggestFn != null ? (prefix, depValues) => {
39
39
  const depArg = isMultiSource ? depValues : depValues[0];
40
40
  return suggestFn(prefix, depArg);
@@ -58,7 +58,7 @@ function extractDependencyMetadata(valueParser) {
58
58
  * dependency sources.
59
59
  */
60
60
  function extractFromBareState(state) {
61
- if (require_dependency.isDependencySourceState(state)) return state.result;
61
+ if (require_internal_dependency.isDependencySourceState(state)) return state.result;
62
62
  if (state != null && typeof state === "object" && Object.hasOwn(state, "success") && typeof state.success === "boolean" && (state.success && Object.hasOwn(state, "value") || !state.success && Object.hasOwn(state, "error"))) return state;
63
63
  return void 0;
64
64
  }
@@ -1,5 +1,5 @@
1
- import { ValueParserResult } from "./valueparser.cjs";
2
- import { Suggestion } from "./internal/parser.cjs";
1
+ import { ValueParser, ValueParserResult } from "./valueparser.cjs";
2
+ import { Mode, Suggestion } from "./internal/parser.cjs";
3
3
 
4
4
  //#region src/dependency-metadata.d.ts
5
5
 
@@ -108,5 +108,36 @@ interface ParserDependencyMetadata {
108
108
  * @internal
109
109
  * @since 1.0.0
110
110
  */
111
+ declare function extractDependencyMetadata<M extends Mode, T>(valueParser: ValueParser<M, T>): ParserDependencyMetadata | undefined;
112
+ /**
113
+ * Options for `composeDependencyMetadata` when the wrapper kind is
114
+ * `"withDefault"`.
115
+ *
116
+ * @internal
117
+ * @since 1.0.0
118
+ */
119
+ interface WithDefaultCompositionOptions {
120
+ /** Thunk returning the default value as a `ValueParserResult`. */
121
+ readonly defaultValue: () => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
122
+ }
123
+ /**
124
+ * Composes dependency metadata through a modifier wrapper.
125
+ *
126
+ * - `"optional"`: composes `extractSourceValue` with array unwrapping.
127
+ * - `"withDefault"`: adds `getMissingSourceValue` if the inner parser
128
+ * preserves a dependency source.
129
+ * - `"map"`: sets `transformsSourceValue` and clears
130
+ * `preservesSourceValue`.
131
+ *
132
+ * Returns `undefined` if `inner` is `undefined`.
133
+ *
134
+ * @param inner The inner parser's metadata.
135
+ * @param wrapperKind The type of modifier being applied.
136
+ * @param options Additional options for certain wrapper kinds.
137
+ * @returns Composed metadata, or `undefined`.
138
+ * @internal
139
+ * @since 1.0.0
140
+ */
141
+ declare function composeDependencyMetadata(inner: ParserDependencyMetadata | undefined, wrapperKind: "optional" | "withDefault" | "map", options?: WithDefaultCompositionOptions): ParserDependencyMetadata | undefined;
111
142
  //#endregion
112
- export { ParserDependencyMetadata };
143
+ export { DependencySourceCapability, DependencyTransformCapability, DerivedDependencyCapability, ParserDependencyMetadata, WithDefaultCompositionOptions, composeDependencyMetadata, extractDependencyMetadata };
@@ -1,5 +1,5 @@
1
- import { ValueParserResult } from "./valueparser.js";
2
- import { Suggestion } from "./internal/parser.js";
1
+ import { ValueParser, ValueParserResult } from "./valueparser.js";
2
+ import { Mode, Suggestion } from "./internal/parser.js";
3
3
 
4
4
  //#region src/dependency-metadata.d.ts
5
5
 
@@ -108,5 +108,36 @@ interface ParserDependencyMetadata {
108
108
  * @internal
109
109
  * @since 1.0.0
110
110
  */
111
+ declare function extractDependencyMetadata<M extends Mode, T>(valueParser: ValueParser<M, T>): ParserDependencyMetadata | undefined;
112
+ /**
113
+ * Options for `composeDependencyMetadata` when the wrapper kind is
114
+ * `"withDefault"`.
115
+ *
116
+ * @internal
117
+ * @since 1.0.0
118
+ */
119
+ interface WithDefaultCompositionOptions {
120
+ /** Thunk returning the default value as a `ValueParserResult`. */
121
+ readonly defaultValue: () => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
122
+ }
123
+ /**
124
+ * Composes dependency metadata through a modifier wrapper.
125
+ *
126
+ * - `"optional"`: composes `extractSourceValue` with array unwrapping.
127
+ * - `"withDefault"`: adds `getMissingSourceValue` if the inner parser
128
+ * preserves a dependency source.
129
+ * - `"map"`: sets `transformsSourceValue` and clears
130
+ * `preservesSourceValue`.
131
+ *
132
+ * Returns `undefined` if `inner` is `undefined`.
133
+ *
134
+ * @param inner The inner parser's metadata.
135
+ * @param wrapperKind The type of modifier being applied.
136
+ * @param options Additional options for certain wrapper kinds.
137
+ * @returns Composed metadata, or `undefined`.
138
+ * @internal
139
+ * @since 1.0.0
140
+ */
141
+ declare function composeDependencyMetadata(inner: ParserDependencyMetadata | undefined, wrapperKind: "optional" | "withDefault" | "map", options?: WithDefaultCompositionOptions): ParserDependencyMetadata | undefined;
111
142
  //#endregion
112
- export { ParserDependencyMetadata };
143
+ export { DependencySourceCapability, DependencyTransformCapability, DerivedDependencyCapability, ParserDependencyMetadata, WithDefaultCompositionOptions, composeDependencyMetadata, extractDependencyMetadata };
@@ -1,6 +1,6 @@
1
1
  const require_message = require('./message.cjs');
2
- const require_dependency = require('./internal/dependency.cjs');
3
- const require_parser = require('./internal/parser.cjs');
2
+ const require_internal_dependency = require('./internal/dependency.cjs');
3
+ const require_internal_parser = require('./internal/parser.cjs');
4
4
 
5
5
  //#region src/dependency-runtime.ts
6
6
  const symbolIds = /* @__PURE__ */ new WeakMap();
@@ -457,6 +457,27 @@ async function replayDerivedParserAsync(node, rawInput, runtime) {
457
457
  return result;
458
458
  }
459
459
  /**
460
+ * Extracts `rawInput` from a parser state that may contain a
461
+ * {@link DeferredParseState}. During the transition period, primitives
462
+ * still produce `DeferredParseState` with `rawInput`.
463
+ *
464
+ * Handles direct `DeferredParseState` and array-wrapped
465
+ * `[DeferredParseState]` (from optional/withDefault wrappers).
466
+ *
467
+ * @param state The parser state to inspect.
468
+ * @returns The raw input string, or `undefined` if the state does not
469
+ * contain a `DeferredParseState`.
470
+ * @internal
471
+ * @since 1.0.0
472
+ */
473
+ function extractRawInputFromState(state) {
474
+ if (state == null) return void 0;
475
+ if (typeof state !== "object") return void 0;
476
+ if (require_internal_dependency.isDeferredParseState(state)) return state.rawInput;
477
+ if (Array.isArray(state) && state.length === 1 && require_internal_dependency.isDeferredParseState(state[0])) return state[0].rawInput;
478
+ return void 0;
479
+ }
480
+ /**
460
481
  * Checks if a value is a plain object (not a class instance) for the
461
482
  * purpose of recursive state traversal.
462
483
  */
@@ -481,7 +502,7 @@ function resolveSingleDeferred(deferred, runtime) {
481
502
  if (resolution.kind !== "resolved") return deferred.preliminaryResult;
482
503
  if (resolution.usedDefaults.every((d) => d)) return deferred.preliminaryResult;
483
504
  const depValue = isMultiDep ? resolution.values : resolution.values[0];
484
- const result = deferred.parser[require_dependency.parseWithDependency](deferred.rawInput, depValue);
505
+ const result = deferred.parser[require_internal_dependency.parseWithDependency](deferred.rawInput, depValue);
485
506
  if (isPromiseLike(result)) throw new TypeError("resolveStateWithRuntime() received an async parseWithDependency() result. Use resolveStateWithRuntimeAsync() instead.");
486
507
  return result;
487
508
  }
@@ -495,7 +516,7 @@ function resolveSingleDeferredAsync(deferred, runtime) {
495
516
  if (resolution.kind !== "resolved") return Promise.resolve(deferred.preliminaryResult);
496
517
  if (resolution.usedDefaults.every((d) => d)) return Promise.resolve(deferred.preliminaryResult);
497
518
  const depValue = isMultiDep ? resolution.values : resolution.values[0];
498
- return Promise.resolve(deferred.parser[require_dependency.parseWithDependency](deferred.rawInput, depValue));
519
+ return Promise.resolve(deferred.parser[require_internal_dependency.parseWithDependency](deferred.rawInput, depValue));
499
520
  }
500
521
  /**
501
522
  * Recursively collects dependency source values from {@link DependencySourceState}
@@ -514,14 +535,14 @@ function collectSourcesFromState(state, runtime, visited = /* @__PURE__ */ new W
514
535
  if (state == null || typeof state !== "object") return;
515
536
  if (visited.has(state)) return;
516
537
  visited.add(state);
517
- if (require_dependency.isDependencySourceState(state)) {
518
- const depId = state[require_dependency.dependencyId];
538
+ if (require_internal_dependency.isDependencySourceState(state)) {
539
+ const depId = state[require_internal_dependency.dependencyId];
519
540
  const result = state.result;
520
541
  if (depId != null && result.success) runtime.registerSource(depId, result.value, "cli");
521
542
  else if (depId != null) runtime.markSourceFailed(depId);
522
543
  return;
523
544
  }
524
- if (require_dependency.isDeferredParseState(state)) return;
545
+ if (require_internal_dependency.isDeferredParseState(state)) return;
525
546
  if (Array.isArray(state)) {
526
547
  for (const item of state) collectSourcesFromState(item, runtime, visited);
527
548
  return;
@@ -559,14 +580,14 @@ function resolveStateWithRuntime(state, runtime) {
559
580
  /** Pass 2 helper: recursively replace DeferredParseState with resolved values. */
560
581
  function resolveDeferredInState(state, runtime, visited = /* @__PURE__ */ new WeakSet(), deferredCache = /* @__PURE__ */ new WeakMap()) {
561
582
  if (state == null) return state;
562
- if (require_dependency.isDeferredParseState(state)) {
583
+ if (require_internal_dependency.isDeferredParseState(state)) {
563
584
  const cached = deferredCache.get(state);
564
585
  if (cached !== void 0) return cached;
565
586
  const resolved = resolveSingleDeferred(state, runtime);
566
587
  deferredCache.set(state, resolved);
567
588
  return resolved;
568
589
  }
569
- if (require_dependency.isDependencySourceState(state)) return state;
590
+ if (require_internal_dependency.isDependencySourceState(state)) return state;
570
591
  if (typeof state === "object") {
571
592
  if (visited.has(state)) return state;
572
593
  visited.add(state);
@@ -601,14 +622,14 @@ function resolveStateWithRuntimeAsync(state, runtime) {
601
622
  /** Async pass 2 helper. */
602
623
  async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE__ */ new WeakSet(), deferredCache = /* @__PURE__ */ new WeakMap()) {
603
624
  if (state == null) return state;
604
- if (require_dependency.isDeferredParseState(state)) {
625
+ if (require_internal_dependency.isDeferredParseState(state)) {
605
626
  const cached = deferredCache.get(state);
606
627
  if (cached !== void 0) return cached;
607
628
  const resolved = resolveSingleDeferredAsync(state, runtime);
608
629
  deferredCache.set(state, resolved);
609
630
  return resolved;
610
631
  }
611
- if (require_dependency.isDependencySourceState(state)) return state;
632
+ if (require_internal_dependency.isDependencySourceState(state)) return state;
612
633
  if (typeof state === "object") {
613
634
  if (visited.has(state)) return state;
614
635
  visited.add(state);
@@ -636,8 +657,8 @@ async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE_
636
657
  function isMatchedState(fieldState, parser) {
637
658
  if (fieldState === void 0) return false;
638
659
  const innerState = Array.isArray(fieldState) && fieldState.length === 1 ? fieldState[0] : fieldState;
639
- if (require_dependency.isPendingDependencySourceState(innerState)) return false;
640
- if (parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && innerState != null && typeof innerState === "object" && Object.hasOwn(innerState, "hasCliValue") && innerState.hasCliValue === false) return false;
660
+ if (require_internal_dependency.isPendingDependencySourceState(innerState)) return false;
661
+ if (parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true && innerState != null && typeof innerState === "object" && Object.hasOwn(innerState, "hasCliValue") && innerState.hasCliValue === false) return false;
641
662
  if (fieldState === parser.initialState) return false;
642
663
  return true;
643
664
  }
@@ -701,7 +722,10 @@ exports.buildRuntimeNodesFromPairs = buildRuntimeNodesFromPairs;
701
722
  exports.collectExplicitSourceValues = collectExplicitSourceValues;
702
723
  exports.collectExplicitSourceValuesAsync = collectExplicitSourceValuesAsync;
703
724
  exports.collectSourcesFromState = collectSourcesFromState;
725
+ exports.createDependencyFingerprint = createDependencyFingerprint;
704
726
  exports.createDependencyRuntimeContext = createDependencyRuntimeContext;
727
+ exports.createReplayKey = createReplayKey;
728
+ exports.extractRawInputFromState = extractRawInputFromState;
705
729
  exports.fillMissingSourceDefaults = fillMissingSourceDefaults;
706
730
  exports.fillMissingSourceDefaultsAsync = fillMissingSourceDefaultsAsync;
707
731
  exports.replayDerivedParser = replayDerivedParser;
@@ -49,7 +49,14 @@ interface DependencyResolution {
49
49
  * @internal
50
50
  * @since 1.0.0
51
51
  */
52
-
52
+ interface SourceDefaultFailure {
53
+ /** The source that failed. */
54
+ readonly sourceId: symbol;
55
+ /** The path of the node. */
56
+ readonly path: readonly PropertyKey[];
57
+ /** The failed result or error message. */
58
+ readonly error: ValueParserResult<unknown>;
59
+ }
53
60
  /**
54
61
  * A key for caching replayed parse results.
55
62
  *
@@ -145,5 +152,193 @@ interface DependencyRuntimeContext {
145
152
  * @internal
146
153
  * @since 1.0.0
147
154
  */
155
+ declare function createDependencyRuntimeContext(registry?: DependencyRegistryLike): DependencyRuntimeContext;
156
+ /**
157
+ * Creates a stable fingerprint from dependency values.
158
+ *
159
+ * @param values The dependency values to fingerprint.
160
+ * @returns A string fingerprint.
161
+ * @internal
162
+ * @since 1.0.0
163
+ */
164
+ declare function createDependencyFingerprint(values: readonly unknown[]): string;
165
+ declare function createReplayKey(path: readonly PropertyKey[], rawInput: string, dependencyValues: readonly unknown[], replayParse?: Function): ReplayKey;
166
+ /**
167
+ * Collects explicit source values from parser states and registers them
168
+ * in the runtime context.
169
+ *
170
+ * @param nodes The runtime nodes to inspect.
171
+ * @param runtime The dependency runtime context.
172
+ * @throws Propagates synchronous errors thrown by `extractSourceValue()`.
173
+ * @throws {TypeError} If `extractSourceValue()` returns a promise-like result.
174
+ * Use {@link collectExplicitSourceValuesAsync} when async source
175
+ * extraction is expected.
176
+ * @internal
177
+ * @since 1.0.0
178
+ */
179
+ declare function collectExplicitSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): void;
180
+ /**
181
+ * Async version of {@link collectExplicitSourceValues}.
182
+ * Awaits async `extractSourceValue` results instead of rejecting
183
+ * promise-like values as the synchronous variant does.
184
+ *
185
+ * @param nodes The runtime nodes to inspect.
186
+ * @param runtime The dependency runtime context.
187
+ * @throws Propagates errors thrown or rejected by `extractSourceValue()`.
188
+ * @internal
189
+ * @since 1.0.0
190
+ */
191
+ declare function collectExplicitSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<void>;
192
+ /**
193
+ * Fills missing source defaults for source parsers whose state is
194
+ * unpopulated.
195
+ *
196
+ * Returns an array of failures for sources whose default evaluation
197
+ * failed (either threw or returned `{ success: false }`). The caller
198
+ * should propagate these so that dependent parsers see the real error
199
+ * instead of silently treating the source as absent.
200
+ *
201
+ * @param nodes The runtime nodes to inspect.
202
+ * @param runtime The dependency runtime context.
203
+ * @returns Failures from default evaluation (empty if all succeeded).
204
+ * @throws {TypeError} If `getMissingSourceValue()` returns a promise-like
205
+ * result. Use {@link fillMissingSourceDefaultsAsync} when async
206
+ * default extraction is expected.
207
+ * @internal
208
+ * @since 1.0.0
209
+ */
210
+ declare function fillMissingSourceDefaults(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): readonly SourceDefaultFailure[];
211
+ /**
212
+ * Async version of {@link fillMissingSourceDefaults}.
213
+ * Awaits async `getMissingSourceValue` results.
214
+ *
215
+ * @param nodes The runtime nodes to inspect.
216
+ * @param runtime The dependency runtime context.
217
+ * @returns Failures from default evaluation (empty if all succeeded).
218
+ * @internal
219
+ * @since 1.0.0
220
+ */
221
+ declare function fillMissingSourceDefaultsAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<readonly SourceDefaultFailure[]>;
222
+ /**
223
+ * Replays a derived parser with resolved dependency values (sync).
224
+ *
225
+ * Returns `undefined` if dependencies cannot be resolved.
226
+ *
227
+ * @param node The runtime node with derived metadata.
228
+ * @param rawInput The raw input to replay.
229
+ * @param runtime The dependency runtime context.
230
+ * @returns The replay result, or `undefined`.
231
+ * @throws {TypeError} If `replayParse()` returns a promise-like result.
232
+ * Use {@link replayDerivedParserAsync} for async replay.
233
+ * @internal
234
+ * @since 1.0.0
235
+ */
236
+ declare function replayDerivedParser(node: RuntimeNode, rawInput: string, runtime: DependencyRuntimeContext): ValueParserResult<unknown> | undefined;
237
+ /**
238
+ * Replays a derived parser with resolved dependency values (async).
239
+ *
240
+ * Returns `undefined` if dependencies cannot be resolved.
241
+ *
242
+ * @param node The runtime node with derived metadata.
243
+ * @param rawInput The raw input to replay.
244
+ * @param runtime The dependency runtime context.
245
+ * @returns The replay result, or `undefined`.
246
+ * @internal
247
+ * @since 1.0.0
248
+ */
249
+ declare function replayDerivedParserAsync(node: RuntimeNode, rawInput: string, runtime: DependencyRuntimeContext): Promise<ValueParserResult<unknown> | undefined>;
250
+ /**
251
+ * Extracts `rawInput` from a parser state that may contain a
252
+ * {@link DeferredParseState}. During the transition period, primitives
253
+ * still produce `DeferredParseState` with `rawInput`.
254
+ *
255
+ * Handles direct `DeferredParseState` and array-wrapped
256
+ * `[DeferredParseState]` (from optional/withDefault wrappers).
257
+ *
258
+ * @param state The parser state to inspect.
259
+ * @returns The raw input string, or `undefined` if the state does not
260
+ * contain a `DeferredParseState`.
261
+ * @internal
262
+ * @since 1.0.0
263
+ */
264
+ declare function extractRawInputFromState(state: unknown): string | undefined;
265
+ /**
266
+ * Recursively collects dependency source values from {@link DependencySourceState}
267
+ * objects found in the state tree and registers them in the runtime.
268
+ *
269
+ * This must run BEFORE deferred resolution so that all source values
270
+ * are available when replaying derived parsers.
271
+ *
272
+ * @param state The state tree to traverse.
273
+ * @param runtime The dependency runtime context to populate.
274
+ * @param visited Cycle guard for recursive traversal.
275
+ * @param excludedFields Optional property keys to skip at the current level.
276
+ * This exclusion set is not propagated recursively.
277
+ */
278
+ declare function collectSourcesFromState(state: unknown, runtime: DependencyRuntimeContext, visited?: WeakSet<object>, excludedFields?: ReadonlySet<PropertyKey>): void;
279
+ /**
280
+ * Recursively resolves all {@link DeferredParseState} objects in a state
281
+ * tree using the dependency runtime (sync).
282
+ *
283
+ * Performs a two-pass traversal:
284
+ * 1. Collect all {@link DependencySourceState} values into the runtime.
285
+ * 2. Resolve all {@link DeferredParseState} using the populated runtime.
286
+ *
287
+ * This replaces the old `resolveDeferredParseStates` with runtime-based
288
+ * resolution. Only traverses plain objects and arrays; class instances
289
+ * and primitives are returned as-is.
290
+ *
291
+ * @param state The state tree to resolve.
292
+ * @param runtime The dependency runtime context.
293
+ * @returns The resolved state tree.
294
+ * @throws {TypeError} If a deferred parser returns a promise-like result from
295
+ * `parseWithDependency()`. Use {@link resolveStateWithRuntimeAsync}
296
+ * for async resolution.
297
+ * @internal
298
+ * @since 1.0.0
299
+ */
300
+ declare function resolveStateWithRuntime(state: unknown, runtime: DependencyRuntimeContext): unknown;
301
+ /**
302
+ * Async version of {@link resolveStateWithRuntime}.
303
+ *
304
+ * @param state The state tree to resolve.
305
+ * @param runtime The dependency runtime context.
306
+ * @returns The resolved state tree.
307
+ * @internal
308
+ * @since 1.0.0
309
+ */
310
+ declare function resolveStateWithRuntimeAsync(state: unknown, runtime: DependencyRuntimeContext): Promise<unknown>;
311
+ /**
312
+ * Builds {@link RuntimeNode}s from field→parser pairs and a state record.
313
+ *
314
+ * Used by `object()` and `merge()` constructs.
315
+ *
316
+ * @param pairs Field→parser pairs.
317
+ * @param state The state record keyed by field name.
318
+ * @param parentPath Optional parent path prefix.
319
+ * @returns An array of runtime nodes.
320
+ * @internal
321
+ * @since 1.0.0
322
+ */
323
+ declare function buildRuntimeNodesFromPairs(pairs: ReadonlyArray<readonly [PropertyKey, {
324
+ readonly dependencyMetadata?: ParserDependencyMetadata;
325
+ readonly initialState?: unknown;
326
+ }]>, state: Record<PropertyKey, unknown>, parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
327
+ /**
328
+ * Builds {@link RuntimeNode}s from a parser array and a state array.
329
+ *
330
+ * Used by `tuple()` and `concat()` constructs.
331
+ *
332
+ * @param parsers The child parsers.
333
+ * @param stateArray The state array (one element per parser).
334
+ * @param parentPath Optional parent path prefix.
335
+ * @returns An array of runtime nodes.
336
+ * @internal
337
+ * @since 1.0.0
338
+ */
339
+ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
340
+ readonly dependencyMetadata?: ParserDependencyMetadata;
341
+ readonly initialState?: unknown;
342
+ }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
148
343
  //#endregion
149
- export { DependencyRuntimeContext, RuntimeNode };
344
+ export { DependencyRequest, DependencyResolution, DependencyRuntimeContext, DependencyValueOrigin, ReplayKey, RuntimeNode, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };