@optique/config 0.10.7-dev.485 → 1.0.0-dev.1109

package/dist/index.d.cts

@@ -1,2 +1,237 @@
-import { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig } from "./index-D25zYfjf.cjs";
-export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { ParserValuePlaceholder, SourceContext } from "@optique/core/context";
+import { Parser } from "@optique/core/parser";
+
+//#region src/index.d.ts
+
+/**
+ * Metadata about the loaded config source.
+ *
+ * @since 1.0.0
+ */
+interface ConfigMeta {
+  /**
+   * Directory containing the config file.
+   */
+  readonly configDir: string;
+  /**
+   * Absolute path to the config file.
+   */
+  readonly configPath: string;
+}
+/**
+ * Sets active config data for a context.
+ * @internal
+ */
+declare function setActiveConfig<T>(contextId: symbol, data: T): void;
+/**
+ * Gets active config data for a context.
+ * @internal
+ */
+declare function getActiveConfig<T>(contextId: symbol): T | undefined;
+/**
+ * Clears active config data for a context.
+ * @internal
+ */
+declare function clearActiveConfig(contextId: symbol): void;
+/**
+ * Sets active config metadata for a context.
+ * @internal
+ */
+declare function setActiveConfigMeta<T>(contextId: symbol, meta: T): void;
+/**
+ * Gets active config metadata for a context.
+ * @internal
+ */
+declare function getActiveConfigMeta<T>(contextId: symbol): T | undefined;
+/**
+ * Clears active config metadata for a context.
+ * @internal
+ */
+declare function clearActiveConfigMeta(contextId: symbol): void;
+/**
+ * Options for creating a config context.
+ *
+ * @template T The output type of the config schema.
+ * @since 0.10.0
+ */
+interface ConfigContextOptions<T> {
+  /**
+   * Standard Schema validator for the config file.
+   * Accepts any Standard Schema-compatible library (Zod, Valibot, ArkType, etc.).
+   */
+  readonly schema: StandardSchemaV1<unknown, T>;
+  /**
+   * Custom parser function for reading config file contents.
+   * If not provided, defaults to JSON.parse.
+   *
+   * This option is only used in single-file mode (with `getConfigPath`).
+   * When using the `load` callback, file parsing is handled by the loader.
+   *
+   * @param contents The raw file contents as Uint8Array.
+   * @returns The parsed config data (will be validated by schema).
+   * @since 1.0.0
+   */
+  readonly fileParser?: (contents: Uint8Array) => unknown;
+}
+/**
+ * Result type for custom config loading.
+ *
+ * @template TConfigMeta Metadata type associated with loaded config data.
+ * @since 1.0.0
+ */
+interface ConfigLoadResult<TConfigMeta = ConfigMeta> {
+  /**
+   * Raw config data to validate against the schema.
+   */
+  readonly config: unknown;
+  /**
+   * Metadata about where the config came from, if available.
+   */
+  readonly meta: TConfigMeta | undefined;
+}
+/**
+ * Required options for ConfigContext when used with `runWith()` or `run()`.
+ * The `ParserValuePlaceholder` will be substituted with the actual parser
+ * result type by `runWith()`.
+ *
+ * Provide *either* `getConfigPath` (single-file mode) *or* `load` (custom
+ * multi-file mode).  At least one must be provided; a runtime error is
+ * thrown otherwise.
+ *
+ * @template TConfigMeta Metadata type for config sources.
+ * @since 0.10.0
+ */
+interface ConfigContextRequiredOptions<TConfigMeta = ConfigMeta> {
+  /**
+   * Function to extract config file path from parsed CLI arguments.
+   * Used in single-file mode.  The `parsed` parameter is typed as the
+   * parser's result type.
+   *
+   * @param parsed The parsed CLI arguments (typed from parser).
+   * @returns The config file path, or undefined if not specified.
+   */
+  readonly getConfigPath?: (parsed: ParserValuePlaceholder) => string | undefined;
+  /**
+   * Custom loader function that receives the first-pass parse result and
+   * returns the config data (or a Promise of it).  This allows full control
+   * over file discovery, loading, merging, and error handling.
+   *
+   * The returned data will be validated against the schema.
+   *
+   * When `load` is provided, `getConfigPath` is ignored.
+   *
+   * @param parsed The result from the first parse pass.
+   * @returns Config data and metadata (config is validated by schema).
+   * @since 1.0.0
+   */
+  readonly load?: (parsed: ParserValuePlaceholder) => Promise<ConfigLoadResult<TConfigMeta>> | ConfigLoadResult<TConfigMeta>;
+}
+/**
+ * A config context that provides configuration data via annotations.
+ *
+ * When used with `runWith()` or `run()`, the options must include either
+ * `getConfigPath` or `load` with the correct parser result type.  The
+ * `ParserValuePlaceholder` in `ConfigContextRequiredOptions` is substituted
+ * with the actual parser type.
+ *
+ * @template T The validated config data type.
+ * @template TConfigMeta Metadata type for config sources.
+ * @since 0.10.0
+ */
+interface ConfigContext<T, TConfigMeta = ConfigMeta> extends SourceContext<ConfigContextRequiredOptions<TConfigMeta>> {
+  /**
+   * The Standard Schema validator for the config file.
+   */
+  readonly schema: StandardSchemaV1<unknown, T>;
+}
+/**
+ * Creates a config context for use with Optique parsers.
+ *
+ * The config context implements the `SourceContext` interface and can be used
+ * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
+ * *@optique/run* to provide configuration file support.
+ *
+ * @template T The output type of the config schema.
+ * @template TConfigMeta The metadata type for config sources.
+ * @param options Configuration options including schema and optional file
+ *   parser.
+ * @returns A config context that can be used with `bindConfig()` and runners.
+ * @throws {TypeError} If `schema` is not a valid Standard Schema object.
+ * @throws {TypeError} If `fileParser` is provided but is not a function.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ * import { createConfigContext } from "@optique/config";
+ *
+ * const schema = z.object({
+ *   host: z.string(),
+ *   port: z.number(),
+ * });
+ *
+ * const configContext = createConfigContext({ schema });
+ * ```
+ */
+declare function createConfigContext<T, TConfigMeta = ConfigMeta>(options: ConfigContextOptions<T>): ConfigContext<T, TConfigMeta>;
+/**
+ * Options for binding a parser to config values.
+ *
+ * @template T The config data type.
+ * @template TValue The value type extracted from config.
+ * @since 0.10.0
+ */
+interface BindConfigOptions<T, TValue, TConfigMeta = ConfigMeta> {
+  /**
+   * The config context to use for fallback values.
+   */
+  readonly context: ConfigContext<T, TConfigMeta>;
+  /**
+   * Key or accessor function to extract the value from config.
+   * Can be a property key (for top-level config values) or a function
+   * that extracts nested values. Accessor callbacks receive config metadata,
+   * if available, as the second argument.
+   */
+  readonly key: keyof T | ((config: T, meta: TConfigMeta | undefined) => TValue);
+  /**
+   * Default value to use when neither CLI nor config provides a value.
+   * If not specified, the parser will fail when no value is available.
+   */
+  readonly default?: TValue;
+}
+/**
+ * Binds a parser to configuration values with fallback priority.
+ *
+ * The binding implements the following priority order:
+ * 1. CLI argument (if provided)
+ * 2. Config file value (if available)
+ * 3. Default value (if specified)
+ * 4. Error (if none of the above)
+ *
+ * @template M The parser mode (sync or async).
+ * @template TValue The parser value type.
+ * @template TState The parser state type.
+ * @template T The config data type.
+ * @param parser The parser to bind to config values.
+ * @param options Binding options including context, key, and default.
+ * @returns A new parser with config fallback behavior.
+ * @throws {TypeError} If `key` is not a property key or function.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { bindConfig } from "@optique/config";
+ * import { option } from "@optique/core/primitives";
+ * import { string } from "@optique/core/valueparser";
+ *
+ * const hostParser = bindConfig(option("--host", string()), {
+ *   context: configContext,
+ *   key: "host",
+ *   default: "localhost",
+ * });
+ * ```
+ */
+declare function bindConfig<M extends "sync" | "async", TValue, TState, T, TConfigMeta = ConfigMeta>(parser: Parser<M, TValue, TState>, options: BindConfigOptions<T, TValue, TConfigMeta>): Parser<M, TValue, TState>;
+//#endregion
+export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigLoadResult, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };

package/dist/index.d.ts

@@ -1,2 +1,237 @@
-import { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig } from "./index-CYn_0yAG.js";
-export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };
+import { ParserValuePlaceholder, SourceContext } from "@optique/core/context";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { Parser } from "@optique/core/parser";
+
+//#region src/index.d.ts
+
+/**
+ * Metadata about the loaded config source.
+ *
+ * @since 1.0.0
+ */
+interface ConfigMeta {
+  /**
+   * Directory containing the config file.
+   */
+  readonly configDir: string;
+  /**
+   * Absolute path to the config file.
+   */
+  readonly configPath: string;
+}
+/**
+ * Sets active config data for a context.
+ * @internal
+ */
+declare function setActiveConfig<T>(contextId: symbol, data: T): void;
+/**
+ * Gets active config data for a context.
+ * @internal
+ */
+declare function getActiveConfig<T>(contextId: symbol): T | undefined;
+/**
+ * Clears active config data for a context.
+ * @internal
+ */
+declare function clearActiveConfig(contextId: symbol): void;
+/**
+ * Sets active config metadata for a context.
+ * @internal
+ */
+declare function setActiveConfigMeta<T>(contextId: symbol, meta: T): void;
+/**
+ * Gets active config metadata for a context.
+ * @internal
+ */
+declare function getActiveConfigMeta<T>(contextId: symbol): T | undefined;
+/**
+ * Clears active config metadata for a context.
+ * @internal
+ */
+declare function clearActiveConfigMeta(contextId: symbol): void;
+/**
+ * Options for creating a config context.
+ *
+ * @template T The output type of the config schema.
+ * @since 0.10.0
+ */
+interface ConfigContextOptions<T> {
+  /**
+   * Standard Schema validator for the config file.
+   * Accepts any Standard Schema-compatible library (Zod, Valibot, ArkType, etc.).
+   */
+  readonly schema: StandardSchemaV1<unknown, T>;
+  /**
+   * Custom parser function for reading config file contents.
+   * If not provided, defaults to JSON.parse.
+   *
+   * This option is only used in single-file mode (with `getConfigPath`).
+   * When using the `load` callback, file parsing is handled by the loader.
+   *
+   * @param contents The raw file contents as Uint8Array.
+   * @returns The parsed config data (will be validated by schema).
+   * @since 1.0.0
+   */
+  readonly fileParser?: (contents: Uint8Array) => unknown;
+}
+/**
+ * Result type for custom config loading.
+ *
+ * @template TConfigMeta Metadata type associated with loaded config data.
+ * @since 1.0.0
+ */
+interface ConfigLoadResult<TConfigMeta = ConfigMeta> {
+  /**
+   * Raw config data to validate against the schema.
+   */
+  readonly config: unknown;
+  /**
+   * Metadata about where the config came from, if available.
+   */
+  readonly meta: TConfigMeta | undefined;
+}
+/**
+ * Required options for ConfigContext when used with `runWith()` or `run()`.
+ * The `ParserValuePlaceholder` will be substituted with the actual parser
+ * result type by `runWith()`.
+ *
+ * Provide *either* `getConfigPath` (single-file mode) *or* `load` (custom
+ * multi-file mode).  At least one must be provided; a runtime error is
+ * thrown otherwise.
+ *
+ * @template TConfigMeta Metadata type for config sources.
+ * @since 0.10.0
+ */
+interface ConfigContextRequiredOptions<TConfigMeta = ConfigMeta> {
+  /**
+   * Function to extract config file path from parsed CLI arguments.
+   * Used in single-file mode.  The `parsed` parameter is typed as the
+   * parser's result type.
+   *
+   * @param parsed The parsed CLI arguments (typed from parser).
+   * @returns The config file path, or undefined if not specified.
+   */
+  readonly getConfigPath?: (parsed: ParserValuePlaceholder) => string | undefined;
+  /**
+   * Custom loader function that receives the first-pass parse result and
+   * returns the config data (or a Promise of it).  This allows full control
+   * over file discovery, loading, merging, and error handling.
+   *
+   * The returned data will be validated against the schema.
+   *
+   * When `load` is provided, `getConfigPath` is ignored.
+   *
+   * @param parsed The result from the first parse pass.
+   * @returns Config data and metadata (config is validated by schema).
+   * @since 1.0.0
+   */
+  readonly load?: (parsed: ParserValuePlaceholder) => Promise<ConfigLoadResult<TConfigMeta>> | ConfigLoadResult<TConfigMeta>;
+}
+/**
+ * A config context that provides configuration data via annotations.
+ *
+ * When used with `runWith()` or `run()`, the options must include either
+ * `getConfigPath` or `load` with the correct parser result type.  The
+ * `ParserValuePlaceholder` in `ConfigContextRequiredOptions` is substituted
+ * with the actual parser type.
+ *
+ * @template T The validated config data type.
+ * @template TConfigMeta Metadata type for config sources.
+ * @since 0.10.0
+ */
+interface ConfigContext<T, TConfigMeta = ConfigMeta> extends SourceContext<ConfigContextRequiredOptions<TConfigMeta>> {
+  /**
+   * The Standard Schema validator for the config file.
+   */
+  readonly schema: StandardSchemaV1<unknown, T>;
+}
+/**
+ * Creates a config context for use with Optique parsers.
+ *
+ * The config context implements the `SourceContext` interface and can be used
+ * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
+ * *@optique/run* to provide configuration file support.
+ *
+ * @template T The output type of the config schema.
+ * @template TConfigMeta The metadata type for config sources.
+ * @param options Configuration options including schema and optional file
+ *   parser.
+ * @returns A config context that can be used with `bindConfig()` and runners.
+ * @throws {TypeError} If `schema` is not a valid Standard Schema object.
+ * @throws {TypeError} If `fileParser` is provided but is not a function.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ * import { createConfigContext } from "@optique/config";
+ *
+ * const schema = z.object({
+ *   host: z.string(),
+ *   port: z.number(),
+ * });
+ *
+ * const configContext = createConfigContext({ schema });
+ * ```
+ */
+declare function createConfigContext<T, TConfigMeta = ConfigMeta>(options: ConfigContextOptions<T>): ConfigContext<T, TConfigMeta>;
+/**
+ * Options for binding a parser to config values.
+ *
+ * @template T The config data type.
+ * @template TValue The value type extracted from config.
+ * @since 0.10.0
+ */
+interface BindConfigOptions<T, TValue, TConfigMeta = ConfigMeta> {
+  /**
+   * The config context to use for fallback values.
+   */
+  readonly context: ConfigContext<T, TConfigMeta>;
+  /**
+   * Key or accessor function to extract the value from config.
+   * Can be a property key (for top-level config values) or a function
+   * that extracts nested values. Accessor callbacks receive config metadata,
+   * if available, as the second argument.
+   */
+  readonly key: keyof T | ((config: T, meta: TConfigMeta | undefined) => TValue);
+  /**
+   * Default value to use when neither CLI nor config provides a value.
+   * If not specified, the parser will fail when no value is available.
+   */
+  readonly default?: TValue;
+}
+/**
+ * Binds a parser to configuration values with fallback priority.
+ *
+ * The binding implements the following priority order:
+ * 1. CLI argument (if provided)
+ * 2. Config file value (if available)
+ * 3. Default value (if specified)
+ * 4. Error (if none of the above)
+ *
+ * @template M The parser mode (sync or async).
+ * @template TValue The parser value type.
+ * @template TState The parser state type.
+ * @template T The config data type.
+ * @param parser The parser to bind to config values.
+ * @param options Binding options including context, key, and default.
+ * @returns A new parser with config fallback behavior.
+ * @throws {TypeError} If `key` is not a property key or function.
+ * @since 0.10.0
+ *
+ * @example
+ * ```typescript
+ * import { bindConfig } from "@optique/config";
+ * import { option } from "@optique/core/primitives";
+ * import { string } from "@optique/core/valueparser";
+ *
+ * const hostParser = bindConfig(option("--host", string()), {
+ *   context: configContext,
+ *   key: "host",
+ *   default: "localhost",
+ * });
+ * ```
+ */
+declare function bindConfig<M extends "sync" | "async", TValue, TState, T, TConfigMeta = ConfigMeta>(parser: Parser<M, TValue, TState>, options: BindConfigOptions<T, TValue, TConfigMeta>): Parser<M, TValue, TState>;
+//#endregion
+export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigLoadResult, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };