@optique/core 0.10.7 → 1.0.0-dev.1116

package/dist/valueparser.js

@@ -14,56 +14,129 @@ function isValueParser(object) {
 * Implementation of the choice parser for both string and number types.
 */
 function choice(choices, options = {}) {
+	if (choices.length < 1) throw new TypeError("Expected at least one choice, but got an empty array.");
+	if (choices.some((c) => c === "")) throw new TypeError("Empty strings are not allowed as choices.");
+	for (const c of choices) if (typeof c !== "string" && typeof c !== "number") throw new TypeError(`Expected every choice to be a string or number, but got ${typeof c}.`);
+	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 isNumberChoice = choices.length > 0 && typeof choices[0] === "number";
-	if (isNumberChoice) {
-		const numberChoices = choices;
-		const numberOptions = options;
+	if (isNumber) {
+		const numberChoices = (() => {
+			const seen = /* @__PURE__ */ new Set();
+			let hasPositiveZero = false;
+			let hasNegativeZero = false;
+			const result = [];
+			for (const v of choices) {
+				if (Object.is(v, -0)) {
+					if (hasNegativeZero) continue;
+					hasNegativeZero = true;
+				} else if (Object.is(v, 0)) {
+					if (hasPositiveZero) continue;
+					hasPositiveZero = true;
+				} else {
+					if (seen.has(v)) continue;
+					seen.add(v);
+				}
+				result.push(v);
+			}
+			return result;
+		})();
+		const numberInvalidChoice = options.errors?.invalidChoice;
+		const numberStrings = numberChoices.map((v) => Object.is(v, -0) ? "-0" : String(v));
+		const frozenNumberChoices = Object.freeze(numberChoices);
 		return {
 			$mode: "sync",
 			metavar,
-			choices,
+			choices: frozenNumberChoices,
 			parse(input) {
-				const parsed = Number(input);
-				if (Number.isNaN(parsed)) return {
-					success: false,
-					error: formatNumberChoiceError(input, numberChoices, numberOptions)
-				};
-				const index = numberChoices.indexOf(parsed);
-				if (index < 0) return {
-					success: false,
-					error: formatNumberChoiceError(input, numberChoices, numberOptions)
-				};
-				return {
+				const index = numberStrings.indexOf(input);
+				if (index >= 0) return {
 					success: true,
 					value: numberChoices[index]
 				};
+				if (/^[+-]?(\d+\.?\d*|\.\d+)$/.test(input)) {
+					const parsed = Number(input);
+					if (Number.isFinite(parsed)) {
+						const canonical = Object.is(parsed, -0) ? "-0" : String(parsed);
+						const normalizedInput = normalizeDecimal(input);
+						const normalizedCanonical = normalizeDecimal(expandScientific(canonical));
+						if (normalizedInput === normalizedCanonical) {
+							const fallbackIndex = numberChoices.findIndex((v) => Object.is(v, parsed));
+							if (fallbackIndex >= 0) return {
+								success: true,
+								value: numberChoices[fallbackIndex]
+							};
+						}
+						if (parsed === 0 && normalizedInput.replace(/^-/, "") === "0" && !numberChoices.some((v) => Object.is(v, -0))) {
+							const zeroIndex = numberChoices.indexOf(0);
+							if (zeroIndex >= 0) return {
+								success: true,
+								value: numberChoices[zeroIndex]
+							};
+						}
+					}
+				}
+				if (/^[+-]?(\d+\.?\d*|\.\d+)[eE][+-]?\d+$/.test(input)) {
+					const parsed = Number(input);
+					if (Number.isFinite(parsed)) {
+						const canonical = Object.is(parsed, -0) ? "-0" : String(parsed);
+						if (/[eE]/.test(canonical)) {
+							const normalizedInput = normalizeDecimal(expandScientific(input));
+							const normalizedCanonical = normalizeDecimal(expandScientific(canonical));
+							if (normalizedInput === normalizedCanonical) {
+								const fallbackIndex = numberChoices.findIndex((v) => Object.is(v, parsed));
+								if (fallbackIndex >= 0) return {
+									success: true,
+									value: numberChoices[fallbackIndex]
+								};
+							}
+						}
+					}
+				}
+				return {
+					success: false,
+					error: formatNumberChoiceError(input, numberChoices, numberChoices, numberInvalidChoice)
+				};
 			},
 			format(value) {
-				return String(value);
+				return Object.is(value, -0) ? "-0" : String(value);
 			},
 			suggest(prefix) {
-				return numberChoices.map((value) => String(value)).filter((valueStr) => valueStr.startsWith(prefix)).map((valueStr) => ({
+				return numberStrings.filter((valueStr, i) => !Number.isNaN(numberChoices[i]) && valueStr.startsWith(prefix)).map((valueStr) => ({
 					kind: "literal",
 					text: valueStr
 				}));
 			}
 		};
 	}
-	const stringChoices = choices;
+	const stringChoices = Object.freeze([...new Set(choices)]);
 	const stringOptions = options;
-	const normalizedValues = stringOptions.caseInsensitive ? stringChoices.map((v) => v.toLowerCase()) : stringChoices;
+	if (stringOptions.caseInsensitive !== void 0 && typeof stringOptions.caseInsensitive !== "boolean") throw new TypeError(`Expected caseInsensitive to be a boolean, but got ${typeof stringOptions.caseInsensitive}: ${String(stringOptions.caseInsensitive)}.`);
+	const caseInsensitive = stringOptions.caseInsensitive ?? false;
+	const normalizedValues = caseInsensitive ? stringChoices.map((v) => v.toLowerCase()) : stringChoices;
+	if (caseInsensitive) {
+		const seen = /* @__PURE__ */ new Map();
+		for (let i = 0; i < stringChoices.length; i++) {
+			const nv = normalizedValues[i];
+			const original = stringChoices[i];
+			const prev = seen.get(nv);
+			if (prev !== void 0 && prev !== original) throw new TypeError(`Ambiguous choices for case-insensitive matching: ${JSON.stringify(prev)} and ${JSON.stringify(original)} both normalize to ${JSON.stringify(nv)}.`);
+			seen.set(nv, original);
+		}
+	}
+	const stringInvalidChoice = stringOptions.errors?.invalidChoice;
 	return {
 		$mode: "sync",
 		metavar,
-		choices,
+		choices: stringChoices,
 		parse(input) {
-			const normalizedInput = stringOptions.caseInsensitive ? input.toLowerCase() : input;
+			const normalizedInput = caseInsensitive ? input.toLowerCase() : input;
 			const index = normalizedValues.indexOf(normalizedInput);
 			if (index < 0) return {
 				success: false,
-				error: formatStringChoiceError(input, stringChoices, stringOptions)
+				error: formatStringChoiceError(input, stringChoices, stringInvalidChoice)
 			};
 			return {
 				success: true,
@@ -74,9 +147,9 @@ function choice(choices, options = {}) {
 			return String(value);
 		},
 		suggest(prefix) {
-			const normalizedPrefix = stringOptions.caseInsensitive ? prefix.toLowerCase() : prefix;
+			const normalizedPrefix = caseInsensitive ? prefix.toLowerCase() : prefix;
 			return stringChoices.filter((value) => {
-				const normalizedValue = stringOptions.caseInsensitive ? value.toLowerCase() : value;
+				const normalizedValue = caseInsensitive ? value.toLowerCase() : value;
 				return normalizedValue.startsWith(normalizedPrefix);
 			}).map((value) => ({
 				kind: "literal",
@@ -86,24 +159,73 @@ function choice(choices, options = {}) {
 	};
 }
 /**
+* Expands a numeric string in scientific notation (e.g., `"1e+21"`,
+* `"1.5e-3"`, `".1e-6"`) into plain decimal form for normalization.
+* Used for both canonical `String(number)` output and user input.
+* Returns the input unchanged if it does not contain scientific notation.
+*/
+function expandScientific(s) {
+	const match = /^([+-]?)(\d+\.?\d*|\.\d+)[eE]([+-]?\d+)$/.exec(s);
+	if (!match) return s;
+	const [, rawSign, mantissa, expStr] = match;
+	const sign = rawSign === "-" ? "-" : "";
+	const exp = parseInt(expStr, 10);
+	const dotPos = mantissa.indexOf(".");
+	const digits = mantissa.replace(".", "");
+	const intLen = dotPos >= 0 ? dotPos : digits.length;
+	const newIntLen = intLen + exp;
+	let result;
+	if (newIntLen >= digits.length) result = digits + "0".repeat(newIntLen - digits.length);
+	else if (newIntLen <= 0) result = "0." + "0".repeat(-newIntLen) + digits;
+	else result = digits.slice(0, newIntLen) + "." + digits.slice(newIntLen);
+	return sign + result;
+}
+/**
+* Normalizes a plain decimal string by stripping leading zeros from the
+* integer part and trailing zeros from the fractional part, so that two
+* strings representing the same mathematical value compare as equal.
+*/
+function normalizeDecimal(s) {
+	let sign = "";
+	let str = s;
+	if (str.startsWith("-") || str.startsWith("+")) {
+		if (str[0] === "-") sign = "-";
+		str = str.slice(1);
+	}
+	const dot = str.indexOf(".");
+	let int;
+	let frac;
+	if (dot >= 0) {
+		int = str.slice(0, dot);
+		frac = str.slice(dot + 1);
+	} else {
+		int = str;
+		frac = "";
+	}
+	int = int.replace(/^0+/, "") || "0";
+	frac = frac.replace(/0+$/, "");
+	return sign + (frac ? int + "." + frac : int);
+}
+/**
 * Formats error message for string choice parser.
 */
-function formatStringChoiceError(input, choices, options) {
-	if (options.errors?.invalidChoice) return typeof options.errors.invalidChoice === "function" ? options.errors.invalidChoice(input, choices) : options.errors.invalidChoice;
+function formatStringChoiceError(input, choices, invalidChoice) {
+	if (invalidChoice) return typeof invalidChoice === "function" ? invalidChoice(input, choices) : invalidChoice;
 	return formatDefaultChoiceError(input, choices);
 }
 /**
 * Formats error message for number choice parser.
 */
-function formatNumberChoiceError(input, choices, options) {
-	if (options.errors?.invalidChoice) return typeof options.errors.invalidChoice === "function" ? options.errors.invalidChoice(input, choices) : options.errors.invalidChoice;
-	return formatDefaultChoiceError(input, choices);
+function formatNumberChoiceError(input, validChoices, allChoices, invalidChoice) {
+	if (invalidChoice) return typeof invalidChoice === "function" ? invalidChoice(input, validChoices) : invalidChoice;
+	return formatDefaultChoiceError(input, allChoices);
 }
 /**
 * Formats default error message for choice parser.
 */
 function formatDefaultChoiceError(input, choices) {
-	const choiceStrings = choices.map((c) => String(c));
+	const choiceStrings = choices.filter((c) => typeof c === "string" || !Number.isNaN(c)).map((c) => Object.is(c, -0) ? "-0" : String(c));
+	if (choiceStrings.length === 0 && choices.length > 0) return message`No valid choices are configured, but got ${input}.`;
 	return message`Expected one of ${valueSet(choiceStrings, { locale: "en-US" })}, but got ${input}.`;
 }
 /**
@@ -119,18 +241,31 @@ function formatDefaultChoiceError(input, choices) {
 * @param options Configuration options for the string parser.
 * @returns A {@link ValueParser} that parses strings according to the
 *          specified options.
+* @throws {TypeError} If `options.pattern` is provided but is not a
+*         `RegExp` instance.
 */
 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 patternSource = options.pattern?.source ?? null;
+	const patternFlags = options.pattern?.flags ?? null;
+	const patternMismatch = options.errors?.patternMismatch;
 	return {
 		$mode: "sync",
 		metavar,
 		parse(input) {
-			if (options.pattern != null && !options.pattern.test(input)) return {
-				success: false,
-				error: options.errors?.patternMismatch ? typeof options.errors.patternMismatch === "function" ? options.errors.patternMismatch(input, options.pattern) : options.errors.patternMismatch : message`Expected a string matching pattern ${text(options.pattern.source)}, but got ${input}.`
-			};
+			if (patternSource != null && patternFlags != null) {
+				const pattern = new RegExp(patternSource, patternFlags);
+				if (pattern.test(input)) return {
+					success: true,
+					value: input
+				};
+				return {
+					success: false,
+					error: patternMismatch ? typeof patternMismatch === "function" ? patternMismatch(input, pattern) : patternMismatch : message`Expected a string matching pattern ${text(patternSource)}, but got ${input}.`
+				};
+			}
 			return {
 				success: true,
 				value: input
@@ -173,8 +308,16 @@ function string(options = {}) {
 * @param options Configuration options specifying the type and constraints.
 * @returns A {@link ValueParser} that converts string input to the specified
 *          integer type.
+* @throws {TypeError} If `options.type` is provided but is neither `"number"`
+*   nor `"bigint"`.
 */
 function integer(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)}.`);
+	if (options?.type !== "bigint") {
+		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}`);
+	}
+	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);
@@ -182,16 +325,11 @@ function integer(options) {
 			$mode: "sync",
 			metavar: metavar$1,
 			parse(input) {
-				let value;
-				try {
-					value = BigInt(input);
-				} catch (e) {
-					if (e instanceof SyntaxError) return {
-						success: false,
-						error: options.errors?.invalidInteger ? typeof options.errors.invalidInteger === "function" ? options.errors.invalidInteger(input) : options.errors.invalidInteger : message`Expected a valid integer, but got ${input}.`
-					};
-					throw e;
-				}
+				if (!input.match(/^-?\d+$/)) return {
+					success: false,
+					error: options.errors?.invalidInteger ? typeof options.errors.invalidInteger === "function" ? options.errors.invalidInteger(input) : options.errors.invalidInteger : message`Expected a valid integer, but got ${input}.`
+				};
+				const value = BigInt(input);
 				if (options.min != null && value < options.min) return {
 					success: false,
 					error: options.errors?.belowMinimum ? typeof options.errors.belowMinimum === "function" ? options.errors.belowMinimum(value, options.min) : options.errors.belowMinimum : message`Expected a value greater than or equal to ${text(options.min.toLocaleString("en"))}, but got ${input}.`
@@ -212,6 +350,15 @@ function integer(options) {
 	}
 	const metavar = options?.metavar ?? "INTEGER";
 	ensureNonEmptyString(metavar);
+	const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+	const minSafe = BigInt(Number.MIN_SAFE_INTEGER);
+	const unsafeIntegerError = options?.errors?.unsafeInteger;
+	function makeUnsafeIntegerError(input) {
+		return {
+			success: false,
+			error: unsafeIntegerError ? typeof unsafeIntegerError === "function" ? unsafeIntegerError(input) : unsafeIntegerError : message`Expected a safe integer between ${text(Number.MIN_SAFE_INTEGER.toLocaleString("en"))} and ${text(Number.MAX_SAFE_INTEGER.toLocaleString("en"))}, but got ${input}. Use type: "bigint" for large values.`
+		};
+	}
 	return {
 		$mode: "sync",
 		metavar,
@@ -220,7 +367,14 @@ function integer(options) {
 				success: false,
 				error: options?.errors?.invalidInteger ? typeof options.errors.invalidInteger === "function" ? options.errors.invalidInteger(input) : options.errors.invalidInteger : message`Expected a valid integer, but got ${input}.`
 			};
-			const value = Number.parseInt(input);
+			let n;
+			try {
+				n = BigInt(input);
+			} catch {
+				return makeUnsafeIntegerError(input);
+			}
+			if (n > maxSafe || n < minSafe) return makeUnsafeIntegerError(input);
+			const value = Number(input);
 			if (options?.min != null && value < options.min) return {
 				success: false,
 				error: options.errors?.belowMinimum ? typeof options.errors.belowMinimum === "function" ? options.errors.belowMinimum(value, options.min) : options.errors.belowMinimum : message`Expected a value greater than or equal to ${text(options.min.toLocaleString("en"))}, but got ${input}.`
@@ -249,6 +403,9 @@ function integer(options) {
 *          numbers.
 */
 function float(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}`);
+	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);
@@ -256,6 +413,10 @@ function float(options = {}) {
 		$mode: "sync",
 		metavar,
 		parse(input) {
+			const invalidNumber = (i) => ({
+				success: false,
+				error: options.errors?.invalidNumber ? typeof options.errors.invalidNumber === "function" ? options.errors.invalidNumber(i) : options.errors.invalidNumber : message`Expected a valid number, but got ${i}.`
+			});
 			let value;
 			const lowerInput = input.toLowerCase();
 			if (lowerInput === "nan" && options.allowNaN) value = NaN;
@@ -263,14 +424,9 @@ function float(options = {}) {
 			else if (lowerInput === "-infinity" && options.allowInfinity) value = -Infinity;
 			else if (floatRegex.test(input)) {
 				value = Number(input);
-				if (Number.isNaN(value)) return {
-					success: false,
-					error: options.errors?.invalidNumber ? typeof options.errors.invalidNumber === "function" ? options.errors.invalidNumber(input) : options.errors.invalidNumber : message`Expected a valid number, but got ${input}.`
-				};
-			} else return {
-				success: false,
-				error: options.errors?.invalidNumber ? typeof options.errors.invalidNumber === "function" ? options.errors.invalidNumber(input) : options.errors.invalidNumber : message`Expected a valid number, but got ${input}.`
-			};
+				if (!Number.isFinite(value) && !options.allowInfinity) return invalidNumber(input);
+				if (Number.isNaN(value)) return invalidNumber(input);
+			} else return invalidNumber(input);
 			if (options.min != null && value < options.min) return {
 				success: false,
 				error: options.errors?.belowMinimum ? typeof options.errors.belowMinimum === "function" ? options.errors.belowMinimum(value, options.min) : options.errors.belowMinimum : message`Expected a value greater than or equal to ${text(options.min.toLocaleString("en"))}, but got ${input}.`
@@ -299,21 +455,24 @@ function float(options = {}) {
 * @returns A {@link ValueParser} that converts string input to `URL` objects.
 */
 function url(options = {}) {
-	const allowedProtocols = options.allowedProtocols?.map((p) => p.toLowerCase());
+	const originalProtocols = options.allowedProtocols != null ? Object.freeze([...options.allowedProtocols]) : void 0;
+	const allowedProtocols = options.allowedProtocols != null ? Object.freeze(options.allowedProtocols.map((p) => p.toLowerCase())) : void 0;
 	const metavar = options.metavar ?? "URL";
 	ensureNonEmptyString(metavar);
+	const invalidUrl = options.errors?.invalidUrl;
+	const disallowedProtocol = options.errors?.disallowedProtocol;
 	return {
 		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (!URL.canParse(input)) return {
 				success: false,
-				error: options.errors?.invalidUrl ? typeof options.errors.invalidUrl === "function" ? options.errors.invalidUrl(input) : options.errors.invalidUrl : message`Invalid URL: ${input}.`
+				error: invalidUrl ? typeof invalidUrl === "function" ? invalidUrl(input) : invalidUrl : message`Invalid URL: ${input}.`
 			};
 			const url$1 = new URL(input);
 			if (allowedProtocols != null && !allowedProtocols.includes(url$1.protocol)) return {
 				success: false,
-				error: options.errors?.disallowedProtocol ? typeof options.errors.disallowedProtocol === "function" ? options.errors.disallowedProtocol(url$1.protocol, options.allowedProtocols) : options.errors.disallowedProtocol : message`URL protocol ${url$1.protocol} is not allowed. Allowed protocols: ${allowedProtocols.join(", ")}.`
+				error: disallowedProtocol ? typeof disallowedProtocol === "function" ? disallowedProtocol(url$1.protocol, originalProtocols) : disallowedProtocol : message`URL protocol ${url$1.protocol} is not allowed. Allowed protocols: ${allowedProtocols.join(", ")}.`
 			};
 			return {
 				success: true,
@@ -367,7 +526,7 @@ function locale(options = {}) {
 			};
 		},
 		format(value) {
-			return value.baseName;
+			return value.toString();
 		},
 		*suggest(prefix) {
 			const commonLocales = [
@@ -617,24 +776,27 @@ 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 allowedVersions = options.allowedVersions != null ? Object.freeze([...options.allowedVersions]) : null;
+	const invalidUuid = options.errors?.invalidUuid;
+	const disallowedVersion = options.errors?.disallowedVersion;
 	return {
 		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (!uuidRegex.test(input)) return {
 				success: false,
-				error: options.errors?.invalidUuid ? typeof options.errors.invalidUuid === "function" ? options.errors.invalidUuid(input) : options.errors.invalidUuid : message`Expected a valid UUID in format ${"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}, but got ${input}.`
+				error: invalidUuid ? typeof invalidUuid === "function" ? invalidUuid(input) : invalidUuid : message`Expected a valid UUID in format ${"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}, but got ${input}.`
 			};
-			if (options.allowedVersions != null && options.allowedVersions.length > 0) {
+			if (allowedVersions != null && allowedVersions.length > 0) {
 				const versionChar = input.charAt(14);
 				const version = parseInt(versionChar, 16);
-				if (!options.allowedVersions.includes(version)) return {
+				if (!allowedVersions.includes(version)) return {
 					success: false,
-					error: options.errors?.disallowedVersion ? typeof options.errors.disallowedVersion === "function" ? options.errors.disallowedVersion(version, options.allowedVersions) : options.errors.disallowedVersion : (() => {
+					error: disallowedVersion ? typeof disallowedVersion === "function" ? disallowedVersion(version, allowedVersions) : disallowedVersion : (() => {
 						let expectedVersions = message``;
 						let i = 0;
-						for (const v of options.allowedVersions) {
-							expectedVersions = i < 1 ? message`${expectedVersions}${v.toLocaleString("en")}` : i + 1 >= options.allowedVersions.length ? message`${expectedVersions}, or ${v.toLocaleString("en")}` : message`${expectedVersions}, ${v.toLocaleString("en")}`;
+						for (const v of allowedVersions) {
+							expectedVersions = i < 1 ? message`${expectedVersions}${v.toLocaleString("en")}` : i + 1 >= allowedVersions.length ? message`${expectedVersions}, or ${v.toLocaleString("en")}` : message`${expectedVersions}, ${v.toLocaleString("en")}`;
 							i++;
 						}
 						return message`Expected UUID version ${expectedVersions}, but got version ${version.toLocaleString("en")}.`;
@@ -686,28 +848,28 @@ function uuid(options = {}) {
 *
 * @param options Configuration options specifying the type and constraints.
 * @returns A {@link ValueParser} that converts string input to port numbers.
+* @throws {TypeError} If `options.type` is provided but is neither `"number"`
+*   nor `"bigint"`.
 * @since 0.10.0
 */
 function port(options) {
+	if (options?.disallowWellKnown !== void 0 && typeof options.disallowWellKnown !== "boolean") throw new TypeError(`Expected disallowWellKnown to be a boolean, but got ${typeof options.disallowWellKnown}: ${String(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 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}.`);
 		return {
 			$mode: "sync",
 			metavar: metavar$1,
 			parse(input) {
-				let value;
-				try {
-					value = BigInt(input);
-				} catch (e) {
-					if (e instanceof SyntaxError) return {
-						success: false,
-						error: options.errors?.invalidPort ? typeof options.errors.invalidPort === "function" ? options.errors.invalidPort(input) : options.errors.invalidPort : message`Expected a valid port number, but got ${input}.`
-					};
-					throw e;
-				}
+				if (!input.match(/^-?\d+$/)) return {
+					success: false,
+					error: options.errors?.invalidPort ? typeof options.errors.invalidPort === "function" ? options.errors.invalidPort(input) : options.errors.invalidPort : message`Expected a valid port number, but got ${input}.`
+				};
+				const value = BigInt(input);
 				if (value < min$1) return {
 					success: false,
 					error: options.errors?.belowMinimum ? typeof options.errors.belowMinimum === "function" ? options.errors.belowMinimum(value, min$1) : options.errors.belowMinimum : message`Expected a port number greater than or equal to ${text(min$1.toLocaleString("en"))}, but got ${input}.`
@@ -730,10 +892,13 @@ 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 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}.`);
 	return {
 		$mode: "sync",
 		metavar,
@@ -948,6 +1113,7 @@ function ipv4(options) {
 *
 * @param options - Options for hostname validation.
 * @returns A value parser for hostnames.
+* @throws {RangeError} If `maxLength` is not a positive integer.
 * @since 0.10.0
 *
 * @example
@@ -971,6 +1137,7 @@ function hostname(options) {
 	const allowUnderscore = options?.allowUnderscore ?? false;
 	const allowLocalhost = options?.allowLocalhost ?? true;
 	const maxLength = options?.maxLength ?? 253;
+	if (!Number.isInteger(maxLength) || maxLength < 1) throw new RangeError("maxLength must be an integer greater than or equal to 1.");
 	return {
 		$mode: "sync",
 		metavar,
@@ -1079,14 +1246,28 @@ function email(options) {
 	const allowMultiple = options?.allowMultiple ?? false;
 	const allowDisplayName = options?.allowDisplayName ?? false;
 	const lowercase = options?.lowercase ?? false;
-	const allowedDomains = options?.allowedDomains;
+	const allowedDomains = options?.allowedDomains != null ? Object.freeze([...options.allowedDomains]) : void 0;
+	if (allowedDomains != null) for (let i = 0; i < allowedDomains.length; i++) {
+		const entry = allowedDomains[i];
+		if (typeof entry !== "string") throw new TypeError(`allowedDomains[${i}] must be a string, got ${typeof entry}.`);
+		if (entry !== entry.trim()) throw new TypeError(`allowedDomains[${i}] must not have leading or trailing whitespace: ${JSON.stringify(entry)}`);
+		if (entry.startsWith("@")) throw new TypeError(`allowedDomains[${i}] must not start with "@": ${JSON.stringify(entry)}`);
+		if (entry === "" || !entry.includes(".")) throw new TypeError(`allowedDomains[${i}] is not a valid domain: ${JSON.stringify(entry)}`);
+		if (entry.startsWith(".") || entry.endsWith(".") || entry.startsWith("-") || entry.endsWith("-")) throw new TypeError(`allowedDomains[${i}] is not a valid domain: ${JSON.stringify(entry)}`);
+		const labels = entry.split(".");
+		for (const label of labels) if (label.length === 0 || label.length > 63 || label.startsWith("-") || label.endsWith("-") || !/^[a-zA-Z0-9-]+$/.test(label)) throw new TypeError(`allowedDomains[${i}] is not a valid domain: ${JSON.stringify(entry)}`);
+		if (labels.length === 4 && labels.every((label) => /^[0-9]+$/.test(label))) throw new TypeError(`allowedDomains[${i}] is not a valid domain: ${JSON.stringify(entry)}`);
+	}
+	const invalidEmail = options?.errors?.invalidEmail;
+	const domainNotAllowed = options?.errors?.domainNotAllowed;
 	const atextRegex = /^[a-zA-Z0-9._+-]+$/;
+	const encoder = new TextEncoder();
 	function validateEmail(input) {
 		const trimmed = input.trim();
 		let emailAddr = trimmed;
-		if (allowDisplayName && trimmed.includes("<") && trimmed.endsWith(">")) {
-			const match = trimmed.match(/<([^>]+)>$/);
-			if (match) emailAddr = match[1].trim();
+		if (allowDisplayName) {
+			const displayNameMatch = trimmed.match(/^((?:"(?:[^"\\]|\\.)*"|[^<>"])+)\s*<([^<>]+)>$/);
+			if (displayNameMatch && /\S/.test(displayNameMatch[1].replace(/"((?:[^"\\]|\\.)*)"/g, (_match, inner) => inner))) emailAddr = displayNameMatch[2].trim();
 		}
 		let atIndex = -1;
 		if (emailAddr.startsWith("\"")) {
@@ -1108,6 +1289,7 @@ function email(options) {
 			isValidLocal = localParts.length > 0 && localParts.every((part) => part.length > 0 && atextRegex.test(part));
 		}
 		if (!isValidLocal) return null;
+		if (encoder.encode(localPart).length > 64) return null;
 		if (!domain$1 || domain$1.length === 0) return null;
 		if (!domain$1.includes(".")) return null;
 		if (domain$1.startsWith(".") || domain$1.endsWith(".") || domain$1.startsWith("-") || domain$1.endsWith("-")) return null;
@@ -1117,32 +1299,64 @@ function email(options) {
 			if (label.startsWith("-") || label.endsWith("-")) return null;
 			if (!/^[a-zA-Z0-9-]+$/.test(label)) return null;
 		}
+		if (domainLabels.length === 4 && domainLabels.every((label) => /^[0-9]+$/.test(label))) return null;
+		if (encoder.encode(emailAddr).length > 254) return null;
 		const resultEmail = emailAddr;
-		return lowercase ? resultEmail.toLowerCase() : resultEmail;
+		if (!lowercase) return resultEmail;
+		const lastAt = resultEmail.lastIndexOf("@");
+		return resultEmail.slice(0, lastAt) + resultEmail.slice(lastAt).toLowerCase();
+	}
+	/**
+	* Splits an input string on commas, respecting quoted segments and
+	* angle-bracket display-name syntax per RFC 5322.
+	*/
+	function splitEmails(input) {
+		const result = [];
+		let current = "";
+		let inQuotes = false;
+		let inAngleBrackets = false;
+		let escaped = false;
+		for (const char of input) {
+			if (escaped) escaped = false;
+			else if (char === "\\" && inQuotes) escaped = true;
+			else if (char === "\"" && !inAngleBrackets) {
+				if (inQuotes) inQuotes = false;
+				else if (current.trim() === "") inQuotes = true;
+			} else if (char === "<" && !inQuotes) inAngleBrackets = true;
+			else if (char === ">" && !inQuotes) inAngleBrackets = false;
+			else if (char === "," && !inQuotes && !inAngleBrackets) {
+				result.push(current);
+				current = "";
+				continue;
+			}
+			current += char;
+		}
+		result.push(current);
+		return result;
 	}
 	return {
 		$mode: "sync",
 		metavar,
 		parse(input) {
 			if (allowMultiple) {
-				const emails = input.split(",").map((e) => e.trim());
+				const emails = splitEmails(input).map((e) => e.trim());
 				const validatedEmails = [];
 				for (const email$1 of emails) {
 					const validated = validateEmail(email$1);
 					if (validated === null) {
-						const errorMsg = options?.errors?.invalidEmail;
+						const errorMsg = invalidEmail;
 						const msg = typeof errorMsg === "function" ? errorMsg(email$1) : errorMsg ?? message`Expected a valid email address, but got ${email$1}.`;
 						return {
 							success: false,
 							error: msg
 						};
 					}
-					if (allowedDomains && allowedDomains.length > 0) {
+					if (allowedDomains != null) {
 						const atIndex = validated.indexOf("@");
 						const domain$1 = validated.substring(atIndex + 1).toLowerCase();
 						const isAllowed = allowedDomains.some((allowed) => domain$1 === allowed.toLowerCase());
 						if (!isAllowed) {
-							const errorMsg = options?.errors?.domainNotAllowed;
+							const errorMsg = domainNotAllowed;
 							if (typeof errorMsg === "function") return {
 								success: false,
 								error: errorMsg(validated, allowedDomains)
@@ -1176,19 +1390,19 @@ function email(options) {
 			} else {
 				const validated = validateEmail(input);
 				if (validated === null) {
-					const errorMsg = options?.errors?.invalidEmail;
+					const errorMsg = invalidEmail;
 					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid email address, but got ${input}.`;
 					return {
 						success: false,
 						error: msg
 					};
 				}
-				if (allowedDomains && allowedDomains.length > 0) {
+				if (allowedDomains != null) {
 					const atIndex = validated.indexOf("@");
 					const domain$1 = validated.substring(atIndex + 1).toLowerCase();
 					const isAllowed = allowedDomains.some((allowed) => domain$1 === allowed.toLowerCase());
 					if (!isAllowed) {
-						const errorMsg = options?.errors?.domainNotAllowed;
+						const errorMsg = domainNotAllowed;
 						if (typeof errorMsg === "function") return {
 							success: false,
 							error: errorMsg(validated, allowedDomains)
@@ -1220,7 +1434,7 @@ function email(options) {
 			}
 		},
 		format(value) {
-			if (Array.isArray(value)) return value.join(",");
+			if (Array.isArray(value)) return value.join(", ");
 			return value;
 		}
 	};
@@ -1237,6 +1451,8 @@ function email(options) {
 *
 * @param options - Options for socket address validation.
 * @returns A value parser for socket addresses.
+* @throws {TypeError} If `separator` contains digit characters, since digits
+*   in the separator would cause ambiguous splitting of port input.
 * @since 0.10.0
 *
 * @example
@@ -1257,9 +1473,10 @@ function email(options) {
 * ```
 */
 function socketAddress(options) {
-	const metavar = options?.metavar ?? "HOST:PORT";
-	ensureNonEmptyString(metavar);
 	const separator = options?.separator ?? ":";
+	if (/\p{Nd}/u.test(separator)) throw new TypeError(`Expected separator to not contain digits, but got: ${JSON.stringify(separator)}.`);
+	const metavar = options?.metavar ?? `HOST${separator}PORT`;
+	ensureNonEmptyString(metavar);
 	const defaultPort = options?.defaultPort;
 	const requirePort = options?.requirePort ?? false;
 	const hostType = options?.host?.type ?? "both";
@@ -1361,9 +1578,13 @@ function socketAddress(options) {
 	};
 }
 function portRange(options) {
-	const metavar = options?.metavar ?? "PORT-PORT";
-	ensureNonEmptyString(metavar);
+	if (options?.disallowWellKnown !== void 0 && typeof options.disallowWellKnown !== "boolean") throw new TypeError(`Expected disallowWellKnown to be a boolean, but got ${typeof options.disallowWellKnown}: ${String(options.disallowWellKnown)}.`);
+	if (options?.allowSingle !== void 0 && typeof options.allowSingle !== "boolean") throw new TypeError(`Expected allowSingle to be a boolean, but got ${typeof options.allowSingle}: ${String(options.allowSingle)}.`);
+	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 separator = options?.separator ?? "-";
+	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 allowSingle = options?.allowSingle ?? false;
 	const isBigInt = options?.type === "bigint";
 	const portParser = isBigInt ? port({
@@ -1609,6 +1830,13 @@ function macAddress(options) {
 *
 * @param options Parser options for domain validation.
 * @returns A parser that accepts valid domain names as strings.
+* @throws {RangeError} If `maxLength` is not a positive integer.
+* @throws {RangeError} If `minLabels` is not a positive integer.
+* @throws {TypeError} If any `allowedTlds` entry is not a string, is empty,
+*   contains dots, has leading/trailing whitespace, or is not a valid DNS
+*   label.
+* @throws {TypeError} If `allowSubdomains` is `false` and `minLabels` is
+*   greater than 2, since non-subdomain domains have exactly 2 labels.
 *
 * @example
 * ``` typescript
@@ -1622,7 +1850,7 @@ function macAddress(options) {
 * option("--root", domain({ allowSubdomains: false }))
 *
 * // Restrict to specific TLDs
-* option("--domain", domain({ allowedTLDs: ["com", "org", "net"] }))
+* option("--domain", domain({ allowedTlds: ["com", "org", "net"] }))
 *
 * // Normalize to lowercase
 * option("--domain", domain({ lowercase: true }))
@@ -1633,17 +1861,44 @@ function macAddress(options) {
 function domain(options) {
 	const metavar = options?.metavar ?? "DOMAIN";
 	const allowSubdomains = options?.allowSubdomains ?? true;
-	const allowedTLDs = options?.allowedTLDs;
+	const allowedTlds = options?.allowedTlds != null ? Object.freeze([...options.allowedTlds]) : void 0;
+	const labelRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
+	if (allowedTlds !== void 0) for (const [i, tld] of allowedTlds.entries()) {
+		if (typeof tld !== "string") {
+			const actualType = Array.isArray(tld) ? "array" : typeof tld;
+			throw new TypeError(`allowedTlds[${i}] must be a string, but got ${actualType}.`);
+		}
+		if (tld.length === 0) throw new TypeError(`allowedTlds[${i}] must not be an empty string.`);
+		if (tld.includes(".")) throw new TypeError(`allowedTlds[${i}] must not contain dots: ${JSON.stringify(tld)}.`);
+		if (tld !== tld.trim()) throw new TypeError(`allowedTlds[${i}] must not have leading or trailing whitespace: ${JSON.stringify(tld)}.`);
+		if (!labelRegex.test(tld)) throw new TypeError(`allowedTlds[${i}] is not a valid DNS label: ${JSON.stringify(tld)}.`);
+	}
+	const allowedTldsLower = allowedTlds != null ? Object.freeze(allowedTlds.map((t) => t.toLowerCase())) : void 0;
 	const minLabels = options?.minLabels ?? 2;
+	const maxLength = options?.maxLength ?? 253;
 	const lowercase = options?.lowercase ?? false;
-	const errors = options?.errors;
-	const labelRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
+	if (!Number.isInteger(maxLength) || maxLength < 1) throw new RangeError("maxLength must be an integer greater than or equal to 1.");
+	if (!Number.isInteger(minLabels) || minLabels < 1) throw new RangeError("minLabels must be an integer greater than or equal to 1.");
+	if (!allowSubdomains && minLabels > 2) throw new TypeError("allowSubdomains: false is incompatible with minLabels > 2, as non-subdomain domains have exactly 2 labels.");
+	const invalidDomain = options?.errors?.invalidDomain;
+	const tooLong = options?.errors?.tooLong;
+	const tooFewLabels = options?.errors?.tooFewLabels;
+	const subdomainsNotAllowed = options?.errors?.subdomainsNotAllowed;
+	const tldNotAllowed = options?.errors?.tldNotAllowed;
 	return {
 		$mode: "sync",
 		metavar,
 		parse(input) {
+			if (input.length > maxLength) {
+				const errorMsg = tooLong;
+				const msg = typeof errorMsg === "function" ? errorMsg(input, maxLength) : errorMsg ?? message`Domain ${input} is too long (maximum ${text(maxLength.toString())} characters).`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
 			if (input.length === 0 || input.startsWith(".") || input.endsWith(".")) {
-				const errorMsg = errors?.invalidDomain;
+				const errorMsg = invalidDomain;
 				if (typeof errorMsg === "function") return {
 					success: false,
 					error: errorMsg(input)
@@ -1668,7 +1923,7 @@ function domain(options) {
 				};
 			}
 			if (input.includes("..")) {
-				const errorMsg = errors?.invalidDomain;
+				const errorMsg = invalidDomain;
 				if (typeof errorMsg === "function") return {
 					success: false,
 					error: errorMsg(input)
@@ -1694,7 +1949,32 @@ function domain(options) {
 			}
 			const labels = input.split(".");
 			for (const label of labels) if (!labelRegex.test(label)) {
-				const errorMsg = errors?.invalidDomain;
+				const errorMsg = invalidDomain;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(input)
+				};
+				const msg = errorMsg ?? [
+					{
+						type: "text",
+						text: "Expected a valid domain name, but got "
+					},
+					{
+						type: "value",
+						value: input
+					},
+					{
+						type: "text",
+						text: "."
+					}
+				];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (labels.length >= 2 && labels.every((l) => /^[0-9]+$/.test(l))) {
+				const errorMsg = invalidDomain;
 				if (typeof errorMsg === "function") return {
 					success: false,
 					error: errorMsg(input)
@@ -1719,7 +1999,7 @@ function domain(options) {
 				};
 			}
 			if (labels.length < minLabels) {
-				const errorMsg = errors?.tooFewLabels;
+				const errorMsg = tooFewLabels;
 				if (typeof errorMsg === "function") return {
 					success: false,
 					error: errorMsg(input, minLabels)
@@ -1744,7 +2024,7 @@ function domain(options) {
 				};
 			}
 			if (!allowSubdomains && labels.length > 2) {
-				const errorMsg = errors?.subdomainsNotAllowed;
+				const errorMsg = subdomainsNotAllowed;
 				if (typeof errorMsg === "function") return {
 					success: false,
 					error: errorMsg(input)
@@ -1768,15 +2048,14 @@ function domain(options) {
 					error: msg
 				};
 			}
-			if (allowedTLDs !== void 0) {
+			if (allowedTlds !== void 0 && allowedTldsLower !== void 0) {
 				const tld = labels[labels.length - 1];
 				const tldLower = tld.toLowerCase();
-				const allowedTLDsLower = allowedTLDs.map((t) => t.toLowerCase());
-				if (!allowedTLDsLower.includes(tldLower)) {
-					const errorMsg = errors?.tldNotAllowed;
+				if (!allowedTldsLower.includes(tldLower)) {
+					const errorMsg = tldNotAllowed;
 					if (typeof errorMsg === "function") return {
 						success: false,
-						error: errorMsg(tld, allowedTLDs)
+						error: errorMsg(tld, allowedTlds)
 					};
 					const msg = errorMsg ?? [
 						{
@@ -1789,7 +2068,7 @@ function domain(options) {
 						},
 						{
 							type: "text",
-							text: ` is not allowed. Allowed TLDs: ${allowedTLDs.join(", ")}.`
+							text: ` is not allowed. Allowed TLDs: ${allowedTlds.join(", ")}.`
 						}
 					];
 					return {
@@ -2237,7 +2516,13 @@ function ip(options) {
 * @since 0.10.0
 */
 function cidr(options) {
+	if (options?.minPrefix != null && !Number.isFinite(options.minPrefix)) throw new RangeError(`Expected minPrefix to be a finite number, but got: ${options.minPrefix}`);
+	if (options?.maxPrefix != null && !Number.isFinite(options.maxPrefix)) throw new RangeError(`Expected maxPrefix to be a finite number, but got: ${options.maxPrefix}`);
+	if (options?.minPrefix != null && options?.maxPrefix != null && options.minPrefix > options.maxPrefix) throw new RangeError(`Expected minPrefix to be less than or equal to maxPrefix, but got minPrefix: ${options.minPrefix} and maxPrefix: ${options.maxPrefix}.`);
 	const version = options?.version ?? "both";
+	const maxPrefixForVersion = version === 4 ? 32 : version === 6 ? 128 : 128;
+	if (options?.minPrefix != null && (options.minPrefix < 0 || options.minPrefix > maxPrefixForVersion)) throw new RangeError(`Expected minPrefix to be between 0 and ${maxPrefixForVersion} for IPv${version === "both" ? "4/6" : version}, but got minPrefix: ${options.minPrefix}.`);
+	if (options?.maxPrefix != null && (options.maxPrefix < 0 || options.maxPrefix > maxPrefixForVersion)) throw new RangeError(`Expected maxPrefix to be between 0 and ${maxPrefixForVersion} for IPv${version === "both" ? "4/6" : version}, but got maxPrefix: ${options.maxPrefix}.`);
 	const minPrefix = options?.minPrefix;
 	const maxPrefix = options?.maxPrefix;
 	const errors = options?.errors;