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

package/dist/dependency.cjs

@@ -0,0 +1,528 @@
+
+//#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();
+	const result = {
+		...parser,
+		[DependencySourceMarker]: true,
+		[DependencyId]: id,
+		derive(options) {
+			return createDerivedValueParser(id, parser, options);
+		},
+		deriveSync(options) {
+			if (parser.$mode === "async") return createAsyncDerivedParserFromSyncFactory(id, options);
+			return createSyncDerivedParser(id, options);
+		},
+		deriveAsync(options) {
+			return createDerivedValueParser(id, parser, 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",
+*   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 depsAsync = options.dependencies.some((dep) => dep.$mode === "async");
+	const factoryReturnsAsync = determineFactoryModeForDeriveFrom(options);
+	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][DependencyId] : Symbol();
+	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);
+}
+/**
+* Determines if the factory returns an async parser for deriveFrom options.
+*/
+function determineFactoryModeForDeriveFrom(options) {
+	const defaultValues = options.defaultValues();
+	const parser = options.factory(...defaultValues);
+	return parser.$mode === "async";
+}
+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);
+		}
+	};
+}
+/**
+* Creates an async derived parser from multiple dependencies when the
+* factory returns an async parser.
+*/
+function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
+	return {
+		$mode: "async",
+		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);
+		},
+		async *suggest(prefix) {
+			const sourceValues = options.defaultValues();
+			const derivedParser = options.factory(...sourceValues);
+			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) {
+	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) {
+	const factoryReturnsAsync = determineFactoryMode(options);
+	const isAsync = sourceParser.$mode === "async" || factoryReturnsAsync;
+	if (isAsync) {
+		if (factoryReturnsAsync) return createAsyncDerivedParserFromAsyncFactory(sourceId, options);
+		return createAsyncDerivedParserFromSyncFactory(sourceId, options);
+	}
+	return createSyncDerivedParser(sourceId, options);
+}
+/**
+* Determines if the factory returns an async parser by calling it with
+* the default value and checking the mode.
+*/
+function determineFactoryMode(options) {
+	const defaultValue = options.defaultValue();
+	const parser = options.factory(defaultValue);
+	return parser.$mode === "async";
+}
+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);
+		}
+	};
+}
+/**
+* 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,
+		[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);
+		},
+		async *suggest(prefix) {
+			const sourceValue = options.defaultValue();
+			const derivedParser = options.factory(sourceValue);
+			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,
+		[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.deriveFromAsync = deriveFromAsync;
+exports.deriveFromSync = deriveFromSync;
+exports.formatDependencyError = formatDependencyError;
+exports.isDeferredParseState = isDeferredParseState;
+exports.isDependencySource = isDependencySource;
+exports.isDependencySourceState = isDependencySourceState;
+exports.isDerivedValueParser = isDerivedValueParser;