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

package/dist/constructs.cjs

@@ -3795,6 +3795,11 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(groupParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return groupParser;
 }
 /**

package/dist/constructs.js

@@ -3795,6 +3795,11 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(groupParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return groupParser;
 }
 /**

package/dist/modifiers.cjs

@@ -306,6 +306,20 @@ function optional(parser) {
 			enumerable: false
 		});
 	}
+	if (typeof parser.validateValue === "function") {
+		const innerValidate = parser.validateValue.bind(parser);
+		Object.defineProperty(optionalParser, "validateValue", {
+			value(v) {
+				if (v === void 0) return require_mode_dispatch.wrapForMode(parser.$mode, {
+					success: true,
+					value: v
+				});
+				return innerValidate(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (parser.dependencyMetadata != null) {
 		const composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
@@ -504,6 +518,16 @@ function withDefault(parser, defaultValue, options) {
 			enumerable: false
 		});
 	}
+	if (typeof parser.validateValue === "function") {
+		const innerValidate = parser.validateValue.bind(parser);
+		Object.defineProperty(withDefaultParser, "validateValue", {
+			value(v) {
+				return innerValidate(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (parser.dependencyMetadata != null) {
 		const composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "withDefault", { defaultValue: () => {
 			let v;
@@ -649,6 +673,7 @@ function map(parser, transform) {
 		}
 	};
 	delete mappedParser.normalizeValue;
+	delete mappedParser.validateValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
 		get() {
 			try {
@@ -1152,6 +1177,72 @@ function multiple(parser, options = {}) {
 			enumerable: false
 		});
 	}
+	{
+		const innerValidate = typeof parser.validateValue === "function" ? parser.validateValue.bind(parser) : void 0;
+		const validateArity = (values) => {
+			if (values.length < min) {
+				const customMessage = options.errors?.tooFew;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(min, values.length) : customMessage : require_message.message`Expected at least ${require_message.text(min.toLocaleString("en"))} values, but got only ${require_message.text(values.length.toLocaleString("en"))}.`
+				};
+			}
+			if (values.length > max) {
+				const customMessage = options.errors?.tooMany;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(max, values.length) : customMessage : require_message.message`Expected at most ${require_message.text(max.toLocaleString("en"))} values, but got ${require_message.text(values.length.toLocaleString("en"))}.`
+				};
+			}
+			return {
+				success: true,
+				value: values
+			};
+		};
+		Object.defineProperty(resultParser, "validateValue", {
+			value(values) {
+				if (!Array.isArray(values)) {
+					const actualType = values === null ? "null" : typeof values;
+					return require_mode_dispatch.wrapForMode(parser.$mode, {
+						success: false,
+						error: require_message.message`Expected an array of values, but received ${actualType}.`
+					});
+				}
+				const arity = validateArity(values);
+				if (!arity.success) return require_mode_dispatch.wrapForMode(parser.$mode, arity);
+				if (innerValidate == null) return require_mode_dispatch.wrapForMode(parser.$mode, arity);
+				return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+					let changed = false;
+					const normalized = [];
+					for (const v of values) {
+						const r = innerValidate(v);
+						if (!r.success) return r;
+						normalized.push(r.value);
+						if (r.value !== v) changed = true;
+					}
+					return {
+						success: true,
+						value: changed ? normalized : values
+					};
+				}, async () => {
+					let changed = false;
+					const normalized = [];
+					for (const v of values) {
+						const r = await innerValidate(v);
+						if (!r.success) return r;
+						normalized.push(r.value);
+						if (r.value !== v) changed = true;
+					}
+					return {
+						success: true,
+						value: changed ? normalized : values
+					};
+				});
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (parser.dependencyMetadata?.source != null) {
 		const innerSource = parser.dependencyMetadata.source;
 		Object.defineProperty(resultParser, "dependencyMetadata", {
@@ -1279,6 +1370,11 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(nonEmptyParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return nonEmptyParser;
 }
 

package/dist/modifiers.js

@@ -1,6 +1,6 @@
 import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { formatMessage, message, text } from "./message.js";
-import { dispatchByMode, dispatchIterableByMode, mapModeValue } from "./mode-dispatch.js";
+import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./mode-dispatch.js";
 import { composeDependencyMetadata } from "./dependency-metadata.js";
 import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
 
@@ -306,6 +306,20 @@ function optional(parser) {
 			enumerable: false
 		});
 	}
+	if (typeof parser.validateValue === "function") {
+		const innerValidate = parser.validateValue.bind(parser);
+		Object.defineProperty(optionalParser, "validateValue", {
+			value(v) {
+				if (v === void 0) return wrapForMode(parser.$mode, {
+					success: true,
+					value: v
+				});
+				return innerValidate(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (parser.dependencyMetadata != null) {
 		const composed = composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
@@ -504,6 +518,16 @@ function withDefault(parser, defaultValue, options) {
 			enumerable: false
 		});
 	}
+	if (typeof parser.validateValue === "function") {
+		const innerValidate = parser.validateValue.bind(parser);
+		Object.defineProperty(withDefaultParser, "validateValue", {
+			value(v) {
+				return innerValidate(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (parser.dependencyMetadata != null) {
 		const composed = composeDependencyMetadata(parser.dependencyMetadata, "withDefault", { defaultValue: () => {
 			let v;
@@ -649,6 +673,7 @@ function map(parser, transform) {
 		}
 	};
 	delete mappedParser.normalizeValue;
+	delete mappedParser.validateValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
 		get() {
 			try {
@@ -1152,6 +1177,72 @@ function multiple(parser, options = {}) {
 			enumerable: false
 		});
 	}
+	{
+		const innerValidate = typeof parser.validateValue === "function" ? parser.validateValue.bind(parser) : void 0;
+		const validateArity = (values) => {
+			if (values.length < min) {
+				const customMessage = options.errors?.tooFew;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(min, values.length) : customMessage : message`Expected at least ${text(min.toLocaleString("en"))} values, but got only ${text(values.length.toLocaleString("en"))}.`
+				};
+			}
+			if (values.length > max) {
+				const customMessage = options.errors?.tooMany;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(max, values.length) : customMessage : message`Expected at most ${text(max.toLocaleString("en"))} values, but got ${text(values.length.toLocaleString("en"))}.`
+				};
+			}
+			return {
+				success: true,
+				value: values
+			};
+		};
+		Object.defineProperty(resultParser, "validateValue", {
+			value(values) {
+				if (!Array.isArray(values)) {
+					const actualType = values === null ? "null" : typeof values;
+					return wrapForMode(parser.$mode, {
+						success: false,
+						error: message`Expected an array of values, but received ${actualType}.`
+					});
+				}
+				const arity = validateArity(values);
+				if (!arity.success) return wrapForMode(parser.$mode, arity);
+				if (innerValidate == null) return wrapForMode(parser.$mode, arity);
+				return dispatchByMode(parser.$mode, () => {
+					let changed = false;
+					const normalized = [];
+					for (const v of values) {
+						const r = innerValidate(v);
+						if (!r.success) return r;
+						normalized.push(r.value);
+						if (r.value !== v) changed = true;
+					}
+					return {
+						success: true,
+						value: changed ? normalized : values
+					};
+				}, async () => {
+					let changed = false;
+					const normalized = [];
+					for (const v of values) {
+						const r = await innerValidate(v);
+						if (!r.success) return r;
+						normalized.push(r.value);
+						if (r.value !== v) changed = true;
+					}
+					return {
+						success: true,
+						value: changed ? normalized : values
+					};
+				});
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (parser.dependencyMetadata?.source != null) {
 		const innerSource = parser.dependencyMetadata.source;
 		Object.defineProperty(resultParser, "dependencyMetadata", {
@@ -1279,6 +1370,11 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(nonEmptyParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return nonEmptyParser;
 }
 

package/dist/parser.d.cts

@@ -262,6 +262,50 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   normalizeValue?(value: TValue): TValue;
+  /**
+   * Optionally re-validates a value as if it had been parsed from CLI
+   * input, surfacing any constraint violations from the underlying value
+   * parser (e.g., regex patterns, numeric bounds, `choice()` values).
+   *
+   * Wrappers like `bindEnv()` and `bindConfig()` call this on fallback
+   * values — environment variables parsed by a looser env parser,
+   * configured defaults, and values loaded from config files — so that
+   * those values obey the same validation semantics as CLI input.
+   * Without it, parser constraints can be silently bypassed through
+   * fallback paths.
+   *
+   * Built-in primitive parsers ({@link option}, {@link argument})
+   * implement this method by round-tripping the value through the inner
+   * {@link ValueParser.format} and {@link ValueParser.parse} calls: the
+   * value is serialized back to a string and re-parsed, which re-runs
+   * every constraint check.  Combinator wrappers ({@link optional},
+   * {@link withDefault}) forward this method from their inner parser.
+   * {@link map} intentionally does *not* forward it because the mapping
+   * function is one-way: the mapped output type no longer corresponds
+   * to the inner parser's constraints.  Exclusive combinators
+   * ({@link or}, `longestMatch()`) and multi-source combinators
+   * (`merge()`, `concat()`) intentionally do not implement this method
+   * because the active branch or key ownership is unknown at validation
+   * time.
+   *
+   * Implementations must wrap any *exception* thrown by `format()` in
+   * `try`/`catch` and return the original value as a successful
+   * {@link ValueParserResult}.  This specifically protects
+   * dependency-derived parsers whose factory cannot run without the
+   * current dependency value, and custom value parsers whose `format()`
+   * intentionally throws for unsupported inputs.  Values that
+   * `format()` successfully serializes to a string are always re-parsed,
+   * and any resulting parse failure is propagated — they represent the
+   * bug class this method exists to surface.
+   *
+   * @param value The candidate value to validate.
+   * @returns A {@link ValueParserResult} indicating success (with the
+   *          possibly-canonicalized value) or failure (with an error
+   *          message).  In async mode, returns a `Promise` resolving to
+   *          the result.
+   * @since 1.0.0
+   */
+  validateValue?(value: TValue): ModeValue<M, ValueParserResult<TValue>>;
   /**
    * Internal dependency metadata describing this parser's dependency
    * capabilities.  Used by the dependency runtime to resolve dependencies

package/dist/parser.d.ts

@@ -262,6 +262,50 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   normalizeValue?(value: TValue): TValue;
+  /**
+   * Optionally re-validates a value as if it had been parsed from CLI
+   * input, surfacing any constraint violations from the underlying value
+   * parser (e.g., regex patterns, numeric bounds, `choice()` values).
+   *
+   * Wrappers like `bindEnv()` and `bindConfig()` call this on fallback
+   * values — environment variables parsed by a looser env parser,
+   * configured defaults, and values loaded from config files — so that
+   * those values obey the same validation semantics as CLI input.
+   * Without it, parser constraints can be silently bypassed through
+   * fallback paths.
+   *
+   * Built-in primitive parsers ({@link option}, {@link argument})
+   * implement this method by round-tripping the value through the inner
+   * {@link ValueParser.format} and {@link ValueParser.parse} calls: the
+   * value is serialized back to a string and re-parsed, which re-runs
+   * every constraint check.  Combinator wrappers ({@link optional},
+   * {@link withDefault}) forward this method from their inner parser.
+   * {@link map} intentionally does *not* forward it because the mapping
+   * function is one-way: the mapped output type no longer corresponds
+   * to the inner parser's constraints.  Exclusive combinators
+   * ({@link or}, `longestMatch()`) and multi-source combinators
+   * (`merge()`, `concat()`) intentionally do not implement this method
+   * because the active branch or key ownership is unknown at validation
+   * time.
+   *
+   * Implementations must wrap any *exception* thrown by `format()` in
+   * `try`/`catch` and return the original value as a successful
+   * {@link ValueParserResult}.  This specifically protects
+   * dependency-derived parsers whose factory cannot run without the
+   * current dependency value, and custom value parsers whose `format()`
+   * intentionally throws for unsupported inputs.  Values that
+   * `format()` successfully serializes to a string are always re-parsed,
+   * and any resulting parse failure is propagated — they represent the
+   * bug class this method exists to surface.
+   *
+   * @param value The candidate value to validate.
+   * @returns A {@link ValueParserResult} indicating success (with the
+   *          possibly-canonicalized value) or failure (with an error
+   *          message).  In async mode, returns a `Promise` resolving to
+   *          the result.
+   * @since 1.0.0
+   */
+  validateValue?(value: TValue): ModeValue<M, ValueParserResult<TValue>>;
   /**
    * Internal dependency metadata describing this parser's dependency
    * capabilities.  Used by the dependency runtime to resolve dependencies

package/dist/primitives.cjs

@@ -438,6 +438,7 @@ function option(...args) {
 	const isAsync = mode === "async";
 	const syncValueParser = valueParser;
 	const dependencyMetadata = valueParser != null ? require_dependency_metadata.extractDependencyMetadata(valueParser) : void 0;
+	const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : require_message.message`${require_message.optionNames(optionNames$1)}: ${error}`;
 	const result = {
 		$mode: mode,
 		$valueType: [],
@@ -619,7 +620,6 @@ function option(...args) {
 			};
 		},
 		complete(state, exec) {
-			const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : require_message.message`${require_message.optionNames(optionNames$1)}: ${error}`;
 			const missing = valueParser == null ? {
 				success: true,
 				value: false
@@ -693,6 +693,50 @@ function option(...args) {
 			enumerable: false
 		});
 	}
+	if (valueParser == null) Object.defineProperty(result, "validateValue", {
+		value(v) {
+			if (typeof v !== "boolean") {
+				const actualType = v === null ? "null" : typeof v;
+				return require_mode_dispatch.wrapForMode(mode, {
+					success: false,
+					error: formatInvalidValueError(require_message.message`Expected a boolean value, but received ${actualType}.`)
+				});
+			}
+			return require_mode_dispatch.wrapForMode(mode, {
+				success: true,
+				value: v
+			});
+		},
+		configurable: true,
+		enumerable: false
+	});
+	else if (!require_dependency.isDerivedValueParser(valueParser)) {
+		const vp = valueParser;
+		const wrapParseResult = (parsed) => parsed.success ? parsed : {
+			success: false,
+			error: formatInvalidValueError(parsed.error)
+		};
+		Object.defineProperty(result, "validateValue", {
+			value(v) {
+				let stringified;
+				try {
+					stringified = vp.format(v);
+				} catch {
+					return require_mode_dispatch.wrapForMode(mode, {
+						success: true,
+						value: v
+					});
+				}
+				if (typeof stringified !== "string") return require_mode_dispatch.wrapForMode(mode, {
+					success: true,
+					value: v
+				});
+				return require_mode_dispatch.dispatchByMode(mode, () => wrapParseResult(vp.parse(stringified)), async () => wrapParseResult(await vp.parse(stringified)));
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (valueParser != null) Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -934,6 +978,7 @@ function argument(valueParser, options = {}) {
 	const isAsync = valueParser.$mode === "async";
 	const syncValueParser = valueParser;
 	const dependencyMetadata = require_dependency_metadata.extractDependencyMetadata(valueParser);
+	const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : require_message.message`${require_message.metavar(valueParser.metavar)}: ${error}`;
 	const optionPattern = /^--?[a-z0-9-]+$/i;
 	const term = {
 		type: "argument",
@@ -1007,7 +1052,6 @@ function argument(valueParser, options = {}) {
 			});
 		},
 		complete(state, exec) {
-			const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : require_message.message`${require_message.metavar(valueParser.metavar)}: ${error}`;
 			const missing = {
 				success: false,
 				error: options.errors?.endOfInput ?? require_message.message`Expected a ${require_message.metavar(valueParser.metavar)}, but too few arguments.`
@@ -1075,6 +1119,34 @@ function argument(valueParser, options = {}) {
 			enumerable: false
 		});
 	}
+	if (!require_dependency.isDerivedValueParser(valueParser)) {
+		const vp = valueParser;
+		const vpMode = valueParser.$mode;
+		const wrapParseResult = (parsed) => parsed.success ? parsed : {
+			success: false,
+			error: formatInvalidValueError(parsed.error)
+		};
+		Object.defineProperty(result, "validateValue", {
+			value(v) {
+				let stringified;
+				try {
+					stringified = vp.format(v);
+				} catch {
+					return require_mode_dispatch.wrapForMode(vpMode, {
+						success: true,
+						value: v
+					});
+				}
+				if (typeof stringified !== "string") return require_mode_dispatch.wrapForMode(vpMode, {
+					success: true,
+					value: v
+				});
+				return require_mode_dispatch.dispatchByMode(vpMode, () => wrapParseResult(syncValueParser.parse(stringified)), async () => wrapParseResult(await vp.parse(stringified)));
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -1316,6 +1388,11 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(result, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**

package/dist/primitives.js

@@ -3,7 +3,7 @@ import { message, metavar, optionName, optionNames, text, valueSet } from "./mes
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./dependency.js";
 import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
-import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
+import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./mode-dispatch.js";
 import { extractDependencyMetadata } from "./dependency-metadata.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, findSimilar } from "./suggestion.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
@@ -438,6 +438,7 @@ function option(...args) {
 	const isAsync = mode === "async";
 	const syncValueParser = valueParser;
 	const dependencyMetadata = valueParser != null ? extractDependencyMetadata(valueParser) : void 0;
+	const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : message`${optionNames(optionNames$1)}: ${error}`;
 	const result = {
 		$mode: mode,
 		$valueType: [],
@@ -619,7 +620,6 @@ function option(...args) {
 			};
 		},
 		complete(state, exec) {
-			const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : message`${optionNames(optionNames$1)}: ${error}`;
 			const missing = valueParser == null ? {
 				success: true,
 				value: false
@@ -693,6 +693,50 @@ function option(...args) {
 			enumerable: false
 		});
 	}
+	if (valueParser == null) Object.defineProperty(result, "validateValue", {
+		value(v) {
+			if (typeof v !== "boolean") {
+				const actualType = v === null ? "null" : typeof v;
+				return wrapForMode(mode, {
+					success: false,
+					error: formatInvalidValueError(message`Expected a boolean value, but received ${actualType}.`)
+				});
+			}
+			return wrapForMode(mode, {
+				success: true,
+				value: v
+			});
+		},
+		configurable: true,
+		enumerable: false
+	});
+	else if (!isDerivedValueParser(valueParser)) {
+		const vp = valueParser;
+		const wrapParseResult = (parsed) => parsed.success ? parsed : {
+			success: false,
+			error: formatInvalidValueError(parsed.error)
+		};
+		Object.defineProperty(result, "validateValue", {
+			value(v) {
+				let stringified;
+				try {
+					stringified = vp.format(v);
+				} catch {
+					return wrapForMode(mode, {
+						success: true,
+						value: v
+					});
+				}
+				if (typeof stringified !== "string") return wrapForMode(mode, {
+					success: true,
+					value: v
+				});
+				return dispatchByMode(mode, () => wrapParseResult(vp.parse(stringified)), async () => wrapParseResult(await vp.parse(stringified)));
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (valueParser != null) Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -934,6 +978,7 @@ function argument(valueParser, options = {}) {
 	const isAsync = valueParser.$mode === "async";
 	const syncValueParser = valueParser;
 	const dependencyMetadata = extractDependencyMetadata(valueParser);
+	const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : message`${metavar(valueParser.metavar)}: ${error}`;
 	const optionPattern = /^--?[a-z0-9-]+$/i;
 	const term = {
 		type: "argument",
@@ -1007,7 +1052,6 @@ function argument(valueParser, options = {}) {
 			});
 		},
 		complete(state, exec) {
-			const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : message`${metavar(valueParser.metavar)}: ${error}`;
 			const missing = {
 				success: false,
 				error: options.errors?.endOfInput ?? message`Expected a ${metavar(valueParser.metavar)}, but too few arguments.`
@@ -1075,6 +1119,34 @@ function argument(valueParser, options = {}) {
 			enumerable: false
 		});
 	}
+	if (!isDerivedValueParser(valueParser)) {
+		const vp = valueParser;
+		const vpMode = valueParser.$mode;
+		const wrapParseResult = (parsed) => parsed.success ? parsed : {
+			success: false,
+			error: formatInvalidValueError(parsed.error)
+		};
+		Object.defineProperty(result, "validateValue", {
+			value(v) {
+				let stringified;
+				try {
+					stringified = vp.format(v);
+				} catch {
+					return wrapForMode(vpMode, {
+						success: true,
+						value: v
+					});
+				}
+				if (typeof stringified !== "string") return wrapForMode(vpMode, {
+					success: true,
+					value: v
+				});
+				return dispatchByMode(vpMode, () => wrapParseResult(syncValueParser.parse(stringified)), async () => wrapParseResult(await vp.parse(stringified)));
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -1316,6 +1388,11 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(result, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1758+0d05b449",
+  "version": "1.0.0-dev.1766+87276239",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",