@optique/config 0.10.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025–2026 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+@optique/config
+===============
+
+Configuration file support for [Optique] with type-safe validation using
+[Standard Schema].
+
+This package enables CLI applications to load default values from configuration
+files with proper priority handling: CLI arguments > config file values >
+defaults.
+
+[Optique]: https://optique.dev/
+[Standard Schema]: https://standardschema.dev/
+
+
+Installation
+------------
+
+~~~~ bash [Deno]
+deno add jsr:@optique/config npm:@standard-schema/spec npm:zod
+npm  add     @optique/config     @standard-schema/spec     zod
+pnpm add     @optique/config     @standard-schema/spec     zod
+bun  add     @optique/config     @standard-schema/spec     zod
+~~~~
+
+
+Quick start
+-----------
+
+~~~~ typescript
+import { z } from "zod";
+import { createConfigContext, bindConfig } from "@optique/config";
+import { runWithConfig } from "@optique/config/run";
+import { object } from "@optique/core/constructs";
+import { option } from "@optique/core/primitives";
+import { string, integer } from "@optique/core/valueparser";
+import { withDefault } from "@optique/core/modifiers";
+
+// 1. Define config schema
+const configSchema = z.object({
+  host: z.string(),
+  port: z.number(),
+});
+
+const configContext = createConfigContext({ schema: configSchema });
+
+// 2. Bind parsers to config values
+const parser = object({
+  config: withDefault(option("--config", string()), "~/.myapp.json"),
+  host: bindConfig(option("--host", string()), {
+    context: configContext,
+    key: "host",
+    default: "localhost",
+  }),
+  port: bindConfig(option("--port", integer()), {
+    context: configContext,
+    key: "port",
+    default: 3000,
+  }),
+});
+
+// 3. Run with config support
+const result = await runWithConfig(parser, configContext, {
+  getConfigPath: (parsed) => parsed.config,
+  args: process.argv.slice(2),
+});
+
+console.log(`Connecting to ${result.host}:${result.port}`);
+~~~~
+
+With a config file `~/.myapp.json`:
+
+~~~~ json
+{
+  "host": "api.example.com",
+  "port": 8080
+}
+~~~~
+
+Running `myapp --host localhost` will use `localhost` from CLI and `8080` from
+the config file.
+
+
+Features
+--------
+
+ -  *Type-safe validation* using Standard Schema (Zod, Valibot, ArkType, etc.)
+ -  *Priority handling*: CLI > config file > defaults
+ -  *Nested config values* with accessor functions
+ -  *Custom file formats* with parser functions
+ -  *Composable* with other data sources via `SourceContext` interface
+
+
+Documentation
+-------------
+
+For complete documentation, visit <https://optique.dev/integrations/config>.
+
+
+License
+-------
+
+MIT License. See [LICENSE](../../LICENSE) for details.

package/dist/index-CZZEDay7.d.cts

@@ -0,0 +1,167 @@
+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>;
+  /**
+   * 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 parser?: (contents: Uint8Array) => unknown;
+}
+/**
+ * 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>;
+  /**
+   * Custom parser function for reading config file contents.
+   */
+  readonly parser?: (contents: Uint8Array) => unknown;
+}
+/**
+ * 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-DiDpcijz.d.ts

@@ -0,0 +1,167 @@
+import { Parser } from "@optique/core/parser";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { ParserValuePlaceholder, SourceContext } from "@optique/core/context";
+
+//#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>;
+  /**
+   * 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 parser?: (contents: Uint8Array) => unknown;
+}
+/**
+ * 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>;
+  /**
+   * Custom parser function for reading config file contents.
+   */
+  readonly parser?: (contents: Uint8Array) => unknown;
+}
+/**
+ * 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.cjs

@@ -0,0 +1,8 @@
+const require_src = require('./src-DVH5fJU9.cjs');
+
+exports.bindConfig = require_src.bindConfig;
+exports.clearActiveConfig = require_src.clearActiveConfig;
+exports.configKey = require_src.configKey;
+exports.createConfigContext = require_src.createConfigContext;
+exports.getActiveConfig = require_src.getActiveConfig;
+exports.setActiveConfig = require_src.setActiveConfig;

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+import { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig } from "./index-CZZEDay7.cjs";
+export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig } from "./index-DiDpcijz.js";
+export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig } from "./src-iXO5MxwN.js";
+
+export { bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };

package/dist/run.cjs

@@ -0,0 +1,114 @@
+const require_src = require('./src-DVH5fJU9.cjs');
+const node_fs_promises = require_src.__toESM(require("node:fs/promises"));
+const __optique_core_parser = require_src.__toESM(require("@optique/core/parser"));
+
+//#region src/run.ts
+/**
+* Runs a parser with configuration file support using two-pass parsing.
+*
+* This function performs the following steps:
+* 1. First pass: Parse arguments to extract the config file path
+* 2. Load and validate: Read the config file 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.
+*
+* @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 execute.
+* @param context The config context with schema and optional custom parser.
+* @param options Run options including getConfigPath and args.
+* @returns Promise that resolves to the parsed result.
+* @throws Error if config file validation fails.
+* @since 0.10.0
+*
+* @example
+* ```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),
+* });
+* ```
+*/
+async function runWithConfig(parser, context, options) {
+	const args = options.args ?? [];
+	const firstPass = (0, __optique_core_parser.parse)(parser, args);
+	let firstPassResult;
+	if (firstPass instanceof Promise) firstPassResult = await firstPass;
+	else firstPassResult = firstPass;
+	if (!firstPassResult.success) {
+		const errorParts = firstPassResult.error.map((part) => {
+			if (part.type === "text") return part.text;
+			if (part.type === "optionName") return part.optionName;
+			if (part.type === "optionNames") return part.optionNames.join(", ");
+			if (part.type === "metavar") return part.metavar;
+			if (part.type === "value") return part.value;
+			if (part.type === "values") return part.values.join(", ");
+			if (part.type === "envVar") return part.envVar;
+			if (part.type === "commandLine") return part.commandLine;
+			if (part.type === "url") return part.url;
+			return "";
+		});
+		throw new Error(`Parsing failed: ${errorParts.join("")}`);
+	}
+	const configPath = options.getConfigPath(firstPassResult.value);
+	let configData;
+	if (configPath) try {
+		const contents = await (0, node_fs_promises.readFile)(configPath);
+		let rawData;
+		if (context.parser) rawData = context.parser(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 (error instanceof Error && error.message.includes("validation")) throw error;
+		configData = void 0;
+	}
+	const annotations = configData ? { [require_src.configKey]: configData } : {};
+	if (configData) require_src.setActiveConfig(context.id, configData);
+	try {
+		const secondPass = (0, __optique_core_parser.parse)(parser, args, { annotations });
+		let secondPassResult;
+		if (secondPass instanceof Promise) secondPassResult = await secondPass;
+		else secondPassResult = secondPass;
+		if (!secondPassResult.success) throw new Error(`Parsing failed: ${String(secondPassResult.error)}`);
+		return secondPassResult.value;
+	} finally {
+		require_src.clearActiveConfig(context.id);
+	}
+}
+
+//#endregion
+exports.runWithConfig = runWithConfig;

package/dist/run.d.cts

@@ -0,0 +1,79 @@
+import { ConfigContext } from "./index-CZZEDay7.cjs";
+import { Parser } from "@optique/core/parser";
+
+//#region src/run.d.ts
+
+/**
+ * Options for runWithConfig.
+ *
+ * @template TValue The parser value type, inferred from the parser.
+ * @since 0.10.0
+ */
+interface RunWithConfigOptions<TValue> {
+  /**
+   * 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;
+  /**
+   * Command-line arguments to parse.
+   * If not provided, defaults to an empty array.
+   */
+  readonly args?: readonly string[];
+}
+/**
+ * Runs a parser with configuration file support using two-pass parsing.
+ *
+ * This function performs the following steps:
+ * 1. First pass: Parse arguments to extract the config file path
+ * 2. Load and validate: Read the config file 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.
+ *
+ * @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 execute.
+ * @param context The config context with schema and optional custom parser.
+ * @param options Run options including getConfigPath and args.
+ * @returns Promise that resolves to the parsed result.
+ * @throws Error if config file validation fails.
+ * @since 0.10.0
+ *
+ * @example
+ * ```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),
+ * });
+ * ```
+ */
+declare function runWithConfig<M extends "sync" | "async", TValue, TState, T>(parser: Parser<M, TValue, TState>, context: ConfigContext<T>, options: RunWithConfigOptions<TValue>): Promise<TValue>;
+//#endregion
+export { RunWithConfigOptions, runWithConfig };