@optique/core 1.1.0-dev.2087 → 1.1.0-dev.2146

package/dist/valueparser.js

@@ -1,4 +1,6 @@
-import { message, text, valueSet } from "./message.js";
+import { cloneMessage, lineBreak, message, metavar, text, valueSet } from "./message.js";
+import { isDerivedValueParser } from "./internal/dependency.js";
+import { deduplicateSuggestions } from "./suggestion.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 
 //#region src/valueparser.ts
@@ -29,8 +31,8 @@ function choice(choices, options = {}) {
 	const isNumber = typeof choices[0] === "number";
 	for (const c of choices) if (isNumber ? typeof c !== "number" : typeof c !== "string") throw new TypeError(`Expected every choice to be the same type, but got both ${isNumber ? "number" : "string"} and ${typeof c}.`);
 	if (isNumber && choices.some((v) => Number.isNaN(v))) throw new TypeError("NaN is not allowed in number choices.");
-	const metavar = options.metavar ?? "TYPE";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options.metavar ?? "TYPE";
+	ensureNonEmptyString(metavar$1);
 	if (isNumber) {
 		const numberChoices = (() => {
 			const seen = /* @__PURE__ */ new Set();
@@ -57,7 +59,7 @@ function choice(choices, options = {}) {
 		const frozenNumberChoices = Object.freeze(numberChoices);
 		return {
 			mode: "sync",
-			metavar,
+			metavar: metavar$1,
 			placeholder: choices[0],
 			choices: frozenNumberChoices,
 			parse(input) {
@@ -139,7 +141,7 @@ function choice(choices, options = {}) {
 	const stringInvalidChoice = stringOptions.errors?.invalidChoice;
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: choices[0],
 		choices: stringChoices,
 		parse(input) {
@@ -294,14 +296,14 @@ function formatDefaultChoiceError(input, choices) {
 */
 function string(options = {}) {
 	if (options.pattern != null && !(options.pattern instanceof RegExp)) throw new TypeError(`Expected pattern to be a RegExp, but got: ${Object.prototype.toString.call(options.pattern)}`);
-	const metavar = options.metavar ?? "STRING";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options.metavar ?? "STRING";
+	ensureNonEmptyString(metavar$1);
 	const patternSource = options.pattern?.source ?? null;
 	const patternFlags = options.pattern?.flags ?? null;
 	const patternMismatch = options.errors?.patternMismatch;
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: options.placeholder ?? "",
 		parse(input) {
 			if (patternSource != null && patternFlags != null) {
@@ -370,11 +372,11 @@ function integer(options) {
 	}
 	if (options?.min != null && options?.max != null && options.min > options.max) throw new RangeError(`Expected min to be less than or equal to max, but got min: ${options.min} and max: ${options.max}.`);
 	if (options?.type === "bigint") {
-		const metavar$1 = options.metavar ?? "INTEGER";
-		ensureNonEmptyString(metavar$1);
+		const metavar$2 = options.metavar ?? "INTEGER";
+		ensureNonEmptyString(metavar$2);
 		return {
 			mode: "sync",
-			metavar: metavar$1,
+			metavar: metavar$2,
 			placeholder: options?.placeholder ?? (options?.min != null && options.min > 0n ? options.min : options?.max != null && options.max < 0n ? options.max : 0n),
 			parse(input) {
 				if (!input.match(/^-?\d+$/)) return {
@@ -400,8 +402,8 @@ function integer(options) {
 			}
 		};
 	}
-	const metavar = options?.metavar ?? "INTEGER";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options?.metavar ?? "INTEGER";
+	ensureNonEmptyString(metavar$1);
 	const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
 	const minSafe = BigInt(Number.MIN_SAFE_INTEGER);
 	const safeMin = Math.max(options?.min ?? Number.MIN_SAFE_INTEGER, Number.MIN_SAFE_INTEGER);
@@ -418,7 +420,7 @@ function integer(options) {
 	}
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: options?.placeholder ?? (firstAllowed > 0 ? firstAllowed : lastAllowed < 0 ? lastAllowed : 0),
 		parse(input) {
 			if (!input.match(/^-?\d+$/)) return {
@@ -465,11 +467,11 @@ function float(options = {}) {
 	if (options.max != null && !Number.isFinite(options.max)) throw new RangeError(`Expected max to be a finite number, but got: ${options.max}`);
 	if (options.min != null && options.max != null && options.min > options.max) throw new RangeError(`Expected min to be less than or equal to max, but got min: ${options.min} and max: ${options.max}.`);
 	const floatRegex = /^[+-]?(?:(?:\d+\.?\d*)|(?:\d*\.\d+))(?:[eE][+-]?\d+)?$/;
-	const metavar = options.metavar ?? "NUMBER";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options.metavar ?? "NUMBER";
+	ensureNonEmptyString(metavar$1);
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: options?.placeholder ?? (options?.min != null && options.min > 0 ? options.min : options?.max != null && options.max < 0 ? options.max : 0),
 		parse(input) {
 			const invalidNumber = (i) => ({
@@ -741,8 +743,8 @@ const FILE_SIZE_UNITS = [
 */
 function fileSize(options = {}) {
 	if (options.type !== void 0 && options.type !== "number" && options.type !== "bigint") throw new TypeError(`Expected type to be "number" or "bigint", but got: ${String(options.type)}.`);
-	const metavar = options.metavar ?? "SIZE";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options.metavar ?? "SIZE";
+	ensureNonEmptyString(metavar$1);
 	checkBooleanOption(options, "allowNegative");
 	checkBooleanOption(options, "siAsBinary");
 	checkEnumOption(options, "defaultUnit", FILE_SIZE_UNITS);
@@ -762,7 +764,7 @@ function fileSize(options = {}) {
 		const numberFormatUnits = siAsBinary ? FORMAT_UNITS_SI_AS_BINARY : FORMAT_UNITS_DEFAULT;
 		return {
 			mode: "sync",
-			metavar,
+			metavar: metavar$1,
 			placeholder: options.placeholder ?? 0n,
 			parse(input) {
 				const match = FILE_SIZE_REGEX.exec(input.trim());
@@ -803,7 +805,7 @@ function fileSize(options = {}) {
 	const formatUnits = siAsBinary ? FORMAT_UNITS_SI_AS_BINARY : FORMAT_UNITS_DEFAULT;
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: options.placeholder ?? 0,
 		parse(input) {
 			const match = FILE_SIZE_REGEX.exec(input.trim());
@@ -1802,8 +1804,8 @@ const VALID_COLOR_FORMATS = [
 * @since 1.1.0
 */
 function color(options = {}) {
-	const metavar = options.metavar ?? "COLOR";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options.metavar ?? "COLOR";
+	ensureNonEmptyString(metavar$1);
 	if (options.formats !== void 0) {
 		for (const fmt of options.formats) if (!VALID_COLOR_FORMATS.includes(fmt)) throw new TypeError(`Expected formats to contain only ${VALID_COLOR_FORMATS.map((v) => JSON.stringify(v)).join(", ")}, but got: ${JSON.stringify(fmt)}.`);
 	}
@@ -1835,7 +1837,7 @@ function color(options = {}) {
 	}
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: options.placeholder ?? defaultPlaceholder,
 		parse(input) {
 			const trimmed = input.trim();
@@ -2009,13 +2011,13 @@ function url(options = {}) {
 	}
 	const originalProtocols = options.allowedProtocols != null ? Object.freeze(originalProtocolsList) : void 0;
 	const allowedProtocols = options.allowedProtocols != null ? Object.freeze(normalizedProtocolsList) : void 0;
-	const metavar = options.metavar ?? "URL";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options.metavar ?? "URL";
+	ensureNonEmptyString(metavar$1);
 	const invalidUrl = options.errors?.invalidUrl;
 	const disallowedProtocol = options.errors?.disallowedProtocol;
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		get placeholder() {
 			return new URL(`${allowedProtocols?.[0] ?? "http:"}//0.invalid`);
 		},
@@ -2083,11 +2085,11 @@ function url(options = {}) {
 *          objects.
 */
 function locale(options = {}) {
-	const metavar = options.metavar ?? "LOCALE";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options.metavar ?? "LOCALE";
+	ensureNonEmptyString(metavar$1);
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: new Intl.Locale("und"),
 		parse(input) {
 			let locale$1;
@@ -2365,8 +2367,8 @@ function locale(options = {}) {
 */
 function uuid(options = {}) {
 	const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-	const metavar = options.metavar ?? "UUID";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options.metavar ?? "UUID";
+	ensureNonEmptyString(metavar$1);
 	checkBooleanOption(options, "strict");
 	const strict = options.strict !== false;
 	const allowedVersions = options.allowedVersions != null ? (() => {
@@ -2383,7 +2385,7 @@ function uuid(options = {}) {
 	const invalidVariant = options.errors?.invalidVariant;
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: "00000000-0000-0000-0000-000000000000",
 		parse(input) {
 			if (!uuidRegex.test(input)) return {
@@ -2483,15 +2485,15 @@ function port(options) {
 	checkBooleanOption(options, "disallowWellKnown");
 	if (options?.type !== void 0 && options.type !== "number" && options.type !== "bigint") throw new TypeError(`Expected type to be "number" or "bigint", but got: ${String(options.type)}.`);
 	if (options?.type === "bigint") {
-		const metavar$1 = options.metavar ?? "PORT";
-		ensureNonEmptyString(metavar$1);
+		const metavar$2 = options.metavar ?? "PORT";
+		ensureNonEmptyString(metavar$2);
 		const min$1 = options.min ?? 1n;
 		const max$1 = options.max ?? 65535n;
 		if (min$1 > max$1) throw new RangeError(`Expected min to be less than or equal to max, but got min: ${min$1} and max: ${max$1}.`);
 		if (options.disallowWellKnown && min$1 < 1024n && max$1 < 1024n) throw new RangeError(`disallowWellKnown is incompatible with the configured port range: all ports ${min$1}..${max$1} are well-known.`);
 		return {
 			mode: "sync",
-			metavar: metavar$1,
+			metavar: metavar$2,
 			placeholder: options.placeholder ?? (options.disallowWellKnown && min$1 < 1024n ? 1024n > min$1 ? 1024n : min$1 : min$1),
 			parse(input) {
 				if (!input.match(/^-?\d+$/)) return {
@@ -2523,15 +2525,15 @@ function port(options) {
 	}
 	if (options?.min != null && !Number.isFinite(options.min)) throw new RangeError(`Expected min to be a finite number, but got: ${options.min}`);
 	if (options?.max != null && !Number.isFinite(options.max)) throw new RangeError(`Expected max to be a finite number, but got: ${options.max}`);
-	const metavar = options?.metavar ?? "PORT";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options?.metavar ?? "PORT";
+	ensureNonEmptyString(metavar$1);
 	const min = options?.min ?? 1;
 	const max = options?.max ?? 65535;
 	if (min > max) throw new RangeError(`Expected min to be less than or equal to max, but got min: ${min} and max: ${max}.`);
 	if (options?.disallowWellKnown && min < 1024 && max < 1024) throw new RangeError(`disallowWellKnown is incompatible with the configured port range: all ports ${min}..${max} are well-known.`);
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: options?.placeholder ?? (options?.disallowWellKnown && min < 1024 ? Math.max(1024, min) : min),
 		parse(input) {
 			if (!input.match(/^-?\d+$/)) return {
@@ -2615,8 +2617,8 @@ function isZeroIp(octets) {
 * ```
 */
 function ipv4(options) {
-	const metavar = options?.metavar ?? "IPV4";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options?.metavar ?? "IPV4";
+	ensureNonEmptyString(metavar$1);
 	const allowPrivate = options?.allowPrivate ?? true;
 	const allowLoopback = options?.allowLoopback ?? true;
 	const allowLinkLocal = options?.allowLinkLocal ?? true;
@@ -2625,7 +2627,7 @@ function ipv4(options) {
 	const allowZero = options?.allowZero ?? true;
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: allowZero ? "0.0.0.0" : allowLoopback ? "127.0.0.1" : "192.0.2.1",
 		parse(input) {
 			const octets = parseIpv4Octets(input);
@@ -2730,8 +2732,8 @@ function ipv4(options) {
 * ```
 */
 function hostname(options) {
-	const metavar = options?.metavar ?? "HOST";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options?.metavar ?? "HOST";
+	ensureNonEmptyString(metavar$1);
 	checkBooleanOption(options, "allowWildcard");
 	checkBooleanOption(options, "allowUnderscore");
 	checkBooleanOption(options, "allowLocalhost");
@@ -2742,7 +2744,7 @@ function hostname(options) {
 	if (!Number.isInteger(maxLength) || maxLength < 1) throw new RangeError("maxLength must be an integer greater than or equal to 1.");
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: options?.placeholder ?? (allowLocalhost ? maxLength >= 9 ? "localhost" : "a.bc" : maxLength >= 11 ? "example.com" : "a.bc"),
 		parse(input) {
 			if (input.length > maxLength) {
@@ -2860,8 +2862,8 @@ function hostname(options) {
 	};
 }
 function email(options) {
-	const metavar = options?.metavar ?? "EMAIL";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options?.metavar ?? "EMAIL";
+	ensureNonEmptyString(metavar$1);
 	const allowMultiple = options?.allowMultiple ?? false;
 	if (options?.placeholder != null) {
 		if (allowMultiple && !Array.isArray(options.placeholder)) throw new TypeError("email() placeholder must be an array when allowMultiple is true.");
@@ -2962,7 +2964,7 @@ function email(options) {
 	}
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: options?.placeholder ?? (options?.allowMultiple ? [`user@${options?.allowedDomains?.[0] ?? "example.com"}`] : `user@${options?.allowedDomains?.[0] ?? "example.com"}`),
 		parse(input) {
 			if (allowMultiple) {
@@ -3121,8 +3123,8 @@ function socketAddress(options) {
 	if (separator === "") throw new TypeError("Expected separator to not be empty.");
 	if (/\p{Nd}/u.test(separator)) throw new TypeError(`Expected separator to not contain digits, but got: ${JSON.stringify(separator)}.`);
 	const formatExample = `host${JSON.stringify(separator).slice(1, -1)}port`;
-	const metavar = options?.metavar ?? `HOST${separator}PORT`;
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options?.metavar ?? `HOST${separator}PORT`;
+	ensureNonEmptyString(metavar$1);
 	const defaultPort = options?.defaultPort;
 	const requirePort = options?.requirePort ?? false;
 	const hostType = options?.host?.type ?? "both";
@@ -3197,7 +3199,7 @@ function socketAddress(options) {
 	}
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		get placeholder() {
 			return {
 				host: hostType === "ip" ? ipParser.placeholder : hostnameParser.placeholder,
@@ -3416,8 +3418,8 @@ function portRange(options) {
 	const separator = options?.separator ?? "-";
 	if (separator === "") throw new TypeError("Expected separator to not be empty.");
 	if (/\p{Nd}/u.test(separator)) throw new TypeError(`Expected separator to not contain digits, but got: ${JSON.stringify(separator)}.`);
-	const metavar = options?.metavar ?? `PORT${separator}PORT`;
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options?.metavar ?? `PORT${separator}PORT`;
+	ensureNonEmptyString(metavar$1);
 	const allowSingle = options?.allowSingle ?? false;
 	const isBigInt = options?.type === "bigint";
 	const portParser = isBigInt ? port({
@@ -3435,7 +3437,7 @@ function portRange(options) {
 	});
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		get placeholder() {
 			return isBigInt ? {
 				start: portParser.placeholder,
@@ -3595,7 +3597,7 @@ function macAddress(options) {
 	const separator = options?.separator ?? "any";
 	const caseOption = options?.case ?? "preserve";
 	const outputSeparator = options?.outputSeparator;
-	const metavar = options?.metavar ?? "MAC";
+	const metavar$1 = options?.metavar ?? "MAC";
 	const colonRegex = /^([0-9a-fA-F]{1,2}):([0-9a-fA-F]{1,2}):([0-9a-fA-F]{1,2}):([0-9a-fA-F]{1,2}):([0-9a-fA-F]{1,2}):([0-9a-fA-F]{1,2})$/;
 	const hyphenRegex = /^([0-9a-fA-F]{1,2})-([0-9a-fA-F]{1,2})-([0-9a-fA-F]{1,2})-([0-9a-fA-F]{1,2})-([0-9a-fA-F]{1,2})-([0-9a-fA-F]{1,2})$/;
 	const dotRegex = /^([0-9a-fA-F]{4})\.([0-9a-fA-F]{4})\.([0-9a-fA-F]{4})$/;
@@ -3627,7 +3629,7 @@ function macAddress(options) {
 	}
 	const parserObj = {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		get placeholder() {
 			const octets = [
 				"00",
@@ -3709,7 +3711,7 @@ function macAddress(options) {
 			};
 		},
 		format(value) {
-			if (typeof value !== "string") return metavar;
+			if (typeof value !== "string") return metavar$1;
 			return normalizeMacValue(value, value);
 		},
 		normalize(value) {
@@ -3758,7 +3760,7 @@ function macAddress(options) {
 * @since 0.10.0
 */
 function domain(options) {
-	const metavar = options?.metavar ?? "DOMAIN";
+	const metavar$1 = options?.metavar ?? "DOMAIN";
 	checkBooleanOption(options, "allowSubdomains");
 	checkBooleanOption(options, "lowercase");
 	const allowSubdomains = options?.allowSubdomains ?? true;
@@ -3791,7 +3793,7 @@ function domain(options) {
 	const tldNotAllowed = options?.errors?.tldNotAllowed;
 	const domainParserObj = {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: options?.placeholder ?? `example.${allowedTldsLower?.[0] ?? "com"}`,
 		parse(input) {
 			if (input.length > maxLength) {
@@ -3997,7 +3999,7 @@ function domain(options) {
 			};
 		},
 		format(value) {
-			if (typeof value !== "string") return metavar;
+			if (typeof value !== "string") return metavar$1;
 			if (!lowercase) return value;
 			return value.split(".").length >= minLabels ? value.toLowerCase() : value;
 		}
@@ -4007,7 +4009,7 @@ function domain(options) {
 		let domParsing = false;
 		Object.defineProperty(domainParserObj, "format", {
 			value(v) {
-				if (typeof v !== "string") return metavar;
+				if (typeof v !== "string") return metavar$1;
 				if (domParsing) return v;
 				domParsing = true;
 				try {
@@ -4072,10 +4074,10 @@ function ipv6(options) {
 	const allowMulticast = options?.allowMulticast ?? true;
 	const allowZero = options?.allowZero ?? true;
 	const errors = options?.errors;
-	const metavar = options?.metavar ?? "IPV6";
+	const metavar$1 = options?.metavar ?? "IPV6";
 	const ipv6ParserObj = {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: allowZero ? "::" : allowLoopback ? "::1" : "2001:db8::1",
 		parse(input) {
 			const normalized = parseAndNormalizeIpv6(input);
@@ -4227,14 +4229,14 @@ function ipv6(options) {
 			};
 		},
 		format(value) {
-			if (typeof value !== "string") return metavar;
+			if (typeof value !== "string") return metavar$1;
 			return parseAndNormalizeIpv6(value) ?? value;
 		}
 	};
 	let ipv6Parsing = false;
 	Object.defineProperty(ipv6ParserObj, "format", {
 		value(v) {
-			if (typeof v !== "string") return metavar;
+			if (typeof v !== "string") return metavar$1;
 			if (ipv6Parsing) return v;
 			ipv6Parsing = true;
 			try {
@@ -4511,7 +4513,7 @@ function checkIpv4MappedRestrictions(octets, normalizedIpv6, ipv4Opts, errors) {
 */
 function ip(options) {
 	const version = options?.version ?? "both";
-	const metavar = options?.metavar ?? "IP";
+	const metavar$1 = options?.metavar ?? "IP";
 	const errors = options?.errors;
 	const ipv4Parser = version === 4 || version === "both" ? ipv4({
 		...options?.ipv4,
@@ -4554,7 +4556,7 @@ function ip(options) {
 	} : void 0;
 	const ipParserObj = {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: version === 6 ? ipv6Parser.placeholder : ipv4Parser.placeholder,
 		parse(input) {
 			let ipv4Error = null;
@@ -4613,14 +4615,14 @@ function ip(options) {
 			};
 		},
 		format(value) {
-			if (typeof value !== "string") return metavar;
+			if (typeof value !== "string") return metavar$1;
 			return parseAndNormalizeIpv6(value) ?? value;
 		}
 	};
 	let ipParsing = false;
 	Object.defineProperty(ipParserObj, "format", {
 		value(v) {
-			if (typeof v !== "string") return metavar;
+			if (typeof v !== "string") return metavar$1;
 			if (ipParsing) return v;
 			ipParsing = true;
 			try {
@@ -4690,7 +4692,7 @@ function cidr(options) {
 	const minPrefix = options?.minPrefix;
 	const maxPrefix = options?.maxPrefix;
 	const errors = options?.errors;
-	const metavar = options?.metavar ?? "CIDR";
+	const metavar$1 = options?.metavar ?? "CIDR";
 	const genericIpSentinel = [];
 	const ipv4Parser = version === 4 || version === "both" ? ipv4({
 		...options?.ipv4,
@@ -4733,7 +4735,7 @@ function cidr(options) {
 	} : void 0;
 	const cidrParserObj = {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		get placeholder() {
 			return version === 6 || version === "both" && (minPrefix ?? 0) > 32 ? {
 				address: ipv6Parser.placeholder,
@@ -5102,12 +5104,12 @@ function cidr(options) {
 				}
 			};
 		},
-		format: ((_) => metavar)
+		format: ((_) => metavar$1)
 	};
 	let cidrParsing = false;
 	Object.defineProperty(cidrParserObj, "format", {
 		value(value) {
-			if (typeof value !== "object" || value == null || !("address" in value) || !("prefix" in value) || !("version" in value)) return metavar;
+			if (typeof value !== "object" || value == null || !("address" in value) || !("prefix" in value) || !("version" in value)) return metavar$1;
 			if (cidrParsing) return `${value.address}/${value.prefix}`;
 			cidrParsing = true;
 			try {
@@ -5155,8 +5157,8 @@ const SEMVER_SUGGESTIONS = Object.freeze([
 ]);
 const SEMVER_SUGGESTIONS_WITH_PREFIX = Object.freeze([...SEMVER_SUGGESTIONS, ...SEMVER_SUGGESTIONS.map((s) => `v${s}`)]);
 function semVer(options = {}) {
-	const metavar = options.metavar ?? "SEMVER";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options.metavar ?? "SEMVER";
+	ensureNonEmptyString(metavar$1);
 	checkEnumOption(options, "type", ["string", "object"]);
 	checkBooleanOption(options, "allowPrefix");
 	const allowPrefix = options.allowPrefix ?? false;
@@ -5171,7 +5173,7 @@ function semVer(options = {}) {
 	}
 	if (objectMode) return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: {
 			major: 0,
 			minor: 0,
@@ -5212,7 +5214,7 @@ function semVer(options = {}) {
 	};
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder: "0.0.0",
 		parse(input) {
 			const m = SEMVER_REGEX.exec(input);
@@ -5267,8 +5269,8 @@ function semVer(options = {}) {
 * @since 1.1.0
 */
 function json(options) {
-	const metavar = options?.metavar ?? "JSON";
-	ensureNonEmptyString(metavar);
+	const metavar$1 = options?.metavar ?? "JSON";
+	ensureNonEmptyString(metavar$1);
 	checkEnumOption(options, "rootType", [
 		"string",
 		"number",
@@ -5290,7 +5292,7 @@ function json(options) {
 	const placeholder = options?.placeholder ?? defaultPlaceholder;
 	return {
 		mode: "sync",
-		metavar,
+		metavar: metavar$1,
 		placeholder,
 		parse(input) {
 			let value;
@@ -5369,6 +5371,257 @@ function findNonFiniteNumber(root) {
 	}
 	return void 0;
 }
+/**
+* Implementation of the {@link firstOf} combinator.
+*/
+function firstOf(...rawArgs) {
+	const args = rawArgs.length > 0 && rawArgs.at(-1) === void 0 ? rawArgs.slice(0, -1) : rawArgs;
+	let parsers;
+	let options;
+	if (args.length > 0 && Array.isArray(args[0])) {
+		parsers = [...args[0]];
+		options = args[1] ?? {};
+	} else {
+		const last = args.at(-1);
+		if (args.length > 0 && typeof last === "object" && last != null && !isValueParser(last)) {
+			options = last;
+			parsers = args.slice(0, -1);
+		} else {
+			options = {};
+			parsers = args;
+		}
+	}
+	if (parsers.length < 2) throw new TypeError("firstOf() requires at least two value parsers.");
+	for (const parser of parsers) {
+		if (!isValueParser(parser)) throw new TypeError("Every firstOf() constituent must be a value parser.");
+		if (parser.mode !== "sync") throw new TypeError("firstOf() only supports sync value parsers, but an async one was given.");
+		if (isDerivedValueParser(parser)) throw new TypeError("firstOf() does not support dependency-derived value parsers (created via deriveFrom() or dependency().derive()); pass the derived parser directly to option() or argument() instead.");
+	}
+	const metavar$1 = options.metavar ?? parsers.map((parser) => parser.metavar).join("|");
+	ensureNonEmptyString(metavar$1);
+	const mergedChoices = parsers.every((parser) => parser.choices != null) ? Object.freeze(parsers.flatMap((parser) => [...parser.choices]).filter((value, index, all) => all.findIndex((other) => Object.is(other, value)) === index)) : void 0;
+	function findOwner(value) {
+		let canonicalizing;
+		for (const parser of parsers) {
+			if (typeof parser.validate === "function") {
+				let result$1;
+				try {
+					result$1 = parser.validate(value);
+				} catch {
+					continue;
+				}
+				if (result$1.success) return {
+					parser,
+					result: result$1
+				};
+				continue;
+			}
+			let formatted;
+			try {
+				formatted = parser.format(value);
+			} catch {
+				continue;
+			}
+			if (typeof formatted !== "string") continue;
+			const result = parser.parse(formatted);
+			if (!result.success) continue;
+			if (ownsRoundTrippedValue(parser, result.value, value)) return {
+				parser,
+				result
+			};
+			if (canonicalizing == null && value !== null && typeof value !== "object" && typeof result.value === typeof value) canonicalizing = {
+				parser,
+				result
+			};
+		}
+		return canonicalizing;
+	}
+	const hasNormalize = parsers.some((parser) => typeof parser.normalize === "function");
+	const hasSuggest = parsers.some((parser) => typeof parser.suggest === "function");
+	return {
+		mode: "sync",
+		metavar: metavar$1,
+		placeholder: parsers[0].placeholder,
+		...mergedChoices != null ? { choices: mergedChoices } : {},
+		parse(input) {
+			const errors = [];
+			for (const parser of parsers) {
+				const result = parser.parse(input);
+				if (result.success) return result;
+				errors.push(result.error);
+			}
+			const noMatch = options.errors?.noMatch;
+			return {
+				success: false,
+				error: noMatch == null ? firstOfNoMatchError(errors) : typeof noMatch === "function" ? noMatch(input, errors) : noMatch
+			};
+		},
+		format(value) {
+			let canonicalizing;
+			let fallback;
+			let firstError;
+			let hasError = false;
+			for (const parser of parsers) {
+				let formatted;
+				try {
+					formatted = parser.format(value);
+				} catch (e) {
+					if (!hasError) {
+						firstError = e;
+						hasError = true;
+					}
+					continue;
+				}
+				if (typeof formatted !== "string") continue;
+				if (typeof parser.validate === "function") {
+					let owned = false;
+					try {
+						owned = parser.validate(value).success;
+					} catch {}
+					if (owned) return formatted;
+				} else {
+					const result = parser.parse(formatted);
+					if (result.success) {
+						if (ownsRoundTrippedValue(parser, result.value, value)) return formatted;
+						if (canonicalizing == null && value !== null && typeof value !== "object" && typeof result.value === typeof value) canonicalizing = formatted;
+					}
+				}
+				fallback ??= formatted;
+			}
+			if (canonicalizing !== void 0) return canonicalizing;
+			if (fallback !== void 0) return fallback;
+			if (hasError) throw firstError;
+			throw new TypeError("No constituent parser could format the given value.");
+		},
+		validate(value) {
+			const owner = findOwner(value);
+			if (owner == null) return {
+				success: false,
+				error: message`Expected a value matching ${metavar(metavar$1)}.`
+			};
+			return owner.result;
+		},
+		...hasNormalize ? { normalize(value) {
+			const owner = findOwner(value);
+			if (owner == null || typeof owner.parser.normalize !== "function") return value;
+			return owner.parser.normalize(value);
+		} } : {},
+		...hasSuggest ? { *suggest(prefix) {
+			const collected = [];
+			for (const parser of parsers) {
+				if (typeof parser.suggest !== "function") continue;
+				for (const suggestion of parser.suggest(prefix)) collected.push(suggestion);
+			}
+			yield* deduplicateSuggestions(collected);
+		} } : {}
+	};
+}
+/**
+* Builds the default error message for {@link firstOf} when every
+* constituent parser fails: a header followed by each constituent's error
+* on its own line.
+*/
+function firstOfNoMatchError(errors) {
+	const terms = [text("Expected one of the following:")];
+	for (const error of errors) terms.push(lineBreak(), text("- "), ...cloneMessage(error));
+	return terms;
+}
+/**
+* Determines whether a {@link firstOf} constituent owns a value, given the
+* result of round-tripping the value through the constituent's `format()`
+* and `parse()`.  The constituent owns the value when the round-trip
+* preserves it exactly, when it yields the constituent's own normalization
+* of it (e.g. a MAC address parser canonicalizing separators and case), or
+* when the round-trip is a recognized parse-level canonicalization: a
+* case-insensitive string match (e.g. a case-insensitive `choice()`
+* folding `"INFO"` to `"info"`) or numeric equality (a number parser
+* folding `-0` to `0`)—the same acceptance the constituent alone would
+* grant a fallback value through round-trip validation.  Parsers with
+* richer parse-level canonicalization should expose it via `normalize()`.
+* A merely *successful* round-trip is not enough otherwise: an arbitrary
+* same-type change means data loss rather than canonicalization (e.g. a
+* clamping `format()` folding 15 into 10), a round-trip that changes the
+* primitive type means the string form belongs to a different branch of
+* the union (e.g. `choice(["1"])` capturing the integer 1), and for
+* object values structural equality is the only way to tell
+* canonicalization from data loss (e.g. a lossy `color()` `format()`
+* dropping fields that belong to a later, more faithful constituent).
+*/
+function ownsRoundTrippedValue(parser, roundTripped, value) {
+	if (valuesEqual(roundTripped, value)) return true;
+	if (typeof parser.normalize === "function") {
+		let normalized;
+		try {
+			normalized = parser.normalize(value);
+		} catch {
+			return false;
+		}
+		if (valuesEqual(roundTripped, normalized)) return true;
+	}
+	if (typeof value === "string" && typeof roundTripped === "string") return value.toLowerCase() === roundTripped.toLowerCase();
+	if (typeof value === "number" && typeof roundTripped === "number") return value === roundTripped;
+	return false;
+}
+/**
+* Structural equality for parsed CLI values: primitives compare with
+* `Object.is` (so `NaN` equals itself and `0` differs from `-0`, matching
+* the distinction `choice()` makes), `Date` and `URL` instances compare by
+* time value and href respectively, arrays and plain objects compare
+* recursively, and other class instances compare by their overridden
+* `toString()` serialization.  Recursion is bounded by the structure of
+* the second argument, which in {@link firstOf} is always a freshly
+* parsed (acyclic) value.
+*/
+function valuesEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a == null || b == null) return false;
+	if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((item, i) => valuesEqual(item, b[i]));
+	if (a instanceof Date || b instanceof Date) return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+	if (a instanceof URL || b instanceof URL) return a instanceof URL && b instanceof URL && a.href === b.href;
+	const prototypeA = Object.getPrototypeOf(a);
+	const prototypeB = Object.getPrototypeOf(b);
+	const plainA = prototypeA === Object.prototype || prototypeA === null;
+	const plainB = prototypeB === Object.prototype || prototypeB === null;
+	if (plainA !== plainB) return false;
+	if (!plainA) {
+		if (prototypeA !== prototypeB) return false;
+		const overridesA = hasCustomToString(a);
+		const overridesB = hasCustomToString(b);
+		if (overridesA !== overridesB) return false;
+		const hasKeys = Object.keys(a).length > 0 || Object.keys(b).length > 0;
+		if (hasKeys && !plainObjectsEqual(a, b)) return false;
+		if (!overridesA) return hasKeys;
+		try {
+			return String(a) === String(b);
+		} catch {
+			return false;
+		}
+	}
+	return plainObjectsEqual(a, b);
+}
+/**
+* Checks whether an object provides a `toString()` implementation other
+* than the generic `Object.prototype.toString`.
+*/
+function hasCustomToString(value) {
+	try {
+		const toString = value.toString;
+		return typeof toString === "function" && toString !== Object.prototype.toString;
+	} catch {
+		return false;
+	}
+}
+/**
+* Compares two objects by their enumerable own keys, recursing into the
+* values with {@link valuesEqual}.
+*/
+function plainObjectsEqual(a, b) {
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+	if (aKeys.length !== bKeys.length) return false;
+	const bRecord = b;
+	return aKeys.every((key) => Object.hasOwn(b, key) && valuesEqual(a[key], bRecord[key]));
+}
 
 //#endregion
-export { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };
+export { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid };