@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/dependency-metadata.cjs

@@ -0,0 +1,139 @@
+const require_dependency = require('./internal/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 plain source state.
+*
+* Accepts either a `DependencySourceState` or a bare
+* `ValueParserResult`-shaped object, and returns `undefined` for
+* unrelated states. Used as the base `extractSourceValue` for plain
+* dependency sources.
+*/
+function extractFromBareState(state) {
+	if (require_dependency.isDependencySourceState(state)) return state.result;
+	if (state != null && typeof state === "object" && Object.hasOwn(state, "success") && typeof state.success === "boolean" && (state.success && Object.hasOwn(state, "value") || !state.success && Object.hasOwn(state, "error"))) return state;
+	return void 0;
+}
+/**
+* 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;
+			const preservesSourceValue = inner.source?.preservesSourceValue !== false;
+			if (inner.source != null) return {
+				...inner,
+				source: {
+					...inner.source,
+					...wrappedExtract != null && { extractSourceValue: wrappedExtract },
+					...preservesSourceValue && options?.defaultValue != null && { getMissingSourceValue: options.defaultValue }
+				}
+			};
+			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,112 @@
+import { ValueParserResult } from "./valueparser.cjs";
+import { Suggestion } from "./internal/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.
+   *
+   * The `state` argument is the current parser state for the source-owning
+   * parser.  Each wrapper composes this method to handle its own 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), a promise that resolves to the
+   * same shape when extraction needs async work, or `undefined` if the state
+   * does not contain a source result at all (unpopulated / wrong shape).
+   * Callers and wrapper authors must handle both direct and promise-wrapped
+   * results when composing `extractSourceValue`.
+   */
+  readonly extractSourceValue: (state: unknown) => ValueParserResult<unknown> | Promise<ValueParserResult<unknown> | undefined> | 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,112 @@
+import { ValueParserResult } from "./valueparser.js";
+import { Suggestion } from "./internal/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.
+   *
+   * The `state` argument is the current parser state for the source-owning
+   * parser.  Each wrapper composes this method to handle its own 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), a promise that resolves to the
+   * same shape when extraction needs async work, or `undefined` if the state
+   * does not contain a source result at all (unpopulated / wrong shape).
+   * Callers and wrapper authors must handle both direct and promise-wrapped
+   * results when composing `extractSourceValue`.
+   */
+  readonly extractSourceValue: (state: unknown) => ValueParserResult<unknown> | Promise<ValueParserResult<unknown> | undefined> | 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,138 @@
+import { defaultValues, dependencyId, dependencyIds, isDependencySource, isDependencySourceState, isDerivedValueParser, parseWithDependency, singleDefaultValue, suggestWithDependency } from "./internal/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 plain source state.
+*
+* Accepts either a `DependencySourceState` or a bare
+* `ValueParserResult`-shaped object, and returns `undefined` for
+* unrelated states. Used as the base `extractSourceValue` for plain
+* dependency sources.
+*/
+function extractFromBareState(state) {
+	if (isDependencySourceState(state)) return state.result;
+	if (state != null && typeof state === "object" && Object.hasOwn(state, "success") && typeof state.success === "boolean" && (state.success && Object.hasOwn(state, "value") || !state.success && Object.hasOwn(state, "error"))) return state;
+	return void 0;
+}
+/**
+* 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;
+			const preservesSourceValue = inner.source?.preservesSourceValue !== false;
+			if (inner.source != null) return {
+				...inner,
+				source: {
+					...inner.source,
+					...wrappedExtract != null && { extractSourceValue: wrappedExtract },
+					...preservesSourceValue && options?.defaultValue != null && { getMissingSourceValue: options.defaultValue }
+				}
+			};
+			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 };