@optique/core 1.0.0-dev.1596 → 1.0.0-dev.1602

package/dist/dependency-metadata.cjs

@@ -0,0 +1,140 @@
+const require_dependency = require('./dependency.cjs');
+
+//#region src/dependency-metadata.ts
+/**
+* Extracts {@link ParserDependencyMetadata} from a value parser by reading
+* old-protocol markers (`dependencySourceMarker`, `derivedValueParserMarker`,
+* etc.).
+*
+* Returns `undefined` if the parser has no dependency-related markers.
+*
+* @param valueParser The value parser to inspect.
+* @returns Metadata, or `undefined` for plain parsers.
+* @internal
+* @since 1.0.0
+*/
+function extractDependencyMetadata(valueParser) {
+	if (require_dependency.isDependencySource(valueParser)) return { source: {
+		kind: "source",
+		sourceId: valueParser[require_dependency.dependencyId],
+		extractSourceValue: extractFromBareState,
+		preservesSourceValue: true
+	} };
+	if (require_dependency.isDerivedValueParser(valueParser)) {
+		const isMultiSource = require_dependency.dependencyIds in valueParser && valueParser[require_dependency.dependencyIds] != null;
+		const allIds = isMultiSource ? valueParser[require_dependency.dependencyIds] : [valueParser[require_dependency.dependencyId]];
+		let defaultValuesFn;
+		if (require_dependency.defaultValues in valueParser && valueParser[require_dependency.defaultValues] != null) defaultValuesFn = valueParser[require_dependency.defaultValues];
+		else if (require_dependency.singleDefaultValue in valueParser && valueParser[require_dependency.singleDefaultValue] != null) {
+			const singleFn = valueParser[require_dependency.singleDefaultValue];
+			defaultValuesFn = () => [singleFn()];
+		}
+		const parser = valueParser;
+		const replayParse = (rawInput, depValues) => {
+			const depArg = isMultiSource ? depValues : depValues[0];
+			return parser[require_dependency.parseWithDependency](rawInput, depArg);
+		};
+		const suggestFn = require_dependency.suggestWithDependency in parser ? parser[require_dependency.suggestWithDependency] : void 0;
+		const replaySuggest = suggestFn != null ? (prefix, depValues) => {
+			const depArg = isMultiSource ? depValues : depValues[0];
+			return suggestFn(prefix, depArg);
+		} : void 0;
+		return { derived: {
+			kind: "derived",
+			dependencyIds: allIds,
+			getDefaultDependencyValues: defaultValuesFn,
+			replayParse,
+			replaySuggest
+		} };
+	}
+	return void 0;
+}
+/**
+* Extracts the source parse result from a bare `DependencySourceState`.
+* Used as the base `extractSourceValue` for plain dependency sources.
+*/
+function extractFromBareState(state) {
+	if (!require_dependency.isDependencySourceState(state)) return void 0;
+	return state.result;
+}
+/**
+* Wraps an inner `extractSourceValue` to unwrap `[innerState]` first.
+* Used by `optional()` and `withDefault()` which wrap state in a
+* single-element array.
+*/
+function unwrapArrayThenExtract(innerExtract) {
+	return (state) => {
+		if (Array.isArray(state) && state.length === 1) return innerExtract(state[0]);
+		return innerExtract(state);
+	};
+}
+/**
+* Composes dependency metadata through a modifier wrapper.
+*
+* - `"optional"`: composes `extractSourceValue` with array unwrapping.
+* - `"withDefault"`: adds `getMissingSourceValue` if the inner parser
+*   preserves a dependency source.
+* - `"map"`: sets `transformsSourceValue` and clears
+*   `preservesSourceValue`.
+*
+* Returns `undefined` if `inner` is `undefined`.
+*
+* @param inner The inner parser's metadata.
+* @param wrapperKind The type of modifier being applied.
+* @param options Additional options for certain wrapper kinds.
+* @returns Composed metadata, or `undefined`.
+* @internal
+* @since 1.0.0
+*/
+function composeDependencyMetadata(inner, wrapperKind, options) {
+	if (inner === void 0) return void 0;
+	switch (wrapperKind) {
+		case "optional": {
+			if (inner.source != null && inner.source.extractSourceValue != null) return {
+				...inner,
+				source: {
+					...inner.source,
+					extractSourceValue: unwrapArrayThenExtract(inner.source.extractSourceValue)
+				}
+			};
+			return inner;
+		}
+		case "withDefault": {
+			const wrappedExtract = inner.source?.extractSourceValue != null ? unwrapArrayThenExtract(inner.source.extractSourceValue) : void 0;
+			if (inner.source != null && inner.source.preservesSourceValue) return {
+				...inner,
+				source: {
+					...inner.source,
+					...wrappedExtract != null && { extractSourceValue: wrappedExtract },
+					getMissingSourceValue: options?.defaultValue
+				}
+			};
+			if (wrappedExtract != null && inner.source != null) return {
+				...inner,
+				source: {
+					...inner.source,
+					extractSourceValue: wrappedExtract
+				}
+			};
+			return inner;
+		}
+		case "map": {
+			const result = {
+				...inner,
+				transform: { transformsSourceValue: true }
+			};
+			if (inner.source != null) return {
+				...result,
+				source: {
+					...inner.source,
+					preservesSourceValue: false
+				}
+			};
+			return result;
+		}
+	}
+}
+
+//#endregion
+exports.composeDependencyMetadata = composeDependencyMetadata;
+exports.extractDependencyMetadata = extractDependencyMetadata;

package/dist/dependency-metadata.d.cts

@@ -0,0 +1,108 @@
+import { ValueParserResult } from "./valueparser.cjs";
+import { Suggestion } from "./parser.cjs";
+
+//#region src/dependency-metadata.d.ts
+
+/**
+ * Metadata for a parser that is a dependency source.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface DependencySourceCapability {
+  /** Discriminant tag. */
+  readonly kind: "source";
+  /** The unique dependency source identifier. */
+  readonly sourceId: symbol;
+  /**
+   * Extracts the dependency source parse result from the parser's state.
+   *
+   * Each wrapper composes this method to handle its state shape:
+   * - plain source: reads from `DependencySourceState`
+   * - `optional()` / `withDefault()`: unwraps `[innerState]` first
+   * - `map()`: reads the pre-transform value from inner state
+   *
+   * Returns the `ValueParserResult` (which may be successful with any
+   * value including `undefined`, or failed), or `undefined` if the state
+   * does not contain a source result at all (unpopulated / wrong shape).
+   */
+  readonly extractSourceValue: (state: unknown) => ValueParserResult<unknown> | undefined;
+  /**
+   * When present, provides a missing-source value (e.g., from a
+   * `withDefault()` wrapper).  Called during the `fillMissingSourceDefaults`
+   * phase of the dependency runtime.
+   */
+  readonly getMissingSourceValue?: () => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
+  /**
+   * Whether the parser's output value is the actual dependency source value.
+   * `false` when a transform like `map()` has been applied.
+   */
+  readonly preservesSourceValue: boolean;
+}
+/**
+ * Metadata for a parser that depends on one or more dependency sources.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface DerivedDependencyCapability {
+  /** Discriminant tag. */
+  readonly kind: "derived";
+  /** The dependency source IDs this parser depends on. */
+  readonly dependencyIds: readonly symbol[];
+  /**
+   * Returns default values for each dependency, used when the
+   * corresponding sources are not provided.
+   */
+  readonly getDefaultDependencyValues?: () => readonly unknown[];
+  /**
+   * Replays a parse with the given raw input and resolved dependency values.
+   */
+  readonly replayParse: (rawInput: string, dependencyValues: readonly unknown[]) => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
+  /**
+   * Replays suggestions with the given prefix and resolved dependency values.
+   */
+  readonly replaySuggest?: (prefix: string, dependencyValues: readonly unknown[]) => Iterable<Suggestion> | AsyncIterable<Suggestion>;
+}
+/**
+ * Metadata indicating that a wrapper transforms the dependency source value.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface DependencyTransformCapability {
+  /** Whether the wrapper transforms the source value. */
+  readonly transformsSourceValue: boolean;
+}
+/**
+ * Composed dependency metadata for a parser node.
+ *
+ * A parser may have any combination of source, derived, and transform
+ * capabilities.  In practice, a parser is typically either a source or
+ * derived, never both.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface ParserDependencyMetadata {
+  /** Present if the parser is (or wraps) a dependency source. */
+  readonly source?: DependencySourceCapability;
+  /** Present if the parser depends on one or more sources. */
+  readonly derived?: DerivedDependencyCapability;
+  /** Present if a transform has been applied. */
+  readonly transform?: DependencyTransformCapability;
+}
+/**
+ * Extracts {@link ParserDependencyMetadata} from a value parser by reading
+ * old-protocol markers (`dependencySourceMarker`, `derivedValueParserMarker`,
+ * etc.).
+ *
+ * Returns `undefined` if the parser has no dependency-related markers.
+ *
+ * @param valueParser The value parser to inspect.
+ * @returns Metadata, or `undefined` for plain parsers.
+ * @internal
+ * @since 1.0.0
+ */
+//#endregion
+export { ParserDependencyMetadata };

package/dist/dependency-metadata.d.ts

@@ -0,0 +1,108 @@
+import { ValueParserResult } from "./valueparser.js";
+import { Suggestion } from "./parser.js";
+
+//#region src/dependency-metadata.d.ts
+
+/**
+ * Metadata for a parser that is a dependency source.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface DependencySourceCapability {
+  /** Discriminant tag. */
+  readonly kind: "source";
+  /** The unique dependency source identifier. */
+  readonly sourceId: symbol;
+  /**
+   * Extracts the dependency source parse result from the parser's state.
+   *
+   * Each wrapper composes this method to handle its state shape:
+   * - plain source: reads from `DependencySourceState`
+   * - `optional()` / `withDefault()`: unwraps `[innerState]` first
+   * - `map()`: reads the pre-transform value from inner state
+   *
+   * Returns the `ValueParserResult` (which may be successful with any
+   * value including `undefined`, or failed), or `undefined` if the state
+   * does not contain a source result at all (unpopulated / wrong shape).
+   */
+  readonly extractSourceValue: (state: unknown) => ValueParserResult<unknown> | undefined;
+  /**
+   * When present, provides a missing-source value (e.g., from a
+   * `withDefault()` wrapper).  Called during the `fillMissingSourceDefaults`
+   * phase of the dependency runtime.
+   */
+  readonly getMissingSourceValue?: () => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
+  /**
+   * Whether the parser's output value is the actual dependency source value.
+   * `false` when a transform like `map()` has been applied.
+   */
+  readonly preservesSourceValue: boolean;
+}
+/**
+ * Metadata for a parser that depends on one or more dependency sources.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface DerivedDependencyCapability {
+  /** Discriminant tag. */
+  readonly kind: "derived";
+  /** The dependency source IDs this parser depends on. */
+  readonly dependencyIds: readonly symbol[];
+  /**
+   * Returns default values for each dependency, used when the
+   * corresponding sources are not provided.
+   */
+  readonly getDefaultDependencyValues?: () => readonly unknown[];
+  /**
+   * Replays a parse with the given raw input and resolved dependency values.
+   */
+  readonly replayParse: (rawInput: string, dependencyValues: readonly unknown[]) => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
+  /**
+   * Replays suggestions with the given prefix and resolved dependency values.
+   */
+  readonly replaySuggest?: (prefix: string, dependencyValues: readonly unknown[]) => Iterable<Suggestion> | AsyncIterable<Suggestion>;
+}
+/**
+ * Metadata indicating that a wrapper transforms the dependency source value.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface DependencyTransformCapability {
+  /** Whether the wrapper transforms the source value. */
+  readonly transformsSourceValue: boolean;
+}
+/**
+ * Composed dependency metadata for a parser node.
+ *
+ * A parser may have any combination of source, derived, and transform
+ * capabilities.  In practice, a parser is typically either a source or
+ * derived, never both.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface ParserDependencyMetadata {
+  /** Present if the parser is (or wraps) a dependency source. */
+  readonly source?: DependencySourceCapability;
+  /** Present if the parser depends on one or more sources. */
+  readonly derived?: DerivedDependencyCapability;
+  /** Present if a transform has been applied. */
+  readonly transform?: DependencyTransformCapability;
+}
+/**
+ * Extracts {@link ParserDependencyMetadata} from a value parser by reading
+ * old-protocol markers (`dependencySourceMarker`, `derivedValueParserMarker`,
+ * etc.).
+ *
+ * Returns `undefined` if the parser has no dependency-related markers.
+ *
+ * @param valueParser The value parser to inspect.
+ * @returns Metadata, or `undefined` for plain parsers.
+ * @internal
+ * @since 1.0.0
+ */
+//#endregion
+export { ParserDependencyMetadata };

package/dist/dependency-metadata.js

@@ -0,0 +1,139 @@
+import { defaultValues, dependencyId, dependencyIds, isDependencySource, isDependencySourceState, isDerivedValueParser, parseWithDependency, singleDefaultValue, suggestWithDependency } from "./dependency.js";
+
+//#region src/dependency-metadata.ts
+/**
+* Extracts {@link ParserDependencyMetadata} from a value parser by reading
+* old-protocol markers (`dependencySourceMarker`, `derivedValueParserMarker`,
+* etc.).
+*
+* Returns `undefined` if the parser has no dependency-related markers.
+*
+* @param valueParser The value parser to inspect.
+* @returns Metadata, or `undefined` for plain parsers.
+* @internal
+* @since 1.0.0
+*/
+function extractDependencyMetadata(valueParser) {
+	if (isDependencySource(valueParser)) return { source: {
+		kind: "source",
+		sourceId: valueParser[dependencyId],
+		extractSourceValue: extractFromBareState,
+		preservesSourceValue: true
+	} };
+	if (isDerivedValueParser(valueParser)) {
+		const isMultiSource = dependencyIds in valueParser && valueParser[dependencyIds] != null;
+		const allIds = isMultiSource ? valueParser[dependencyIds] : [valueParser[dependencyId]];
+		let defaultValuesFn;
+		if (defaultValues in valueParser && valueParser[defaultValues] != null) defaultValuesFn = valueParser[defaultValues];
+		else if (singleDefaultValue in valueParser && valueParser[singleDefaultValue] != null) {
+			const singleFn = valueParser[singleDefaultValue];
+			defaultValuesFn = () => [singleFn()];
+		}
+		const parser = valueParser;
+		const replayParse = (rawInput, depValues) => {
+			const depArg = isMultiSource ? depValues : depValues[0];
+			return parser[parseWithDependency](rawInput, depArg);
+		};
+		const suggestFn = suggestWithDependency in parser ? parser[suggestWithDependency] : void 0;
+		const replaySuggest = suggestFn != null ? (prefix, depValues) => {
+			const depArg = isMultiSource ? depValues : depValues[0];
+			return suggestFn(prefix, depArg);
+		} : void 0;
+		return { derived: {
+			kind: "derived",
+			dependencyIds: allIds,
+			getDefaultDependencyValues: defaultValuesFn,
+			replayParse,
+			replaySuggest
+		} };
+	}
+	return void 0;
+}
+/**
+* Extracts the source parse result from a bare `DependencySourceState`.
+* Used as the base `extractSourceValue` for plain dependency sources.
+*/
+function extractFromBareState(state) {
+	if (!isDependencySourceState(state)) return void 0;
+	return state.result;
+}
+/**
+* Wraps an inner `extractSourceValue` to unwrap `[innerState]` first.
+* Used by `optional()` and `withDefault()` which wrap state in a
+* single-element array.
+*/
+function unwrapArrayThenExtract(innerExtract) {
+	return (state) => {
+		if (Array.isArray(state) && state.length === 1) return innerExtract(state[0]);
+		return innerExtract(state);
+	};
+}
+/**
+* Composes dependency metadata through a modifier wrapper.
+*
+* - `"optional"`: composes `extractSourceValue` with array unwrapping.
+* - `"withDefault"`: adds `getMissingSourceValue` if the inner parser
+*   preserves a dependency source.
+* - `"map"`: sets `transformsSourceValue` and clears
+*   `preservesSourceValue`.
+*
+* Returns `undefined` if `inner` is `undefined`.
+*
+* @param inner The inner parser's metadata.
+* @param wrapperKind The type of modifier being applied.
+* @param options Additional options for certain wrapper kinds.
+* @returns Composed metadata, or `undefined`.
+* @internal
+* @since 1.0.0
+*/
+function composeDependencyMetadata(inner, wrapperKind, options) {
+	if (inner === void 0) return void 0;
+	switch (wrapperKind) {
+		case "optional": {
+			if (inner.source != null && inner.source.extractSourceValue != null) return {
+				...inner,
+				source: {
+					...inner.source,
+					extractSourceValue: unwrapArrayThenExtract(inner.source.extractSourceValue)
+				}
+			};
+			return inner;
+		}
+		case "withDefault": {
+			const wrappedExtract = inner.source?.extractSourceValue != null ? unwrapArrayThenExtract(inner.source.extractSourceValue) : void 0;
+			if (inner.source != null && inner.source.preservesSourceValue) return {
+				...inner,
+				source: {
+					...inner.source,
+					...wrappedExtract != null && { extractSourceValue: wrappedExtract },
+					getMissingSourceValue: options?.defaultValue
+				}
+			};
+			if (wrappedExtract != null && inner.source != null) return {
+				...inner,
+				source: {
+					...inner.source,
+					extractSourceValue: wrappedExtract
+				}
+			};
+			return inner;
+		}
+		case "map": {
+			const result = {
+				...inner,
+				transform: { transformsSourceValue: true }
+			};
+			if (inner.source != null) return {
+				...result,
+				source: {
+					...inner.source,
+					preservesSourceValue: false
+				}
+			};
+			return result;
+		}
+	}
+}
+
+//#endregion
+export { composeDependencyMetadata, extractDependencyMetadata };

