@optique/env 1.4.0-dev.2675 → 1.4.0-dev.2678

package/README.md

@@ -76,6 +76,10 @@ Features
  -  *.env file loading* without mutating `process.env` or `Deno.env`
  -  *Custom env source* for Deno, tests, and custom runtimes
  -  *Composable contexts* with `run()`/`runAsync()`/`runWith()`
+ -  *Direct fallback reads* through `bindEnv()`'s `readFallback()` method,
+    useful when a CLI parse fails before returning a value. It reads only the
+    environment variable or default and returns a result, not a partial CLI
+    parse.
 
 
 Documentation

package/dist/index.cjs

@@ -336,7 +336,8 @@ function createEnvContext(options = {}) {
 *
 * @param parser Parser that reads CLI values.
 * @param options Environment binding options.
-* @returns A parser with environment fallback behavior.
+* @returns A parser with environment fallback behavior and a direct
+*          `readFallback()` method.
 * @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
@@ -523,10 +524,75 @@ function bindEnv(parser, options) {
 		configurable: true,
 		enumerable: false
 	});
+	Object.defineProperty(boundParser, "readFallback", {
+		value: () => {
+			const sourceData = {
+				prefix: options.context.prefix,
+				source: options.context.source
+			};
+			const missing = {
+				success: false,
+				error: __optique_core_message.message`Missing required environment variable: ${(0, __optique_core_message.envVar)(`${sourceData.prefix}${options.key}`)}`
+			};
+			return (0, __optique_core_extension.dispatchByMode)(parser.mode, () => {
+				const result = getEnvFallback(options, parser.mode, sourceData, parser);
+				return result ?? missing;
+			}, async () => {
+				const result = getEnvFallback(options, parser.mode, sourceData, parser);
+				const awaited = await result;
+				return awaited ?? missing;
+			});
+		},
+		configurable: true,
+		enumerable: false
+	});
 	(0, __optique_core_extension.delegateOptionParsing)(boundParser, parser, getInnerState);
 	return (0, __optique_core_fluent.fluent)(boundParser);
 }
 /**
+* Reads and validates the environment value or configured default.
+* Returns `undefined` before mode dispatch when neither is available, so
+* normal completion can still delegate to the wrapped parser.
+*/
+function getEnvFallback(options, mode, sourceData, innerParser) {
+	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
+	const rawValue = sourceData?.source(fullKey);
+	const validateSync = (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return innerParser.validateValue(parsed.value);
+	};
+	const validateAsync = async (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return await innerParser.validateValue(parsed.value);
+	};
+	if (rawValue !== void 0) {
+		if (typeof rawValue !== "string") {
+			const type = rawValue === null ? "null" : Array.isArray(rawValue) ? "array" : typeof rawValue;
+			return (0, __optique_core_extension.wrapForMode)(mode, {
+				success: false,
+				error: __optique_core_message.message`Environment variable ${(0, __optique_core_message.envVar)(fullKey)} must be a string, but got: ${type}.`
+			});
+		}
+		return (0, __optique_core_extension.dispatchByMode)(mode, () => {
+			const parsed = options.parser.parse(rawValue);
+			return validateSync(parsed);
+		}, async () => {
+			const parsed = await options.parser.parse(rawValue);
+			return await validateAsync(parsed);
+		});
+	}
+	if (options.default !== void 0) return (0, __optique_core_extension.dispatchByMode)(mode, () => validateSync({
+		success: true,
+		value: options.default
+	}), () => validateAsync({
+		success: true,
+		value: options.default
+	}));
+	return void 0;
+}
+/**
 * Resolves a `bindEnv()` fallback value with env > default > inner
 * `complete()` priority, running each candidate through the inner
 * parser's `validateValue()` hook when available so the inner CLI
@@ -565,42 +631,10 @@ function bindEnv(parser, options) {
 function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 	const annotations = (0, __optique_core_annotations.getAnnotations)(state);
 	const sourceData = annotations?.[options.context.id];
-	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
-	const rawValue = sourceData?.source(fullKey);
-	const validateSync = (parsed) => {
-		if (!parsed.success) return parsed;
-		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
-		return innerParser.validateValue(parsed.value);
-	};
-	const validateAsync = async (parsed) => {
-		if (!parsed.success) return parsed;
-		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
-		return await innerParser.validateValue(parsed.value);
-	};
-	if (rawValue !== void 0) {
-		if (typeof rawValue !== "string") {
-			const type = rawValue === null ? "null" : Array.isArray(rawValue) ? "array" : typeof rawValue;
-			return (0, __optique_core_extension.wrapForMode)(mode, {
-				success: false,
-				error: __optique_core_message.message`Environment variable ${(0, __optique_core_message.envVar)(fullKey)} must be a string, but got: ${type}.`
-			});
-		}
-		return (0, __optique_core_extension.dispatchByMode)(mode, () => {
-			const parsed = options.parser.parse(rawValue);
-			return validateSync(parsed);
-		}, async () => {
-			const parsed = await options.parser.parse(rawValue);
-			return await validateAsync(parsed);
-		});
-	}
-	if (options.default !== void 0) return (0, __optique_core_extension.dispatchByMode)(mode, () => validateSync({
-		success: true,
-		value: options.default
-	}), () => validateAsync({
-		success: true,
-		value: options.default
-	}));
+	const fallback = getEnvFallback(options, mode, sourceData, innerParser);
+	if (fallback !== void 0) return fallback;
 	const envContextAbsent = annotations != null && !(options.context.id in annotations);
+	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
 	if (innerParser != null) {
 		const completeState = innerState ?? (annotations != null && innerParser.initialState == null && (0, __optique_core_extension.getTraits)(innerParser).inheritsAnnotations === true ? (0, __optique_core_extension.injectAnnotations)(innerParser.initialState, annotations) : innerParser.initialState);
 		const innerResult = innerParser.complete(completeState, exec);

package/dist/index.d.cts

@@ -2,8 +2,8 @@ import { HiddenVisibility } from "@optique/core/usage";
 import { SourceContext } from "@optique/core/context";
 import { FluentParser } from "@optique/core/fluent";
 import { Message } from "@optique/core/message";
-import { Mode, Parser } from "@optique/core/parser";
-import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
+import { Mode, ModeValue, Parser } from "@optique/core/parser";
+import { NonEmptyString, ValueParser, ValueParserResult } from "@optique/core/valueparser";
 
 //#region src/index.d.ts
 
@@ -158,6 +158,30 @@ interface BindEnvOptions<M extends Mode, TValue> {
    */
   readonly default?: TValue;
 }
+/**
+ * A parser bound to an environment variable whose fallback can also be read
+ * independently of CLI parsing.
+ *
+ * @template M The execution mode of the parser.
+ * @template TValue The parser result value.
+ * @template TState The parser state.
+ * @since 1.4.0
+ */
+type EnvBoundParser<M extends Mode, TValue, TState> = FluentParser<M, TValue, TState> & {
+  /**
+   * Reads this binding's environment value or configured default without
+   * reading CLI input or completing the wrapped parser.
+   *
+   * @returns A parsed fallback result, or a failure if the value is invalid
+   *          or neither the environment nor a default supplies a value.
+   *          Async bindings return a promise.
+   * @throws {Error} If the environment source, value parser, or wrapped
+   *                 parser's validation hook throws. Async bindings reject
+   *                 their promise instead.
+   * @since 1.4.0
+   */
+  readonly readFallback: () => ModeValue<M, ValueParserResult<TValue>>;
+};
 /**
  * Binds a parser to environment variables with fallback behavior.
  *
@@ -188,7 +212,8 @@ 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.
+ * @returns A parser with environment fallback behavior and a direct
+ *          `readFallback()` method.
  * @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
@@ -201,7 +226,7 @@ interface BindEnvOptions<M extends Mode, TValue> {
  *                 CLI tokens are parsed (see issue #414).
  * @since 1.0.0
  */
-declare function bindEnv<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, options: BindEnvOptions<M, TValue>): FluentParser<M, TValue, TState>;
+declare function bindEnv<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, options: BindEnvOptions<M, TValue>): EnvBoundParser<M, TValue, TState>;
 /**
  * Options for the {@link bool} parser.
  *
@@ -239,4 +264,4 @@ interface BoolOptions {
  */
 declare function bool(options?: BoolOptions): ValueParser<"sync", boolean>;
 //#endregion
-export { BindEnvOptions, BoolOptions, EnvContext, EnvContextOptions, EnvFileOptions, EnvFilePaths, EnvFileSubstitute, EnvSource, bindEnv, bool, createEnvContext };
+export { BindEnvOptions, BoolOptions, EnvBoundParser, EnvContext, EnvContextOptions, EnvFileOptions, EnvFilePaths, EnvFileSubstitute, EnvSource, bindEnv, bool, createEnvContext };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { HiddenVisibility } from "@optique/core/usage";
 import { FluentParser } from "@optique/core/fluent";
 import { Message } from "@optique/core/message";
-import { NonEmptyString, ValueParser } from "@optique/core/valueparser";
+import { NonEmptyString, ValueParser, ValueParserResult } from "@optique/core/valueparser";
 import { SourceContext } from "@optique/core/context";
-import { Mode, Parser } from "@optique/core/parser";
+import { Mode, ModeValue, Parser } from "@optique/core/parser";
 
 //#region src/index.d.ts
 
@@ -158,6 +158,30 @@ interface BindEnvOptions<M extends Mode, TValue> {
    */
   readonly default?: TValue;
 }
+/**
+ * A parser bound to an environment variable whose fallback can also be read
+ * independently of CLI parsing.
+ *
+ * @template M The execution mode of the parser.
+ * @template TValue The parser result value.
+ * @template TState The parser state.
+ * @since 1.4.0
+ */
+type EnvBoundParser<M extends Mode, TValue, TState> = FluentParser<M, TValue, TState> & {
+  /**
+   * Reads this binding's environment value or configured default without
+   * reading CLI input or completing the wrapped parser.
+   *
+   * @returns A parsed fallback result, or a failure if the value is invalid
+   *          or neither the environment nor a default supplies a value.
+   *          Async bindings return a promise.
+   * @throws {Error} If the environment source, value parser, or wrapped
+   *                 parser's validation hook throws. Async bindings reject
+   *                 their promise instead.
+   * @since 1.4.0
+   */
+  readonly readFallback: () => ModeValue<M, ValueParserResult<TValue>>;
+};
 /**
  * Binds a parser to environment variables with fallback behavior.
  *
@@ -188,7 +212,8 @@ 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.
+ * @returns A parser with environment fallback behavior and a direct
+ *          `readFallback()` method.
  * @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
@@ -201,7 +226,7 @@ interface BindEnvOptions<M extends Mode, TValue> {
  *                 CLI tokens are parsed (see issue #414).
  * @since 1.0.0
  */
-declare function bindEnv<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, options: BindEnvOptions<M, TValue>): FluentParser<M, TValue, TState>;
+declare function bindEnv<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, options: BindEnvOptions<M, TValue>): EnvBoundParser<M, TValue, TState>;
 /**
  * Options for the {@link bool} parser.
  *
@@ -239,4 +264,4 @@ interface BoolOptions {
  */
 declare function bool(options?: BoolOptions): ValueParser<"sync", boolean>;
 //#endregion
-export { BindEnvOptions, BoolOptions, EnvContext, EnvContextOptions, EnvFileOptions, EnvFilePaths, EnvFileSubstitute, EnvSource, bindEnv, bool, createEnvContext };
+export { BindEnvOptions, BoolOptions, EnvBoundParser, EnvContext, EnvContextOptions, EnvFileOptions, EnvFilePaths, EnvFileSubstitute, EnvSource, bindEnv, bool, createEnvContext };

package/dist/index.js

@@ -313,7 +313,8 @@ function createEnvContext(options = {}) {
 *
 * @param parser Parser that reads CLI values.
 * @param options Environment binding options.
-* @returns A parser with environment fallback behavior.
+* @returns A parser with environment fallback behavior and a direct
+*          `readFallback()` method.
 * @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
@@ -500,10 +501,75 @@ function bindEnv(parser, options) {
 		configurable: true,
 		enumerable: false
 	});
