@optique/core 1.0.0-dev.1611 → 1.0.0-dev.1658

package/dist/dependency-runtime.d.ts

@@ -1,5 +1,6 @@
 import { DependencyRegistryLike } from "./registry-types.js";
 import { ValueParserResult } from "./valueparser.js";
+import { ParserDependencyMetadata } from "./dependency-metadata.js";
 
 //#region src/dependency-runtime.d.ts
 
@@ -76,7 +77,32 @@ interface ReplayKey {
  * @internal
  * @since 1.0.0
  */
-
+interface RuntimeNode {
+  /** Path from root to this parser node. */
+  readonly path: readonly PropertyKey[];
+  /** The parser (only the metadata field is inspected). */
+  readonly parser: {
+    readonly dependencyMetadata?: ParserDependencyMetadata;
+  };
+  /** The parser's current state. */
+  readonly state: unknown;
+  /**
+   * Whether the parser consumed explicit input during parsing.
+   * When `true`, the parser's state reflects user-provided input (which
+   * may have failed validation).  Missing-source defaults must not override
+   * explicit parse failures.
+   * @since 1.0.0
+   */
+  readonly matched?: boolean;
+  /**
+   * Snapshotted default dependency values for derived parsers.
+   * Constructs should populate this at node creation time (once) to
+   * avoid re-evaluating dynamic `getDefaultDependencyValues()` thunks
+   * at replay time.
+   * @since 1.0.0
+   */
+  readonly defaultDependencyValues?: readonly unknown[];
+}
 /**
  * Dependency runtime context for centralized dependency resolution.
  *
@@ -120,4 +146,4 @@ interface DependencyRuntimeContext {
  * @since 1.0.0
  */
 //#endregion
-export { DependencyRuntimeContext };
+export { DependencyRuntimeContext, RuntimeNode };

package/dist/dependency-runtime.js

@@ -1,4 +1,6 @@
+import { message } from "./message.js";
 import { dependencyId, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, parseWithDependency } from "./dependency.js";
+import { unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
 
 //#region src/dependency-runtime.ts
 const symbolIds = /* @__PURE__ */ new WeakMap();
@@ -18,7 +20,11 @@ var DependencyRuntimeContextImpl = class {
 	#replayCache = /* @__PURE__ */ new Map();
 	#failedSources = /* @__PURE__ */ new Set();
 	constructor(registry) {
-		this.registry = registry;
+		if (registry instanceof FailedAwareRegistry) {
+			this.registry = registry.rebindFailedSources(this.#failedSources);
+			return;
+		}
+		this.registry = new FailedAwareRegistry(registry, this.#failedSources);
 	}
 	registerSource(sourceId, value, _origin) {
 		this.registry.set(sourceId, value);
@@ -48,6 +54,47 @@ var DependencyRuntimeContextImpl = class {
 		return resolveRequest(this, request);
 	}
 };
+/**
+* Registry wrapper that hides values for sources that have failed.
+*
+* The wrapper lets clones share an underlying registry while maintaining
+* an isolated failed-source view, so later lookups do not reuse stale
+* values after extraction errors.
+*
+* @internal
+*/
+var FailedAwareRegistry = class FailedAwareRegistry {
+	#inner;
+	#failedSources;
+	constructor(inner, failedSources) {
+		this.#inner = inner;
+		this.#failedSources = failedSources;
+	}
+	set(id, value) {
+		this.#inner.set(id, value);
+		this.#failedSources.delete(id);
+	}
+	get(id) {
+		if (this.#failedSources.has(id)) return void 0;
+		return this.#inner.get(id);
+	}
+	has(id) {
+		if (this.#failedSources.has(id)) return false;
+		return this.#inner.has(id);
+	}
+	copyFailedSources(target) {
+		for (const sourceId of this.#failedSources) target.add(sourceId);
+	}
+	rebindFailedSources(target) {
+		this.copyFailedSources(target);
+		return new FailedAwareRegistry(this.#inner, target);
+	}
+	clone() {
+		const failedSources = new Set(this.#failedSources);
+		const innerClone = this.#inner.clone();
+		return innerClone instanceof FailedAwareRegistry ? innerClone.rebindFailedSources(failedSources) : new FailedAwareRegistry(innerClone, failedSources);
+	}
+};
 function resolveRequest(ctx, request) {
 	const values = [];
 	const usedDefaults = [];
@@ -55,13 +102,13 @@ function resolveRequest(ctx, request) {
 	let defaultedCount = 0;
 	for (let i = 0; i < request.dependencyIds.length; i++) {
 		const id = request.dependencyIds[i];
-		if (ctx.hasSource(id)) {
+		if (ctx.isSourceFailed(id)) {
+			values.push(void 0);
+			usedDefaults.push(false);
+		} else if (ctx.hasSource(id)) {
 			values.push(ctx.getSource(id));
 			usedDefaults.push(false);
 			resolvedCount++;
-		} else if (ctx.isSourceFailed(id)) {
-			values.push(void 0);
-			usedDefaults.push(false);
 		} else if (request.defaultValues != null && i < request.defaultValues.length) {
 			values.push(request.defaultValues[i]);
 			usedDefaults.push(true);
@@ -126,11 +173,80 @@ function createDependencyRuntimeContext(registry) {
 	return new DependencyRuntimeContextImpl(registry ?? new SimpleRegistry());
 }
 /**
+* Creates a stable fingerprint from dependency values.
+*
+* @param values The dependency values to fingerprint.
+* @returns A string fingerprint.
+* @internal
+* @since 1.0.0
+*/
+function createDependencyFingerprint(values) {
+	return values.map((v) => {
+		const raw = fingerprintValue(v);
+		return `${raw.length}:${raw}`;
+	}).join("");
+}
+const objectIds = /* @__PURE__ */ new WeakMap();
+let objectIdCounter = 0;
+function fingerprintValue(v) {
+	if (v === void 0) return "u:";
+	if (v === null) return "n:";
+	if (typeof v === "string") return `s:${v}`;
+	if (typeof v === "number") {
+		if (Object.is(v, -0)) return "d:-0";
+		return `d:${v}`;
+	}
+	if (typeof v === "boolean") return `b:${v}`;
+	if (typeof v === "symbol") return `y:${stableSymbolKey(v)}`;
+	if (typeof v === "object" || typeof v === "function") {
+		let id = objectIds.get(v);
+		if (id === void 0) {
+			id = objectIdCounter++;
+			objectIds.set(v, id);
+		}
+		return `o:${id}`;
+	}
+	return `?:${String(v)}`;
+}
+/**
+* Creates a {@link ReplayKey} from a path, raw input, and dependency values.
+*
+* @param path The parser path.
+* @param rawInput The raw input string.
+* @param dependencyValues The dependency values.
+* @returns A replay key.
+* @internal
+* @since 1.0.0
+*/
+const parserIds = /* @__PURE__ */ new WeakMap();
+let parserIdCounter = 0;
+/** Get a stable identity string for a replayParse function reference. */
+function getParserFingerprint(replayParse) {
+	let id = parserIds.get(replayParse);
+	if (id === void 0) {
+		id = parserIdCounter++;
+		parserIds.set(replayParse, id);
+	}
+	return `p:${id}`;
+}
+function createReplayKey(path, rawInput, dependencyValues, replayParse) {
+	return {
+		path,
+		rawInput,
+		dependencyFingerprint: createDependencyFingerprint(dependencyValues),
+		parserFingerprint: replayParse != null ? getParserFingerprint(replayParse) : ""
+	};
+}
+/**
 * Collects explicit source values from parser states and registers them
 * in the runtime context.
 *
 * @param nodes The runtime nodes to inspect.
 * @param runtime The dependency runtime context.
+* @throws Propagates synchronous errors thrown by `extractSourceValue()`.
+* @throws {TypeError} If `extractSourceValue()` returns a promise-like result.
+*         Use {@link collectExplicitSourceValuesAsync} when async source
+*         extraction is expected.
 * @internal
 * @since 1.0.0
 */
@@ -140,12 +256,207 @@ function collectExplicitSourceValues(nodes, runtime) {
 		if (meta?.source == null) continue;
 		if (meta.source.extractSourceValue == null) continue;
 		const result = meta.source.extractSourceValue(node.state);
-		if (result == null) continue;
-		if (result.success) runtime.registerSource(meta.source.sourceId, result.value, "cli");
-		else runtime.markSourceFailed(meta.source.sourceId);
+		if (isPromiseLike(result)) throw new TypeError(`collectExplicitSourceValues() received an async extractSourceValue() result for ${String(meta.source.sourceId)}. Use collectExplicitSourceValuesAsync() instead.`);
+		registerExplicitSourceValue(meta.source.sourceId, result, runtime);
+	}
+}
+function registerExplicitSourceValue(sourceId, result, runtime) {
+	if (result == null) return;
+	if (result.success) runtime.registerSource(sourceId, result.value, "cli");
+	else runtime.markSourceFailed(sourceId);
+}
+function isPromiseLike(value) {
+	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
+}
+/**
+* Async version of {@link collectExplicitSourceValues}.
+* Awaits async `extractSourceValue` results instead of rejecting
+* promise-like values as the synchronous variant does.
+*
+* @param nodes The runtime nodes to inspect.
+* @param runtime The dependency runtime context.
+* @throws Propagates errors thrown or rejected by `extractSourceValue()`.
+* @internal
+* @since 1.0.0
+*/
+async function collectExplicitSourceValuesAsync(nodes, runtime) {
+	for (const node of nodes) {
+		const meta = node.parser.dependencyMetadata;
+		if (meta?.source == null) continue;
+		if (meta.source.extractSourceValue == null) continue;
+		const result = await meta.source.extractSourceValue(node.state);
+		registerExplicitSourceValue(meta.source.sourceId, result, runtime);
 	}
 }
 /**
+* Fills missing source defaults for source parsers whose state is
+* unpopulated.
+*
+* Returns an array of failures for sources whose default evaluation
+* failed (either threw or returned `{ success: false }`).  The caller
+* should propagate these so that dependent parsers see the real error
+* instead of silently treating the source as absent.
+*
+* @param nodes The runtime nodes to inspect.
+* @param runtime The dependency runtime context.
+* @returns Failures from default evaluation (empty if all succeeded).
+* @throws {TypeError} If `getMissingSourceValue()` returns a promise-like
+*         result. Use {@link fillMissingSourceDefaultsAsync} when async
+*         default extraction is expected.
+* @internal
+* @since 1.0.0
+*/
+function fillMissingSourceDefaults(nodes, runtime) {
+	const failures = [];
+	for (const node of nodes) {
+		const meta = node.parser.dependencyMetadata;
+		if (meta?.source == null) continue;
+		if (runtime.hasSource(meta.source.sourceId)) continue;
+		if (runtime.isSourceFailed(meta.source.sourceId)) continue;
+		if (node.matched === true) continue;
+		if (!meta.source.preservesSourceValue) continue;
+		if (meta.source.getMissingSourceValue == null) continue;
+		let result;
+		try {
+			result = meta.source.getMissingSourceValue();
+		} catch (e) {
+			const msg = e instanceof Error ? e.message : String(e);
+			failures.push({
+				sourceId: meta.source.sourceId,
+				path: node.path,
+				error: {
+					success: false,
+					error: message`Default value evaluation failed: ${msg}`
+				}
+			});
+			continue;
+		}
+		if (isPromiseLike(result)) throw new TypeError(`fillMissingSourceDefaults() received an async getMissingSourceValue() result for ${String(meta.source.sourceId)}. Use fillMissingSourceDefaultsAsync() instead.`);
+		if (result.success) runtime.registerSource(meta.source.sourceId, result.value, "default");
+		else failures.push({
+			sourceId: meta.source.sourceId,
+			path: node.path,
+			error: result
+		});
+	}
+	return failures;
+}
+/**
+* Async version of {@link fillMissingSourceDefaults}.
+* Awaits async `getMissingSourceValue` results.
+*
+* @param nodes The runtime nodes to inspect.
+* @param runtime The dependency runtime context.
+* @returns Failures from default evaluation (empty if all succeeded).
+* @internal
+* @since 1.0.0
+*/
+async function fillMissingSourceDefaultsAsync(nodes, runtime) {
+	const failures = [];
+	for (const node of nodes) {
+		const meta = node.parser.dependencyMetadata;
+		if (meta?.source == null) continue;
+		if (runtime.hasSource(meta.source.sourceId)) continue;
+		if (runtime.isSourceFailed(meta.source.sourceId)) continue;
+		if (node.matched === true) continue;
+		if (!meta.source.preservesSourceValue) continue;
+		if (meta.source.getMissingSourceValue == null) continue;
+		let result;
+		try {
+			result = await meta.source.getMissingSourceValue();
+		} catch (e) {
+			const msg = e instanceof Error ? e.message : String(e);
+			failures.push({
+				sourceId: meta.source.sourceId,
+				path: node.path,
+				error: {
+					success: false,
+					error: message`Default value evaluation failed: ${msg}`
+				}
+			});
+			continue;
+		}
+		if (result.success) runtime.registerSource(meta.source.sourceId, result.value, "default");
+		else failures.push({
+			sourceId: meta.source.sourceId,
+			path: node.path,
+			error: result
+		});
+	}
+	return failures;
+}
+/**
+* Replays a derived parser with resolved dependency values (sync).
+*
+* Returns `undefined` if dependencies cannot be resolved.
+*
+* @param node The runtime node with derived metadata.
+* @param rawInput The raw input to replay.
+* @param runtime The dependency runtime context.
+* @returns The replay result, or `undefined`.
+* @throws {TypeError} If `replayParse()` returns a promise-like result.
+*         Use {@link replayDerivedParserAsync} for async replay.
+* @internal
+* @since 1.0.0
+*/
+function replayDerivedParser(node, rawInput, runtime) {
+	const meta = node.parser.dependencyMetadata;
+	if (meta?.derived == null) return void 0;
+	let defaults = node.defaultDependencyValues;
+	if (defaults == null && meta.derived.getDefaultDependencyValues != null) try {
+		defaults = meta.derived.getDefaultDependencyValues();
+	} catch {
+		return void 0;
+	}
+	const resolution = runtime.resolveDependencies({
+		dependencyIds: meta.derived.dependencyIds,
+		defaultValues: defaults
+	});
+	if (resolution.kind === "missing") return void 0;
+	if (resolution.kind === "partial") return void 0;
+	const key = createReplayKey(node.path, rawInput, resolution.values, meta.derived.replayParse);
+	const cached = runtime.getReplayResult(key);
+	if (cached != null) return cached;
+	const result = meta.derived.replayParse(rawInput, resolution.values);
+	if (isPromiseLike(result)) throw new TypeError("replayDerivedParser() received an async replayParse() result. Use replayDerivedParserAsync() instead.");
+	runtime.setReplayResult(key, result);
+	return result;
+}
+/**
+* Replays a derived parser with resolved dependency values (async).
+*
+* Returns `undefined` if dependencies cannot be resolved.
+*
+* @param node The runtime node with derived metadata.
+* @param rawInput The raw input to replay.
+* @param runtime The dependency runtime context.
+* @returns The replay result, or `undefined`.
+* @internal
+* @since 1.0.0
+*/
+async function replayDerivedParserAsync(node, rawInput, runtime) {
+	const meta = node.parser.dependencyMetadata;
+	if (meta?.derived == null) return void 0;
+	let defaults = node.defaultDependencyValues;
+	if (defaults == null && meta.derived.getDefaultDependencyValues != null) try {
+		defaults = meta.derived.getDefaultDependencyValues();
+	} catch {
+		return void 0;
+	}
+	const resolution = runtime.resolveDependencies({
+		dependencyIds: meta.derived.dependencyIds,
+		defaultValues: defaults
+	});
+	if (resolution.kind === "missing") return void 0;
+	if (resolution.kind === "partial") return void 0;
+	const key = createReplayKey(node.path, rawInput, resolution.values, meta.derived.replayParse);
+	const cached = runtime.getReplayResult(key);
+	if (cached != null) return cached;
+	const result = await meta.derived.replayParse(rawInput, resolution.values);
+	runtime.setReplayResult(key, result);
+	return result;
+}
+/**
 * Checks if a value is a plain object (not a class instance) for the
 * purpose of recursive state traversal.
 */
@@ -168,9 +479,10 @@ function resolveSingleDeferred(deferred, runtime) {
 		defaultValues: deferred.defaultValues
 	});
 	if (resolution.kind !== "resolved") return deferred.preliminaryResult;
+	if (resolution.usedDefaults.every((d) => d)) return deferred.preliminaryResult;
 	const depValue = isMultiDep ? resolution.values : resolution.values[0];
 	const result = deferred.parser[parseWithDependency](deferred.rawInput, depValue);
-	if (result instanceof Promise) return deferred.preliminaryResult;
+	if (isPromiseLike(result)) throw new TypeError("resolveStateWithRuntime() received an async parseWithDependency() result. Use resolveStateWithRuntimeAsync() instead.");
 	return result;
 }
 /**
@@ -179,8 +491,14 @@ function resolveSingleDeferred(deferred, runtime) {
 *
 * This must run BEFORE deferred resolution so that all source values
 * are available when replaying derived parsers.
+*
+* @param state The state tree to traverse.
+* @param runtime The dependency runtime context to populate.
+* @param visited Cycle guard for recursive traversal.
+* @param excludedFields Optional property keys to skip at the current level.
+*                       This exclusion set is not propagated recursively.
 */
-function collectSourcesFromState(state, runtime, visited = /* @__PURE__ */ new WeakSet()) {
+function collectSourcesFromState(state, runtime, visited = /* @__PURE__ */ new WeakSet(), excludedFields) {
 	if (state == null || typeof state !== "object") return;
 	if (visited.has(state)) return;
 	visited.add(state);
@@ -196,7 +514,10 @@ function collectSourcesFromState(state, runtime, visited = /* @__PURE__ */ new W
 		for (const item of state) collectSourcesFromState(item, runtime, visited);
 		return;
 	}
-	if (typeof state === "object") for (const key of Reflect.ownKeys(state)) collectSourcesFromState(state[key], runtime, visited);
+	if (typeof state === "object") for (const key of Reflect.ownKeys(state)) {
+		if (excludedFields?.has(key)) continue;
+		collectSourcesFromState(state[key], runtime, visited);
+	}
 }
 /**
 * Recursively resolves all {@link DeferredParseState} objects in a state
@@ -213,6 +534,9 @@ function collectSourcesFromState(state, runtime, visited = /* @__PURE__ */ new W
 * @param state The state tree to resolve.
 * @param runtime The dependency runtime context.
 * @returns The resolved state tree.
+* @throws {TypeError} If a deferred parser returns a promise-like result from
+*         `parseWithDependency()`. Use {@link resolveStateWithRuntimeAsync}
+*         for async resolution.
 * @internal
 * @since 1.0.0
 */
@@ -266,6 +590,7 @@ async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE_
 			defaultValues: deferred.defaultValues
 		});
 		if (resolution.kind !== "resolved") return deferred.preliminaryResult;
+		if (resolution.usedDefaults.every((d) => d)) return deferred.preliminaryResult;
 		const depValue = isMultiDep ? resolution.values : resolution.values[0];
 		return Promise.resolve(deferred.parser[parseWithDependency](deferred.rawInput, depValue));
 	}
@@ -287,8 +612,9 @@ async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE_
 */
 function isMatchedState(fieldState, parser) {
 	if (fieldState === void 0) return false;
-	if (Array.isArray(fieldState) && fieldState.length === 1 && isPendingDependencySourceState(fieldState[0])) return false;
-	if (isPendingDependencySourceState(fieldState)) return false;
+	const innerState = Array.isArray(fieldState) && fieldState.length === 1 ? fieldState[0] : fieldState;
+	if (isPendingDependencySourceState(innerState)) return false;
+	if (parser[unmatchedNonCliDependencySourceStateMarker] === true && innerState != null && typeof innerState === "object" && Object.hasOwn(innerState, "hasCliValue") && innerState.hasCliValue === false) return false;
 	if (fieldState === parser.initialState) return false;
 	return true;
 }
@@ -318,6 +644,33 @@ function buildRuntimeNodesFromPairs(pairs, state, parentPath) {
 	}
 	return nodes;
 }
+/**
+* Builds {@link RuntimeNode}s from a parser array and a state array.
+*
+* Used by `tuple()` and `concat()` constructs.
+*
+* @param parsers The child parsers.
+* @param stateArray The state array (one element per parser).
+* @param parentPath Optional parent path prefix.
+* @returns An array of runtime nodes.
+* @internal
+* @since 1.0.0
+*/
+function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
+	const prefix = parentPath ?? [];
+	const nodes = [];
+	for (let i = 0; i < parsers.length; i++) {
+		const parser = parsers[i];
+		const elemState = i < stateArray.length ? stateArray[i] : void 0;
+		nodes.push({
+			path: [...prefix, i],
+			parser,
+			state: elemState,
+			matched: isMatchedState(elemState, parser)
+		});
+	}
+	return nodes;
+}
 
 //#endregion
-export { buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectSourcesFromState, createDependencyRuntimeContext, resolveStateWithRuntime, resolveStateWithRuntimeAsync };
+export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyRuntimeContext, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };