@optique/env 1.0.0-dev.0 → 1.0.0-dev.1116

package/dist/index.cjs

@@ -23,6 +23,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
 const __optique_core_message = __toESM(require("@optique/core/message"));
+const __optique_core_mode_dispatch = __toESM(require("@optique/core/mode-dispatch"));
 const __optique_core_valueparser = __toESM(require("@optique/core/valueparser"));
 
 //#region src/index.ts
@@ -62,16 +63,20 @@ function defaultEnvSource(key) {
 *
 * @param options Environment context options.
 * @returns A context that provides environment source annotations.
+* @throws {TypeError} If `source` is not a function.
 * @since 1.0.0
 */
 function createEnvContext(options = {}) {
 	const contextId = Symbol(`@optique/env context:${Math.random()}`);
-	const source = options.source ?? defaultEnvSource;
+	const rawSource = options.source;
+	if (rawSource !== void 0 && typeof rawSource !== "function") throw new TypeError(`Expected source to be a function, but got: ${rawSource === null ? "null" : Array.isArray(rawSource) ? "array" : typeof rawSource}.`);
+	const source = rawSource ?? defaultEnvSource;
 	const prefix = options.prefix ?? "";
 	return {
 		id: contextId,
 		prefix,
 		source,
+		mode: "static",
 		getAnnotations() {
 			const sourceData = {
 				prefix,
@@ -98,13 +103,22 @@ function createEnvContext(options = {}) {
 * @param parser Parser that reads CLI values.
 * @param options Environment binding options.
 * @returns A parser with environment fallback behavior.
+* @throws {TypeError} If `key` is not a string or `parser` is not a valid
+*                    {@link ValueParser}.
+* @throws {Error} If the inner parser throws while parsing or completing a
+*                 value, if the environment source throws while reading a
+*                 variable, or if the environment value parser throws while
+*                 parsing the environment variable value.
 * @since 1.0.0
 */
 function bindEnv(parser, options) {
+	if (typeof options.key !== "string") throw new TypeError(`Expected key to be a string, but got: ${options.key === null ? "null" : Array.isArray(options.key) ? "array" : typeof options.key}.`);
+	if (!(0, __optique_core_valueparser.isValueParser)(options.parser)) throw new TypeError(`Expected parser to be a ValueParser, but got: ${options.parser === null ? "null" : Array.isArray(options.parser) ? "array" : typeof options.parser}.`);
 	const envBindStateKey = Symbol("@optique/env/bindState");
 	function isEnvBindState(value) {
 		return value != null && typeof value === "object" && envBindStateKey in value;
 	}
+	const deferPromptUntilConfigResolves = parser.shouldDeferCompletion;
 	return {
 		$mode: parser.$mode,
 		$valueType: parser.$valueType,
@@ -122,25 +136,25 @@ function bindEnv(parser, options) {
 				...context,
 				state: innerState
 			} : context;
-			const processResult = (result$1) => {
-				if (result$1.success) {
-					const cliConsumed = result$1.consumed.length > 0;
+			const processResult = (result) => {
+				if (result.success) {
+					const cliConsumed = result.consumed.length > 0;
 					const nextState$1 = {
 						[envBindStateKey]: true,
 						hasCliValue: cliConsumed,
-						cliState: result$1.next.state,
+						cliState: result.next.state,
 						...annotations && { [__optique_core_annotations.annotationKey]: annotations }
 					};
 					return {
 						success: true,
 						next: {
-							...result$1.next,
+							...result.next,
 							state: nextState$1
 						},
-						consumed: result$1.consumed
+						consumed: result.consumed
 					};
 				}
-				if (result$1.consumed > 0) return result$1;
+				if (result.consumed > 0) return result;
 				const nextState = {
 					[envBindStateKey]: true,
 					hasCliValue: false,
@@ -155,48 +169,47 @@ function bindEnv(parser, options) {
 					consumed: []
 				};
 			};
-			const result = parser.parse(innerContext);
-			if (result instanceof Promise) return result.then(processResult);
-			return processResult(result);
+			return (0, __optique_core_mode_dispatch.mapModeValue)(parser.$mode, parser.parse(innerContext), processResult);
 		},
 		complete: (state) => {
 			if (isEnvBindState(state) && state.hasCliValue) return parser.complete(state.cliState);
 			return getEnvOrDefault(state, options, parser.$mode, parser, isEnvBindState(state) ? state.cliState : void 0);
 		},
 		suggest: parser.suggest,
+		...typeof deferPromptUntilConfigResolves === "function" ? { shouldDeferCompletion: deferPromptUntilConfigResolves.bind(parser) } : {},
 		getDocFragments(state, upperDefaultValue) {
 			const defaultValue = upperDefaultValue ?? options.default;
 			return parser.getDocFragments(state, defaultValue);
 		}
 	};
 }
-function wrapForMode(mode, value) {
-	if (mode === "async") return Promise.resolve(value);
-	return value;
-}
 function getEnvOrDefault(state, options, mode, innerParser, innerState) {
 	const annotations = (0, __optique_core_annotations.getAnnotations)(state);
 	const sourceData = annotations?.[options.context.id] ?? getActiveEnvSource(options.context.id);
 	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
 	const rawValue = sourceData?.source(fullKey);
 	if (rawValue !== void 0) {
+		if (typeof rawValue !== "string") {
+			const type = rawValue === null ? "null" : Array.isArray(rawValue) ? "array" : typeof rawValue;
+			return (0, __optique_core_mode_dispatch.wrapForMode)(mode, {
+				success: false,
+				error: __optique_core_message.message`Environment variable ${(0, __optique_core_message.envVar)(fullKey)} must be a string, but got: ${type}.`
+			});
+		}
 		const parsed = options.parser.parse(rawValue);
-		if (parsed instanceof Promise) return parsed;
-		return wrapForMode(mode, parsed);
+		return (0, __optique_core_mode_dispatch.wrapForMode)(mode, parsed);
 	}
-	if (options.default !== void 0) return wrapForMode(mode, {
+	if (options.default !== void 0) return (0, __optique_core_mode_dispatch.wrapForMode)(mode, {
 		success: true,
 		value: options.default
 	});
 	if (innerParser != null) {
 		const completeState = innerState ?? innerParser.initialState;
-		const result = innerParser.complete(completeState);
-		if (result instanceof Promise) return result;
-		return wrapForMode(mode, result);
+		return (0, __optique_core_mode_dispatch.wrapForMode)(mode, innerParser.complete(completeState));
 	}
-	return wrapForMode(mode, {
+	return (0, __optique_core_mode_dispatch.wrapForMode)(mode, {
 		success: false,
-		error: __optique_core_message.message`Missing required environment variable: ${fullKey}.`
+		error: __optique_core_message.message`Missing required environment variable: ${(0, __optique_core_message.envVar)(fullKey)}`
 	});
 }
 const TRUE_LITERALS = [
@@ -221,6 +234,7 @@ const FALSE_LITERALS = [
 *
 * @param options Parser configuration options.
 * @returns A value parser for Boolean values.
+* @throws {TypeError} If `options.metavar` is an empty string.
 * @since 1.0.0
 */
 function bool(options = {}) {
@@ -247,6 +261,14 @@ function bool(options = {}) {
 		},
 		format(value) {
 			return value ? "true" : "false";
+		},
+		suggest(prefix) {
+			const allLiterals = [...TRUE_LITERALS, ...FALSE_LITERALS];
+			const normalizedPrefix = prefix.toLowerCase();
+			return allLiterals.filter((lit) => lit.startsWith(normalizedPrefix)).map((lit) => ({
+				kind: "literal",
+				text: lit
+			}));
 		}
 	};
 }

package/dist/index.d.cts

@@ -72,6 +72,7 @@ declare function clearActiveEnvSource(contextId: symbol): void;
  *
  * @param options Environment context options.
  * @returns A context that provides environment source annotations.
+ * @throws {TypeError} If `source` is not a function.
  * @since 1.0.0
  */
 declare function createEnvContext(options?: EnvContextOptions): EnvContext;
@@ -92,6 +93,10 @@ interface BindEnvOptions<M extends Mode, TValue> {
   readonly key: string;
   /**
    * Value parser used to parse the environment variable string value.
+   *
+   * In sync mode, the value parser must also be synchronous.
+   * In async mode, either sync or async value parsers are accepted,
+   * since the async pipeline can await sync results as well.
    */
   readonly parser: ValueParser<M extends "sync" ? "sync" : Mode, TValue>;
   /**
@@ -112,6 +117,12 @@ interface BindEnvOptions<M extends Mode, TValue> {
  * @param parser Parser that reads CLI values.
  * @param options Environment binding options.
  * @returns A parser with environment fallback behavior.
+ * @throws {TypeError} If `key` is not a string or `parser` is not a valid
+ *                    {@link ValueParser}.
+ * @throws {Error} If the inner parser throws while parsing or completing a
+ *                 value, if the environment source throws while reading a
+ *                 variable, or if the environment value parser throws while
+ *                 parsing the environment variable value.
  * @since 1.0.0
  */
 declare function bindEnv<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, options: BindEnvOptions<M, TValue>): Parser<M, TValue, TState>;
@@ -147,6 +158,7 @@ interface BoolOptions {
  *
  * @param options Parser configuration options.
  * @returns A value parser for Boolean values.
+ * @throws {TypeError} If `options.metavar` is an empty string.
  * @since 1.0.0
  */
 declare function bool(options?: BoolOptions): ValueParser<"sync", boolean>;

package/dist/index.d.ts

@@ -72,6 +72,7 @@ declare function clearActiveEnvSource(contextId: symbol): void;
  *
  * @param options Environment context options.
  * @returns A context that provides environment source annotations.
+ * @throws {TypeError} If `source` is not a function.
  * @since 1.0.0
  */
 declare function createEnvContext(options?: EnvContextOptions): EnvContext;
@@ -92,6 +93,10 @@ interface BindEnvOptions<M extends Mode, TValue> {
   readonly key: string;
   /**
    * Value parser used to parse the environment variable string value.
+   *
+   * In sync mode, the value parser must also be synchronous.
+   * In async mode, either sync or async value parsers are accepted,
+   * since the async pipeline can await sync results as well.
    */
   readonly parser: ValueParser<M extends "sync" ? "sync" : Mode, TValue>;
   /**
@@ -112,6 +117,12 @@ interface BindEnvOptions<M extends Mode, TValue> {
  * @param parser Parser that reads CLI values.
  * @param options Environment binding options.
  * @returns A parser with environment fallback behavior.
+ * @throws {TypeError} If `key` is not a string or `parser` is not a valid
+ *                    {@link ValueParser}.
+ * @throws {Error} If the inner parser throws while parsing or completing a
+ *                 value, if the environment source throws while reading a
+ *                 variable, or if the environment value parser throws while
+ *                 parsing the environment variable value.
  * @since 1.0.0
  */
 declare function bindEnv<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, options: BindEnvOptions<M, TValue>): Parser<M, TValue, TState>;
@@ -147,6 +158,7 @@ interface BoolOptions {
  *
  * @param options Parser configuration options.
  * @returns A value parser for Boolean values.
+ * @throws {TypeError} If `options.metavar` is an empty string.
  * @since 1.0.0
  */
 declare function bool(options?: BoolOptions): ValueParser<"sync", boolean>;

package/dist/index.js

@@ -1,6 +1,7 @@
 import { annotationKey, getAnnotations } from "@optique/core/annotations";
-import { message, valueSet } from "@optique/core/message";
-import { ensureNonEmptyString } from "@optique/core/valueparser";
+import { envVar, message, valueSet } from "@optique/core/message";
+import { mapModeValue, wrapForMode } from "@optique/core/mode-dispatch";
+import { ensureNonEmptyString, isValueParser } from "@optique/core/valueparser";
 
 //#region src/index.ts
 const activeEnvSourceRegistry = /* @__PURE__ */ new Map();
@@ -39,16 +40,20 @@ function defaultEnvSource(key) {
 *
 * @param options Environment context options.
 * @returns A context that provides environment source annotations.
+* @throws {TypeError} If `source` is not a function.
 * @since 1.0.0
 */
 function createEnvContext(options = {}) {
 	const contextId = Symbol(`@optique/env context:${Math.random()}`);
-	const source = options.source ?? defaultEnvSource;
+	const rawSource = options.source;
+	if (rawSource !== void 0 && typeof rawSource !== "function") throw new TypeError(`Expected source to be a function, but got: ${rawSource === null ? "null" : Array.isArray(rawSource) ? "array" : typeof rawSource}.`);
+	const source = rawSource ?? defaultEnvSource;
 	const prefix = options.prefix ?? "";
 	return {
 		id: contextId,
 		prefix,
 		source,
+		mode: "static",
 		getAnnotations() {
 			const sourceData = {
 				prefix,
@@ -75,13 +80,22 @@ function createEnvContext(options = {}) {
 * @param parser Parser that reads CLI values.
 * @param options Environment binding options.
 * @returns A parser with environment fallback behavior.
+* @throws {TypeError} If `key` is not a string or `parser` is not a valid
+*                    {@link ValueParser}.
+* @throws {Error} If the inner parser throws while parsing or completing a
+*                 value, if the environment source throws while reading a
+*                 variable, or if the environment value parser throws while
+*                 parsing the environment variable value.
 * @since 1.0.0
 */
 function bindEnv(parser, options) {
+	if (typeof options.key !== "string") throw new TypeError(`Expected key to be a string, but got: ${options.key === null ? "null" : Array.isArray(options.key) ? "array" : typeof options.key}.`);
+	if (!isValueParser(options.parser)) throw new TypeError(`Expected parser to be a ValueParser, but got: ${options.parser === null ? "null" : Array.isArray(options.parser) ? "array" : typeof options.parser}.`);
 	const envBindStateKey = Symbol("@optique/env/bindState");
 	function isEnvBindState(value) {
 		return value != null && typeof value === "object" && envBindStateKey in value;
 	}
+	const deferPromptUntilConfigResolves = parser.shouldDeferCompletion;
 	return {
 		$mode: parser.$mode,
 		$valueType: parser.$valueType,
@@ -99,25 +113,25 @@ function bindEnv(parser, options) {
 				...context,
 				state: innerState
 			} : context;
-			const processResult = (result$1) => {
-				if (result$1.success) {
-					const cliConsumed = result$1.consumed.length > 0;
+			const processResult = (result) => {
+				if (result.success) {
+					const cliConsumed = result.consumed.length > 0;
 					const nextState$1 = {
 						[envBindStateKey]: true,
 						hasCliValue: cliConsumed,
-						cliState: result$1.next.state,
+						cliState: result.next.state,
 						...annotations && { [annotationKey]: annotations }
 					};
 					return {
 						success: true,
 						next: {
-							...result$1.next,
+							...result.next,
 							state: nextState$1
 						},
-						consumed: result$1.consumed
+						consumed: result.consumed
 					};
 				}
-				if (result$1.consumed > 0) return result$1;
+				if (result.consumed > 0) return result;
 				const nextState = {
 					[envBindStateKey]: true,
 					hasCliValue: false,
@@ -132,33 +146,34 @@ function bindEnv(parser, options) {
 					consumed: []
 				};
 			};
-			const result = parser.parse(innerContext);
-			if (result instanceof Promise) return result.then(processResult);
-			return processResult(result);
+			return mapModeValue(parser.$mode, parser.parse(innerContext), processResult);
 		},
 		complete: (state) => {
 			if (isEnvBindState(state) && state.hasCliValue) return parser.complete(state.cliState);
 			return getEnvOrDefault(state, options, parser.$mode, parser, isEnvBindState(state) ? state.cliState : void 0);
 		},
 		suggest: parser.suggest,
+		...typeof deferPromptUntilConfigResolves === "function" ? { shouldDeferCompletion: deferPromptUntilConfigResolves.bind(parser) } : {},
 		getDocFragments(state, upperDefaultValue) {
 			const defaultValue = upperDefaultValue ?? options.default;
 			return parser.getDocFragments(state, defaultValue);
 		}
 	};
 }
-function wrapForMode(mode, value) {
-	if (mode === "async") return Promise.resolve(value);
-	return value;
-}
 function getEnvOrDefault(state, options, mode, innerParser, innerState) {
 	const annotations = getAnnotations(state);
 	const sourceData = annotations?.[options.context.id] ?? getActiveEnvSource(options.context.id);
 	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
 	const rawValue = sourceData?.source(fullKey);
 	if (rawValue !== void 0) {
+		if (typeof rawValue !== "string") {
+			const type = rawValue === null ? "null" : Array.isArray(rawValue) ? "array" : typeof rawValue;
+			return wrapForMode(mode, {
+				success: false,
+				error: message`Environment variable ${envVar(fullKey)} must be a string, but got: ${type}.`
+			});
+		}
 		const parsed = options.parser.parse(rawValue);
-		if (parsed instanceof Promise) return parsed;
 		return wrapForMode(mode, parsed);
 	}
 	if (options.default !== void 0) return wrapForMode(mode, {
@@ -167,13 +182,11 @@ function getEnvOrDefault(state, options, mode, innerParser, innerState) {
 	});
 	if (innerParser != null) {
 		const completeState = innerState ?? innerParser.initialState;
-		const result = innerParser.complete(completeState);
-		if (result instanceof Promise) return result;
-		return wrapForMode(mode, result);
+		return wrapForMode(mode, innerParser.complete(completeState));
 	}
 	return wrapForMode(mode, {
 		success: false,
-		error: message`Missing required environment variable: ${fullKey}.`
+		error: message`Missing required environment variable: ${envVar(fullKey)}`
 	});
 }
 const TRUE_LITERALS = [
@@ -198,6 +211,7 @@ const FALSE_LITERALS = [
 *
 * @param options Parser configuration options.
 * @returns A value parser for Boolean values.
+* @throws {TypeError} If `options.metavar` is an empty string.
 * @since 1.0.0
 */
 function bool(options = {}) {
@@ -224,6 +238,14 @@ function bool(options = {}) {
 		},
 		format(value) {
 			return value ? "true" : "false";
+		},
+		suggest(prefix) {
+			const allLiterals = [...TRUE_LITERALS, ...FALSE_LITERALS];
+			const normalizedPrefix = prefix.toLowerCase();
+			return allLiterals.filter((lit) => lit.startsWith(normalizedPrefix)).map((lit) => ({
+				kind: "literal",
+				text: lit
+			}));
 		}
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/env",
-  "version": "1.0.0-dev.0",
+  "version": "1.0.0-dev.1116+6084dd3a",
   "description": "Environment variable support for Optique",
   "keywords": [
     "CLI",
@@ -54,7 +54,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.0.0"
+    "@optique/core": "1.0.0-dev.1116+6084dd3a"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",