+	Object.defineProperty(boundParser, "readFallback", {
+		value: () => {
+			const sourceData = {
+				prefix: options.context.prefix,
+				source: options.context.source
+			};
+			const missing = {
+				success: false,
+				error: message`Missing required environment variable: ${envVar(`${sourceData.prefix}${options.key}`)}`
+			};
+			return dispatchByMode(parser.mode, () => {
+				const result = getEnvFallback(options, parser.mode, sourceData, parser);
+				return result ?? missing;
+			}, async () => {
+				const result = getEnvFallback(options, parser.mode, sourceData, parser);
+				const awaited = await result;
+				return awaited ?? missing;
+			});
+		},
+		configurable: true,
+		enumerable: false
+	});
 	delegateOptionParsing(boundParser, parser, getInnerState);
 	return fluent(boundParser);
 }
 /**
+* Reads and validates the environment value or configured default.
+* Returns `undefined` before mode dispatch when neither is available, so
+* normal completion can still delegate to the wrapped parser.
+*/
+function getEnvFallback(options, mode, sourceData, innerParser) {
+	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
+	const rawValue = sourceData?.source(fullKey);
+	const validateSync = (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return innerParser.validateValue(parsed.value);
+	};
+	const validateAsync = async (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return await innerParser.validateValue(parsed.value);
+	};
+	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}.`
+			});
+		}
+		return dispatchByMode(mode, () => {
+			const parsed = options.parser.parse(rawValue);
+			return validateSync(parsed);
+		}, async () => {
+			const parsed = await options.parser.parse(rawValue);
+			return await validateAsync(parsed);
+		});
+	}
+	if (options.default !== void 0) return dispatchByMode(mode, () => validateSync({
+		success: true,
+		value: options.default
+	}), () => validateAsync({
+		success: true,
+		value: options.default
+	}));
+	return void 0;
+}
+/**
 * Resolves a `bindEnv()` fallback value with env > default > inner
 * `complete()` priority, running each candidate through the inner
 * parser's `validateValue()` hook when available so the inner CLI
@@ -542,42 +608,10 @@ function bindEnv(parser, options) {
 function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 	const annotations = getAnnotations(state);
 	const sourceData = annotations?.[options.context.id];
-	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
-	const rawValue = sourceData?.source(fullKey);
-	const validateSync = (parsed) => {
-		if (!parsed.success) return parsed;
-		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
-		return innerParser.validateValue(parsed.value);
-	};
-	const validateAsync = async (parsed) => {
-		if (!parsed.success) return parsed;
-		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
-		return await innerParser.validateValue(parsed.value);
-	};
-	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}.`
-			});
-		}
-		return dispatchByMode(mode, () => {
-			const parsed = options.parser.parse(rawValue);
-			return validateSync(parsed);
-		}, async () => {
-			const parsed = await options.parser.parse(rawValue);
-			return await validateAsync(parsed);
-		});
-	}
-	if (options.default !== void 0) return dispatchByMode(mode, () => validateSync({
-		success: true,
-		value: options.default
-	}), () => validateAsync({
-		success: true,
-		value: options.default
-	}));
+	const fallback = getEnvFallback(options, mode, sourceData, innerParser);
+	if (fallback !== void 0) return fallback;
 	const envContextAbsent = annotations != null && !(options.context.id in annotations);
+	const fullKey = `${sourceData?.prefix ?? options.context.prefix}${options.key}`;
 	if (innerParser != null) {
 		const completeState = innerState ?? (annotations != null && innerParser.initialState == null && getTraits(innerParser).inheritsAnnotations === true ? injectAnnotations(innerParser.initialState, annotations) : innerParser.initialState);
 		const innerResult = innerParser.complete(completeState, exec);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/env",
-  "version": "1.4.0-dev.2675",
+  "version": "1.4.0-dev.2678",
   "description": "Environment variable support for Optique",
   "keywords": [
     "CLI",
@@ -60,10 +60,10 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.4.0-dev.2675+980e94e9"
+    "@optique/core": "1.4.0-dev.2678+a475f32a"
   },
   "devDependencies": {
-    "@optique/config": "1.4.0-dev.2675+980e94e9",
+    "@optique/config": "1.4.0-dev.2678+a475f32a",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",