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

package/README.md

@@ -29,11 +29,11 @@ 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";
+import { runAsync } from "@optique/run";
 
 // 1. Define config schema
 const configSchema = z.object({
@@ -58,8 +58,9 @@ const parser = object({
   }),
 });
 
-// 3. Run with config support
-const result = await runWithConfig(parser, configContext, {
+// 3. Run with config support via contexts
+const result = await runAsync(parser, {
+  contexts: [configContext],
   getConfigPath: (parsed) => parsed.config,
   args: process.argv.slice(2),
 });

package/dist/index.cjs

@@ -1,12 +1,373 @@
-const require_src = require('./src-loxvrkxq.cjs');
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
 
-exports.bindConfig = require_src.bindConfig;
-exports.clearActiveConfig = require_src.clearActiveConfig;
-exports.clearActiveConfigMeta = require_src.clearActiveConfigMeta;
-exports.configKey = require_src.configKey;
-exports.configMetaKey = require_src.configMetaKey;
-exports.createConfigContext = require_src.createConfigContext;
-exports.getActiveConfig = require_src.getActiveConfig;
-exports.getActiveConfigMeta = require_src.getActiveConfigMeta;
-exports.setActiveConfig = require_src.setActiveConfig;
-exports.setActiveConfigMeta = require_src.setActiveConfigMeta;
+//#endregion
+const node_fs_promises = __toESM(require("node:fs/promises"));
+const node_path = __toESM(require("node:path"));
+const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
+const __optique_core_message = __toESM(require("@optique/core/message"));
+
+//#region src/index.ts
+/**
+* Unique symbol for config data in annotations.
+* @since 0.10.0
+*/
+const configKey = Symbol.for("@optique/config");
+/**
+* Unique symbol for config metadata in annotations.
+* @since 1.0.0
+*/
+const configMetaKey = Symbol.for("@optique/config/meta");
+/**
+* Internal registry for active config data during config context execution.
+* This is a workaround for the limitation that object() doesn't propagate
+* annotations to child field parsers.
+* @internal
+*/
+const activeConfigRegistry = /* @__PURE__ */ new Map();
+/**
+* Internal registry for active config metadata during config context execution.
+* @internal
+*/
+const activeConfigMetaRegistry = /* @__PURE__ */ new Map();
+/**
+* Sets active config data for a context.
+* @internal
+*/
+function setActiveConfig(contextId, data) {
+	activeConfigRegistry.set(contextId, data);
+}
+/**
+* Gets active config data for a context.
+* @internal
+*/
+function getActiveConfig(contextId) {
+	return activeConfigRegistry.get(contextId);
+}
+/**
+* Clears active config data for a context.
+* @internal
+*/
+function clearActiveConfig(contextId) {
+	activeConfigRegistry.delete(contextId);
+}
+/**
+* Sets active config metadata for a context.
+* @internal
+*/
+function setActiveConfigMeta(contextId, meta) {
+	activeConfigMetaRegistry.set(contextId, meta);
+}
+/**
+* Gets active config metadata for a context.
+* @internal
+*/
+function getActiveConfigMeta(contextId) {
+	return activeConfigMetaRegistry.get(contextId);
+}
+/**
+* Clears active config metadata for a context.
+* @internal
+*/
+function clearActiveConfigMeta(contextId) {
+	activeConfigMetaRegistry.delete(contextId);
+}
+function isErrnoException(error) {
+	return typeof error === "object" && error !== null && "code" in error;
+}
+/**
+* Validates raw data against a Standard Schema and returns the validated value.
+* @internal
+*/
+async function validateWithSchema(schema, rawData) {
+	const validation = schema["~standard"].validate(rawData);
+	const validationResult = validation instanceof Promise ? await validation : validation;
+	if (validationResult.issues) {
+		const firstIssue = validationResult.issues[0];
+		throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
+	}
+	return validationResult.value;
+}
+/**
+* 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.
+* @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 });
+* ```
+*/
+function createConfigContext(options) {
+	const contextId = Symbol.for(`@optique/config:${Math.random()}`);
+	return {
+		id: contextId,
+		schema: options.schema,
+		async getAnnotations(parsed, runtimeOptions) {
+			if (!parsed) return {};
+			const opts = runtimeOptions;
+			if (!opts || !opts.getConfigPath && !opts.load) throw new TypeError("Either getConfigPath or load must be provided in the runner options when using ConfigContext.");
+			let configData;
+			let configMeta;
+			const parsedValue = parsed;
+			if (opts.load) {
+				const loaded = await Promise.resolve(opts.load(parsedValue));
+				configData = await validateWithSchema(options.schema, loaded.config);
+				configMeta = loaded.meta;
+			} else if (opts.getConfigPath) {
+				const configPath = opts.getConfigPath(parsedValue);
+				if (configPath) {
+					const absoluteConfigPath = (0, node_path.resolve)(configPath);
+					const singleFileMeta = {
+						configDir: (0, node_path.dirname)(absoluteConfigPath),
+						configPath: absoluteConfigPath
+					};
+					try {
+						const contents = await (0, node_fs_promises.readFile)(absoluteConfigPath);
+						let rawData;
+						if (options.fileParser) rawData = options.fileParser(contents);
+						else {
+							const text = new TextDecoder().decode(contents);
+							rawData = JSON.parse(text);
+						}
+						configData = await validateWithSchema(options.schema, rawData);
+						configMeta = singleFileMeta;
+					} catch (error) {
+						if (isErrnoException(error) && error.code === "ENOENT") configData = void 0;
+						else if (error instanceof SyntaxError) throw new Error(`Failed to parse config file ${absoluteConfigPath}: ${error.message}`);
+						else throw error;
+					}
+				}
+			}
+			if (configData !== void 0 && configData !== null) {
+				setActiveConfig(contextId, configData);
+				if (configMeta !== void 0) {
+					setActiveConfigMeta(contextId, configMeta);
+					return {
+						[configKey]: configData,
+						[configMetaKey]: configMeta
+					};
+				}
+				return { [configKey]: configData };
+			}
+			return {};
+		},
+		[Symbol.dispose]() {
+			clearActiveConfig(contextId);
+			clearActiveConfigMeta(contextId);
+		}
+	};
+}
+/**
+* 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",
+* });
+* ```
+*/
+function bindConfig(parser, options) {
+	return {
+		$mode: parser.$mode,
+		$valueType: parser.$valueType,
+		$stateType: parser.$stateType,
+		priority: parser.priority,
+		usage: options.default !== void 0 ? [{
+			type: "optional",
+			terms: parser.usage
+		}] : parser.usage,
+		initialState: parser.initialState,
+		parse: (context) => {
+			const annotations = (0, __optique_core_annotations.getAnnotations)(context.state);
+			const result = parser.parse(context);
+			if (!(result instanceof Promise)) {
+				if (result.success) {
+					const newState$1 = {
+						hasCliValue: true,
+						cliState: result.next.state,
+						...annotations && { [__optique_core_annotations.annotationKey]: annotations }
+					};
+					return {
+						success: true,
+						next: {
+							...result.next,
+							state: newState$1
+						},
+						consumed: result.consumed
+					};
+				}
+				const newState = {
+					hasCliValue: false,
+					...annotations && { [__optique_core_annotations.annotationKey]: annotations }
+				};
+				return {
+					success: true,
+					next: {
+						...context,
+						state: newState
+					},
+					consumed: []
+				};
+			}
+			return result.then((res) => {
+				if (res.success) {
+					const newState$1 = {
+						hasCliValue: true,
+						cliState: res.next.state,
+						...annotations && { [__optique_core_annotations.annotationKey]: annotations }
+					};
+					return {
+						success: true,
+						next: {
+							...res.next,
+							state: newState$1
+						},
+						consumed: res.consumed
+					};
+				}
+				const newState = {
+					hasCliValue: false,
+					...annotations && { [__optique_core_annotations.annotationKey]: annotations }
+				};
+				return {
+					success: true,
+					next: {
+						...context,
+						state: newState
+					},
+					consumed: []
+				};
+			});
+		},
+		complete: (state) => {
+			const bindState = state;
+			if (bindState?.hasCliValue && bindState.cliState !== void 0) {
+				const innerResult = parser.complete(bindState.cliState);
+				if (innerResult instanceof Promise) return innerResult.then((res) => {
+					if (res.success) return {
+						success: true,
+						value: res.value
+					};
+					return res;
+				});
+				if (innerResult.success) return {
+					success: true,
+					value: innerResult.value
+				};
+				return innerResult;
+			}
+			return getConfigOrDefault(state, options);
+		},
+		suggest: parser.suggest,
+		getDocFragments(state, upperDefaultValue) {
+			const defaultValue = upperDefaultValue ?? options.default;
+			return parser.getDocFragments(state, defaultValue);
+		}
+	};
+}
+/**
+* Helper function to get value from config or default.
+* Checks both annotations (for top-level parsers) and the active config
+* registry (for parsers nested inside object() when used with context-aware
+* runners).
+*/
+function getConfigOrDefault(state, options) {
+	const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+	let configData = annotations?.[configKey];
+	let configMeta = annotations?.[configMetaKey];
+	if (configData === void 0 || configData === null) {
+		const contextId = options.context.id;
+		configData = getActiveConfig(contextId);
+		configMeta = getActiveConfigMeta(contextId);
+	}
+	let configValue;
+	if (configData !== void 0 && configData !== null) if (typeof options.key === "function") try {
+		configValue = options.key(configData, configMeta);
+	} catch {
+		configValue = void 0;
+	}
+	else configValue = configData[options.key];
+	if (configValue !== void 0) return {
+		success: true,
+		value: configValue
+	};
+	if (options.default !== void 0) return {
+		success: true,
+		value: options.default
+	};
+	return {
+		success: false,
+		error: __optique_core_message.message`Missing required configuration value.`
+	};
+}
+
+//#endregion
+exports.bindConfig = bindConfig;
+exports.clearActiveConfig = clearActiveConfig;
+exports.clearActiveConfigMeta = clearActiveConfigMeta;
+exports.configKey = configKey;
+exports.configMetaKey = configMetaKey;
+exports.createConfigContext = createConfigContext;
+exports.getActiveConfig = getActiveConfig;
+exports.getActiveConfigMeta = getActiveConfigMeta;
+exports.setActiveConfig = setActiveConfig;
+exports.setActiveConfigMeta = setActiveConfigMeta;

package/dist/index.d.cts

@@ -1,2 +1,244 @@
-import { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta } from "./index-BZLEbR0f.cjs";
-export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };
+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;
+/**
+ * Unique symbol for config metadata in annotations.
+ * @since 1.0.0
+ */
+declare const configMetaKey: unique symbol;
+/**
+ * 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.
+   */
+  readonly meta: TConfigMeta;
+}
+/**
+ * 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.
+ * @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
+   * as the second argument.
+   */
+  readonly key: keyof T | ((config: T, meta: TConfigMeta) => 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, 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, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };