@optique/core 0.10.0-dev.291 → 0.10.0-dev.292

package/dist/constructs.cjs

@@ -1,4 +1,5 @@
 const require_message = require('./message.cjs');
+const require_dependency = require('./dependency.cjs');
 const require_usage = require('./usage.cjs');
 const require_suggestion = require('./suggestion.cjs');
 
@@ -531,6 +532,72 @@ async function* suggestObjectAsync(context, prefix, parserPairs) {
 	}
 	yield* require_suggestion.deduplicateSuggestions(suggestions);
 }
+/**
+* Resolves deferred parse states in an object's field states.
+* This function builds a dependency registry from DependencySourceState fields
+* and re-parses DeferredParseState fields using the actual dependency values.
+*
+* @param fieldStates A record of field names to their state values
+* @returns The field states with deferred states resolved to their actual values
+* @internal
+*/
+function resolveDeferredParseStates(fieldStates) {
+	const registry = new require_dependency.DependencyRegistry();
+	for (const key of Reflect.ownKeys(fieldStates)) {
+		const fieldState = fieldStates[key];
+		if (require_dependency.isDependencySourceState(fieldState)) {
+			const depId = fieldState[require_dependency.DependencyId];
+			const result = fieldState.result;
+			if (result.success) registry.set(depId, result.value);
+		}
+	}
+	const resolvedStates = { ...fieldStates };
+	for (const key of Reflect.ownKeys(fieldStates)) {
+		const fieldState = fieldStates[key];
+		if (require_dependency.isDeferredParseState(fieldState)) {
+			const deferredState = fieldState;
+			const depId = deferredState.dependencyId;
+			if (registry.has(depId)) {
+				const dependencyValue = registry.get(depId);
+				const parser = deferredState.parser;
+				const reParseResult = parser[require_dependency.ParseWithDependency](deferredState.rawInput, dependencyValue);
+				if (reParseResult instanceof Promise) resolvedStates[key] = deferredState.preliminaryResult;
+				else resolvedStates[key] = reParseResult;
+			} else resolvedStates[key] = deferredState.preliminaryResult;
+		}
+	}
+	return resolvedStates;
+}
+/**
+* Async version of resolveDeferredParseStates for async parsers.
+* @internal
+*/
+async function resolveDeferredParseStatesAsync(fieldStates) {
+	const registry = new require_dependency.DependencyRegistry();
+	for (const key of Reflect.ownKeys(fieldStates)) {
+		const fieldState = fieldStates[key];
+		if (require_dependency.isDependencySourceState(fieldState)) {
+			const depId = fieldState[require_dependency.DependencyId];
+			const result = fieldState.result;
+			if (result.success) registry.set(depId, result.value);
+		}
+	}
+	const resolvedStates = { ...fieldStates };
+	for (const key of Reflect.ownKeys(fieldStates)) {
+		const fieldState = fieldStates[key];
+		if (require_dependency.isDeferredParseState(fieldState)) {
+			const deferredState = fieldState;
+			const depId = deferredState.dependencyId;
+			if (registry.has(depId)) {
+				const dependencyValue = registry.get(depId);
+				const parser = deferredState.parser;
+				const reParseResult = parser[require_dependency.ParseWithDependency](deferredState.rawInput, dependencyValue);
+				resolvedStates[key] = await Promise.resolve(reParseResult);
+			} else resolvedStates[key] = deferredState.preliminaryResult;
+		}
+	}
+	return resolvedStates;
+}
 function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
 	let parsers;
@@ -689,10 +756,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			return parseSync(context);
 		},
 		complete(state) {
+			const resolvedState = isAsync ? state : resolveDeferredParseStates(state);
 			if (!isAsync) {
 				const result = {};
 				for (const field of parserKeys) {
-					const valueResult = parsers[field].complete(state[field]);
+					const valueResult = parsers[field].complete(resolvedState[field]);
 					if (valueResult.success) result[field] = valueResult.value;
 					else return {
 						success: false,
@@ -705,9 +773,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				};
 			}
 			return (async () => {
+				const resolvedState$1 = await resolveDeferredParseStatesAsync(state);
 				const result = {};
 				for (const field of parserKeys) {
-					const valueResult = await parsers[field].complete(state[field]);
+					const valueResult = await parsers[field].complete(resolvedState$1[field]);
 					if (valueResult.success) result[field] = valueResult.value;
 					else return {
 						success: false,

package/dist/constructs.js

@@ -1,4 +1,5 @@
 import { message, optionName, values } from "./message.js";
+import { DependencyId, DependencyRegistry, ParseWithDependency, isDeferredParseState, isDependencySourceState } from "./dependency.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames } from "./usage.js";
 import { createErrorWithSuggestions, deduplicateSuggestions } from "./suggestion.js";
 
@@ -531,6 +532,72 @@ async function* suggestObjectAsync(context, prefix, parserPairs) {
 	}
 	yield* deduplicateSuggestions(suggestions);
 }
+/**
+* Resolves deferred parse states in an object's field states.
+* This function builds a dependency registry from DependencySourceState fields
+* and re-parses DeferredParseState fields using the actual dependency values.
+*
+* @param fieldStates A record of field names to their state values
+* @returns The field states with deferred states resolved to their actual values
+* @internal
+*/
+function resolveDeferredParseStates(fieldStates) {
+	const registry = new DependencyRegistry();
+	for (const key of Reflect.ownKeys(fieldStates)) {
+		const fieldState = fieldStates[key];
+		if (isDependencySourceState(fieldState)) {
+			const depId = fieldState[DependencyId];
+			const result = fieldState.result;
+			if (result.success) registry.set(depId, result.value);
+		}
+	}
+	const resolvedStates = { ...fieldStates };
+	for (const key of Reflect.ownKeys(fieldStates)) {
+		const fieldState = fieldStates[key];
+		if (isDeferredParseState(fieldState)) {
+			const deferredState = fieldState;
+			const depId = deferredState.dependencyId;
+			if (registry.has(depId)) {
+				const dependencyValue = registry.get(depId);
+				const parser = deferredState.parser;
+				const reParseResult = parser[ParseWithDependency](deferredState.rawInput, dependencyValue);
+				if (reParseResult instanceof Promise) resolvedStates[key] = deferredState.preliminaryResult;
+				else resolvedStates[key] = reParseResult;
+			} else resolvedStates[key] = deferredState.preliminaryResult;
+		}
+	}
+	return resolvedStates;
+}
+/**
+* Async version of resolveDeferredParseStates for async parsers.
+* @internal
+*/
+async function resolveDeferredParseStatesAsync(fieldStates) {
+	const registry = new DependencyRegistry();
+	for (const key of Reflect.ownKeys(fieldStates)) {
+		const fieldState = fieldStates[key];
+		if (isDependencySourceState(fieldState)) {
+			const depId = fieldState[DependencyId];
+			const result = fieldState.result;
+			if (result.success) registry.set(depId, result.value);
+		}
+	}
+	const resolvedStates = { ...fieldStates };
+	for (const key of Reflect.ownKeys(fieldStates)) {
+		const fieldState = fieldStates[key];
+		if (isDeferredParseState(fieldState)) {
+			const deferredState = fieldState;
+			const depId = deferredState.dependencyId;
+			if (registry.has(depId)) {
+				const dependencyValue = registry.get(depId);
+				const parser = deferredState.parser;
+				const reParseResult = parser[ParseWithDependency](deferredState.rawInput, dependencyValue);
+				resolvedStates[key] = await Promise.resolve(reParseResult);
+			} else resolvedStates[key] = deferredState.preliminaryResult;
+		}
+	}
+	return resolvedStates;
+}
 function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
 	let parsers;
@@ -689,10 +756,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			return parseSync(context);
 		},
 		complete(state) {
+			const resolvedState = isAsync ? state : resolveDeferredParseStates(state);
 			if (!isAsync) {
 				const result = {};
 				for (const field of parserKeys) {
-					const valueResult = parsers[field].complete(state[field]);
+					const valueResult = parsers[field].complete(resolvedState[field]);
 					if (valueResult.success) result[field] = valueResult.value;
 					else return {
 						success: false,
@@ -705,9 +773,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				};
 			}
 			return (async () => {
+				const resolvedState$1 = await resolveDeferredParseStatesAsync(state);
 				const result = {};
 				for (const field of parserKeys) {
-					const valueResult = await parsers[field].complete(state[field]);
+					const valueResult = await parsers[field].complete(resolvedState$1[field]);
 					if (valueResult.success) result[field] = valueResult.value;
 					else return {
 						success: false,

package/dist/dependency.cjs

@@ -0,0 +1,383 @@
+
+//#region src/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 access the parseWithDependency method on derived parsers.
+* @since 0.10.0
+*/
+const ParseWithDependency = Symbol.for("@optique/core/dependency/ParseWithDependency");
+/**
+* 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",
+*   factory: (dir) => gitBranch({ dir }),
+*   defaultValue: () => process.cwd(),
+* });
+* ```
+* @since 0.10.0
+*/
+function dependency(parser) {
+	const id = Symbol();
+	return {
+		...parser,
+		[DependencySourceMarker]: true,
+		[DependencyId]: id,
+		derive(options) {
+			return createDerivedValueParser(id, parser, options);
+		}
+	};
+}
+/**
+* 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",
+*   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"],
+* });
+* ```
+* @since 0.10.0
+*/
+function deriveFrom(options) {
+	const isAsync = options.dependencies.some((dep) => dep.$mode === "async");
+	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][DependencyId] : Symbol();
+	if (isAsync) return createAsyncDerivedFromParser(sourceId, options);
+	return createSyncDerivedFromParser(sourceId, options);
+}
+function createSyncDerivedFromParser(sourceId, options) {
+	return {
+		$mode: "sync",
+		metavar: options.metavar,
+		[DerivedValueParserMarker]: true,
+		[DependencyId]: sourceId,
+		parse(input) {
+			const sourceValues = options.defaultValues();
+			const derivedParser = options.factory(...sourceValues);
+			return derivedParser.parse(input);
+		},
+		[ParseWithDependency](input, dependencyValue) {
+			const derivedParser = options.factory(...dependencyValue);
+			return derivedParser.parse(input);
+		},
+		format(value) {
+			const sourceValues = options.defaultValues();
+			const derivedParser = options.factory(...sourceValues);
+			return derivedParser.format(value);
+		},
+		*suggest(prefix) {
+			const sourceValues = options.defaultValues();
+			const derivedParser = options.factory(...sourceValues);
+			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+		}
+	};
+}
+function createAsyncDerivedFromParser(sourceId, options) {
+	return {
+		$mode: "async",
+		metavar: options.metavar,
+		[DerivedValueParserMarker]: true,
+		[DependencyId]: sourceId,
+		parse(input) {
+			const sourceValues = options.defaultValues();
+			const derivedParser = options.factory(...sourceValues);
+			return Promise.resolve(derivedParser.parse(input));
+		},
+		[ParseWithDependency](input, dependencyValue) {
+			const derivedParser = options.factory(...dependencyValue);
+			return Promise.resolve(derivedParser.parse(input));
+		},
+		format(value) {
+			const sourceValues = options.defaultValues();
+			const derivedParser = options.factory(...sourceValues);
+			return derivedParser.format(value);
+		},
+		async *suggest(prefix) {
+			const sourceValues = options.defaultValues();
+			const derivedParser = options.factory(...sourceValues);
+			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+		}
+	};
+}
+function createDerivedValueParser(sourceId, sourceParser, options) {
+	if (sourceParser.$mode === "async") return createAsyncDerivedParser(sourceId, options);
+	return createSyncDerivedParser(sourceId, options);
+}
+function createSyncDerivedParser(sourceId, options) {
+	return {
+		$mode: "sync",
+		metavar: options.metavar,
+		[DerivedValueParserMarker]: true,
+		[DependencyId]: sourceId,
+		parse(input) {
+			const sourceValue = options.defaultValue();
+			const derivedParser = options.factory(sourceValue);
+			return derivedParser.parse(input);
+		},
+		[ParseWithDependency](input, dependencyValue) {
+			const derivedParser = options.factory(dependencyValue);
+			return derivedParser.parse(input);
+		},
+		format(value) {
+			const sourceValue = options.defaultValue();
+			const derivedParser = options.factory(sourceValue);
+			return derivedParser.format(value);
+		},
+		*suggest(prefix) {
+			const sourceValue = options.defaultValue();
+			const derivedParser = options.factory(sourceValue);
+			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+		}
+	};
+}
+function createAsyncDerivedParser(sourceId, options) {
+	return {
+		$mode: "async",
+		metavar: options.metavar,
+		[DerivedValueParserMarker]: true,
+		[DependencyId]: sourceId,
+		parse(input) {
+			const sourceValue = options.defaultValue();
+			const derivedParser = options.factory(sourceValue);
+			return Promise.resolve(derivedParser.parse(input));
+		},
+		[ParseWithDependency](input, dependencyValue) {
+			const derivedParser = options.factory(dependencyValue);
+			return Promise.resolve(derivedParser.parse(input));
+		},
+		format(value) {
+			const sourceValue = options.defaultValue();
+			const derivedParser = options.factory(sourceValue);
+			return derivedParser.format(value);
+		},
+		async *suggest(prefix) {
+			const sourceValue = options.defaultValue();
+			const derivedParser = options.factory(sourceValue);
+			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;
+}
+/**
+* Creates a deferred parse state for a DerivedValueParser.
+*
+* @template T The type of value the parser will produce.
+* @template S The type of the source dependency value.
+* @param rawInput The raw input string to be parsed.
+* @param parser The DerivedValueParser that will parse the input.
+* @param preliminaryResult The parse result using default dependency value.
+* @returns A DeferredParseState object.
+* @since 0.10.0
+*/
+function createDeferredParseState(rawInput, parser, preliminaryResult) {
+	return {
+		[DeferredParseMarker]: true,
+		rawInput,
+		parser,
+		dependencyId: parser[DependencyId],
+		preliminaryResult
+	};
+}
+/**
+* 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 dependencyId The dependency ID.
+* @returns A DependencySourceState object.
+* @since 0.10.0
+*/
+function createDependencySourceState(result, dependencyId) {
+	return {
+		[DependencySourceStateMarker]: true,
+		[DependencyId]: dependencyId,
+		result
+	};
+}
+/**
+* A registry for storing resolved dependency values during parsing.
+* This is used to pass dependency values from DependencySource options
+* to DerivedValueParser options.
+* @since 0.10.0
+*/
+var DependencyRegistry = class DependencyRegistry {
+	values = /* @__PURE__ */ new Map();
+	/**
+	* Registers a resolved dependency value.
+	* @param id The dependency ID.
+	* @param value The resolved value.
+	*/
+	set(id, value) {
+		this.values.set(id, value);
+	}
+	/**
+	* Gets a resolved dependency value.
+	* @param id The dependency ID.
+	* @returns The resolved value, or undefined if not found.
+	*/
+	get(id) {
+		return this.values.get(id);
+	}
+	/**
+	* Checks if a dependency has been resolved.
+	* @param id The dependency ID.
+	* @returns `true` if the dependency has been resolved.
+	*/
+	has(id) {
+		return this.values.has(id);
+	}
+	/**
+	* Creates a copy of the registry.
+	*/
+	clone() {
+		const copy = new DependencyRegistry();
+		for (const [id, value] of this.values) copy.values.set(id, value);
+		return copy;
+	}
+};
+/**
+* Formats a {@link DependencyError} into a human-readable {@link Message}.
+*
+* @param error The dependency error to format.
+* @returns A Message describing the error.
+* @since 0.10.0
+*/
+function formatDependencyError(error) {
+	switch (error.kind) {
+		case "duplicate": return [{
+			type: "text",
+			text: `Dependency used in multiple locations: ${error.locations.join(", ")}.`
+		}];
+		case "unresolved": return [{
+			type: "text",
+			text: `Unresolved dependency for ${error.derivedParserMetavar}: the dependency was not provided.`
+		}];
+		case "circular": return [{
+			type: "text",
+			text: `Circular dependency detected.`
+		}];
+	}
+}
+
+//#endregion
+exports.DeferredParseMarker = DeferredParseMarker;
+exports.DependencyId = DependencyId;
+exports.DependencyRegistry = DependencyRegistry;
+exports.DependencySourceMarker = DependencySourceMarker;
+exports.DependencySourceStateMarker = DependencySourceStateMarker;
+exports.DerivedValueParserMarker = DerivedValueParserMarker;
+exports.ParseWithDependency = ParseWithDependency;
+exports.createDeferredParseState = createDeferredParseState;
+exports.createDependencySourceState = createDependencySourceState;
+exports.dependency = dependency;
+exports.deriveFrom = deriveFrom;
+exports.formatDependencyError = formatDependencyError;
+exports.isDeferredParseState = isDeferredParseState;
+exports.isDependencySource = isDependencySource;
+exports.isDependencySourceState = isDependencySourceState;
+exports.isDerivedValueParser = isDerivedValueParser;