@optique/core 1.3.0-dev.2383 → 1.3.0-dev.2385

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.
@@ -59,6 +59,26 @@ function filterPreCompletedRuntimeNodes(nodes, preCompletedKeys) {
59
59
  });
60
60
  }
61
61
  /**
62
+ * Filters a construct's runtime nodes for the effectful scheduling pass.
63
+ *
64
+ * A settled Phase 1 pre-completion excludes an *effectful* node: its
65
+ * completion already ran and must not run again. Structural
66
+ * (non-effectful) nodes always stay in the pass, whether pre-completed
67
+ * or not: the scheduler re-registers their extracted values so that
68
+ * registration order follows declaration order across structural and
69
+ * effectful occurrences of a shared source.
70
+ */
71
+ function filterSchedulableRuntimeNodes(nodes, preCompleted) {
72
+ const settledKeys = settledPreCompletedKeys(preCompleted);
73
+ if (settledKeys.size < 1) return nodes;
74
+ return nodes.filter((node) => {
75
+ if (node.parser.dependencyMetadata?.source?.completeSource == null) return true;
76
+ const segment = node.path.at(-1);
77
+ if (typeof segment === "number") return !settledKeys.has(String(segment));
78
+ return segment == null || !settledKeys.has(segment);
79
+ });
80
+ }
81
+ /**
62
82
  * Runs the effectful source completion pass for a construct's direct
63
83
  * children and merges the completed results into the construct's
64
84
  * pre-completed cache so its final completion phase reuses them instead
@@ -2467,7 +2487,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
2467
2487
  const allRuntimeNodes = require_dependency_runtime.buildRuntimeNodesFromPairs(asyncParserPairs, annotatedState, exec?.path);
2468
2488
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
2469
2489
  await require_dependency_runtime.collectExplicitSourceValuesAsync(runtimeNodes, runtime);
2470
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), annotatedState, runtime, childExec, preCompleted);
2490
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), annotatedState, runtime, childExec, preCompleted);
2471
2491
  if (effectfulFailure != null) return effectfulFailure;
2472
2492
  const resolvedFieldStates = await require_dependency_runtime.resolveStateWithRuntimeAsync(annotatedState, runtime);
2473
2493
  const result = {};
@@ -2593,7 +2613,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
2593
2613
  const allRuntimeNodes = require_dependency_runtime.buildRuntimeNodesFromPairs(asyncParserPairs, annotatedState, exec?.path);
2594
2614
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
2595
2615
  await require_dependency_runtime.collectExplicitSourceValuesAsync(runtimeNodes, runtime);
2596
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), annotatedState, runtime, childExec, preCompleted);
2616
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), annotatedState, runtime, childExec, preCompleted);
2597
2617
  if (effectfulFailure != null) return null;
2598
2618
  const resolvedFieldStates = await require_dependency_runtime.resolveStateWithRuntimeAsync(annotatedState, runtime);
2599
2619
  const result = {};
@@ -3016,7 +3036,7 @@ function createSeqComplete(parsers, combinedMode) {
3016
3036
  const allRuntimeNodes = require_dependency_runtime.buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
3017
3037
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
3018
3038
  await require_dependency_runtime.collectExplicitSourceValuesAsync(runtimeNodes, runtime);
3019
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
3039
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), stateArray, runtime, childExec, preCompleted);
3020
3040
  if (effectfulFailure != null) return effectfulFailure;
3021
3041
  const phase3Exec = {
3022
3042
  ...childExec,
@@ -3511,7 +3531,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
3511
3531
  const allRuntimeNodes = require_dependency_runtime.buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
3512
3532
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
3513
3533
  await require_dependency_runtime.collectExplicitSourceValuesAsync(runtimeNodes, runtime);
3514
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
3534
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), stateArray, runtime, childExec, preCompleted);
3515
3535
  if (effectfulFailure != null) return effectfulFailure;
3516
3536
  const phase3Exec = {
3517
3537
  ...childExec,
@@ -3599,7 +3619,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
3599
3619
  const allRuntimeNodes = require_dependency_runtime.buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
3600
3620
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
3601
3621
  await require_dependency_runtime.collectExplicitSourceValuesAsync(runtimeNodes, runtime);
3602
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
3622
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), stateArray, runtime, childExec, preCompleted);
3603
3623
  if (effectfulFailure != null) return null;
3604
3624
  const phase3Exec = {
3605
3625
  ...childExec,
@@ -3865,7 +3885,7 @@ function seq(...rawArgs) {
3865
3885
  const allRuntimeNodes = require_dependency_runtime.buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
3866
3886
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
3867
3887
  await require_dependency_runtime.collectExplicitSourceValuesAsync(runtimeNodes, runtime);
3868
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
3888
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), stateArray, runtime, childExec, preCompleted);
3869
3889
  if (effectfulFailure != null) return null;
3870
3890
  const phase3Exec = {
3871
3891
  ...childExec,
@@ -5447,7 +5467,7 @@ function concat(...parsers) {
5447
5467
  const allRuntimeNodes = require_dependency_runtime.buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
5448
5468
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
5449
5469
  await require_dependency_runtime.collectExplicitSourceValuesAsync(runtimeNodes, runtime);
5450
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
5470
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), stateArray, runtime, childExec, preCompleted);
5451
5471
  if (effectfulFailure != null) return effectfulFailure;
5452
5472
  const phase3Exec = {
5453
5473
  ...childExec,
@@ -5555,7 +5575,7 @@ function concat(...parsers) {
5555
5575
  const allRuntimeNodes = require_dependency_runtime.buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
5556
5576
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
5557
5577
  await require_dependency_runtime.collectExplicitSourceValuesAsync(runtimeNodes, runtime);
5558
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
5578
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), stateArray, runtime, childExec, preCompleted);
5559
5579
  if (effectfulFailure != null) return null;
5560
5580
  const phase3Exec = {
5561
5581
  ...childExec,
@@ -59,6 +59,26 @@ function filterPreCompletedRuntimeNodes(nodes, preCompletedKeys) {
59
59
  });
60
60
  }
61
61
  /**
62
+ * Filters a construct's runtime nodes for the effectful scheduling pass.
63
+ *
64
+ * A settled Phase 1 pre-completion excludes an *effectful* node: its
65
+ * completion already ran and must not run again. Structural
66
+ * (non-effectful) nodes always stay in the pass, whether pre-completed
67
+ * or not: the scheduler re-registers their extracted values so that
68
+ * registration order follows declaration order across structural and
69
+ * effectful occurrences of a shared source.
70
+ */
71
+ function filterSchedulableRuntimeNodes(nodes, preCompleted) {
72
+ const settledKeys = settledPreCompletedKeys(preCompleted);
73
+ if (settledKeys.size < 1) return nodes;
74
+ return nodes.filter((node) => {
75
+ if (node.parser.dependencyMetadata?.source?.completeSource == null) return true;
76
+ const segment = node.path.at(-1);
77
+ if (typeof segment === "number") return !settledKeys.has(String(segment));
78
+ return segment == null || !settledKeys.has(segment);
79
+ });
80
+ }
81
+ /**
62
82
  * Runs the effectful source completion pass for a construct's direct
63
83
  * children and merges the completed results into the construct's
64
84
  * pre-completed cache so its final completion phase reuses them instead
@@ -2467,7 +2487,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
2467
2487
  const allRuntimeNodes = buildRuntimeNodesFromPairs(asyncParserPairs, annotatedState, exec?.path);
2468
2488
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
2469
2489
  await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
2470
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), annotatedState, runtime, childExec, preCompleted);
2490
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), annotatedState, runtime, childExec, preCompleted);
2471
2491
  if (effectfulFailure != null) return effectfulFailure;
2472
2492
  const resolvedFieldStates = await resolveStateWithRuntimeAsync(annotatedState, runtime);
2473
2493
  const result = {};
@@ -2593,7 +2613,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
2593
2613
  const allRuntimeNodes = buildRuntimeNodesFromPairs(asyncParserPairs, annotatedState, exec?.path);
2594
2614
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
2595
2615
  await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
2596
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), annotatedState, runtime, childExec, preCompleted);
2616
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), annotatedState, runtime, childExec, preCompleted);
2597
2617
  if (effectfulFailure != null) return null;
2598
2618
  const resolvedFieldStates = await resolveStateWithRuntimeAsync(annotatedState, runtime);
2599
2619
  const result = {};
@@ -3016,7 +3036,7 @@ function createSeqComplete(parsers, combinedMode) {
3016
3036
  const allRuntimeNodes = buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
3017
3037
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
3018
3038
  await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
3019
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
3039
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), stateArray, runtime, childExec, preCompleted);
3020
3040
  if (effectfulFailure != null) return effectfulFailure;
3021
3041
  const phase3Exec = {
3022
3042
  ...childExec,
@@ -3511,7 +3531,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
3511
3531
  const allRuntimeNodes = buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
3512
3532
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
3513
3533
  await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
3514
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
3534
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), stateArray, runtime, childExec, preCompleted);
3515
3535
  if (effectfulFailure != null) return effectfulFailure;
3516
3536
  const phase3Exec = {
3517
3537
  ...childExec,
@@ -3599,7 +3619,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
3599
3619
  const allRuntimeNodes = buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
3600
3620
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
3601
3621
  await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
3602
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
3622
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), stateArray, runtime, childExec, preCompleted);
3603
3623
  if (effectfulFailure != null) return null;
3604
3624
  const phase3Exec = {
3605
3625
  ...childExec,
@@ -3865,7 +3885,7 @@ function seq(...rawArgs) {
3865
3885
  const allRuntimeNodes = buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
3866
3886
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
3867
3887
  await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
3868
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
3888
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), stateArray, runtime, childExec, preCompleted);
3869
3889
  if (effectfulFailure != null) return null;
3870
3890
  const phase3Exec = {
3871
3891
  ...childExec,
@@ -5447,7 +5467,7 @@ function concat(...parsers) {
5447
5467
  const allRuntimeNodes = buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
5448
5468
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
5449
5469
  await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
5450
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
5470
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), stateArray, runtime, childExec, preCompleted);
5451
5471
  if (effectfulFailure != null) return effectfulFailure;
5452
5472
  const phase3Exec = {
5453
5473
  ...childExec,
@@ -5555,7 +5575,7 @@ function concat(...parsers) {
5555
5575
  const allRuntimeNodes = buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
5556
5576
  const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
5557
5577
  await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
5558
- const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
5578
+ const effectfulFailure = await scheduleEffectfulSourceCompletions(filterSchedulableRuntimeNodes(allRuntimeNodes, preCompleted), stateArray, runtime, childExec, preCompleted);
5559
5579
  if (effectfulFailure != null) return null;
5560
5580
  const phase3Exec = {
5561
5581
  ...childExec,
@@ -627,15 +627,16 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
627
627
  }
628
628
  const schedulable = nodes.filter((node) => node.parser.dependencyMetadata?.source?.completeSource != null);
629
629
  if (schedulable.length === 0) return empty;
630
- const preexisting = /* @__PURE__ */ new Set();
631
- for (const node of schedulable) {
632
- const source = node.parser.dependencyMetadata?.source;
633
- if (source != null && runtime.hasSource(source.sourceId) && session?.effectfulSources.has(source.sourceId) !== true) preexisting.add(source.sourceId);
634
- }
635
630
  const completed = [];
636
- for (const node of schedulable) {
631
+ for (const node of nodes) {
637
632
  const source = node.parser.dependencyMetadata?.source;
638
- if (source?.completeSource == null) continue;
633
+ if (source == null) continue;
634
+ if (source.completeSource == null) {
635
+ if (source.extractSourceValue == null || (options?.isReusable?.(node) ?? true) === false) continue;
636
+ const extracted = await source.extractSourceValue(node.state);
637
+ if (extracted?.success === true && extracted.value !== void 0) runtime.registerSource(source.sourceId, extracted.value);
638
+ continue;
639
+ }
639
640
  const pathKey = serializeSchedulingPath(node.path);
640
641
  const priorResult = session?.completedByPath.get(pathKey);
641
642
  if (priorResult != null) {
@@ -645,7 +646,6 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
645
646
  });
646
647
  continue;
647
648
  }
648
- if (preexisting.has(source.sourceId)) continue;
649
649
  const reusable = source.preservesSourceValue && (options?.isReusable?.(node) ?? true);
650
650
  if (!reusable && session == null) continue;
651
651
  const childExec = {
@@ -627,15 +627,16 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
627
627
  }
628
628
  const schedulable = nodes.filter((node) => node.parser.dependencyMetadata?.source?.completeSource != null);
629
629
  if (schedulable.length === 0) return empty;
630
- const preexisting = /* @__PURE__ */ new Set();
631
- for (const node of schedulable) {
632
- const source = node.parser.dependencyMetadata?.source;
633
- if (source != null && runtime.hasSource(source.sourceId) && session?.effectfulSources.has(source.sourceId) !== true) preexisting.add(source.sourceId);
634
- }
635
630
  const completed = [];
636
- for (const node of schedulable) {
631
+ for (const node of nodes) {
637
632
  const source = node.parser.dependencyMetadata?.source;
638
- if (source?.completeSource == null) continue;
633
+ if (source == null) continue;
634
+ if (source.completeSource == null) {
635
+ if (source.extractSourceValue == null || (options?.isReusable?.(node) ?? true) === false) continue;
636
+ const extracted = await source.extractSourceValue(node.state);
637
+ if (extracted?.success === true && extracted.value !== void 0) runtime.registerSource(source.sourceId, extracted.value);
638
+ continue;
639
+ }
639
640
  const pathKey = serializeSchedulingPath(node.path);
640
641
  const priorResult = session?.completedByPath.get(pathKey);
641
642
  if (priorResult != null) {
@@ -645,7 +646,6 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
645
646
  });
646
647
  continue;
647
648
  }
648
- if (preexisting.has(source.sourceId)) continue;
649
649
  const reusable = source.preservesSourceValue && (options?.isReusable?.(node) ?? true);
650
650
  if (!reusable && session == null) continue;
651
651
  const childExec = {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@optique/core",
3
- "version": "1.3.0-dev.2383",
3
+ "version": "1.3.0-dev.2385",
4
4
  "description": "Type-safe combinatorial command-line interface parser",
5
5
  "keywords": [
6
6
  "CLI",
@@ -221,7 +221,7 @@
221
221
  },
222
222
  "sideEffects": false,
223
223
  "devDependencies": {
224
- "@optique/env": "1.3.0-dev.2383+4053ebf3",
224
+ "@optique/env": "1.3.0-dev.2385+011936e3",
225
225
  "@types/node": "^24.0.0",
226
226
  "fast-check": "^4.7.0",
227
227
  "tsdown": "^0.13.0",