@optique/core 1.0.0-dev.921 → 1.0.1

package/dist/internal/dependency.d.cts

@@ -0,0 +1,539 @@
+import { NonEmptyString } from "../nonempty.cjs";
+import { ValueParser, ValueParserResult } from "../valueparser.cjs";
+import { Mode, Suggestion } from "./parser.cjs";
+
+//#region src/internal/dependency.d.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
+ */
+declare const dependencySourceMarker: unique symbol;
+/**
+ * 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
+ */
+declare const derivedValueParserMarker: unique symbol;
+/**
+ * A unique symbol used to store the dependency ID on value parsers.
+ * @since 0.10.0
+ */
+declare const dependencyId: unique symbol;
+/**
+ * A unique symbol used to store multiple dependency IDs on derived parsers
+ * that depend on multiple sources (created via {@link deriveFrom}).
+ * @since 0.10.0
+ */
+declare const dependencyIds: unique symbol;
+/**
+ * A unique symbol used to store the default values function on derived parsers.
+ * This is used during partial dependency resolution to fill in missing values.
+ * @since 0.10.0
+ */
+declare const defaultValues: unique symbol;
+/**
+ * A unique symbol used to store the single default value thunk on derived
+ * parsers created by {@link DependencySource.derive}.  Unlike
+ * {@link defaultValues} (which `createDeferredParseState` only falls back to
+ * when no parse-time snapshot is available), this symbol is only read by the
+ * dependency-metadata bridge so that
+ * single-source defaults are accessible without double evaluation.
+ * @internal
+ */
+declare const singleDefaultValue: unique symbol;
+/**
+ * A unique symbol used to store the snapshotted default dependency values on
+ * a parse result produced by a derived parser's default path.
+ *
+ * @internal
+ */
+
+/**
+ * A unique symbol used to access the parseWithDependency method on derived parsers.
+ * @since 0.10.0
+ */
+declare const parseWithDependency: unique symbol;
+/**
+ * A unique symbol used to access the suggestWithDependency method on derived parsers.
+ * This method generates suggestions using the provided dependency values instead of defaults.
+ * @since 0.10.0
+ */
+declare const suggestWithDependency: unique symbol;
+/**
+ * Combines two modes into a single mode.
+ * If either mode is async, the result is async.
+ * @template M1 The first mode.
+ * @template M2 The second mode.
+ * @since 0.10.0
+ */
+type CombineMode<M1 extends Mode, M2 extends Mode> = M1 extends "async" ? "async" : M2 extends "async" ? "async" : "sync";
+/**
+ * Options for creating a derived value parser.
+ *
+ * @template S The type of the source dependency value.
+ * @template T The type of the derived parser value.
+ * @template FM The mode of the factory's returned parser.
+ * @since 0.10.0
+ */
+interface DeriveOptions<S, T, FM extends Mode = Mode> {
+  /**
+   * The metavariable name for the derived parser. Used in help messages
+   * to indicate what kind of value this parser expects.
+   */
+  readonly metavar: NonEmptyString;
+  /**
+   * Factory function that creates a {@link ValueParser} based on the
+   * dependency source's value.
+   *
+   * @param sourceValue The value parsed from the dependency source.
+   * @returns A {@link ValueParser} for the derived value.
+   */
+  readonly factory: (sourceValue: S) => ValueParser<NoInfer<FM>, T>;
+  /**
+   * Default value to use when the dependency source is not provided.
+   * This allows the derived parser to work even when the dependency
+   * is optional.
+   *
+   * @returns The default value for the dependency source.
+   */
+  readonly defaultValue: () => S;
+  /**
+   * The execution mode of the factory's returned parser.  This tells the
+   * runtime whether the factory returns a sync or async parser, avoiding
+   * the need to call the factory during parser construction.
+   *
+   * @since 1.0.0
+   */
+  readonly mode: FM;
+}
+/**
+ * Options for creating a derived value parser with a synchronous factory.
+ *
+ * @template S The type of the source dependency value.
+ * @template T The type of the derived parser value.
+ * @since 0.10.0
+ */
+interface DeriveSyncOptions<S, T> {
+  /**
+   * The metavariable name for the derived parser.
+   */
+  readonly metavar: NonEmptyString;
+  /**
+   * Factory function that creates a synchronous {@link ValueParser}.
+   */
+  readonly factory: (sourceValue: S) => ValueParser<"sync", T>;
+  /**
+   * Default value to use when the dependency source is not provided.
+   */
+  readonly defaultValue: () => S;
+}
+/**
+ * Options for creating a derived value parser with an asynchronous factory.
+ *
+ * @template S The type of the source dependency value.
+ * @template T The type of the derived parser value.
+ * @since 0.10.0
+ */
+interface DeriveAsyncOptions<S, T> {
+  /**
+   * The metavariable name for the derived parser.
+   */
+  readonly metavar: NonEmptyString;
+  /**
+   * Factory function that creates an asynchronous {@link ValueParser}.
+   */
+  readonly factory: (sourceValue: S) => ValueParser<"async", T>;
+  /**
+   * Default value to use when the dependency source is not provided.
+   */
+  readonly defaultValue: () => S;
+}
+/**
+ * Represents a dependency source that can be used to create derived parsers.
+ *
+ * A dependency source wraps a {@link ValueParser} and provides methods to
+ * create derived parsers that depend on the parsed value. This enables
+ * inter-option dependencies where one option's valid values depend on
+ * another option's value.
+ *
+ * @template M The execution mode of the parser (`"sync"` or `"async"`).
+ * @template T The type of value this dependency source produces.
+ * @since 0.10.0
+ */
+interface DependencySource<M extends Mode = "sync", T = unknown> extends ValueParser<M, T> {
+  /**
+   * Marker to identify this as a dependency source.
+   * @internal
+   */
+  readonly [dependencySourceMarker]: true;
+  /**
+   * Unique identifier for this dependency source.
+   * @internal
+   */
+  readonly [dependencyId]: symbol;
+  /**
+   * Creates a derived value parser whose behavior depends on this
+   * dependency source's value.
+   *
+   * The derived parser uses a factory function to create parsers based on
+   * the source value. The factory can return either a sync or async parser,
+   * and the resulting derived parser's mode will be the combination of
+   * the source mode and the factory's returned parser mode.
+   *
+   * @template U The type of value the derived parser produces.
+   * @template FM The mode of the factory's returned parser.
+   * @param options Configuration for the derived parser.
+   * @returns A {@link DerivedValueParser} that depends on this source.
+   * @throws {TypeError} If the `mode` field is missing or invalid.
+   */
+  derive<U, FM extends Mode = "sync">(options: DeriveOptions<T, U, FM>): DerivedValueParser<CombineMode<M, FM>, U, T>;
+  /**
+   * Creates a derived value parser with a synchronous factory.
+   *
+   * This is a convenience method that explicitly requires a sync factory,
+   * making the type inference more predictable.
+   *
+   * @template U 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 this source.
+   * @since 0.10.0
+   */
+  deriveSync<U>(options: DeriveSyncOptions<T, U>): DerivedValueParser<M, U, T>;
+  /**
+   * Creates a derived value parser with an asynchronous factory.
+   *
+   * This is a convenience method that explicitly requires an async factory,
+   * making the type inference more predictable.
+   *
+   * @template U 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 this source.
+   * @since 0.10.0
+   */
+  deriveAsync<U>(options: DeriveAsyncOptions<T, U>): DerivedValueParser<"async", U, T>;
+}
+/**
+ * Extracts the value type from a DependencySource.
+ * @template D The DependencySource type.
+ * @since 0.10.0
+ */
+type DependencyValue<D> = D extends DependencySource<Mode, infer T> ? T : never;
+/**
+ * Extracts the mode from a DependencySource.
+ * @template D The DependencySource type.
+ * @since 0.10.0
+ */
+type DependencyMode<D> = D extends DependencySource<infer M, unknown> ? M : never;
+/**
+ * Maps a tuple of DependencySources to a tuple of their value types.
+ * @template T The tuple of DependencySource types.
+ * @since 0.10.0
+ */
+type DependencyValues<T extends readonly unknown[]> = { [K in keyof T]: T[K] extends DependencySource<Mode, infer V> ? V : never };
+/**
+ * Combines modes from multiple dependency sources.
+ * If any source is async, the result is async.
+ * @template T The tuple of DependencySource types.
+ * @since 0.10.0
+ */
+type CombinedDependencyMode<T extends readonly unknown[]> = "async" extends { [K in keyof T]: T[K] extends DependencySource<infer M, unknown> ? M : never }[number] ? "async" : "sync";
+/**
+ * Minimal structural supertype for dependency-source tuple constraints.
+ *
+ * TypeScript cannot express an existential type like
+ * `DependencySource<Mode, some T>`, and `DependencySource<Mode, unknown>` is
+ * too strict because dependency sources are invariant in their value type.
+ * This structural view preserves assignability without resorting to `any`.
+ *
+ * @since 0.10.0
+ */
+interface AnyDependencySource<M extends Mode = Mode> {
+  readonly [dependencySourceMarker]: true;
+  readonly [dependencyId]: symbol;
+  readonly mode: M;
+}
+/**
+ * Options for creating a derived value parser from multiple dependencies.
+ *
+ * @template Deps A tuple of DependencySource types.
+ * @template T The type of the derived parser value.
+ * @template FM The mode of the factory's returned parser.
+ * @since 0.10.0
+ */
+interface DeriveFromOptions<Deps extends readonly AnyDependencySource[], T, FM extends Mode = Mode> {
+  /**
+   * The metavariable name for the derived parser. Used in help messages
+   * to indicate what kind of value this parser expects.
+   */
+  readonly metavar: NonEmptyString;
+  /**
+   * The dependency sources that this derived parser depends on.
+   */
+  readonly dependencies: Deps;
+  /**
+   * Factory function that creates a {@link ValueParser} based on the
+   * dependency sources' values.
+   *
+   * @param values The values parsed from the dependency sources (in order).
+   * @returns A {@link ValueParser} for the derived value.
+   */
+  readonly factory: (...values: DependencyValues<Deps>) => ValueParser<NoInfer<FM>, T>;
+  /**
+   * Default values to use when the dependency sources are not provided.
+   * Must return a tuple with the same length and types as the dependencies.
+   *
+   * @returns A tuple of default values for each dependency source.
+   */
+  readonly defaultValues: () => DependencyValues<Deps>;
+  /**
+   * The execution mode of the factory's returned parser.  This tells the
+   * runtime whether the factory returns a sync or async parser, avoiding
+   * the need to call the factory during parser construction.
+   *
+   * @since 1.0.0
+   */
+  readonly mode: FM;
+}
+/**
+ * Options for creating a derived value parser from multiple dependencies
+ * with a synchronous factory.
+ *
+ * @template Deps A tuple of DependencySource types.
+ * @template T The type of the derived parser value.
+ * @since 0.10.0
+ */
+interface DeriveFromSyncOptions<Deps extends readonly AnyDependencySource[], T> {
+  /**
+   * The metavariable name for the derived parser.
+   */
+  readonly metavar: NonEmptyString;
+  /**
+   * The dependency sources that this derived parser depends on.
+   */
+  readonly dependencies: Deps;
+  /**
+   * Factory function that creates a synchronous {@link ValueParser}.
+   */
+  readonly factory: (...values: DependencyValues<Deps>) => ValueParser<"sync", T>;
+  /**
+   * Default values to use when the dependency sources are not provided.
+   */
+  readonly defaultValues: () => DependencyValues<Deps>;
+}
+/**
+ * Options for creating a derived value parser from multiple dependencies
+ * with an asynchronous factory.
+ *
+ * @template Deps A tuple of DependencySource types.
+ * @template T The type of the derived parser value.
+ * @since 0.10.0
+ */
+interface DeriveFromAsyncOptions<Deps extends readonly AnyDependencySource[], T> {
+  /**
+   * The metavariable name for the derived parser.
+   */
+  readonly metavar: NonEmptyString;
+  /**
+   * The dependency sources that this derived parser depends on.
+   */
+  readonly dependencies: Deps;
+  /**
+   * Factory function that creates an asynchronous {@link ValueParser}.
+   */
+  readonly factory: (...values: DependencyValues<Deps>) => ValueParser<"async", T>;
+  /**
+   * Default values to use when the dependency sources are not provided.
+   */
+  readonly defaultValues: () => DependencyValues<Deps>;
+}
+/**
+ * A value parser that depends on another parser's value.
+ *
+ * A derived value parser cannot be nested (i.e., you cannot call
+ * {@link DependencySource.derive} on a {@link DerivedValueParser}).
+ *
+ * @template M The execution mode of the parser (`"sync"` or `"async"`).
+ * @template T The type of value this parser produces.
+ * @template S The type of the source dependency value.
+ * @since 0.10.0
+ */
+interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown> extends ValueParser<M, T> {
+  /**
+   * Marker to identify this as a derived value parser.
+   * @internal
+   */
+  readonly [derivedValueParserMarker]: true;
+  /**
+   * The unique identifier of the dependency source this parser depends on.
+   * For parsers created with {@link deriveFrom} that have multiple dependencies,
+   * this is set to the first dependency's ID for backwards compatibility.
+   * @internal
+   */
+  readonly [dependencyId]: symbol;
+  /**
+   * The unique identifiers of all dependency sources this parser depends on.
+   * Present only for parsers created with {@link deriveFrom} that have multiple
+   * dependencies. If present, this takes precedence over {@link dependencyId}
+   * during dependency resolution.
+   * @internal
+   */
+  readonly [dependencyIds]?: readonly symbol[];
+  /**
+   * The default values function for this parser's dependencies.
+   * Used during partial dependency resolution to fill in missing values.
+   * @internal
+   */
+  readonly [defaultValues]?: () => readonly unknown[];
+  /**
+   * The single default value thunk for single-source derived parsers.
+   * Read by the dependency-metadata bridge; not consumed by
+   * `createDeferredParseState()`.
+   * @internal
+   */
+  readonly [singleDefaultValue]?: () => S;
+  /**
+   * Parses the input using the actual dependency value instead of the default.
+   * This method is used during dependency resolution in `complete()`.
+   *
+   * @param input The raw input string to parse.
+   * @param dependencyValue The resolved dependency value.
+   * @returns The parse result.
+   * @internal
+   */
+  readonly [parseWithDependency]: (input: string, dependencyValue: S) => ValueParserResult<T> | Promise<ValueParserResult<T>>;
+  /**
+   * Generates suggestions using the provided dependency value instead of the default.
+   * This method is used during shell completion when dependency sources have been parsed.
+   *
+   * @param prefix The input prefix to filter suggestions.
+   * @param dependencyValue The resolved dependency value.
+   * @returns An iterable of suggestions.
+   * @internal
+   */
+  readonly [suggestWithDependency]?: (prefix: string, dependencyValue: S) => Iterable<Suggestion> | AsyncIterable<Suggestion>;
+}
+/**
+ * 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",
+ *   mode: "sync",
+ *   factory: (dir) => gitBranch({ dir }),
+ *   defaultValue: () => process.cwd(),
+ * });
+ * ```
+ * @since 0.10.0
+ */
+declare function dependency<M extends Mode, T>(parser: ValueParser<M, T>): DependencySource<M, T>;
+/**
+ * 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
+ */
+declare function isDependencySource<M extends Mode, T>(parser: ValueParser<M, T>): parser is DependencySource<M, T>;
+/**
+ * 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
+ */
+declare function isDerivedValueParser<M extends Mode, T>(parser: ValueParser<M, T>): parser is DerivedValueParser<M, T, unknown>;
+/**
+ * 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",
+ *   mode: "sync",
+ *   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"],
+ * });
+ * ```
+ * @throws {TypeError} If the `mode` field is missing or invalid.
+ * @since 0.10.0
+ */
+declare function deriveFrom<Deps extends readonly AnyDependencySource[], T, FM extends Mode = "sync">(options: DeriveFromOptions<Deps, T, FM>): DerivedValueParser<CombineMode<CombinedDependencyMode<Deps>, FM>, T, DependencyValues<Deps>>;
+/**
+ * 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
+ */
+declare function deriveFromSync<Deps extends readonly AnyDependencySource[], T>(options: DeriveFromSyncOptions<Deps, T>): DerivedValueParser<CombinedDependencyMode<Deps>, T, DependencyValues<Deps>>;
+/**
+ * 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
+ */
+declare function deriveFromAsync<Deps extends readonly AnyDependencySource[], T>(options: DeriveFromAsyncOptions<Deps, T>): DerivedValueParser<"async", T, DependencyValues<Deps>>;
+/**
+ * Attaches a default dependency snapshot to a derived parser's parse result.
+ *
+ * @param result The parse result to annotate.
+ * @param values The dependency values used for the default-path parse.
+ * @returns A cloned parse result with an internal snapshot attached.
+ * @internal
+ */
+//#endregion
+export { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser };