@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/internal/dependency.js

@@ -0,0 +1,964 @@
+import { message } from "../message.js";
+
+//#region src/internal/dependency.ts
+/**
+* A unique symbol used to identify dependency sources at compile time.
+* This marker is used to distinguish {@link DependencySource} from regular
+* {@link ValueParser} instances.
+* @since 0.10.0
+*/
+const dependencySourceMarker = Symbol.for("@optique/core/dependency/dependencySourceMarker");
+/**
+* A unique symbol used to identify derived value parsers at compile time.
+* This marker is used to distinguish {@link DerivedValueParser} from regular
+* {@link ValueParser} instances.
+* @since 0.10.0
+*/
+const derivedValueParserMarker = Symbol.for("@optique/core/dependency/derivedValueParserMarker");
+/**
+* A unique symbol used to store the dependency ID on value parsers.
+* @since 0.10.0
+*/
+const dependencyId = Symbol.for("@optique/core/dependency/dependencyId");
+/**
+* A unique symbol used to store multiple dependency IDs on derived parsers
+* that depend on multiple sources (created via {@link deriveFrom}).
+* @since 0.10.0
+*/
+const dependencyIds = Symbol.for("@optique/core/dependency/dependencyIds");
+/**
+* A unique symbol used to store the default values function on derived parsers.
+* This is used during partial dependency resolution to fill in missing values.
+* @since 0.10.0
+*/
+const defaultValues = Symbol.for("@optique/core/dependency/defaultValues");
+/**
+* A unique symbol used to store the single default value thunk on derived
+* parsers created by {@link DependencySource.derive}.  Unlike
+* {@link defaultValues} (which `createDeferredParseState` only falls back to
+* when no parse-time snapshot is available), this symbol is only read by the
+* dependency-metadata bridge so that
+* single-source defaults are accessible without double evaluation.
+* @internal
+*/
+const singleDefaultValue = Symbol.for("@optique/core/dependency/singleDefaultValue");
+/**
+* A unique symbol used to store the snapshotted default dependency values on
+* a parse result produced by a derived parser's default path.
+*
+* @internal
+*/
+const defaultDependencyValueSnapshot = Symbol.for("@optique/core/dependency/defaultDependencyValueSnapshot");
+/**
+* A unique symbol used to access the parseWithDependency method on derived parsers.
+* @since 0.10.0
+*/
+const parseWithDependency = Symbol.for("@optique/core/dependency/parseWithDependency");
+/**
+* A unique symbol used to access the suggestWithDependency method on derived parsers.
+* This method generates suggestions using the provided dependency values instead of defaults.
+* @since 0.10.0
+*/
+const suggestWithDependency = Symbol.for("@optique/core/dependency/suggestWithDependency");
+/**
+* Creates a dependency source from a {@link ValueParser}.
+*
+* A dependency source wraps an existing value parser and enables creating
+* derived parsers that depend on the parsed value. This is useful for
+* scenarios where one option's valid values depend on another option's value.
+*
+* @template M The execution mode of the value parser.
+* @template T The type of value the parser produces.
+* @param parser The value parser to wrap as a dependency source.
+* @returns A {@link DependencySource} that can be used to create
+*          derived parsers.
+* @example
+* ```typescript
+* import { dependency } from "@optique/core/dependency";
+* import { string } from "@optique/core/valueparser";
+*
+* // Create a dependency source for a directory path
+* const cwdParser = dependency(string({ metavar: "DIR" }));
+*
+* // Create a derived parser that depends on the directory
+* const branchParser = cwdParser.derive({
+*   metavar: "BRANCH",
+*   mode: "sync",
+*   factory: (dir) => gitBranch({ dir }),
+*   defaultValue: () => process.cwd(),
+* });
+* ```
+* @since 0.10.0
+*/
+function dependency(parser) {
+	const id = Symbol();
+	const result = {
+		...parser,
+		[dependencySourceMarker]: true,
+		[dependencyId]: id,
+		derive(options) {
+			if (options.mode !== "sync" && options.mode !== "async") throw new TypeError("derive() requires an explicit mode field (\"sync\" or \"async\").");
+			return createDerivedValueParser(id, parser, options, options.mode);
+		},
+		deriveSync(options) {
+			if (parser.mode === "async") return createAsyncDerivedParserFromSyncFactory(id, options);
+			return createSyncDerivedParser(id, options);
+		},
+		deriveAsync(options) {
+			return createAsyncDerivedParserFromAsyncFactory(id, options);
+		}
+	};
+	return result;
+}
+/**
+* Checks if a value parser is a {@link DependencySource}.
+*
+* @param parser The value parser to check.
+* @returns `true` if the parser is a dependency source, `false` otherwise.
+* @since 0.10.0
+*/
+function isDependencySource(parser) {
+	return dependencySourceMarker in parser && parser[dependencySourceMarker] === true;
+}
+/**
+* Checks if a value parser is a {@link DerivedValueParser}.
+*
+* @param parser The value parser to check.
+* @returns `true` if the parser is a derived value parser, `false` otherwise.
+* @since 0.10.0
+*/
+function isDerivedValueParser(parser) {
+	return derivedValueParserMarker in parser && parser[derivedValueParserMarker] === true;
+}
+/**
+* Creates a derived value parser from multiple dependency sources.
+*
+* This function allows creating a parser whose behavior depends on
+* multiple other parsers' values. This is useful for scenarios where
+* an option's valid values depend on a combination of other options.
+*
+* @template Deps A tuple of DependencySource types.
+* @template T The type of value the derived parser produces.
+* @param options Configuration for the derived parser.
+* @returns A {@link DerivedValueParser} that depends on the given sources.
+* @example
+* ```typescript
+* import { dependency, deriveFrom } from "@optique/core/dependency";
+* import { string, choice } from "@optique/core/valueparser";
+*
+* const dirParser = dependency(string({ metavar: "DIR" }));
+* const modeParser = dependency(choice(["dev", "prod"]));
+*
+* const configParser = deriveFrom({
+*   metavar: "CONFIG",
+*   mode: "sync",
+*   dependencies: [dirParser, modeParser] as const,
+*   factory: (dir, mode) =>
+*     choice(mode === "dev"
+*       ? [`${dir}/dev.json`, `${dir}/dev.yaml`]
+*       : [`${dir}/prod.json`, `${dir}/prod.yaml`]),
+*   defaultValues: () => ["/config", "dev"],
+* });
+* ```
+* @throws {TypeError} If the `mode` field is missing or invalid.
+* @since 0.10.0
+*/
+function deriveFrom(options) {
+	if (options.mode !== "sync" && options.mode !== "async") throw new TypeError("deriveFrom() requires an explicit mode field (\"sync\" or \"async\").");
+	const depsAsync = options.dependencies.some((dep) => dep.mode === "async");
+	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
+	const factoryReturnsAsync = options.mode === "async";
+	const isAsync = depsAsync || factoryReturnsAsync;
+	if (isAsync) {
+		if (factoryReturnsAsync) return createAsyncDerivedFromParserFromAsyncFactory(sourceId, options);
+		return createAsyncDerivedFromParserFromSyncFactory(sourceId, options);
+	}
+	return createSyncDerivedFromParser(sourceId, options);
+}
+/**
+* Creates a derived value parser from multiple dependency sources
+* with a synchronous factory.
+*
+* This function allows creating a parser whose behavior depends on
+* multiple other parsers' values. The factory explicitly returns
+* a sync parser.
+*
+* @template Deps A tuple of DependencySource types.
+* @template T The type of value the derived parser produces.
+* @param options Configuration for the derived parser with sync factory.
+* @returns A {@link DerivedValueParser} that depends on the given sources.
+* @since 0.10.0
+*/
+function deriveFromSync(options) {
+	const depsAsync = options.dependencies.some((dep) => dep.mode === "async");
+	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
+	if (depsAsync) return createAsyncDerivedFromParserFromSyncFactory(sourceId, options);
+	return createSyncDerivedFromParser(sourceId, options);
+}
+/**
+* Creates a derived value parser from multiple dependency sources
+* with an asynchronous factory.
+*
+* This function allows creating a parser whose behavior depends on
+* multiple other parsers' values. The factory explicitly returns
+* an async parser.
+*
+* @template Deps A tuple of DependencySource types.
+* @template T The type of value the derived parser produces.
+* @param options Configuration for the derived parser with async factory.
+* @returns A {@link DerivedValueParser} that depends on the given sources.
+* @since 0.10.0
+*/
+function deriveFromAsync(options) {
+	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
+	return createAsyncDerivedFromParserFromAsyncFactory(sourceId, options);
+}
+function isAsyncModeParser(parser) {
+	return parser.mode === "async";
+}
+/**
+* Shared helper for derived value parser `normalize()` implementations.
+* Builds the inner parser from the factory and delegates to its
+* `normalize()` if available, falling back to the original value on error.
+*/
+function normalizeWithDerivedParser(value, getParser) {
+	let derivedParser;
+	try {
+		derivedParser = getParser();
+	} catch {
+		return value;
+	}
+	if (derivedParser && typeof derivedParser.normalize === "function") try {
+		return derivedParser.normalize(value);
+	} catch {
+		return value;
+	}
+	return value;
+}
+/**
+* Attaches a default dependency snapshot to a derived parser's parse result.
+*
+* @param result The parse result to annotate.
+* @param values The dependency values used for the default-path parse.
+* @returns A cloned parse result with an internal snapshot attached.
+* @internal
+*/
+function snapshotDefaultDependencyValues(result, values) {
+	const snapshot = getSnapshottedDefaultDependencyValues(result) ?? values;
+	return attachDefaultDependencySnapshot(result, snapshot);
+}
+function attachDefaultDependencySnapshot(result, values) {
+	const annotated = Object.create(Object.getPrototypeOf(result), Object.getOwnPropertyDescriptors(result));
+	Object.defineProperty(annotated, defaultDependencyValueSnapshot, {
+		value: [...values],
+		configurable: true,
+		enumerable: false
+	});
+	return annotated;
+}
+/**
+* Reads the snapshotted default dependency values from a parse result.
+*
+* @param result The parse result to inspect.
+* @returns The snapshotted dependency values, if present.
+* @internal
+*/
+function getSnapshottedDefaultDependencyValues(result) {
+	return result[defaultDependencyValueSnapshot];
+}
+async function parseDerivedResultAsync(parser, input) {
+	return await parser.parse(input);
+}
+function parseDerivedResultSync(parser, input) {
+	const result = parser.parse(input);
+	if (isPromiseLike(result)) throw new TypeError("Sync derived parser parse() returned a promise-like result. Use an async derived parser instead.");
+	return result;
+}
+function isPromiseLike(value) {
+	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
+}
+async function parseDerivedResultWithSnapshotAsync(parser, input, sourceValues) {
+	const snapshot = [...sourceValues];
+	return attachDefaultDependencySnapshot(await parseDerivedResultAsync(parser, input), snapshot);
+}
+function createSyncDerivedFromParser(sourceId, options) {
+	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
+	return {
+		mode: "sync",
+		metavar: options.metavar,
+		get placeholder() {
+			try {
+				return options.factory(...options.defaultValues()).placeholder;
+			} catch {
+				return void 0;
+			}
+		},
+		[derivedValueParserMarker]: true,
+		[dependencyId]: sourceId,
+		[dependencyIds]: alldependencyIds,
+		[defaultValues]: options.defaultValues,
+		parse(input) {
+			let derivedParser;
+			let sourceValues;
+			try {
+				sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				const failure = {
+					success: false,
+					error: message`Derived parser error: ${msg}`
+				};
+				return sourceValues == null ? failure : snapshotDefaultDependencyValues(failure, sourceValues);
+			}
+			if (isAsyncModeParser(derivedParser)) {
+				const failure = {
+					success: false,
+					error: message`Factory returned an async parser where a sync parser is required.`
+				};
+				return sourceValues == null ? failure : snapshotDefaultDependencyValues(failure, sourceValues);
+			}
+			const snapshot = [...sourceValues];
+			return attachDefaultDependencySnapshot(parseDerivedResultSync(derivedParser, input), snapshot);
+		},
+		[parseWithDependency](input, dependencyValue) {
+			let derivedParser;
+			try {
+				derivedParser = options.factory(...dependencyValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return {
+					success: false,
+					error: message`Factory error: ${msg}`
+				};
+			}
+			if (isAsyncModeParser(derivedParser)) {
+				const failure = {
+					success: false,
+					error: message`Factory returned an async parser where a sync parser is required.`
+				};
+				return failure;
+			}
+			return parseDerivedResultSync(derivedParser, input);
+		},
+		format(value) {
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return String(value);
+			}
+			return derivedParser.format(value);
+		},
+		*suggest(prefix) {
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return;
+			}
+			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
+			yield* derivedParser.suggest(prefix);
+		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(...options.defaultValues()));
+		},
+		*[suggestWithDependency](prefix, dependencyValue) {
+			let derivedParser;
+			try {
+				derivedParser = options.factory(...dependencyValue);
+			} catch {
+				try {
+					const sourceValues = options.defaultValues();
+					derivedParser = options.factory(...sourceValues);
+				} catch {
+					return;
+				}
+			}
+			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
+			yield* derivedParser.suggest(prefix);
+		}
+	};
+}
+/**
+* Creates an async derived parser from multiple dependencies when the
+* factory returns an async parser.
+*/
+function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
+	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
+	return {
+		mode: "async",
+		metavar: options.metavar,
+		get placeholder() {
+			try {
+				return options.factory(...options.defaultValues()).placeholder;
+			} catch {
+				return void 0;
+			}
+		},
+		[derivedValueParserMarker]: true,
+		[dependencyId]: sourceId,
+		[dependencyIds]: alldependencyIds,
+		[defaultValues]: options.defaultValues,
+		async parse(input) {
+			let derivedParser;
+			let sourceValues;
+			try {
+				sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				const failure = {
+					success: false,
+					error: message`Derived parser error: ${msg}`
+				};
+				return sourceValues == null ? failure : snapshotDefaultDependencyValues(failure, sourceValues);
+			}
+			return await parseDerivedResultWithSnapshotAsync(derivedParser, input, sourceValues);
+		},
+		async [parseWithDependency](input, dependencyValue) {
+			let derivedParser;
+			try {
+				derivedParser = options.factory(...dependencyValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return {
+					success: false,
+					error: message`Factory error: ${msg}`
+				};
+			}
+			return await parseDerivedResultAsync(derivedParser, input);
+		},
+		format(value) {
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return String(value);
+			}
+			return derivedParser.format(value);
+		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(...options.defaultValues()));
+		},
+		async *suggest(prefix) {
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return;
+			}
+			if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
+		},
+		async *[suggestWithDependency](prefix, dependencyValue) {
+			let derivedParser;
+			try {
+				derivedParser = options.factory(...dependencyValue);
+			} catch {
+				try {
+					const sourceValues = options.defaultValues();
+					derivedParser = options.factory(...sourceValues);
+				} catch {
+					return;
+				}
+			}
+			if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
+		}
+	};
+}
+/**
+* Creates an async derived parser from multiple dependencies when the
+* sources are async but the factory returns a sync parser.
+*/
+function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
+	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
+	return {
+		mode: "async",
+		metavar: options.metavar,
+		get placeholder() {
+			try {
+				return options.factory(...options.defaultValues()).placeholder;
+			} catch {
+				return void 0;
+			}
+		},
+		[derivedValueParserMarker]: true,
+		[dependencyId]: sourceId,
+		[dependencyIds]: alldependencyIds,
+		[defaultValues]: options.defaultValues,
+		async parse(input) {
+			let derivedParser;
+			let sourceValues;
+			try {
+				sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				const failure = {
+					success: false,
+					error: message`Derived parser error: ${msg}`
+				};
+				return sourceValues == null ? failure : snapshotDefaultDependencyValues(failure, sourceValues);
+			}
+			return await parseDerivedResultWithSnapshotAsync(derivedParser, input, sourceValues);
+		},
+		async [parseWithDependency](input, dependencyValue) {
+			let derivedParser;
+			try {
+				derivedParser = options.factory(...dependencyValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return {
+					success: false,
+					error: message`Factory error: ${msg}`
+				};
+			}
+			return await parseDerivedResultAsync(derivedParser, input);
+		},
+		format(value) {
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return String(value);
+			}
+			return derivedParser.format(value);
+		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(...options.defaultValues()));
+		},
+		async *suggest(prefix) {
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return;
+			}
+			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+		},
+		*[suggestWithDependency](prefix, dependencyValue) {
+			let derivedParser;
+			try {
+				derivedParser = options.factory(...dependencyValue);
+			} catch {
+				try {
+					const sourceValues = options.defaultValues();
+					derivedParser = options.factory(...sourceValues);
+				} catch {
+					return;
+				}
+			}
+			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+		}
+	};
+}
+function createDerivedValueParser(sourceId, sourceParser, options, factoryMode) {
+	const factoryReturnsAsync = factoryMode === "async";
+	const isAsync = sourceParser.mode === "async" || factoryReturnsAsync;
+	if (isAsync) {
+		if (factoryReturnsAsync) return createAsyncDerivedParserFromAsyncFactory(sourceId, options);
+		return createAsyncDerivedParserFromSyncFactory(sourceId, options);
+	}
+	return createSyncDerivedParser(sourceId, options);
+}
+function createSyncDerivedParser(sourceId, options) {
+	return {
+		mode: "sync",
+		metavar: options.metavar,
+		get placeholder() {
+			try {
+				return options.factory(options.defaultValue()).placeholder;
+			} catch {
+				return void 0;
+			}
+		},
+		[derivedValueParserMarker]: true,
+		[dependencyId]: sourceId,
+		[singleDefaultValue]: options.defaultValue,
+		parse(input) {
+			let derivedParser;
+			let hasSourceValue = false;
+			let sourceValue;
+			try {
+				sourceValue = options.defaultValue();
+				hasSourceValue = true;
+				derivedParser = options.factory(sourceValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				const failure = {
+					success: false,
+					error: message`Derived parser error: ${msg}`
+				};
+				return hasSourceValue ? snapshotDefaultDependencyValues(failure, [sourceValue]) : failure;
+			}
+			if (isAsyncModeParser(derivedParser)) {
+				const failure = {
+					success: false,
+					error: message`Factory returned an async parser where a sync parser is required.`
+				};
+				return hasSourceValue ? snapshotDefaultDependencyValues(failure, [sourceValue]) : failure;
+			}
+			return attachDefaultDependencySnapshot(parseDerivedResultSync(derivedParser, input), [sourceValue]);
+		},
+		[parseWithDependency](input, dependencyValue) {
+			let derivedParser;
+			try {
+				derivedParser = options.factory(dependencyValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return {
+					success: false,
+					error: message`Factory error: ${msg}`
+				};
+			}
+			if (isAsyncModeParser(derivedParser)) return {
+				success: false,
+				error: message`Factory returned an async parser where a sync parser is required.`
+			};
+			return parseDerivedResultSync(derivedParser, input);
+		},
+		format(value) {
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return String(value);
+			}
+			return derivedParser.format(value);
+		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(options.defaultValue()));
+		},
+		*suggest(prefix) {
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return;
+			}
+			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
+			yield* derivedParser.suggest(prefix);
+		},
+		*[suggestWithDependency](prefix, dependencyValue) {
+			let derivedParser;
+			try {
+				derivedParser = options.factory(dependencyValue);
+			} catch {
+				try {
+					derivedParser = options.factory(options.defaultValue());
+				} catch {
+					return;
+				}
+			}
+			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
+			yield* derivedParser.suggest(prefix);
+		}
+	};
+}
+/**
+* Creates an async derived parser when the factory returns an async parser.
+* The parse result is awaited since the factory returns an async parser.
+*/
+function createAsyncDerivedParserFromAsyncFactory(sourceId, options) {
+	return {
+		mode: "async",
+		metavar: options.metavar,
+		get placeholder() {
+			try {
+				return options.factory(options.defaultValue()).placeholder;
+			} catch {
+				return void 0;
+			}
+		},
+		[derivedValueParserMarker]: true,
+		[dependencyId]: sourceId,
+		[singleDefaultValue]: options.defaultValue,
+		async parse(input) {
+			let derivedParser;
+			let hasSourceValue = false;
+			let sourceValue;
+			try {
+				sourceValue = options.defaultValue();
+				hasSourceValue = true;
+				derivedParser = options.factory(sourceValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				const failure = {
+					success: false,
+					error: message`Derived parser error: ${msg}`
+				};
+				return hasSourceValue ? snapshotDefaultDependencyValues(failure, [sourceValue]) : failure;
+			}
+			return await parseDerivedResultWithSnapshotAsync(derivedParser, input, [sourceValue]);
+		},
+		async [parseWithDependency](input, dependencyValue) {
+			let derivedParser;
+			try {
+				derivedParser = options.factory(dependencyValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return {
+					success: false,
+					error: message`Factory error: ${msg}`
+				};
+			}
+			return await parseDerivedResultAsync(derivedParser, input);
+		},
+		format(value) {
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return String(value);
+			}
+			return derivedParser.format(value);
+		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(options.defaultValue()));
+		},
+		async *suggest(prefix) {
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return;
+			}
+			if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
+		},
+		async *[suggestWithDependency](prefix, dependencyValue) {
+			let derivedParser;
+			try {
+				derivedParser = options.factory(dependencyValue);
+			} catch {
+				try {
+					derivedParser = options.factory(options.defaultValue());
+				} catch {
+					return;
+				}
+			}
+			if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
+		}
+	};
+}
+/**
+* Creates an async derived parser when the source is async but the factory
+* returns a sync parser. The sync result is wrapped in a Promise.
+*/
+function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
+	return {
+		mode: "async",
+		metavar: options.metavar,
+		get placeholder() {
+			try {
+				return options.factory(options.defaultValue()).placeholder;
+			} catch {
+				return void 0;
+			}
+		},
+		[derivedValueParserMarker]: true,
+		[dependencyId]: sourceId,
+		[singleDefaultValue]: options.defaultValue,
+		async parse(input) {
+			let derivedParser;
+			let hasSourceValue = false;
+			let sourceValue;
+			try {
+				sourceValue = options.defaultValue();
+				hasSourceValue = true;
+				derivedParser = options.factory(sourceValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				const failure = {
+					success: false,
+					error: message`Derived parser error: ${msg}`
+				};
+				return hasSourceValue ? snapshotDefaultDependencyValues(failure, [sourceValue]) : failure;
+			}
+			return await parseDerivedResultWithSnapshotAsync(derivedParser, input, [sourceValue]);
+		},
+		async [parseWithDependency](input, dependencyValue) {
+			let derivedParser;
+			try {
+				derivedParser = options.factory(dependencyValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return {
+					success: false,
+					error: message`Factory error: ${msg}`
+				};
+			}
+			return await parseDerivedResultAsync(derivedParser, input);
+		},
+		format(value) {
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return String(value);
+			}
+			return derivedParser.format(value);
+		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(options.defaultValue()));
+		},
+		async *suggest(prefix) {
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return;
+			}
+			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+		},
+		*[suggestWithDependency](prefix, dependencyValue) {
+			let derivedParser;
+			try {
+				derivedParser = options.factory(dependencyValue);
+			} catch {
+				try {
+					derivedParser = options.factory(options.defaultValue());
+				} catch {
+					return;
+				}
+			}
+			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+		}
+	};
+}
+/**
+* A unique symbol used to identify deferred parse states.
+* @since 0.10.0
+*/
+const deferredParseMarker = Symbol.for("@optique/core/dependency/deferredParseMarker");
+/**
+* Checks if a value is a {@link DeferredParseState}.
+*
+* @param value The value to check.
+* @returns `true` if the value is a deferred parse state, `false` otherwise.
+* @since 0.10.0
+*/
+function isDeferredParseState(value) {
+	return typeof value === "object" && value !== null && deferredParseMarker in value && value[deferredParseMarker] === true;
+}
+/**
+* Gets all dependency IDs from a derived parser.
+* If the parser was created with `deriveFrom` (multiple dependencies),
+* returns the array of dependency IDs. Otherwise, returns an array
+* containing the single dependency ID.
+*
+* @param parser The derived value parser to get dependency IDs from.
+* @returns An array of dependency ID symbols.
+* @internal
+* @since 0.10.0
+*/
+function getDependencyIds(parser) {
+	if (dependencyIds in parser) return parser[dependencyIds];
+	return [parser[dependencyId]];
+}
+/**
+* Gets the default values function from a multi-source derived parser, if
+* present.
+*
+* Single-source `derive()` defaults must stay lazy during suggestion-time
+* replay so missing dependencies do not eagerly evaluate side-effectful
+* `defaultValue()` thunks.
+*
+* @param parser The derived value parser to get the default values function from.
+* @returns The default values function, or undefined if not available.
+* @internal
+* @since 0.10.0
+*/
+function getDefaultValuesFunction(parser) {
+	if (Object.hasOwn(parser, defaultValues)) return parser[defaultValues];
+	return void 0;
+}
+/**
+* A unique symbol used to identify dependency source parse states.
+* @since 0.10.0
+*/
+const dependencySourceStateMarker = Symbol.for("@optique/core/dependency/dependencySourceStateMarker");
+/**
+* Checks if a value is a {@link DependencySourceState}.
+*
+* @param value The value to check.
+* @returns `true` if the value is a dependency source state, `false` otherwise.
+* @since 0.10.0
+*/
+function isDependencySourceState(value) {
+	return typeof value === "object" && value !== null && dependencySourceStateMarker in value && value[dependencySourceStateMarker] === true;
+}
+/**
+* Creates a dependency source state from a parse result.
+*
+* @template T The type of value the state contains.
+* @param result The parse result.
+* @param depId The dependency ID.
+* @returns A DependencySourceState object.
+* @since 0.10.0
+*/
+function createDependencySourceState(result, depId) {
+	return {
+		[dependencySourceStateMarker]: true,
+		[dependencyId]: depId,
+		result
+	};
+}
+/**
+* A unique symbol used to identify pending dependency source states.
+* @since 0.10.0
+*/
+const pendingDependencySourceStateMarker = Symbol.for("@optique/core/dependency/pendingDependencySourceStateMarker");
+/**
+* Checks if a value is a {@link PendingDependencySourceState}.
+*
+* @param value The value to check.
+* @returns `true` if the value is a pending dependency source state.
+* @since 0.10.0
+*/
+function isPendingDependencySourceState(value) {
+	return typeof value === "object" && value !== null && pendingDependencySourceStateMarker in value && value[pendingDependencySourceStateMarker] === true;
+}
+/**
+* A unique symbol used to identify parsers that wrap a dependency source.
+* This is used by withDefault to indicate it contains an inner parser
+* with a PendingDependencySourceState initialState.
+* @since 0.10.0
+*/
+const wrappedDependencySourceMarker = Symbol.for("@optique/core/dependency/wrappedDependencySourceMarker");
+/**
+* A unique symbol used to indicate that a wrapper transforms the dependency
+* source value. This is used by withDefault to determine whether its default
+* value should be registered as the dependency value.
+*
+* When a wrapper has this marker set to `true`, it means the wrapper transforms
+* the dependency source value (e.g., via map()), so the wrapper's output is NOT
+* a valid dependency source value.
+*
+* @since 0.10.0
+*/
+const transformsDependencyValueMarker = Symbol.for("@optique/core/dependency/transformsDependencyValueMarker");
+/**
+* Checks if a parser wraps a dependency source (has wrappedDependencySourceMarker).
+*
+* @param parser The parser to check.
+* @returns `true` if the parser wraps a dependency source.
+* @since 0.10.0
+*/
+function isWrappedDependencySource(parser) {
+	return typeof parser === "object" && parser !== null && wrappedDependencySourceMarker in parser;
+}
+
+//#endregion
+export { createDependencySourceState, defaultValues, dependency, dependencyId, dependencyIds, deriveFrom, deriveFromAsync, deriveFromSync, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, singleDefaultValue, suggestWithDependency, wrappedDependencySourceMarker };