@optique/env 1.0.0-dev.1758 → 1.0.0-dev.1766

package/dist/index.cjs

@@ -111,8 +111,12 @@ function createEnvContext(options = {}) {
 *                    {@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.
+*                 variable, if the environment value parser throws while
+*                 parsing the environment variable value, or if the inner
+*                 parser's {@link Parser.validateValue} hook throws while
+*                 re-validating a fallback value (environment variable value
+*                 or configured `default`) — the hook can run even when no
+*                 CLI tokens are parsed (see issue #414).
 * @since 1.0.0
 */
 function bindEnv(parser, options) {
@@ -207,17 +211,22 @@ function bindEnv(parser, options) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(boundParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	const dependencyMetadata = (0, __optique_core_parser.composeWrappedSourceMetadata)(parser.dependencyMetadata, (sourceMetadata) => ({
 		...sourceMetadata,
 		extractSourceValue: (state) => {
 			if (!isEnvBindState(state)) {
-				if (sourceMetadata.preservesSourceValue) return getEnvSourceValue(state, options, state, sourceMetadata.extractSourceValue);
+				if (sourceMetadata.preservesSourceValue) return getEnvSourceValue(state, options, state, sourceMetadata.extractSourceValue, parser);
 				return sourceMetadata.extractSourceValue(state);
 			}
 			if (state.hasCliValue) return sourceMetadata.extractSourceValue(state.cliState);
 			const innerState = state.cliState ?? state;
 			if (!sourceMetadata.preservesSourceValue) return sourceMetadata.extractSourceValue(innerState);
-			return getEnvSourceValue(state, options, innerState, sourceMetadata.extractSourceValue);
+			return getEnvSourceValue(state, options, innerState, sourceMetadata.extractSourceValue, parser);
 		}
 	}));
 	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
@@ -227,11 +236,57 @@ function bindEnv(parser, options) {
 	});
 	return boundParser;
 }
+/**
+* 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
+* parser's constraints are enforced on fallback values (see issue
+* #414).
+*
+* @param state The wrapper state, which may carry env annotations.
+* @param options The binding options with lookup and default settings.
+* @param mode The parser mode (`"sync"` or `"async"`), used to
+*             dispatch env parsing and fallback validation.
+* @param innerParser Optional wrapped parser.  When present, its
+*                    `validateValue()` hook is used to re-validate
+*                    fallback values and its `complete()` is
+*                    delegated to as the last fallback.
+* @param innerState Optional unwrapped inner state to pass through to
+*                   `innerParser.complete()`.
+* @param exec Optional execution context forwarded to
+*             `innerParser.complete()`.
+* @returns The resolved value as a mode-dependent result.
+* @throws {Error} Propagates errors thrown by the env source callback
+*                 (`sourceData.source(fullKey)`) while reading the
+*                 environment variable.
+* @throws {Error} Propagates errors thrown by
+*                 `options.parser.parse(rawValue)` (sync or async)
+*                 while parsing the raw env string into `TValue`.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` while re-validating
+*                 a successful env-sourced value or the configured
+*                 `default` against the inner CLI parser's
+*                 constraints.
+* @throws {Error} Propagates errors thrown by `innerParser.complete()`
+*                 when falling through to the inner parser (e.g.,
+*                 `bindEnv(bindConfig(...))` with neither env nor
+*                 default set).
+*/
 function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 	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);
+	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;
@@ -240,13 +295,21 @@ function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 				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);
-		return (0, __optique_core_mode_dispatch.wrapForMode)(mode, parsed);
+		return (0, __optique_core_mode_dispatch.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_mode_dispatch.wrapForMode)(mode, {
+	if (options.default !== void 0) return (0, __optique_core_mode_dispatch.dispatchByMode)(mode, () => validateSync({
 		success: true,
 		value: options.default
-	});
+	}), () => validateAsync({
+		success: true,
+		value: options.default
+	}));
 	if (innerParser != null) {
 		const completeState = innerState ?? (annotations != null && innerParser.initialState == null && Reflect.get(innerParser, __optique_core_parser.inheritParentAnnotationsKey) === true ? (0, __optique_core_annotations.injectAnnotations)(innerParser.initialState, annotations) : innerParser.initialState);
 		return (0, __optique_core_mode_dispatch.wrapForMode)(mode, innerParser.complete(completeState, exec));
@@ -264,20 +327,37 @@ function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 * `options.default` and finally delegates to the wrapped parser's source
 * extractor.
 *
+* When `innerParser` exposes a `validateValue` hook, env-sourced values
+* and the configured default are re-validated against the inner parser's
+* CLI constraints (see issue #414).  This is only called from the
+* `preservesSourceValue: true` branch in {@link bindEnv}, so the source
+* value type is guaranteed to equal `TValue`.
+*
 * @param state The wrapper state, which may carry env annotations.
 * @param options The binding options with lookup and default settings.
 * @param innerState The unwrapped inner state for delegated extraction.
 * @param extractInnerSourceValue The wrapped parser's source extractor.
+* @param innerParser The wrapped parser, used to revalidate fallback values.
 * @returns The resolved source value, an async source value, or `undefined`.
 * @throws {Error} Propagates errors thrown by the env source callback
 *                 (`sourceData.source(fullKey)`).
 * @throws {Error} Propagates errors thrown by `options.parser.parse(rawValue)`.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` while revalidating a
+*                 successful env-sourced value or the configured
+*                 `default` against the inner CLI parser's constraints
+*                 (see issue #414).
 */
-function getEnvSourceValue(state, options, innerState, extractInnerSourceValue) {
+function getEnvSourceValue(state, options, innerState, extractInnerSourceValue, innerParser) {
 	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);
+	const validateFallback = (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return innerParser.validateValue(parsed.value);
+	};
 	if (rawValue !== void 0) {
 		if (typeof rawValue !== "string") {
 			const type = rawValue === null ? "null" : Array.isArray(rawValue) ? "array" : typeof rawValue;
@@ -286,13 +366,12 @@ function getEnvSourceValue(state, options, innerState, extractInnerSourceValue)
 				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);
-		return parsed;
+		return (0, __optique_core_mode_dispatch.mapModeValue)(options.parser.$mode, options.parser.parse(rawValue), (p) => validateFallback(p));
 	}
-	if (options.default !== void 0) return {
+	if (options.default !== void 0) return validateFallback({
 		success: true,
 		value: options.default
-	};
+	});
 	return extractInnerSourceValue(innerState);
 }
 const TRUE_LITERALS = [

package/dist/index.d.cts

@@ -122,8 +122,12 @@ interface BindEnvOptions<M extends Mode, TValue> {
  *                    {@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.
+ *                 variable, if the environment value parser throws while
+ *                 parsing the environment variable value, or if the inner
+ *                 parser's {@link Parser.validateValue} hook throws while
+ *                 re-validating a fallback value (environment variable value
+ *                 or configured `default`) — the hook can run even when no
+ *                 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>): Parser<M, TValue, TState>;

package/dist/index.d.ts

@@ -122,8 +122,12 @@ interface BindEnvOptions<M extends Mode, TValue> {
  *                    {@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.
+ *                 variable, if the environment value parser throws while
+ *                 parsing the environment variable value, or if the inner
+ *                 parser's {@link Parser.validateValue} hook throws while
+ *                 re-validating a fallback value (environment variable value
+ *                 or configured `default`) — the hook can run even when no
+ *                 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>): Parser<M, TValue, TState>;

package/dist/index.js

@@ -1,6 +1,6 @@
 import { annotationKey, getAnnotations, injectAnnotations, isInjectedAnnotationWrapper } from "@optique/core/annotations";
 import { envVar, message, valueSet } from "@optique/core/message";
-import { mapModeValue, wrapForMode } from "@optique/core/mode-dispatch";
+import { dispatchByMode, mapModeValue, wrapForMode } from "@optique/core/mode-dispatch";
 import { composeWrappedSourceMetadata, defineInheritedAnnotationParser, getDelegatingSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "@optique/core/parser";
 import { ensureNonEmptyString, isValueParser } from "@optique/core/valueparser";
 
@@ -88,8 +88,12 @@ function createEnvContext(options = {}) {
 *                    {@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.
+*                 variable, if the environment value parser throws while
+*                 parsing the environment variable value, or if the inner
+*                 parser's {@link Parser.validateValue} hook throws while
+*                 re-validating a fallback value (environment variable value
+*                 or configured `default`) — the hook can run even when no
+*                 CLI tokens are parsed (see issue #414).
 * @since 1.0.0
 */
 function bindEnv(parser, options) {
@@ -184,17 +188,22 @@ function bindEnv(parser, options) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(boundParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	const dependencyMetadata = composeWrappedSourceMetadata(parser.dependencyMetadata, (sourceMetadata) => ({
 		...sourceMetadata,
 		extractSourceValue: (state) => {
 			if (!isEnvBindState(state)) {
-				if (sourceMetadata.preservesSourceValue) return getEnvSourceValue(state, options, state, sourceMetadata.extractSourceValue);
+				if (sourceMetadata.preservesSourceValue) return getEnvSourceValue(state, options, state, sourceMetadata.extractSourceValue, parser);
 				return sourceMetadata.extractSourceValue(state);
 			}
 			if (state.hasCliValue) return sourceMetadata.extractSourceValue(state.cliState);
 			const innerState = state.cliState ?? state;
 			if (!sourceMetadata.preservesSourceValue) return sourceMetadata.extractSourceValue(innerState);
-			return getEnvSourceValue(state, options, innerState, sourceMetadata.extractSourceValue);
+			return getEnvSourceValue(state, options, innerState, sourceMetadata.extractSourceValue, parser);
 		}
 	}));
 	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
@@ -204,11 +213,57 @@ function bindEnv(parser, options) {
 	});
 	return boundParser;
 }
+/**
+* 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
+* parser's constraints are enforced on fallback values (see issue
+* #414).
+*
+* @param state The wrapper state, which may carry env annotations.
+* @param options The binding options with lookup and default settings.
+* @param mode The parser mode (`"sync"` or `"async"`), used to
+*             dispatch env parsing and fallback validation.
+* @param innerParser Optional wrapped parser.  When present, its
+*                    `validateValue()` hook is used to re-validate
+*                    fallback values and its `complete()` is
+*                    delegated to as the last fallback.
+* @param innerState Optional unwrapped inner state to pass through to
+*                   `innerParser.complete()`.
+* @param exec Optional execution context forwarded to
+*             `innerParser.complete()`.
+* @returns The resolved value as a mode-dependent result.
+* @throws {Error} Propagates errors thrown by the env source callback
+*                 (`sourceData.source(fullKey)`) while reading the
+*                 environment variable.
+* @throws {Error} Propagates errors thrown by
+*                 `options.parser.parse(rawValue)` (sync or async)
+*                 while parsing the raw env string into `TValue`.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` while re-validating
+*                 a successful env-sourced value or the configured
+*                 `default` against the inner CLI parser's
+*                 constraints.
+* @throws {Error} Propagates errors thrown by `innerParser.complete()`
+*                 when falling through to the inner parser (e.g.,
+*                 `bindEnv(bindConfig(...))` with neither env nor
+*                 default set).
+*/
 function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 	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);
+	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;
@@ -217,13 +272,21 @@ function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 				error: message`Environment variable ${envVar(fullKey)} must be a string, but got: ${type}.`
 			});
 		}
