@optique/core 1.0.0-dev.1598 → 1.0.0-dev.1608

package/dist/dependency-runtime.cjs

@@ -0,0 +1,328 @@
+const require_dependency = require('./dependency.cjs');
+
+//#region src/dependency-runtime.ts
+const symbolIds = /* @__PURE__ */ new WeakMap();
+let symbolCounter = 0;
+function stableSymbolKey(sym) {
+	const registeredKey = Symbol.keyFor(sym);
+	if (registeredKey !== void 0) return `reg:${registeredKey}`;
+	let id = symbolIds.get(sym);
+	if (id === void 0) {
+		id = `sym:${symbolCounter++}`;
+		symbolIds.set(sym, id);
+	}
+	return id;
+}
+var DependencyRuntimeContextImpl = class {
+	registry;
+	#replayCache = /* @__PURE__ */ new Map();
+	#failedSources = /* @__PURE__ */ new Set();
+	constructor(registry) {
+		this.registry = registry;
+	}
+	registerSource(sourceId, value, _origin) {
+		this.registry.set(sourceId, value);
+	}
+	hasSource(sourceId) {
+		return this.registry.has(sourceId);
+	}
+	getSource(sourceId) {
+		return this.registry.get(sourceId);
+	}
+	resolveDependencies(request) {
+		return resolveRequest(this, request);
+	}
+	getReplayResult(key) {
+		return this.#replayCache.get(serializeReplayKey(key));
+	}
+	setReplayResult(key, result) {
+		this.#replayCache.set(serializeReplayKey(key), result);
+	}
+	markSourceFailed(sourceId) {
+		this.#failedSources.add(sourceId);
+	}
+	isSourceFailed(sourceId) {
+		return this.#failedSources.has(sourceId);
+	}
+	getSuggestionDependencies(request) {
+		return resolveRequest(this, request);
+	}
+};
+function resolveRequest(ctx, request) {
+	const values = [];
+	const usedDefaults = [];
+	let resolvedCount = 0;
+	let defaultedCount = 0;
+	for (let i = 0; i < request.dependencyIds.length; i++) {
+		const id = request.dependencyIds[i];
+		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);
+			defaultedCount++;
+		} else {
+			values.push(void 0);
+			usedDefaults.push(false);
+		}
+	}
+	const total = request.dependencyIds.length;
+	const foundOrDefaulted = resolvedCount + defaultedCount;
+	let kind;
+	if (foundOrDefaulted === total) kind = "resolved";
+	else if (resolvedCount === 0 && defaultedCount === 0) kind = "missing";
+	else kind = "partial";
+	return {
+		kind,
+		values,
+		usedDefaults
+	};
+}
+/** Length-prefix a segment so that no delimiter escaping is needed. */
+function lengthPrefix(s) {
+	return `${s.length}:${s}`;
+}
+function serializePathSegment(p) {
+	if (typeof p === "string") return lengthPrefix(`s${p}`);
+	if (typeof p === "number") return lengthPrefix(`n${p}`);
+	return lengthPrefix(`y${stableSymbolKey(p)}`);
+}
+function serializeReplayKey(key) {
+	const pathStr = key.path.map(serializePathSegment).join("");
+	return `${pathStr}\x01${lengthPrefix(key.rawInput)}\x01${key.dependencyFingerprint}\x01${key.parserFingerprint}`;
+}
+/** Minimal registry implementation for standalone use. */
+var SimpleRegistry = class SimpleRegistry {
+	#map = /* @__PURE__ */ new Map();
+	set(id, value) {
+		this.#map.set(id, value);
+	}
+	get(id) {
+		return this.#map.get(id);
+	}
+	has(id) {
+		return this.#map.has(id);
+	}
+	clone() {
+		const copy = new SimpleRegistry();
+		for (const [k, v] of this.#map) copy.set(k, v);
+		return copy;
+	}
+};
+/**
+* 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
+*/
+function createDependencyRuntimeContext(registry) {
+	return new DependencyRuntimeContextImpl(registry ?? new SimpleRegistry());
+}
+/**
+* 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.
+* @internal
+* @since 1.0.0
+*/
+function collectExplicitSourceValues(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 = 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);
+	}
+}
+/**
+* Checks if a value is a plain object (not a class instance) for the
+* purpose of recursive state traversal.
+*/
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* Resolves a single {@link DeferredParseState} using the dependency runtime.
+*
+* Returns the replay result if all dependencies are available, or the
+* preliminary result if dependencies are missing.
+*/
+function resolveSingleDeferred(deferred, runtime) {
+	const isMultiDep = deferred.dependencyIds != null && deferred.dependencyIds.length > 0;
+	const depIds = isMultiDep ? deferred.dependencyIds : [deferred.dependencyId];
+	const resolution = runtime.resolveDependencies({
+		dependencyIds: depIds,
+		defaultValues: deferred.defaultValues
+	});
+	if (resolution.kind !== "resolved") return deferred.preliminaryResult;
+	const depValue = isMultiDep ? resolution.values : resolution.values[0];
+	const result = deferred.parser[require_dependency.parseWithDependency](deferred.rawInput, depValue);
+	if (result instanceof Promise) return deferred.preliminaryResult;
+	return result;
+}
+/**
+* Recursively collects dependency source values from {@link DependencySourceState}
+* objects found in the state tree and registers them in the runtime.
+*
+* This must run BEFORE deferred resolution so that all source values
+* are available when replaying derived parsers.
+*/
+function collectSourcesFromState(state, runtime, visited = /* @__PURE__ */ new WeakSet()) {
+	if (state == null || typeof state !== "object") return;
+	if (visited.has(state)) return;
+	visited.add(state);
+	if (require_dependency.isDependencySourceState(state)) {
+		const depId = state[require_dependency.dependencyId];
+		const result = state.result;
+		if (depId != null && result.success) runtime.registerSource(depId, result.value, "cli");
+		else if (depId != null) runtime.markSourceFailed(depId);
+		return;
+	}
+	if (require_dependency.isDeferredParseState(state)) return;
+	if (Array.isArray(state)) {
+		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);
+}
+/**
+* Recursively resolves all {@link DeferredParseState} objects in a state
+* tree using the dependency runtime (sync).
+*
+* Performs a two-pass traversal:
+*  1. Collect all {@link DependencySourceState} values into the runtime.
+*  2. Resolve all {@link DeferredParseState} using the populated runtime.
+*
+* This replaces the old `resolveDeferredParseStates` with runtime-based
+* resolution.  Only traverses plain objects and arrays; class instances
+* and primitives are returned as-is.
+*
+* @param state The state tree to resolve.
+* @param runtime The dependency runtime context.
+* @returns The resolved state tree.
+* @internal
+* @since 1.0.0
+*/
+function resolveStateWithRuntime(state, runtime) {
+	collectSourcesFromState(state, runtime);
+	return resolveDeferredInState(state, runtime);
+}
+/** Pass 2 helper: recursively replace DeferredParseState with resolved values. */
+function resolveDeferredInState(state, runtime, visited = /* @__PURE__ */ new WeakSet()) {
+	if (state == null) return state;
+	if (typeof state === "object") {
+		if (visited.has(state)) return state;
+		visited.add(state);
+	}
+	if (require_dependency.isDeferredParseState(state)) return resolveSingleDeferred(state, runtime);
+	if (require_dependency.isDependencySourceState(state)) return state;
+	if (Array.isArray(state)) return state.map((item) => resolveDeferredInState(item, runtime, visited));
+	if (isPlainObject(state)) {
+		const resolved = Object.create(Object.getPrototypeOf(state));
+		for (const key of Reflect.ownKeys(state)) resolved[key] = resolveDeferredInState(state[key], runtime, visited);
+		return resolved;
+	}
+	return state;
+}
+/**
+* Async version of {@link resolveStateWithRuntime}.
+*
+* @param state The state tree to resolve.
+* @param runtime The dependency runtime context.
+* @returns The resolved state tree.
+* @internal
+* @since 1.0.0
+*/
+function resolveStateWithRuntimeAsync(state, runtime) {
+	collectSourcesFromState(state, runtime);
+	return resolveDeferredInStateAsync(state, runtime);
+}
+/** Async pass 2 helper. */
+async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE__ */ new WeakSet()) {
+	if (state == null) return state;
+	if (typeof state === "object") {
+		if (visited.has(state)) return state;
+		visited.add(state);
+	}
+	if (require_dependency.isDeferredParseState(state)) {
+		const deferred = state;
+		const isMultiDep = deferred.dependencyIds != null && deferred.dependencyIds.length > 0;
+		const depIds = isMultiDep ? deferred.dependencyIds : [deferred.dependencyId];
+		const resolution = runtime.resolveDependencies({
+			dependencyIds: depIds,
+			defaultValues: deferred.defaultValues
+		});
+		if (resolution.kind !== "resolved") return deferred.preliminaryResult;
+		const depValue = isMultiDep ? resolution.values : resolution.values[0];
+		return Promise.resolve(deferred.parser[require_dependency.parseWithDependency](deferred.rawInput, depValue));
+	}
+	if (require_dependency.isDependencySourceState(state)) return state;
+	if (Array.isArray(state)) return Promise.all(state.map((item) => resolveDeferredInStateAsync(item, runtime, visited)));
+	if (isPlainObject(state)) {
+		const resolved = Object.create(Object.getPrototypeOf(state));
+		const keys = Reflect.ownKeys(state);
+		await Promise.all(keys.map(async (key) => {
+			resolved[key] = await resolveDeferredInStateAsync(state[key], runtime, visited);
+		}));
+		return resolved;
+	}
+	return state;
+}
+/**
+* Determines whether a parser state represents an explicit match (the user
+* provided input) rather than an initial/pending state.
+*/
+function isMatchedState(fieldState, parser) {
+	if (fieldState === void 0) return false;
+	if (Array.isArray(fieldState) && fieldState.length === 1 && require_dependency.isPendingDependencySourceState(fieldState[0])) return false;
+	if (require_dependency.isPendingDependencySourceState(fieldState)) return false;
+	if (fieldState === parser.initialState) return false;
+	return true;
+}
+/**
+* Builds {@link RuntimeNode}s from field→parser pairs and a state record.
+*
+* Used by `object()` and `merge()` constructs.
+*
+* @param pairs Field→parser pairs.
+* @param state The state record keyed by field name.
+* @param parentPath Optional parent path prefix.
+* @returns An array of runtime nodes.
+* @internal
+* @since 1.0.0
+*/
+function buildRuntimeNodesFromPairs(pairs, state, parentPath) {
+	const prefix = parentPath ?? [];
+	const nodes = [];
+	for (const [field, parser] of pairs) {
+		const fieldState = Object.hasOwn(state, field) ? state[field] : void 0;
+		nodes.push({
+			path: [...prefix, field],
+			parser,
+			state: fieldState,
+			matched: isMatchedState(fieldState, parser)
+		});
+	}
+	return nodes;
+}
+
+//#endregion
+exports.buildRuntimeNodesFromPairs = buildRuntimeNodesFromPairs;
+exports.collectExplicitSourceValues = collectExplicitSourceValues;
+exports.collectSourcesFromState = collectSourcesFromState;
+exports.createDependencyRuntimeContext = createDependencyRuntimeContext;
+exports.resolveStateWithRuntime = resolveStateWithRuntime;
+exports.resolveStateWithRuntimeAsync = resolveStateWithRuntimeAsync;

package/dist/dependency-runtime.d.cts

@@ -0,0 +1,123 @@
+import { DependencyRegistryLike } from "./registry-types.cjs";
+import { ValueParserResult } from "./valueparser.cjs";
+
+//#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-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 };