@optique/core 1.1.0-dev.2096 → 1.1.0-dev.2148

package/dist/internal/dependency.cjs

@@ -885,6 +885,37 @@ function getDefaultValuesFunction(parser) {
 	return void 0;
 }
 /**
+* 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) {
+	const multipleIds = dependencyIds in parser ? parser[dependencyIds] : void 0;
+	const defaultValuesFn = getDefaultValuesFunction(parser);
+	let defaultVals = getSnapshottedDefaultDependencyValues(preliminaryResult);
+	if (defaultVals != null) defaultVals = [...defaultVals];
+	if (defaultVals == null && defaultValuesFn != null) try {
+		defaultVals = [...defaultValuesFn()];
+	} catch {
+		defaultVals = void 0;
+	}
+	return {
+		[deferredParseMarker]: true,
+		rawInput,
+		parser,
+		dependencyId: parser[dependencyId],
+		dependencyIds: multipleIds,
+		defaultValues: defaultVals,
+		preliminaryResult
+	};
+}
+/**
 * A unique symbol used to identify dependency source parse states.
 * @since 0.10.0
 */
@@ -931,6 +962,19 @@ function isPendingDependencySourceState(value) {
 	return typeof value === "object" && value !== null && pendingDependencySourceStateMarker in value && value[pendingDependencySourceStateMarker] === true;
 }
 /**
+* Creates a pending dependency source state.
+*
+* @param depId The dependency ID.
+* @returns A PendingDependencySourceState object.
+* @since 0.10.0
+*/
+function createPendingDependencySourceState(depId) {
+	return {
+		[pendingDependencySourceStateMarker]: true,
+		[dependencyId]: depId
+	};
+}
+/**
 * 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.
@@ -950,6 +994,16 @@ const wrappedDependencySourceMarker = Symbol.for("@optique/core/dependency/wrapp
 */
 const transformsDependencyValueMarker = Symbol.for("@optique/core/dependency/transformsDependencyValueMarker");
 /**
+* Checks if a parser transforms the dependency value (has transformsDependencyValueMarker).
+*
+* @param parser The parser to check.
+* @returns `true` if the parser transforms the dependency value.
+* @since 0.10.0
+*/
+function transformsDependencyValue(parser) {
+	return typeof parser === "object" && parser !== null && transformsDependencyValueMarker in parser && parser[transformsDependencyValueMarker] === true;
+}
+/**
 * Checks if a parser wraps a dependency source (has wrappedDependencySourceMarker).
 *
 * @param parser The parser to check.
@@ -959,16 +1013,89 @@ const transformsDependencyValueMarker = Symbol.for("@optique/core/dependency/tra
 function isWrappedDependencySource(parser) {
 	return typeof parser === "object" && parser !== null && wrappedDependencySourceMarker in parser;
 }
+/**
+* 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.DependencyRegistry = DependencyRegistry;
+exports.createDeferredParseState = createDeferredParseState;
 exports.createDependencySourceState = createDependencySourceState;
+exports.createPendingDependencySourceState = createPendingDependencySourceState;
+exports.defaultDependencyValueSnapshot = defaultDependencyValueSnapshot;
 exports.defaultValues = defaultValues;
+exports.deferredParseMarker = deferredParseMarker;
 exports.dependency = dependency;
 exports.dependencyId = dependencyId;
 exports.dependencyIds = dependencyIds;
+exports.dependencySourceMarker = dependencySourceMarker;
+exports.dependencySourceStateMarker = dependencySourceStateMarker;
 exports.deriveFrom = deriveFrom;
 exports.deriveFromAsync = deriveFromAsync;
 exports.deriveFromSync = deriveFromSync;
+exports.derivedValueParserMarker = derivedValueParserMarker;
+exports.formatDependencyError = formatDependencyError;
 exports.getDefaultValuesFunction = getDefaultValuesFunction;
 exports.getDependencyIds = getDependencyIds;
 exports.getSnapshottedDefaultDependencyValues = getSnapshottedDefaultDependencyValues;
@@ -979,6 +1106,10 @@ exports.isDerivedValueParser = isDerivedValueParser;
 exports.isPendingDependencySourceState = isPendingDependencySourceState;
 exports.isWrappedDependencySource = isWrappedDependencySource;
 exports.parseWithDependency = parseWithDependency;
+exports.pendingDependencySourceStateMarker = pendingDependencySourceStateMarker;
 exports.singleDefaultValue = singleDefaultValue;
+exports.snapshotDefaultDependencyValues = snapshotDefaultDependencyValues;
 exports.suggestWithDependency = suggestWithDependency;
+exports.transformsDependencyValue = transformsDependencyValue;
+exports.transformsDependencyValueMarker = transformsDependencyValueMarker;
 exports.wrappedDependencySourceMarker = wrappedDependencySourceMarker;

package/dist/internal/dependency.d.cts

@@ -1,4 +1,6 @@
 import { NonEmptyString } from "../nonempty.cjs";
+import { Message } from "../message.cjs";
+import { DependencyRegistryLike } from "../registry-types.cjs";
 import { ValueParser, ValueParserResult } from "../valueparser.cjs";
 import { Mode, Suggestion } from "./parser.cjs";
 
@@ -51,7 +53,7 @@ declare const singleDefaultValue: unique symbol;
  *
  * @internal
  */
-
+declare const defaultDependencyValueSnapshot: unique symbol;
 /**
  * A unique symbol used to access the parseWithDependency method on derived parsers.
  * @since 0.10.0
@@ -535,5 +537,312 @@ declare function deriveFromAsync<Deps extends readonly AnyDependencySource[], T>
  * @returns A cloned parse result with an internal snapshot attached.
  * @internal
  */
+declare function snapshotDefaultDependencyValues<T>(result: ValueParserResult<T>, values: readonly unknown[]): ValueParserResult<T>;
+/**
+ * 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
+ */
+declare function getSnapshottedDefaultDependencyValues<T>(result: ValueParserResult<T>): readonly unknown[] | undefined;
+/**
+ * A unique symbol used to identify deferred parse states.
+ * @since 0.10.0
+ */
+declare const deferredParseMarker: unique symbol;
+/**
+ * Represents a deferred parse state for a DerivedValueParser.
+ *
+ * When a DerivedValueParser is used in an option or argument, the raw
+ * input string is stored along with the parser reference. The actual
+ * parsing is deferred until `complete()` time when all dependencies
+ * have been resolved.
+ *
+ * @template T The type of value this parser will produce after resolution.
+ * @since 0.10.0
+ */
+interface DeferredParseState<T = unknown> {
+  /**
+   * Marker to identify this as a deferred parse state.
+   */
+  readonly [deferredParseMarker]: true;
+  /**
+   * The raw input string to be parsed.
+   */
+  readonly rawInput: string;
+  /**
+   * The DerivedValueParser that will parse the input.
+   */
+  readonly parser: DerivedValueParser<Mode, T, unknown>;
+  /**
+   * The dependency ID that this parser depends on (for single-dependency parsers).
+   */
+  readonly dependencyId: symbol;
+  /**
+   * The dependency IDs that this parser depends on (for multi-dependency parsers).
+   * If present, this is used instead of `dependencyId`.
+   */
+  readonly dependencyIds?: readonly symbol[];
+  /**
+   * The default values to use for dependencies that are not provided.
+   * For multi-dependency parsers, this is a tuple of default values in order.
+   * For single-dependency parsers, this is the single default value.
+   */
+  readonly defaultValues?: readonly unknown[];
+  /**
+   * The preliminary parse result using the default dependency value.
+   * This is used as a fallback if dependency resolution is not needed
+   * or if the dependency was not provided.
+   */
+  readonly preliminaryResult: ValueParserResult<T>;
+}
+/**
+ * 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
+ */
+declare function isDeferredParseState<T>(value: unknown): value is DeferredParseState<T>;
+/**
+ * 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
+ */
+declare function getDependencyIds<M extends Mode, T, S>(parser: DerivedValueParser<M, T, S>): readonly symbol[];
+/**
+ * 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
+ */
+declare function getDefaultValuesFunction<M extends Mode, T, S>(parser: DerivedValueParser<M, T, S>): (() => readonly unknown[]) | undefined;
+/**
+ * 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
+ */
+declare function createDeferredParseState<T, S>(rawInput: string, parser: DerivedValueParser<Mode, T, S>, preliminaryResult: ValueParserResult<T>): DeferredParseState<T>;
+/**
+ * A unique symbol used to identify dependency source parse states.
+ * @since 0.10.0
+ */
+declare const dependencySourceStateMarker: unique symbol;
+/**
+ * Represents a parse state from a DependencySource.
+ * This wraps the normal ValueParserResult with the dependency ID so that
+ * it can be matched with DeferredParseState during resolution.
+ *
+ * @template T The type of value this state contains.
+ * @since 0.10.0
+ */
+interface DependencySourceState<T = unknown> {
+  /**
+   * Marker to identify this as a dependency source state.
+   */
+  readonly [dependencySourceStateMarker]: true;
+  /**
+   * The dependency ID of the source.
+   */
+  readonly [dependencyId]: symbol;
+  /**
+   * The underlying parse result.
+   */
+  readonly result: ValueParserResult<T>;
+}
+/**
+ * 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
+ */
+declare function isDependencySourceState<T>(value: unknown): value is DependencySourceState<T>;
+/**
+ * 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
+ */
+declare function createDependencySourceState<T>(result: ValueParserResult<T>, depId: symbol): DependencySourceState<T>;
+/**
+ * A unique symbol used to identify pending dependency source states.
+ * @since 0.10.0
+ */
+declare const pendingDependencySourceStateMarker: unique symbol;
+/**
+ * Represents a pending dependency source state.
+ * This is used when a dependency source option was not provided, but its
+ * dependency ID still needs to be tracked for later resolution with a
+ * default value.
+ *
+ * @since 0.10.0
+ */
+interface PendingDependencySourceState {
+  /**
+   * Marker to identify this as a pending dependency source state.
+   */
+  readonly [pendingDependencySourceStateMarker]: true;
+  /**
+   * The dependency ID of the source.
+   */
+  readonly [dependencyId]: symbol;
+}
+/**
+ * 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
+ */
+declare function isPendingDependencySourceState(value: unknown): value is PendingDependencySourceState;
+/**
+ * Creates a pending dependency source state.
+ *
+ * @param depId The dependency ID.
+ * @returns A PendingDependencySourceState object.
+ * @since 0.10.0
+ */
+declare function createPendingDependencySourceState(depId: symbol): PendingDependencySourceState;
+/**
+ * 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
+ */
+declare const wrappedDependencySourceMarker: unique symbol;
+/**
+ * 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
+ */
+declare const transformsDependencyValueMarker: unique symbol;
+/**
+ * Checks if a parser transforms the dependency value (has transformsDependencyValueMarker).
+ *
+ * @param parser The parser to check.
+ * @returns `true` if the parser transforms the dependency value.
+ * @since 0.10.0
+ */
+declare function transformsDependencyValue(parser: unknown): parser is {
+  [transformsDependencyValueMarker]: true;
+};
+/**
+ * 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
+ */
+declare function isWrappedDependencySource(parser: unknown): parser is {
+  [wrappedDependencySourceMarker]: PendingDependencySourceState;
+};
+/**
+ * Represents a resolved dependency value stored during parsing.
+ * @since 0.10.0
+ */
+interface ResolvedDependency<T = unknown> {
+  /**
+   * The dependency ID.
+   */
+  readonly id: symbol;
+  /**
+   * The resolved value.
+   */
+  readonly value: T;
+}
+/**
+ * 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
+ */
+declare class DependencyRegistry implements DependencyRegistryLike {
+  private readonly values;
+  /**
+   * Registers a resolved dependency value.
+   * @param id The dependency ID.
+   * @param value The resolved value.
+   */
+  set<T>(id: symbol, value: T): void;
+  /**
+   * Gets a resolved dependency value.
+   * @param id The dependency ID.
+   * @returns The resolved value, or undefined if not found.
+   */
+  get<T>(id: symbol): T | undefined;
+  /**
+   * Checks if a dependency has been resolved.
+   * @param id The dependency ID.
+   * @returns `true` if the dependency has been resolved.
+   */
+  has(id: symbol): boolean;
+  /**
+   * Creates a copy of the registry.
+   */
+  clone(): DependencyRegistry;
+}
+/**
+ * Error types for dependency resolution failures.
+ * @since 0.10.0
+ */
+type DependencyError = {
+  /**
+   * The dependency was used in multiple locations.
+   */
+  readonly kind: "duplicate";
+  readonly dependencyId: symbol;
+  readonly locations: readonly string[];
+} | {
+  /**
+   * A derived parser references a dependency that was not provided.
+   */
+  readonly kind: "unresolved";
+  readonly dependencyId: symbol;
+  readonly derivedParserMetavar: string;
+} | {
+  /**
+   * Circular dependency detected.
+   */
+  readonly kind: "circular";
+  readonly cycle: readonly symbol[];
+};
+/**
+ * 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
+ */
+declare function formatDependencyError(error: DependencyError): Message;
 //#endregion
-export { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser };
+export { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };