@optique/config 1.0.0-dev.1758 → 1.0.0-dev.1772

package/dist/index.cjs

@@ -281,6 +281,11 @@ function createConfigContext(options) {
 * @param options Binding options including context, key, and default.
 * @returns A new parser with config fallback behavior.
 * @throws {TypeError} If `key` is not a property key or function.
+* @throws {Error} If the inner parser's {@link Parser.validateValue} hook
+*                 throws while re-validating a fallback value (a
+*                 config-sourced value or the configured `default`) —
+*                 the hook can run even when no CLI tokens are parsed
+*                 (see issue #414).
 * @since 0.10.0
 *
 * @example
@@ -370,7 +375,7 @@ function bindConfig(parser, options) {
 		},
 		complete: (state, exec) => {
 			if (isConfigBindState(state) && state.hasCliValue) return parser.complete(state.cliState, exec);
-			return (0, __optique_core_mode_dispatch.wrapForMode)(parser.$mode, getConfigOrDefault(state, options));
+			return getConfigOrDefault(state, options, parser.$mode, parser);
 		},
 		suggest: (context, prefix) => {
 			const innerState = getSuggestInnerState(context.state);
@@ -398,22 +403,30 @@ function bindConfig(parser, options) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(boundParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	(0, __optique_core_parser.defineInheritedAnnotationParser)(boundParser);
 	const dependencyMetadata = (0, __optique_core_parser.composeWrappedSourceMetadata)(parser.dependencyMetadata, (sourceMetadata) => ({
 		...sourceMetadata,
-		getMissingSourceValue: sourceMetadata.preservesSourceValue !== false && options.default !== void 0 ? () => ({
-			success: true,
-			value: options.default
-		}) : void 0,
+		getMissingSourceValue: sourceMetadata.preservesSourceValue !== false && options.default !== void 0 ? () => {
+			if (typeof parser.validateValue === "function") return parser.validateValue(options.default);
+			return {
+				success: true,
+				value: options.default
+			};
+		} : void 0,
 		extractSourceValue: (state) => {
 			if (!isConfigBindState(state)) {
-				if (sourceMetadata.preservesSourceValue) return getConfigSourceValue(state, options, state, sourceMetadata.extractSourceValue);
+				if (sourceMetadata.preservesSourceValue) return getConfigSourceValue(state, options, state, sourceMetadata.extractSourceValue, parser);
 				return sourceMetadata.extractSourceValue(state);
 			}
 			if (state.hasCliValue) return sourceMetadata.extractSourceValue(state.cliState);
 			const fallbackState = state.cliState ?? state;
 			if (!sourceMetadata.preservesSourceValue) return sourceMetadata.extractSourceValue(fallbackState);
-			return getConfigSourceValue(state, options, fallbackState, sourceMetadata.extractSourceValue);
+			return getConfigSourceValue(state, options, fallbackState, sourceMetadata.extractSourceValue, parser);
 		}
 	}));
 	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
@@ -428,9 +441,24 @@ function bindConfig(parser, options) {
 * Checks both annotations (for top-level parsers) and the active config
 * registry (for parsers nested inside object() when used with context-aware
 * runners).
+*
+* When `innerParser.validateValue` is available, the returned fallback
+* value is routed through it so that the inner CLI parser's constraints
+* (regex patterns, numeric bounds, choices, etc.) are enforced on
+* config-sourced values and configured defaults (see issue #414).  If
+* `innerParser` is absent or does not implement `validateValue` (for
+* example, the inner parser is wrapped in `map()`), the value is
+* returned unchanged to preserve existing behavior.
+*
 * @throws {TypeError} If the key callback returns a Promise or thenable.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` (via
+*                 {@link validateFallbackValue}) while revalidating a
+*                 config-sourced value or the configured `default`
+*                 against the inner CLI parser's constraints (see
+*                 issue #414).
 */
-function getConfigOrDefault(state, options) {
+function getConfigOrDefault(state, options, mode, innerParser) {
 	const annotations = (0, __optique_core_annotations.getAnnotations)(state);
 	const contextId = options.context.id;
 	const annotationValue = annotations?.[contextId];
@@ -445,18 +473,32 @@ function getConfigOrDefault(state, options) {
 		configValue = options.key(configData, configMeta);
 		if (configValue != null && (typeof configValue === "object" || typeof configValue === "function") && "then" in configValue && typeof configValue.then === "function") throw new TypeError("The key callback must return a synchronous value, but got a thenable.");
 	} 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 {
+	if (configValue !== void 0) return validateFallbackValue(mode, innerParser, configValue);
+	if (options.default !== void 0) return validateFallbackValue(mode, innerParser, options.default);
+	return (0, __optique_core_mode_dispatch.wrapForMode)(mode, {
 		success: false,
 		error: __optique_core_message.message`Missing required configuration value.`
-	};
+	});
+}
+/**
+* Routes a (successful) fallback value through the inner parser's
+* `validateValue()` hook, or returns the value unchanged when no
+* validator is available.  See {@link getConfigOrDefault} for context.
+*
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` while revalidating the
+*                 fallback value against the inner CLI parser's
+*                 constraints (see issue #414).  When the hook returns
+*                 a failed {@link Result} the failure is propagated
+*                 through the return value; only an actual exception
+*                 thrown by the hook escapes through this path.
+*/
+function validateFallbackValue(mode, innerParser, value) {
+	if (innerParser == null || typeof innerParser.validateValue !== "function") return (0, __optique_core_mode_dispatch.wrapForMode)(mode, {
+		success: true,
+		value
+	});
+	return innerParser.validateValue(value);
 }
 /**
 * Resolves a config-backed dependency source with fallback priority.
@@ -466,27 +508,46 @@ function getConfigOrDefault(state, options) {
 * back to `options.default` and finally delegates to the wrapped parser's
 * source extractor.
 *
+* When `innerParser` exposes `validateValue`, the returned fallback is
+* routed through it so that the inner CLI parser's constraints are
+* enforced on config-sourced source values and configured defaults
+* (see issue #414).  This helper is only invoked from the
+* `preservesSourceValue: true` branch in {@link bindConfig}, so the
+* source value type is guaranteed to equal `TValue`.
+*
 * @param state The wrapper state, which may carry config 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 {TypeError} If {@link getConfigOrDefault} rejects a thenable-returning
 *                     key callback.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` (via
+*                 {@link getConfigOrDefault} / {@link validateFallbackValue})
+*                 while revalidating a config-sourced value or the
+*                 configured `default` against the inner CLI parser's
+*                 constraints (see issue #414).
 */
-function getConfigSourceValue(state, options, innerState, extractInnerSourceValue) {
+function getConfigSourceValue(state, options, innerState, extractInnerSourceValue, innerParser) {
 	const annotations = (0, __optique_core_annotations.getAnnotations)(state);
 	const contextId = options.context.id;
 	const annotationValue = annotations?.[contextId];
 	const configData = annotationValue?.data ?? getActiveConfig(contextId);
+	const validateFallback = (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return innerParser.validateValue(parsed.value);
+	};
 	if (configData !== void 0 && configData !== null) {
-		const resolved = getConfigOrDefault(state, options);
-		if (resolved.success) return resolved;
+		const resolved = getConfigOrDefault(state, options, "sync", void 0);
+		if (resolved.success) return validateFallback(resolved);
 	}
-	if (options.default !== void 0) return {
+	if (options.default !== void 0) return validateFallback({
 		success: true,
 		value: options.default
-	};
+	});
 	return extractInnerSourceValue(innerState);
 }
 

package/dist/index.d.cts

@@ -223,6 +223,11 @@ interface BindConfigOptions<T, TValue, TConfigMeta = ConfigMeta> {
  * @param options Binding options including context, key, and default.
  * @returns A new parser with config fallback behavior.
  * @throws {TypeError} If `key` is not a property key or function.
+ * @throws {Error} If the inner parser's {@link Parser.validateValue} hook
+ *                 throws while re-validating a fallback value (a
+ *                 config-sourced value or the configured `default`) —
+ *                 the hook can run even when no CLI tokens are parsed
+ *                 (see issue #414).
  * @since 0.10.0
  *
  * @example

package/dist/index.d.ts

@@ -223,6 +223,11 @@ interface BindConfigOptions<T, TValue, TConfigMeta = ConfigMeta> {
  * @param options Binding options including context, key, and default.
  * @returns A new parser with config fallback behavior.
  * @throws {TypeError} If `key` is not a property key or function.
+ * @throws {Error} If the inner parser's {@link Parser.validateValue} hook
+ *                 throws while re-validating a fallback value (a
+ *                 config-sourced value or the configured `default`) —
+ *                 the hook can run even when no CLI tokens are parsed
+ *                 (see issue #414).
  * @since 0.10.0
  *
  * @example

package/dist/index.js

@@ -258,6 +258,11 @@ function createConfigContext(options) {
 * @param options Binding options including context, key, and default.
 * @returns A new parser with config fallback behavior.
 * @throws {TypeError} If `key` is not a property key or function.
+* @throws {Error} If the inner parser's {@link Parser.validateValue} hook
+*                 throws while re-validating a fallback value (a
+*                 config-sourced value or the configured `default`) —
+*                 the hook can run even when no CLI tokens are parsed
+*                 (see issue #414).
 * @since 0.10.0
 *
 * @example
@@ -347,7 +352,7 @@ function bindConfig(parser, options) {
 		},
 		complete: (state, exec) => {
 			if (isConfigBindState(state) && state.hasCliValue) return parser.complete(state.cliState, exec);
-			return wrapForMode(parser.$mode, getConfigOrDefault(state, options));
+			return getConfigOrDefault(state, options, parser.$mode, parser);
 		},
 		suggest: (context, prefix) => {
 			const innerState = getSuggestInnerState(context.state);
@@ -375,22 +380,30 @@ function bindConfig(parser, options) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(boundParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	defineInheritedAnnotationParser(boundParser);
 	const dependencyMetadata = composeWrappedSourceMetadata(parser.dependencyMetadata, (sourceMetadata) => ({
 		...sourceMetadata,
-		getMissingSourceValue: sourceMetadata.preservesSourceValue !== false && options.default !== void 0 ? () => ({
-			success: true,
-			value: options.default
-		}) : void 0,
+		getMissingSourceValue: sourceMetadata.preservesSourceValue !== false && options.default !== void 0 ? () => {
+			if (typeof parser.validateValue === "function") return parser.validateValue(options.default);
+			return {
+				success: true,
+				value: options.default
+			};
+		} : void 0,
 		extractSourceValue: (state) => {
 			if (!isConfigBindState(state)) {
-				if (sourceMetadata.preservesSourceValue) return getConfigSourceValue(state, options, state, sourceMetadata.extractSourceValue);
+				if (sourceMetadata.preservesSourceValue) return getConfigSourceValue(state, options, state, sourceMetadata.extractSourceValue, parser);
 				return sourceMetadata.extractSourceValue(state);
 			}
 			if (state.hasCliValue) return sourceMetadata.extractSourceValue(state.cliState);
 			const fallbackState = state.cliState ?? state;
 			if (!sourceMetadata.preservesSourceValue) return sourceMetadata.extractSourceValue(fallbackState);
-			return getConfigSourceValue(state, options, fallbackState, sourceMetadata.extractSourceValue);
+			return getConfigSourceValue(state, options, fallbackState, sourceMetadata.extractSourceValue, parser);
 		}
 	}));
 	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
@@ -405,9 +418,24 @@ function bindConfig(parser, options) {
 * Checks both annotations (for top-level parsers) and the active config
 * registry (for parsers nested inside object() when used with context-aware
 * runners).
+*
+* When `innerParser.validateValue` is available, the returned fallback
+* value is routed through it so that the inner CLI parser's constraints
+* (regex patterns, numeric bounds, choices, etc.) are enforced on
+* config-sourced values and configured defaults (see issue #414).  If
+* `innerParser` is absent or does not implement `validateValue` (for
+* example, the inner parser is wrapped in `map()`), the value is
+* returned unchanged to preserve existing behavior.
+*
 * @throws {TypeError} If the key callback returns a Promise or thenable.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` (via
+*                 {@link validateFallbackValue}) while revalidating a
+*                 config-sourced value or the configured `default`
+*                 against the inner CLI parser's constraints (see
+*                 issue #414).
 */
-function getConfigOrDefault(state, options) {
+function getConfigOrDefault(state, options, mode, innerParser) {
 	const annotations = getAnnotations(state);
 	const contextId = options.context.id;
 	const annotationValue = annotations?.[contextId];
@@ -422,18 +450,32 @@ function getConfigOrDefault(state, options) {
 		configValue = options.key(configData, configMeta);
 		if (configValue != null && (typeof configValue === "object" || typeof configValue === "function") && "then" in configValue && typeof configValue.then === "function") throw new TypeError("The key callback must return a synchronous value, but got a thenable.");
 	} 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 {
+	if (configValue !== void 0) return validateFallbackValue(mode, innerParser, configValue);
+	if (options.default !== void 0) return validateFallbackValue(mode, innerParser, options.default);
+	return wrapForMode(mode, {
 		success: false,
 		error: message`Missing required configuration value.`
-	};
+	});
+}
+/**
+* Routes a (successful) fallback value through the inner parser's
+* `validateValue()` hook, or returns the value unchanged when no
+* validator is available.  See {@link getConfigOrDefault} for context.
+*
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` while revalidating the
+*                 fallback value against the inner CLI parser's
+*                 constraints (see issue #414).  When the hook returns
+*                 a failed {@link Result} the failure is propagated
+*                 through the return value; only an actual exception
+*                 thrown by the hook escapes through this path.
+*/
+function validateFallbackValue(mode, innerParser, value) {
+	if (innerParser == null || typeof innerParser.validateValue !== "function") return wrapForMode(mode, {
+		success: true,
+		value
+	});
+	return innerParser.validateValue(value);
 }
 /**
 * Resolves a config-backed dependency source with fallback priority.
@@ -443,27 +485,46 @@ function getConfigOrDefault(state, options) {
 * back to `options.default` and finally delegates to the wrapped parser's
 * source extractor.
 *
+* When `innerParser` exposes `validateValue`, the returned fallback is
+* routed through it so that the inner CLI parser's constraints are
+* enforced on config-sourced source values and configured defaults
+* (see issue #414).  This helper is only invoked from the
+* `preservesSourceValue: true` branch in {@link bindConfig}, so the
+* source value type is guaranteed to equal `TValue`.
+*
 * @param state The wrapper state, which may carry config 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 {TypeError} If {@link getConfigOrDefault} rejects a thenable-returning
 *                     key callback.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` (via
+*                 {@link getConfigOrDefault} / {@link validateFallbackValue})
+*                 while revalidating a config-sourced value or the
+*                 configured `default` against the inner CLI parser's
+*                 constraints (see issue #414).
 */
-function getConfigSourceValue(state, options, innerState, extractInnerSourceValue) {
+function getConfigSourceValue(state, options, innerState, extractInnerSourceValue, innerParser) {
 	const annotations = getAnnotations(state);
 	const contextId = options.context.id;
 	const annotationValue = annotations?.[contextId];
 	const configData = annotationValue?.data ?? getActiveConfig(contextId);
+	const validateFallback = (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return innerParser.validateValue(parsed.value);
+	};
 	if (configData !== void 0 && configData !== null) {
-		const resolved = getConfigOrDefault(state, options);
-		if (resolved.success) return resolved;
+		const resolved = getConfigOrDefault(state, options, "sync", void 0);
+		if (resolved.success) return validateFallback(resolved);
 	}
-	if (options.default !== void 0) return {
+	if (options.default !== void 0) return validateFallback({
 		success: true,
 		value: options.default
-	};
+	});
 	return extractInnerSourceValue(innerState);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/config",
-  "version": "1.0.0-dev.1758+0d05b449",
+  "version": "1.0.0-dev.1772+a1288062",
   "description": "Configuration file support for Optique with Standard Schema validation",
   "keywords": [
     "CLI",
@@ -59,7 +59,7 @@
     "@standard-schema/spec": "^1.1.0"
   },
   "dependencies": {
-    "@optique/core": "1.0.0-dev.1758+0d05b449"
+    "@optique/core": "1.0.0-dev.1772+a1288062"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",
@@ -67,7 +67,7 @@
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
     "zod": "^3.25.0 || ^4.0.0",
-    "@optique/env": "1.0.0-dev.1758+0d05b449"
+    "@optique/env": "1.0.0-dev.1772+a1288062"
   },
   "scripts": {
     "build": "tsdown",