-		const parsed = options.parser.parse(rawValue);
-		return wrapForMode(mode, parsed);
+		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 wrapForMode(mode, {
+	if (options.default !== void 0) return dispatchByMode(mode, () => validateSync({
 		success: true,
 		value: options.default
-	});
+	}), () => validateAsync({
+		success: true,
+		value: options.default
+	}));
 	if (innerParser != null) {
 		const completeState = innerState ?? (annotations != null && innerParser.initialState == null && Reflect.get(innerParser, inheritParentAnnotationsKey) === true ? injectAnnotations(innerParser.initialState, annotations) : innerParser.initialState);
 		return wrapForMode(mode, innerParser.complete(completeState, exec));
@@ -241,20 +304,37 @@ function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 * `options.default` and finally delegates to the wrapped parser's source
 * extractor.
 *
+* When `innerParser` exposes a `validateValue` hook, env-sourced values
+* and the configured default are re-validated against the inner parser's
+* CLI constraints (see issue #414).  This is only called from the
+* `preservesSourceValue: true` branch in {@link bindEnv}, so the source
+* value type is guaranteed to equal `TValue`.
+*
 * @param state The wrapper state, which may carry env annotations.
 * @param options The binding options with lookup and default settings.
 * @param innerState The unwrapped inner state for delegated extraction.
 * @param extractInnerSourceValue The wrapped parser's source extractor.
+* @param innerParser The wrapped parser, used to revalidate fallback values.
 * @returns The resolved source value, an async source value, or `undefined`.
 * @throws {Error} Propagates errors thrown by the env source callback
 *                 (`sourceData.source(fullKey)`).
 * @throws {Error} Propagates errors thrown by `options.parser.parse(rawValue)`.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` while revalidating a
+*                 successful env-sourced value or the configured
+*                 `default` against the inner CLI parser's constraints
+*                 (see issue #414).
 */
-function getEnvSourceValue(state, options, innerState, extractInnerSourceValue) {
+function getEnvSourceValue(state, options, innerState, extractInnerSourceValue, innerParser) {
 	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);
+	const validateFallback = (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return innerParser.validateValue(parsed.value);
+	};
 	if (rawValue !== void 0) {
 		if (typeof rawValue !== "string") {
 			const type = rawValue === null ? "null" : Array.isArray(rawValue) ? "array" : typeof rawValue;
@@ -263,13 +343,12 @@ function getEnvSourceValue(state, options, innerState, extractInnerSourceValue)
 				error: message`Environment variable ${envVar(fullKey)} must be a string, but got: ${type}.`
 			};
 		}
-		const parsed = options.parser.parse(rawValue);
-		return parsed;
+		return mapModeValue(options.parser.$mode, options.parser.parse(rawValue), (p) => validateFallback(p));
 	}
-	if (options.default !== void 0) return {
+	if (options.default !== void 0) return validateFallback({
 		success: true,
 		value: options.default
-	};
+	});
 	return extractInnerSourceValue(innerState);
 }
 const TRUE_LITERALS = [

package/package.json

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