@optique/config 1.0.0-dev.429 → 1.0.0-dev.432

package/dist/run.d.cts

@@ -1,323 +0,0 @@
-import { ConfigContext, ConfigMeta } from "./index-BZLEbR0f.cjs";
-import { Parser } from "@optique/core/parser";
-import { RunOptions } from "@optique/core/facade";
-
-//#region src/run.d.ts
-
-/**
- * Options for single-file config loading.
- *
- * @template TValue The parser value type, inferred from the parser.
- * @template THelp The return type when help is shown.
- * @template TError The return type when an error occurs.
- * @since 0.10.0
- */
-interface SingleFileOptions<TValue, THelp = void, TError = never> {
-  /**
-   * Function to extract the config file path from parsed CLI arguments.
-   * This function receives the result of the first parse pass and should
-   * return the config file path or undefined if no config file is specified.
-   *
-   * The `parsed` parameter is typed based on the parser's result type,
-   * providing full type safety without manual type assertions.
-   */
-  readonly getConfigPath: (parsed: TValue) => string | undefined;
-  /**
-   * Custom parser function for reading config file contents.
-   * If not provided, defaults to JSON.parse.
-   *
-   * @param contents The raw file contents as Uint8Array.
-   * @returns The parsed config data (will be validated by schema).
-   */
-  readonly fileParser?: (contents: Uint8Array) => unknown;
-  /**
-   * Command-line arguments to parse.
-   * If not provided, defaults to an empty array.
-   */
-  readonly args?: readonly string[];
-  /**
-   * Name of the program for help/error output.
-   * If not provided, inferred from process.argv[1].
-   */
-  readonly programName?: string;
-  /**
-   * Help configuration. See RunOptions for details.
-   */
-  readonly help?: RunOptions<THelp, TError>["help"];
-  /**
-   * Version configuration. See RunOptions for details.
-   */
-  readonly version?: RunOptions<THelp, TError>["version"];
-  /**
-   * Completion configuration. See RunOptions for details.
-   */
-  readonly completion?: RunOptions<THelp, TError>["completion"];
-  /**
-   * Output function for standard output. See RunOptions for details.
-   */
-  readonly stdout?: RunOptions<THelp, TError>["stdout"];
-  /**
-   * Output function for standard error. See RunOptions for details.
-   */
-  readonly stderr?: RunOptions<THelp, TError>["stderr"];
-  /**
-   * Whether to enable colored output. See RunOptions for details.
-   */
-  readonly colors?: RunOptions<THelp, TError>["colors"];
-  /**
-   * Maximum width for output formatting. See RunOptions for details.
-   */
-  readonly maxWidth?: RunOptions<THelp, TError>["maxWidth"];
-  /**
-   * Whether and how to display default values. See RunOptions for details.
-   */
-  readonly showDefault?: RunOptions<THelp, TError>["showDefault"];
-  /**
-   * Whether and how to display valid choices. See RunOptions for details.
-   */
-  readonly showChoices?: RunOptions<THelp, TError>["showChoices"];
-  /**
-   * What to display above error messages. See RunOptions for details.
-   */
-  readonly aboveError?: RunOptions<THelp, TError>["aboveError"];
-  /**
-   * Brief description for help text. See RunOptions for details.
-   */
-  readonly brief?: RunOptions<THelp, TError>["brief"];
-  /**
-   * Detailed description for help text. See RunOptions for details.
-   */
-  readonly description?: RunOptions<THelp, TError>["description"];
-  /**
-   * Usage examples for help text. See RunOptions for details.
-   */
-  readonly examples?: RunOptions<THelp, TError>["examples"];
-  /**
-   * Author information for help text. See RunOptions for details.
-   */
-  readonly author?: RunOptions<THelp, TError>["author"];
-  /**
-   * Bug reporting information for help text. See RunOptions for details.
-   */
-  readonly bugs?: RunOptions<THelp, TError>["bugs"];
-  /**
-   * Footer text for help. See RunOptions for details.
-   */
-  readonly footer?: RunOptions<THelp, TError>["footer"];
-  /**
-   * Error handler. See RunOptions for details.
-   */
-  readonly onError?: RunOptions<THelp, TError>["onError"];
-}
-/**
- * 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.
-   */
-  readonly meta: TConfigMeta;
-}
-/**
- * Options for custom config loading with multi-file merging support.
- *
- * @template TValue The parser value type, inferred from the parser.
- * @template THelp The return type when help is shown.
- * @template TError The return type when an error occurs.
- * @since 0.10.0
- */
-interface CustomLoadOptions<TValue, TConfigMeta = ConfigMeta, THelp = void, TError = never> {
-  /**
-   * 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.
-   *
-   * @param parsed The result from the first parse pass.
-   * @returns Config data and metadata (config is validated by schema).
-   */
-  readonly load: (parsed: TValue) => Promise<ConfigLoadResult<TConfigMeta>> | ConfigLoadResult<TConfigMeta>;
-  /**
-   * Command-line arguments to parse.
-   * If not provided, defaults to an empty array.
-   */
-  readonly args?: readonly string[];
-  /**
-   * Name of the program for help/error output.
-   * If not provided, inferred from process.argv[1].
-   */
-  readonly programName?: string;
-  /**
-   * Help configuration. See RunOptions for details.
-   */
-  readonly help?: RunOptions<THelp, TError>["help"];
-  /**
-   * Version configuration. See RunOptions for details.
-   */
-  readonly version?: RunOptions<THelp, TError>["version"];
-  /**
-   * Completion configuration. See RunOptions for details.
-   */
-  readonly completion?: RunOptions<THelp, TError>["completion"];
-  /**
-   * Output function for standard output. See RunOptions for details.
-   */
-  readonly stdout?: RunOptions<THelp, TError>["stdout"];
-  /**
-   * Output function for standard error. See RunOptions for details.
-   */
-  readonly stderr?: RunOptions<THelp, TError>["stderr"];
-  /**
-   * Whether to enable colored output. See RunOptions for details.
-   */
-  readonly colors?: RunOptions<THelp, TError>["colors"];
-  /**
-   * Maximum width for output formatting. See RunOptions for details.
-   */
-  readonly maxWidth?: RunOptions<THelp, TError>["maxWidth"];
-  /**
-   * Whether and how to display default values. See RunOptions for details.
-   */
-  readonly showDefault?: RunOptions<THelp, TError>["showDefault"];
-  /**
-   * Whether and how to display valid choices. See RunOptions for details.
-   */
-  readonly showChoices?: RunOptions<THelp, TError>["showChoices"];
-  /**
-   * What to display above error messages. See RunOptions for details.
-   */
-  readonly aboveError?: RunOptions<THelp, TError>["aboveError"];
-  /**
-   * Brief description for help text. See RunOptions for details.
-   */
-  readonly brief?: RunOptions<THelp, TError>["brief"];
-  /**
-   * Detailed description for help text. See RunOptions for details.
-   */
-  readonly description?: RunOptions<THelp, TError>["description"];
-  /**
-   * Usage examples for help text. See RunOptions for details.
-   */
-  readonly examples?: RunOptions<THelp, TError>["examples"];
-  /**
-   * Author information for help text. See RunOptions for details.
-   */
-  readonly author?: RunOptions<THelp, TError>["author"];
-  /**
-   * Bug reporting information for help text. See RunOptions for details.
-   */
-  readonly bugs?: RunOptions<THelp, TError>["bugs"];
-  /**
-   * Footer text for help. See RunOptions for details.
-   */
-  readonly footer?: RunOptions<THelp, TError>["footer"];
-  /**
-   * Error handler. See RunOptions for details.
-   */
-  readonly onError?: RunOptions<THelp, TError>["onError"];
-}
-/**
- * Options for runWithConfig.
- *
- * @template TValue The parser value type, inferred from the parser.
- * @template THelp The return type when help is shown.
- * @template TError The return type when an error occurs.
- * @since 0.10.0
- */
-type RunWithConfigOptions<TValue, TConfigMeta = ConfigMeta, THelp = void, TError = never> = SingleFileOptions<TValue, THelp, TError> | CustomLoadOptions<TValue, TConfigMeta, THelp, TError>;
-/**
- * Runs a parser with configuration file support using two-pass parsing.
- *
- * This function performs the following steps:
- * 1. First pass: Parse arguments to extract config path or data
- * 2. Load and validate: Load config file(s) and validate using Standard Schema
- * 3. Second pass: Parse arguments again with config data as annotations
- *
- * The priority order for values is: CLI > config file > default.
- *
- * The function also supports help, version, and completion features. When these
- * special commands are detected, config loading is skipped entirely, ensuring
- * these features work even when config files don't exist.
- *
- * @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.
- * @template TConfigMeta The config metadata type.
- * @template THelp The return type when help is shown.
- * @template TError The return type when an error occurs.
- * @param parser The parser to execute.
- * @param context The config context with schema.
- * @param options Run options - either SingleFileOptions or CustomLoadOptions.
- * @returns Promise that resolves to the parsed result.
- * @throws Error if config file validation fails.
- * @since 0.10.0
- *
- * @example Single file mode
- * ```typescript
- * import { z } from "zod";
- * import { runWithConfig } from "@optique/config/run";
- * import { createConfigContext, bindConfig } from "@optique/config";
- *
- * const schema = z.object({
- *   host: z.string(),
- *   port: z.number(),
- * });
- *
- * const context = createConfigContext({ schema });
- *
- * const parser = object({
- *   config: option("--config", string()),
- *   host: bindConfig(option("--host", string()), {
- *     context,
- *     key: "host",
- *     default: "localhost",
- *   }),
- * });
- *
- * const result = await runWithConfig(parser, context, {
- *   getConfigPath: (parsed) => parsed.config,
- *   args: process.argv.slice(2),
- *   help: { mode: "option", onShow: () => process.exit(0) },
- *   version: { value: "1.0.0", onShow: () => process.exit(0) },
- * });
- * ```
- *
- * @example Custom load mode (multi-file merging)
- * ```typescript
- * import { deepMerge } from "es-toolkit";
- *
- * const result = await runWithConfig(parser, context, {
- *   load: async (parsed) => {
- *     const configs = await Promise.all([
- *       loadToml("/etc/app/config.toml").catch(() => ({})),
- *       loadToml("~/.config/app/config.toml").catch(() => ({})),
- *       loadToml("./.app.toml").catch(() => ({})),
- *     ]);
- *
- *     const configPath = parsed.config ?? "./.app.toml";
- *     return {
- *       config: deepMerge(...configs),
- *       meta: {
- *         configPath,
- *         configDir: configPath.slice(0, configPath.lastIndexOf("/")),
- *       },
- *     };
- *   },
- *   args: process.argv.slice(2),
- *   help: { mode: "option", onShow: () => process.exit(0) },
- * });
- * ```
- */
-declare function runWithConfig<M extends "sync" | "async", TValue, TState, T, THelp = void, TError = never>(parser: Parser<M, TValue, TState>, context: ConfigContext<T, ConfigMeta>, options: SingleFileOptions<TValue, THelp, TError>): Promise<TValue>;
-declare function runWithConfig<M extends "sync" | "async", TValue, TState, T, TConfigMeta = ConfigMeta, THelp = void, TError = never>(parser: Parser<M, TValue, TState>, context: ConfigContext<T, TConfigMeta>, options: CustomLoadOptions<TValue, TConfigMeta, THelp, TError>): Promise<TValue>;
-//#endregion
-export { ConfigLoadResult, CustomLoadOptions, RunWithConfigOptions, SingleFileOptions, runWithConfig };

package/dist/run.d.ts

@@ -1,323 +0,0 @@
-import { ConfigContext, ConfigMeta } from "./index-0XaZnIP1.js";
-import { RunOptions } from "@optique/core/facade";
-import { Parser } from "@optique/core/parser";
-
-//#region src/run.d.ts
-
-/**
- * Options for single-file config loading.
- *
- * @template TValue The parser value type, inferred from the parser.
- * @template THelp The return type when help is shown.
- * @template TError The return type when an error occurs.
- * @since 0.10.0
- */
-interface SingleFileOptions<TValue, THelp = void, TError = never> {
-  /**
-   * Function to extract the config file path from parsed CLI arguments.
-   * This function receives the result of the first parse pass and should
-   * return the config file path or undefined if no config file is specified.
-   *
-   * The `parsed` parameter is typed based on the parser's result type,
-   * providing full type safety without manual type assertions.
-   */
-  readonly getConfigPath: (parsed: TValue) => string | undefined;
-  /**
-   * Custom parser function for reading config file contents.
-   * If not provided, defaults to JSON.parse.
-   *
-   * @param contents The raw file contents as Uint8Array.
-   * @returns The parsed config data (will be validated by schema).
-   */
-  readonly fileParser?: (contents: Uint8Array) => unknown;
-  /**
-   * Command-line arguments to parse.
-   * If not provided, defaults to an empty array.
-   */
-  readonly args?: readonly string[];
-  /**
-   * Name of the program for help/error output.
-   * If not provided, inferred from process.argv[1].
-   */
-  readonly programName?: string;
-  /**
-   * Help configuration. See RunOptions for details.
-   */
-  readonly help?: RunOptions<THelp, TError>["help"];
-  /**
-   * Version configuration. See RunOptions for details.
-   */
-  readonly version?: RunOptions<THelp, TError>["version"];
-  /**
-   * Completion configuration. See RunOptions for details.
-   */
-  readonly completion?: RunOptions<THelp, TError>["completion"];
-  /**
-   * Output function for standard output. See RunOptions for details.
-   */
-  readonly stdout?: RunOptions<THelp, TError>["stdout"];
-  /**
-   * Output function for standard error. See RunOptions for details.
-   */
-  readonly stderr?: RunOptions<THelp, TError>["stderr"];
-  /**
-   * Whether to enable colored output. See RunOptions for details.
-   */
-  readonly colors?: RunOptions<THelp, TError>["colors"];
-  /**
-   * Maximum width for output formatting. See RunOptions for details.
-   */
-  readonly maxWidth?: RunOptions<THelp, TError>["maxWidth"];
-  /**
-   * Whether and how to display default values. See RunOptions for details.
-   */
-  readonly showDefault?: RunOptions<THelp, TError>["showDefault"];
-  /**
-   * Whether and how to display valid choices. See RunOptions for details.
-   */
-  readonly showChoices?: RunOptions<THelp, TError>["showChoices"];
-  /**
-   * What to display above error messages. See RunOptions for details.
-   */
-  readonly aboveError?: RunOptions<THelp, TError>["aboveError"];
-  /**
-   * Brief description for help text. See RunOptions for details.
-   */
-  readonly brief?: RunOptions<THelp, TError>["brief"];
-  /**
-   * Detailed description for help text. See RunOptions for details.
-   */
-  readonly description?: RunOptions<THelp, TError>["description"];
-  /**
-   * Usage examples for help text. See RunOptions for details.
-   */
-  readonly examples?: RunOptions<THelp, TError>["examples"];
-  /**
-   * Author information for help text. See RunOptions for details.
-   */
-  readonly author?: RunOptions<THelp, TError>["author"];
-  /**
-   * Bug reporting information for help text. See RunOptions for details.
-   */
-  readonly bugs?: RunOptions<THelp, TError>["bugs"];
-  /**
-   * Footer text for help. See RunOptions for details.
-   */
-  readonly footer?: RunOptions<THelp, TError>["footer"];
-  /**
-   * Error handler. See RunOptions for details.
-   */
-  readonly onError?: RunOptions<THelp, TError>["onError"];
-}
-/**
- * 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.
-   */
-  readonly meta: TConfigMeta;
-}
-/**
- * Options for custom config loading with multi-file merging support.
- *
- * @template TValue The parser value type, inferred from the parser.
- * @template THelp The return type when help is shown.
- * @template TError The return type when an error occurs.
- * @since 0.10.0
- */
-interface CustomLoadOptions<TValue, TConfigMeta = ConfigMeta, THelp = void, TError = never> {
-  /**
-   * 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.
-   *
-   * @param parsed The result from the first parse pass.
-   * @returns Config data and metadata (config is validated by schema).
-   */
-  readonly load: (parsed: TValue) => Promise<ConfigLoadResult<TConfigMeta>> | ConfigLoadResult<TConfigMeta>;
-  /**
-   * Command-line arguments to parse.
-   * If not provided, defaults to an empty array.
-   */
-  readonly args?: readonly string[];
-  /**
-   * Name of the program for help/error output.
-   * If not provided, inferred from process.argv[1].
-   */
-  readonly programName?: string;
-  /**
-   * Help configuration. See RunOptions for details.
-   */
-  readonly help?: RunOptions<THelp, TError>["help"];
-  /**
-   * Version configuration. See RunOptions for details.
-   */
-  readonly version?: RunOptions<THelp, TError>["version"];
-  /**
-   * Completion configuration. See RunOptions for details.
-   */
-  readonly completion?: RunOptions<THelp, TError>["completion"];
-  /**
-   * Output function for standard output. See RunOptions for details.
-   */
-  readonly stdout?: RunOptions<THelp, TError>["stdout"];
-  /**
-   * Output function for standard error. See RunOptions for details.
-   */
-  readonly stderr?: RunOptions<THelp, TError>["stderr"];
-  /**
-   * Whether to enable colored output. See RunOptions for details.
-   */
-  readonly colors?: RunOptions<THelp, TError>["colors"];
-  /**
-   * Maximum width for output formatting. See RunOptions for details.
-   */
-  readonly maxWidth?: RunOptions<THelp, TError>["maxWidth"];
-  /**
-   * Whether and how to display default values. See RunOptions for details.
-   */
-  readonly showDefault?: RunOptions<THelp, TError>["showDefault"];
-  /**
-   * Whether and how to display valid choices. See RunOptions for details.
-   */
-  readonly showChoices?: RunOptions<THelp, TError>["showChoices"];
-  /**
-   * What to display above error messages. See RunOptions for details.
-   */
-  readonly aboveError?: RunOptions<THelp, TError>["aboveError"];
-  /**
-   * Brief description for help text. See RunOptions for details.
-   */
-  readonly brief?: RunOptions<THelp, TError>["brief"];
-  /**
-   * Detailed description for help text. See RunOptions for details.
-   */
-  readonly description?: RunOptions<THelp, TError>["description"];
-  /**
-   * Usage examples for help text. See RunOptions for details.
-   */
-  readonly examples?: RunOptions<THelp, TError>["examples"];
-  /**
-   * Author information for help text. See RunOptions for details.
-   */
-  readonly author?: RunOptions<THelp, TError>["author"];
-  /**
-   * Bug reporting information for help text. See RunOptions for details.
-   */
-  readonly bugs?: RunOptions<THelp, TError>["bugs"];
-  /**
-   * Footer text for help. See RunOptions for details.
-   */
-  readonly footer?: RunOptions<THelp, TError>["footer"];
-  /**
-   * Error handler. See RunOptions for details.
-   */
-  readonly onError?: RunOptions<THelp, TError>["onError"];
-}
-/**
- * Options for runWithConfig.
- *
- * @template TValue The parser value type, inferred from the parser.
- * @template THelp The return type when help is shown.
- * @template TError The return type when an error occurs.
- * @since 0.10.0
- */
-type RunWithConfigOptions<TValue, TConfigMeta = ConfigMeta, THelp = void, TError = never> = SingleFileOptions<TValue, THelp, TError> | CustomLoadOptions<TValue, TConfigMeta, THelp, TError>;
-/**
- * Runs a parser with configuration file support using two-pass parsing.
- *
- * This function performs the following steps:
- * 1. First pass: Parse arguments to extract config path or data
- * 2. Load and validate: Load config file(s) and validate using Standard Schema
- * 3. Second pass: Parse arguments again with config data as annotations
- *
- * The priority order for values is: CLI > config file > default.
- *
- * The function also supports help, version, and completion features. When these
- * special commands are detected, config loading is skipped entirely, ensuring
- * these features work even when config files don't exist.
- *
- * @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.
- * @template TConfigMeta The config metadata type.
- * @template THelp The return type when help is shown.
- * @template TError The return type when an error occurs.
- * @param parser The parser to execute.
- * @param context The config context with schema.
- * @param options Run options - either SingleFileOptions or CustomLoadOptions.
- * @returns Promise that resolves to the parsed result.
- * @throws Error if config file validation fails.
- * @since 0.10.0
- *
- * @example Single file mode
- * ```typescript
- * import { z } from "zod";
- * import { runWithConfig } from "@optique/config/run";
- * import { createConfigContext, bindConfig } from "@optique/config";
- *
- * const schema = z.object({
- *   host: z.string(),
- *   port: z.number(),
- * });
- *
- * const context = createConfigContext({ schema });
- *
- * const parser = object({
- *   config: option("--config", string()),
- *   host: bindConfig(option("--host", string()), {
- *     context,
- *     key: "host",
- *     default: "localhost",
- *   }),
- * });
- *
- * const result = await runWithConfig(parser, context, {
- *   getConfigPath: (parsed) => parsed.config,
- *   args: process.argv.slice(2),
- *   help: { mode: "option", onShow: () => process.exit(0) },
- *   version: { value: "1.0.0", onShow: () => process.exit(0) },
- * });
- * ```
- *
- * @example Custom load mode (multi-file merging)
- * ```typescript
- * import { deepMerge } from "es-toolkit";
- *
- * const result = await runWithConfig(parser, context, {
- *   load: async (parsed) => {
- *     const configs = await Promise.all([
- *       loadToml("/etc/app/config.toml").catch(() => ({})),
- *       loadToml("~/.config/app/config.toml").catch(() => ({})),
- *       loadToml("./.app.toml").catch(() => ({})),
- *     ]);
- *
- *     const configPath = parsed.config ?? "./.app.toml";
- *     return {
- *       config: deepMerge(...configs),
- *       meta: {
- *         configPath,
- *         configDir: configPath.slice(0, configPath.lastIndexOf("/")),
- *       },
- *     };
- *   },
- *   args: process.argv.slice(2),
- *   help: { mode: "option", onShow: () => process.exit(0) },
- * });
- * ```
- */
-declare function runWithConfig<M extends "sync" | "async", TValue, TState, T, THelp = void, TError = never>(parser: Parser<M, TValue, TState>, context: ConfigContext<T, ConfigMeta>, options: SingleFileOptions<TValue, THelp, TError>): Promise<TValue>;
-declare function runWithConfig<M extends "sync" | "async", TValue, TState, T, TConfigMeta = ConfigMeta, THelp = void, TError = never>(parser: Parser<M, TValue, TState>, context: ConfigContext<T, TConfigMeta>, options: CustomLoadOptions<TValue, TConfigMeta, THelp, TError>): Promise<TValue>;
-//#endregion
-export { ConfigLoadResult, CustomLoadOptions, RunWithConfigOptions, SingleFileOptions, runWithConfig };