@optique/config 0.10.0-dev.0

package/dist/run.d.ts

@@ -0,0 +1,79 @@
+import { ConfigContext } from "./index-DiDpcijz.js";
+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 };

package/dist/run.js

@@ -0,0 +1,114 @@
+import { clearActiveConfig, configKey, setActiveConfig } from "./src-iXO5MxwN.js";
+import { readFile } from "node:fs/promises";
+import { parse } from "@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 = 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 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 ? { [configKey]: configData } : {};
+	if (configData) setActiveConfig(context.id, configData);
+	try {
+		const secondPass = 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 {
+		clearActiveConfig(context.id);
+	}
+}
+
+//#endregion
+export { runWithConfig };

package/dist/src-DVH5fJU9.cjs

@@ -0,0 +1,295 @@
+//#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));
+
+//#endregion
+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");
+/**
+* Internal registry for active config data during runWithConfig execution.
+* This is a workaround for the limitation that object() doesn't propagate
+* annotations to child field parsers.
+* @internal
+*/
+const activeConfigRegistry = /* @__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);
+}
+/**
+* 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 });
+* ```
+*/
+function createConfigContext(options) {
+	return {
+		id: configKey,
+		schema: options.schema,
+		parser: options.parser,
+		getAnnotations(parsed) {
+			if (!parsed) return {};
+			return {};
+		}
+	};
+}
+/**
+* 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: 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 getConfigOrDefault(state, options);
+				});
+				if (innerResult.success) return {
+					success: true,
+					value: innerResult.value
+				};
+				return getConfigOrDefault(state, options);
+			}
+			return getConfigOrDefault(state, options);
+		},
+		suggest: parser.suggest,
+		getDocFragments: parser.getDocFragments
+	};
+}
+/**
+* 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 runWithConfig).
+*/
+function getConfigOrDefault(state, options) {
+	const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+	let configData = annotations?.[configKey];
+	if (configData === void 0 || configData === null) {
+		const contextId = options.context.id;
+		configData = getActiveConfig(contextId);
+	}
+	let configValue;
+	if (configData !== void 0 && configData !== null) if (typeof options.key === "function") try {
+		configValue = options.key(configData);
+	} 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
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});
+Object.defineProperty(exports, 'bindConfig', {
+  enumerable: true,
+  get: function () {
+    return bindConfig;
+  }
+});
+Object.defineProperty(exports, 'clearActiveConfig', {
+  enumerable: true,
+  get: function () {
+    return clearActiveConfig;
+  }
+});
+Object.defineProperty(exports, 'configKey', {
+  enumerable: true,
+  get: function () {
+    return configKey;
+  }
+});
+Object.defineProperty(exports, 'createConfigContext', {
+  enumerable: true,
+  get: function () {
+    return createConfigContext;
+  }
+});
+Object.defineProperty(exports, 'getActiveConfig', {
+  enumerable: true,
+  get: function () {
+    return getActiveConfig;
+  }
+});
+Object.defineProperty(exports, 'setActiveConfig', {
+  enumerable: true,
+  get: function () {
+    return setActiveConfig;
+  }
+});

package/dist/src-iXO5MxwN.js

@@ -0,0 +1,231 @@
+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");
+/**
+* Internal registry for active config data during runWithConfig execution.
+* This is a workaround for the limitation that object() doesn't propagate
+* annotations to child field parsers.
+* @internal
+*/
+const activeConfigRegistry = /* @__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);
+}
+/**
+* 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 });
+* ```
+*/
+function createConfigContext(options) {
+	return {
+		id: configKey,
+		schema: options.schema,
+		parser: options.parser,
+		getAnnotations(parsed) {
+			if (!parsed) return {};
+			return {};
+		}
+	};
+}
+/**
+* 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: 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 getConfigOrDefault(state, options);
+				});
+				if (innerResult.success) return {
+					success: true,
+					value: innerResult.value
+				};
+				return getConfigOrDefault(state, options);
+			}
+			return getConfigOrDefault(state, options);
+		},
+		suggest: parser.suggest,
+		getDocFragments: parser.getDocFragments
+	};
+}
+/**
+* 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 runWithConfig).
+*/
+function getConfigOrDefault(state, options) {
+	const annotations = getAnnotations(state);
+	let configData = annotations?.[configKey];
+	if (configData === void 0 || configData === null) {
+		const contextId = options.context.id;
+		configData = getActiveConfig(contextId);
+	}
+	let configValue;
+	if (configData !== void 0 && configData !== null) if (typeof options.key === "function") try {
+		configValue = options.key(configData);
+	} 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, configKey, createConfigContext, getActiveConfig, setActiveConfig };