@optique/config 1.0.0-dev.428 → 1.0.0-dev.431

package/dist/index-CYn_0yAG.d.ts

@@ -1,155 +0,0 @@
-import { StandardSchemaV1 } from "@standard-schema/spec";
-import { ParserValuePlaceholder, SourceContext } from "@optique/core/context";
-import { Parser } from "@optique/core/parser";
-
-//#region src/index.d.ts
-
-/**
- * Unique symbol for config data in annotations.
- * @since 0.10.0
- */
-declare const configKey: unique symbol;
-/**
- * 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;
-/**
- * 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>;
-}
-/**
- * Required options for ConfigContext when used with runWith().
- * The `ParserValuePlaceholder` will be substituted with the actual parser
- * result type by runWith().
- *
- * @since 0.10.0
- */
-interface ConfigContextRequiredOptions {
-  /**
-   * Function to extract config file path from parsed CLI arguments.
-   * 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;
-}
-/**
- * A config context that provides configuration data via annotations.
- *
- * When used with `runWith()`, the options must include `getConfigPath` with
- * the correct parser result type. The `ParserValuePlaceholder` in
- * `ConfigContextRequiredOptions` is substituted with the actual parser type.
- *
- * @template T The validated config data type.
- * @since 0.10.0
- */
-interface ConfigContext<T> extends SourceContext<ConfigContextRequiredOptions> {
-  /**
-   * 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() or runWithConfig() to provide configuration file support.
- *
- * @template T The output type of the config schema.
- * @param options Configuration options including schema and optional parser.
- * @returns A config context that can be used with bindConfig() and runWithConfig().
- * @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>(options: ConfigContextOptions<T>): ConfigContext<T>;
-/**
- * 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> {
-  /**
-   * The config context to use for fallback values.
-   */
-  readonly context: ConfigContext<T>;
-  /**
-   * 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.
-   */
-  readonly key: keyof T | ((config: T) => 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.
- * @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>(parser: Parser<M, TValue, TState>, options: BindConfigOptions<T, TValue>): Parser<M, TValue, TState>;
-//#endregion
-export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };

package/dist/index-D25zYfjf.d.cts

@@ -1,155 +0,0 @@
-import { StandardSchemaV1 } from "@standard-schema/spec";
-import { ParserValuePlaceholder, SourceContext } from "@optique/core/context";
-import { Parser } from "@optique/core/parser";
-
-//#region src/index.d.ts
-
-/**
- * Unique symbol for config data in annotations.
- * @since 0.10.0
- */
-declare const configKey: unique symbol;
-/**
- * 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;
-/**
- * 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>;
-}
-/**
- * Required options for ConfigContext when used with runWith().
- * The `ParserValuePlaceholder` will be substituted with the actual parser
- * result type by runWith().
- *
- * @since 0.10.0
- */
-interface ConfigContextRequiredOptions {
-  /**
-   * Function to extract config file path from parsed CLI arguments.
-   * 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;
-}
-/**
- * A config context that provides configuration data via annotations.
- *
- * When used with `runWith()`, the options must include `getConfigPath` with
- * the correct parser result type. The `ParserValuePlaceholder` in
- * `ConfigContextRequiredOptions` is substituted with the actual parser type.
- *
- * @template T The validated config data type.
- * @since 0.10.0
- */
-interface ConfigContext<T> extends SourceContext<ConfigContextRequiredOptions> {
-  /**
-   * 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() or runWithConfig() to provide configuration file support.
- *
- * @template T The output type of the config schema.
- * @param options Configuration options including schema and optional parser.
- * @returns A config context that can be used with bindConfig() and runWithConfig().
- * @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>(options: ConfigContextOptions<T>): ConfigContext<T>;
-/**
- * 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> {
-  /**
-   * The config context to use for fallback values.
-   */
-  readonly context: ConfigContext<T>;
-  /**
-   * 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.
-   */
-  readonly key: keyof T | ((config: T) => 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.
- * @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>(parser: Parser<M, TValue, TState>, options: BindConfigOptions<T, TValue>): Parser<M, TValue, TState>;
-//#endregion
-export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };

package/dist/run.cjs

@@ -1,189 +0,0 @@
-const require_src = require('./src-9MkUoh9z.cjs');
-const node_fs_promises = require_src.__toESM(require("node:fs/promises"));
-const node_path = require_src.__toESM(require("node:path"));
-const node_process = require_src.__toESM(require("node:process"));
-const __optique_core_facade = require_src.__toESM(require("@optique/core/facade"));
-
-//#region src/run.ts
-function isErrnoException(error) {
-	return typeof error === "object" && error !== null && "code" in error;
-}
-/**
-* Helper function to create a wrapper SourceContext for config loading.
-* @internal
-*/
-function createConfigSourceContext(context, options) {
-	return {
-		id: context.id,
-		async getAnnotations(parsed) {
-			if (!parsed) return {};
-			let configData;
-			if ("load" in options) {
-				const customOptions = options;
-				try {
-					const rawData = await Promise.resolve(customOptions.load(parsed));
-					const validation = context.schema["~standard"].validate(rawData);
-					let validationResult;
-					if (validation instanceof Promise) validationResult = await validation;
-					else validationResult = validation;
-					if (validationResult.issues) {
-						const firstIssue = validationResult.issues[0];
-						throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
-					}
-					configData = validationResult.value;
-				} catch (error) {
-					if (error instanceof Error && error.message.includes("validation")) throw error;
-					throw error;
-				}
-			} else {
-				const singleFileOptions = options;
-				const configPath = singleFileOptions.getConfigPath(parsed);
-				if (configPath) try {
-					const contents = await (0, node_fs_promises.readFile)(configPath);
-					let rawData;
-					if (singleFileOptions.fileParser) rawData = singleFileOptions.fileParser(contents);
-					else {
-						const text = new TextDecoder().decode(contents);
-						rawData = JSON.parse(text);
-					}
-					const validation = context.schema["~standard"].validate(rawData);
-					let validationResult;
-					if (validation instanceof Promise) validationResult = await validation;
-					else validationResult = validation;
-					if (validationResult.issues) {
-						const firstIssue = validationResult.issues[0];
-						throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
-					}
-					configData = validationResult.value;
-				} catch (error) {
-					if (isErrnoException(error) && error.code === "ENOENT") configData = void 0;
-					else if (error instanceof SyntaxError) throw new Error(`Failed to parse config file ${configPath}: ${error.message}`);
-					else throw error;
-				}
-			}
-			if (configData !== void 0 && configData !== null) {
-				require_src.setActiveConfig(context.id, configData);
-				return { [require_src.configKey]: configData };
-			}
-			return {};
-		}
-	};
-}
-/**
-* 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 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(() => ({})),
-*     ]);
-*     return deepMerge(...configs);
-*   },
-*   args: process.argv.slice(2),
-*   help: { mode: "option", onShow: () => process.exit(0) },
-* });
-* ```
-*/
-async function runWithConfig(parser, context, options) {
-	const effectiveProgramName = options.programName ?? (typeof node_process.default !== "undefined" && node_process.default.argv?.[1] ? (0, node_path.basename)(node_process.default.argv[1]) : "cli");
-	const wrapperContext = createConfigSourceContext(context, options);
-	try {
-		return await (0, __optique_core_facade.runWith)(parser, effectiveProgramName, [wrapperContext], {
-			args: options.args ?? [],
-			help: options.help,
-			version: options.version,
-			completion: options.completion,
-			stdout: options.stdout,
-			stderr: options.stderr,
-			colors: options.colors,
-			maxWidth: options.maxWidth,
-			showDefault: options.showDefault,
-			showChoices: options.showChoices,
-			aboveError: options.aboveError,
-			brief: options.brief,
-			description: options.description,
-			examples: options.examples,
-			author: options.author,
-			bugs: options.bugs,
-			footer: options.footer,
-			onError: options.onError
-		});
-	} catch (error) {
-		if (error instanceof Error && error.message.startsWith("Failed to parse config file ")) {
-			const stderr = options.stderr ?? console.error;
-			stderr(`Error: ${error.message}`);
-			if (options.onError) try {
-				options.onError(1);
-			} catch {
-				options.onError();
-			}
-			throw error;
-		}
-		throw error;
-	} finally {
-		require_src.clearActiveConfig(context.id);
-	}
-}
-
-//#endregion
-exports.runWithConfig = runWithConfig;