package/dist/dependency-runtime.d.cts

@@ -0,0 +1,123 @@
+import { DependencyRegistryLike } from "./registry-types.cjs";
+import { ValueParserResult } from "./valueparser.cjs";
+
+//#region src/dependency-runtime.d.ts
+
+/**
+ * The origin of a dependency source value.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+type DependencyValueOrigin = "cli" | "default" | "config" | "env" | "prompt" | "derived-precomplete";
+/**
+ * A request to resolve one or more dependency values.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface DependencyRequest {
+  /** The dependency source IDs to resolve. */
+  readonly dependencyIds: readonly symbol[];
+  /** Optional default values (one per ID) for missing sources. */
+  readonly defaultValues?: readonly unknown[];
+}
+/**
+ * The result of a dependency resolution request.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface DependencyResolution {
+  /**
+   * - `"resolved"`: all dependency values are available.
+   * - `"partial"`: some are available, some are missing.
+   * - `"missing"`: none are available.
+   */
+  readonly kind: "resolved" | "partial" | "missing";
+  /** The resolved values (one per requested ID, `undefined` for missing). */
+  readonly values: readonly unknown[];
+  /** For each position, whether the value came from a default. */
+  readonly usedDefaults: readonly boolean[];
+}
+/**
+ * A failure that occurred while evaluating a missing-source default.
+ * Returned by `fillMissingSourceDefaults()` so the caller can propagate
+ * the error instead of silently treating the source as absent.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+
+/**
+ * A key for caching replayed parse results.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface ReplayKey {
+  /** Path from root to the parser node. */
+  readonly path: readonly PropertyKey[];
+  /** The raw input string that was parsed. */
+  readonly rawInput: string;
+  /** A stable fingerprint of the dependency values used. */
+  readonly dependencyFingerprint: string;
+  /**
+   * A per-parser identity string that disambiguates different derived
+   * parsers sharing the same path (e.g., alternative branches).
+   * @since 1.0.0
+   */
+  readonly parserFingerprint: string;
+}
+/**
+ * A runtime node representing a child parser's position, metadata, and state.
+ * Used as input to the shared runtime helpers.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+
+/**
+ * Dependency runtime context for centralized dependency resolution.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface DependencyRuntimeContext {
+  /** The underlying registry (for bridge interop). */
+  readonly registry: DependencyRegistryLike;
+  /** Register a source value with its origin. */
+  registerSource(sourceId: symbol, value: unknown, origin: DependencyValueOrigin): void;
+  /** Check if a source has been registered. */
+  hasSource(sourceId: symbol): boolean;
+  /** Get a registered source value. */
+  getSource(sourceId: symbol): unknown;
+  /** Resolve dependency values for a request. */
+  resolveDependencies(request: DependencyRequest): DependencyResolution;
+  /** Get a cached replay result. */
+  getReplayResult(key: ReplayKey): ValueParserResult<unknown> | undefined;
+  /** Cache a replay result. */
+  setReplayResult(key: ReplayKey, result: ValueParserResult<unknown>): void;
+  /**
+   * Mark a source as explicitly failed (user provided input that did
+   * not pass validation).  Derived parsers should not fall back to
+   * defaults for failed sources.
+   */
+  markSourceFailed(sourceId: symbol): void;
+  /**
+   * Check if a source was explicitly attempted but failed validation.
+   */
+  isSourceFailed(sourceId: symbol): boolean;
+  /** Resolve dependencies for suggestions (same semantics as resolve). */
+  getSuggestionDependencies(request: DependencyRequest): DependencyResolution;
+}
+/**
+ * Creates a new {@link DependencyRuntimeContext}.
+ *
+ * @param registry Optional existing registry to wrap for bridge interop.
+ * @returns A new runtime context.
+ * @internal
+ * @since 1.0.0
+ */
+//#endregion
+export { DependencyRuntimeContext };