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

package/dist/index.d.ts

@@ -1,2 +1,244 @@
-import { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta } from "./index-0XaZnIP1.js";
-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 };

package/dist/index.js

@@ -1,3 +1,341 @@
-import { bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta } from "./src-DaFxoeAp.js";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { annotationKey, getAnnotations } from "@optique/core/annotations";
+import { message } from "@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 = resolve(configPath);
+					const singleFileMeta = {
+						configDir: dirname(absoluteConfigPath),
+						configPath: absoluteConfigPath
+					};
+					try {
+						const contents = await 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 = 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 && { [annotationKey]: annotations }
+					};
+					return {
+						success: true,
+						next: {
+							...result.next,
+							state: newState$1
+						},
+						consumed: result.consumed
+					};
+				}
+				const newState = {
+					hasCliValue: false,
+					...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 && { [annotationKey]: annotations }
+					};
+					return {
+						success: true,
+						next: {
+							...res.next,
+							state: newState$1
+						},
+						consumed: res.consumed
+					};
+				}
+				const newState = {
+					hasCliValue: false,
+					...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 = 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: message`Missing required configuration value.`
+	};
+}
+
+//#endregion
 export { bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/config",
-  "version": "1.0.0-dev.429+66edc8ed",
+  "version": "1.0.0-dev.432+dddcca3d",
   "description": "Configuration file support for Optique with Standard Schema validation",
   "keywords": [
     "CLI",
@@ -52,14 +52,6 @@
       },
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    },
-    "./run": {
-      "types": {
-        "import": "./dist/run.d.ts",
-        "require": "./dist/run.d.cts"
-      },
-      "import": "./dist/run.js",
-      "require": "./dist/run.cjs"
     }
   },
   "sideEffects": false,
@@ -67,7 +59,7 @@
     "@standard-schema/spec": "^1.1.0"
   },
   "dependencies": {
-    "@optique/core": "1.0.0-dev.429+66edc8ed"
+    "@optique/core": "1.0.0-dev.432+dddcca3d"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",