@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/dependency-runtime.d.cts

@@ -0,0 +1,149 @@
+import { DependencyRegistryLike } from "./registry-types.cjs";
+import { ValueParserResult } from "./valueparser.cjs";
+import { ParserDependencyMetadata } from "./dependency-metadata.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
+ */
+interface RuntimeNode {
+  /** Path from root to this parser node. */
+  readonly path: readonly PropertyKey[];
+  /** The parser (only the metadata field is inspected). */
+  readonly parser: {
+    readonly dependencyMetadata?: ParserDependencyMetadata;
+  };
+  /** The parser's current state. */
+  readonly state: unknown;
+  /**
+   * Whether the parser consumed explicit input during parsing.
+   * When `true`, the parser's state reflects user-provided input (which
+   * may have failed validation).  Missing-source defaults must not override
+   * explicit parse failures.
+   * @since 1.0.0
+   */
+  readonly matched?: boolean;
+  /**
+   * Snapshotted default dependency values for derived parsers.
+   * Constructs should populate this at node creation time (once) to
+   * avoid re-evaluating dynamic `getDefaultDependencyValues()` thunks
+   * at replay time.
+   * @since 1.0.0
+   */
+  readonly defaultDependencyValues?: readonly unknown[];
+}
+/**
+ * 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, RuntimeNode };

package/dist/dependency-runtime.d.ts

@@ -0,0 +1,149 @@
+import { DependencyRegistryLike } from "./registry-types.js";
+import { ValueParserResult } from "./valueparser.js";
+import { ParserDependencyMetadata } from "./dependency-metadata.js";
+
+//#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
+ */
+interface RuntimeNode {
+  /** Path from root to this parser node. */
+  readonly path: readonly PropertyKey[];
+  /** The parser (only the metadata field is inspected). */
+  readonly parser: {
+    readonly dependencyMetadata?: ParserDependencyMetadata;
+  };
+  /** The parser's current state. */
+  readonly state: unknown;
+  /**
+   * Whether the parser consumed explicit input during parsing.
+   * When `true`, the parser's state reflects user-provided input (which
+   * may have failed validation).  Missing-source defaults must not override
+   * explicit parse failures.
+   * @since 1.0.0
+   */
+  readonly matched?: boolean;
+  /**
+   * Snapshotted default dependency values for derived parsers.
+   * Constructs should populate this at node creation time (once) to
+   * avoid re-evaluating dynamic `getDefaultDependencyValues()` thunks
+   * at replay time.
+   * @since 1.0.0
+   */
+  readonly defaultDependencyValues?: readonly unknown[];
+}
+/**
+ * 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, RuntimeNode };