@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/valueparser.cjs

@@ -6,9 +6,18 @@ const require_nonempty = require('./nonempty.cjs');
 * A predicate function that checks if an object is a {@link ValueParser}.
 * @param object The object to check.
 * @return `true` if the object is a {@link ValueParser}, `false` otherwise.
+* @throws {TypeError} If the object looks like a value parser (has `mode`,
+*   `metavar`, `parse`, and `format`) but is missing the required
+*   `placeholder` property.
 */
 function isValueParser(object) {
-	return typeof object === "object" && object != null && "$mode" in object && (object.$mode === "sync" || object.$mode === "async") && "metavar" in object && typeof object.metavar === "string" && "parse" in object && typeof object.parse === "function" && "format" in object && typeof object.format === "function";
+	if (typeof object !== "object" || object == null || !("mode" in object) || object.mode !== "sync" && object.mode !== "async") return false;
+	const hasMetavar = "metavar" in object && typeof object.metavar === "string";
+	const hasParse = "parse" in object && typeof object.parse === "function";
+	const hasFormat = "format" in object && typeof object.format === "function";
+	const hasPlaceholder = "placeholder" in object;
+	if (hasMetavar && hasParse && hasFormat && !hasPlaceholder) throw new TypeError("Value parser is missing the required placeholder property. All value parsers must define a placeholder value.");
+	return hasMetavar && hasParse && hasFormat && hasPlaceholder;
 }
 /**
 * Implementation of the choice parser for both string and number types.
@@ -47,8 +56,9 @@ function choice(choices, options = {}) {
 		const numberStrings = numberChoices.map((v) => Object.is(v, -0) ? "-0" : String(v));
 		const frozenNumberChoices = Object.freeze(numberChoices);
 		return {
-			$mode: "sync",
+			mode: "sync",
 			metavar,
+			placeholder: choices[0],
 			choices: frozenNumberChoices,
 			parse(input) {
 				const index = numberStrings.indexOf(input);
@@ -113,7 +123,7 @@ function choice(choices, options = {}) {
 	}
 	const stringChoices = Object.freeze([...new Set(choices)]);
 	const stringOptions = options;
-	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)}.`);
+	checkBooleanOption(stringOptions, "caseInsensitive");
 	const caseInsensitive = stringOptions.caseInsensitive ?? false;
 	const normalizedValues = caseInsensitive ? stringChoices.map((v) => v.toLowerCase()) : stringChoices;
 	if (caseInsensitive) {
@@ -128,8 +138,9 @@ function choice(choices, options = {}) {
 	}
 	const stringInvalidChoice = stringOptions.errors?.invalidChoice;
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		placeholder: choices[0],
 		choices: stringChoices,
 		parse(input) {
 			const normalizedInput = caseInsensitive ? input.toLowerCase() : input;
@@ -159,6 +170,40 @@ function choice(choices, options = {}) {
 	};
 }
 /**
+* Validates that an option value, if present, is a boolean.
+* Throws a {@link TypeError} if the value is defined but not a boolean.
+*
+* @template T The type of the options object.
+* @param options The options object to check.
+* @param key The key of the option to validate.
+* @throws {TypeError} If the option value is defined but not a boolean.
+* @since 1.0.0
+*/
+function checkBooleanOption(options, key) {
+	const value = options?.[key];
+	if (value !== void 0 && typeof value !== "boolean") throw new TypeError(`Expected ${String(key)} to be a boolean, but got ${typeof value}: ${String(value)}.`);
+}
+/**
+* Validates that an option value, if present, is one of the allowed values.
+* Throws a {@link TypeError} if the value is defined but not in the allowed
+* list.
+*
+* @template T The type of the options object.
+* @param options The options object to check.
+* @param key The key of the option to validate.
+* @param allowed The list of allowed values.
+* @throws {TypeError} If the option value is defined but not in the allowed
+*   list.
+* @since 1.0.0
+*/
+function checkEnumOption(options, key, allowed) {
+	const value = options?.[key];
+	if (value !== void 0 && (typeof value !== "string" || !allowed.includes(value))) {
+		const rendered = typeof value === "string" ? JSON.stringify(value) : typeof value === "symbol" ? value.toString() : String(value);
+		throw new TypeError(`Expected ${String(key)} to be one of ${allowed.map((v) => JSON.stringify(v)).join(", ")}, but got ${typeof value}: ${rendered}.`);
+	}
+}
+/**
 * 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.
@@ -226,7 +271,10 @@ function formatNumberChoiceError(input, validChoices, allChoices, invalidChoice)
 function formatDefaultChoiceError(input, choices) {
 	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 require_message.message`No valid choices are configured, but got ${input}.`;
-	return require_message.message`Expected one of ${require_message.valueSet(choiceStrings, { locale: "en-US" })}, but got ${input}.`;
+	return require_message.message`Expected one of ${require_message.valueSet(choiceStrings, {
+		fallback: "",
+		locale: "en-US"
+	})}, but got ${input}.`;
 }
 /**
 * Creates a {@link ValueParser} for strings.
@@ -252,8 +300,9 @@ function string(options = {}) {
 	const patternFlags = options.pattern?.flags ?? null;
 	const patternMismatch = options.errors?.patternMismatch;
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		placeholder: options.placeholder ?? "",
 		parse(input) {
 			if (patternSource != null && patternFlags != null) {
 				const pattern = new RegExp(patternSource, patternFlags);
@@ -308,14 +357,25 @@ 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"`.
+* @throws {RangeError} If the configured min/max range for number mode contains
+*   no safe integers.
 */
 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";
 		require_nonempty.ensureNonEmptyString(metavar$1);
 		return {
-			$mode: "sync",
+			mode: "sync",
 			metavar: metavar$1,
+			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 {
 					success: false,
@@ -344,6 +404,11 @@ function integer(options) {
 	require_nonempty.ensureNonEmptyString(metavar);
 	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);
+	const safeMax = Math.min(options?.max ?? Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+	const firstAllowed = Math.ceil(safeMin);
+	const lastAllowed = Math.floor(safeMax);
+	if (firstAllowed > lastAllowed) throw new RangeError("The configured integer range contains no safe integers. Use type: \"bigint\" instead.");
 	const unsafeIntegerError = options?.errors?.unsafeInteger;
 	function makeUnsafeIntegerError(input) {
 		return {
@@ -352,8 +417,9 @@ function integer(options) {
 		};
 	}
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		placeholder: options?.placeholder ?? (firstAllowed > 0 ? firstAllowed : lastAllowed < 0 ? lastAllowed : 0),
 		parse(input) {
 			if (!input.match(/^-?\d+$/)) return {
 				success: false,
@@ -395,12 +461,16 @@ 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";
 	require_nonempty.ensureNonEmptyString(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		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) => ({
 				success: false,
@@ -435,6 +505,19 @@ function float(options = {}) {
 	};
 }
 /**
+* The set of URL schemes that are considered "special" by the WHATWG URL
+* Standard.  These schemes always use the `://` authority syntax.
+* Non-special schemes use only `:` (e.g., `mailto:`, `urn:`).
+*/
+const SPECIAL_URL_SCHEMES = new Set([
+	"ftp",
+	"file",
+	"http",
+	"https",
+	"ws",
+	"wss"
+]);
+/**
 * Creates a {@link ValueParser} for URL values.
 *
 * This parser validates that the input is a well-formed URL and optionally
@@ -442,17 +525,39 @@ function float(options = {}) {
 * object.
 * @param options Configuration options for the URL parser.
 * @returns A {@link ValueParser} that converts string input to `URL` objects.
+* @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+*   string ending with a colon (e.g., `"https:"`).
 */
 function url(options = {}) {
-	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 originalProtocolsList = [];
+	const normalizedProtocolsList = [];
+	if (options.allowedProtocols != null) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const protocol of options.allowedProtocols) {
+			if (typeof protocol !== "string" || !/^[a-z][a-z0-9+\-.]*:$/i.test(protocol)) {
+				const rendered = typeof protocol === "string" ? JSON.stringify(protocol) : String(protocol);
+				throw new TypeError(`Each allowed protocol must be a valid protocol ending with a colon (e.g., "https:"), got: ${rendered}.`);
+			}
+			const normalized = protocol.toLowerCase();
+			if (seen.has(normalized)) continue;
+			seen.add(normalized);
+			originalProtocolsList.push(protocol);
+			normalizedProtocolsList.push(normalized);
+		}
+		if (originalProtocolsList.length === 0) throw new TypeError("allowedProtocols must not be empty.");
+	}
+	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";
 	require_nonempty.ensureNonEmptyString(metavar);
 	const invalidUrl = options.errors?.invalidUrl;
 	const disallowedProtocol = options.errors?.disallowedProtocol;
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			return new URL(`${allowedProtocols?.[0] ?? "http:"}//0.invalid`);
+		},
 		parse(input) {
 			if (!URL.canParse(input)) return {
 				success: false,
@@ -461,7 +566,28 @@ function url(options = {}) {
 			const url$1 = new URL(input);
 			if (allowedProtocols != null && !allowedProtocols.includes(url$1.protocol)) return {
 				success: false,
-				error: disallowedProtocol ? typeof disallowedProtocol === "function" ? disallowedProtocol(url$1.protocol, originalProtocols) : disallowedProtocol : require_message.message`URL protocol ${url$1.protocol} is not allowed. Allowed protocols: ${allowedProtocols.join(", ")}.`
+				error: disallowedProtocol ? typeof disallowedProtocol === "function" ? disallowedProtocol(url$1.protocol, originalProtocols) : disallowedProtocol : [
+					{
+						type: "text",
+						text: "URL protocol "
+					},
+					{
+						type: "value",
+						value: url$1.protocol
+					},
+					{
+						type: "text",
+						text: " is not allowed. Allowed protocols: "
+					},
+					...require_message.valueSet(originalProtocols, {
+						fallback: "",
+						locale: "en-US"
+					}),
+					{
+						type: "text",
+						text: "."
+					}
+				]
 			};
 			return {
 				success: true,
@@ -472,12 +598,15 @@ function url(options = {}) {
 			return value.href;
 		},
 		*suggest(prefix) {
-			if (allowedProtocols && prefix.length > 0 && !prefix.includes("://")) for (const protocol of allowedProtocols) {
+			if (allowedProtocols && prefix.length > 0 && !prefix.includes(":")) for (const protocol of allowedProtocols) {
 				const cleanProtocol = protocol.replace(/:+$/, "");
-				if (cleanProtocol.startsWith(prefix.toLowerCase())) yield {
-					kind: "literal",
-					text: `${cleanProtocol}://`
-				};
+				if (cleanProtocol.startsWith(prefix.toLowerCase())) {
+					const suffix = SPECIAL_URL_SCHEMES.has(cleanProtocol) ? "://" : ":";
+					yield {
+						kind: "literal",
+						text: `${cleanProtocol}${suffix}`
+					};
+				}
 			}
 		}
 	};
@@ -496,8 +625,9 @@ function locale(options = {}) {
 	const metavar = options.metavar ?? "LOCALE";
 	require_nonempty.ensureNonEmptyString(metavar);
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		placeholder: new Intl.Locale("und"),
 		parse(input) {
 			let locale$1;
 			try {
@@ -754,31 +884,59 @@ function locale(options = {}) {
 *
 * This parser validates that the input is a well-formed UUID string in the
 * standard format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where each `x`
-* is a hexadecimal digit.  The parser can optionally restrict to specific
-* UUID versions.
+* is a hexadecimal digit.
 *
+* By default, the parser enforces strict [RFC 9562] validation: it requires
+* a standardized version digit (1 through 8) and the RFC 9562 variant bits
+* (`10xx`).  The nil and max UUIDs are accepted as special standard values.
+* Set `strict: false` to disable the default RFC 9562 version/variant
+* checks.  An explicit {@link UuidOptions.allowedVersions} list still
+* constrains the version nibble even in lenient mode.
+*
+* [RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562
 * @param options Configuration options for the UUID parser.
 * @returns A {@link ValueParser} that converts string input to {@link Uuid}
 *          strings.
+* @throws {TypeError} If any element of
+*   {@link UuidOptions.allowedVersions} is not an integer.
+* @throws {RangeError} If any element of
+*   {@link UuidOptions.allowedVersions} is outside the range 1 to 8.
 */
 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";
 	require_nonempty.ensureNonEmptyString(metavar);
-	const allowedVersions = options.allowedVersions != null ? Object.freeze([...options.allowedVersions]) : null;
+	checkBooleanOption(options, "strict");
+	const strict = options.strict !== false;
+	const allowedVersions = options.allowedVersions != null ? (() => {
+		const unique = /* @__PURE__ */ new Set();
+		for (const v of options.allowedVersions) {
+			if (!Number.isInteger(v)) throw new TypeError(`Expected every element of allowedVersions to be an integer, but got value "${typeof v === "symbol" ? v.toString() : String(v)}" of type "${Array.isArray(v) ? "array" : v === null ? "null" : typeof v}".`);
+			if (v < 1 || v > 8) throw new RangeError(`Expected every element of allowedVersions to be between 1 and 8, but got: ${v}.`);
+			unique.add(v);
+		}
+		return Object.freeze([...unique]);
+	})() : null;
 	const invalidUuid = options.errors?.invalidUuid;
 	const disallowedVersion = options.errors?.disallowedVersion;
+	const invalidVariant = options.errors?.invalidVariant;
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		placeholder: "00000000-0000-0000-0000-000000000000",
 		parse(input) {
 			if (!uuidRegex.test(input)) return {
 				success: false,
 				error: invalidUuid ? typeof invalidUuid === "function" ? invalidUuid(input) : invalidUuid : require_message.message`Expected a valid UUID in format ${"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}, but got ${input}.`
 			};
+			const lower = input.toLowerCase();
+			if (lower === "00000000-0000-0000-0000-000000000000" || lower === "ffffffff-ffff-ffff-ffff-ffffffffffff") return {
+				success: true,
+				value: input
+			};
+			const versionChar = input.charAt(14);
+			const version = parseInt(versionChar, 16);
 			if (allowedVersions != null && allowedVersions.length > 0) {
-				const versionChar = input.charAt(14);
-				const version = parseInt(versionChar, 16);
 				if (!allowedVersions.includes(version)) return {
 					success: false,
 					error: disallowedVersion ? typeof disallowedVersion === "function" ? disallowedVersion(version, allowedVersions) : disallowedVersion : (() => {
@@ -791,6 +949,25 @@ function uuid(options = {}) {
 						return require_message.message`Expected UUID version ${expectedVersions}, but got version ${version.toLocaleString("en")}.`;
 					})()
 				};
+			} else if (strict && (version < 1 || version > 8)) return {
+				success: false,
+				error: disallowedVersion ? typeof disallowedVersion === "function" ? disallowedVersion(version, [
+					1,
+					2,
+					3,
+					4,
+					5,
+					6,
+					7,
+					8
+				]) : disallowedVersion : require_message.message`Expected UUID version 1 through 8, but got version ${version.toLocaleString("en")}.`
+			};
+			if (strict) {
+				const variantChar = input.charAt(19).toLowerCase();
+				if (variantChar !== "8" && variantChar !== "9" && variantChar !== "a" && variantChar !== "b") return {
+					success: false,
+					error: invalidVariant ? typeof invalidVariant === "function" ? invalidVariant(input) : invalidVariant : require_message.message`Expected RFC 9562 variant (8, 9, a, or b at position 20), but got ${variantChar} in ${input}.`
+				};
 			}
 			return {
 				success: true,
@@ -837,18 +1014,24 @@ 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)}.`);
+	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";
 		require_nonempty.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}.`);
+		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",
+			mode: "sync",
 			metavar: metavar$1,
+			placeholder: options.placeholder ?? (options.disallowWellKnown && min$1 < 1024n ? 1024n > min$1 ? 1024n : min$1 : min$1),
 			parse(input) {
 				if (!input.match(/^-?\d+$/)) return {
 					success: false,
@@ -877,13 +1060,18 @@ 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";
 	require_nonempty.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}.`);
+	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",
+		mode: "sync",
 		metavar,
+		placeholder: options?.placeholder ?? (options?.disallowWellKnown && min < 1024 ? Math.max(1024, min) : min),
 		parse(input) {
 			if (!input.match(/^-?\d+$/)) return {
 				success: false,
@@ -975,11 +1163,12 @@ function ipv4(options) {
 	const allowBroadcast = options?.allowBroadcast ?? true;
 	const allowZero = options?.allowZero ?? true;
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		placeholder: allowZero ? "0.0.0.0" : allowLoopback ? "127.0.0.1" : "192.0.2.1",
 		parse(input) {
-			const parts = input.split(".");
-			if (parts.length !== 4) {
+			const octets = parseIpv4Octets(input);
+			if (octets === null) {
 				const errorMsg = options?.errors?.invalidIpv4;
 				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
 				return {
@@ -987,43 +1176,6 @@ function ipv4(options) {
 					error: msg
 				};
 			}
-			const octets = [];
-			for (const part of parts) {
-				if (part.length === 0) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (part.trim() !== part) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				if (part.length > 1 && part[0] === "0") {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				const octet = Number(part);
-				if (!Number.isInteger(octet) || octet < 0 || octet > 255) {
-					const errorMsg = options?.errors?.invalidIpv4;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid IPv4 address, but got ${input}.`;
-					return {
-						success: false,
-						error: msg
-					};
-				}
-				octets.push(octet);
-			}
 			const ipAddress = octets.join(".");
 			if (!allowPrivate && isPrivateIp(octets)) {
 				const errorMsg = options?.errors?.privateNotAllowed;
@@ -1092,9 +1244,14 @@ function ipv4(options) {
 * - Labels can contain alphanumeric characters and hyphens
 * - Labels cannot start or end with a hyphen
 * - Total length ≤ 253 characters (default)
+* - Dotted all-numeric strings (e.g., `192.168.0.1`) are rejected as they
+*   resemble IPv4 addresses rather than DNS hostnames
 *
 * @param options - Options for hostname validation.
 * @returns A value parser for hostnames.
+* @throws {TypeError} If `allowWildcard`, `allowUnderscore`, or
+*   `allowLocalhost` is not a boolean.
+* @throws {RangeError} If `maxLength` is not a positive integer.
 * @since 0.10.0
 *
 * @example
@@ -1114,13 +1271,18 @@ function ipv4(options) {
 function hostname(options) {
 	const metavar = options?.metavar ?? "HOST";
 	require_nonempty.ensureNonEmptyString(metavar);
+	checkBooleanOption(options, "allowWildcard");
+	checkBooleanOption(options, "allowUnderscore");
+	checkBooleanOption(options, "allowLocalhost");
 	const allowWildcard = options?.allowWildcard ?? false;
 	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",
+		mode: "sync",
 		metavar,
+		placeholder: options?.placeholder ?? (allowLocalhost ? maxLength >= 9 ? "localhost" : "a.bc" : maxLength >= 11 ? "example.com" : "a.bc"),
 		parse(input) {
 			if (input.length > maxLength) {
 				const errorMsg = options?.errors?.tooLong;
@@ -1130,7 +1292,7 @@ function hostname(options) {
 					error: msg
 				};
 			}
-			if (!allowLocalhost && input === "localhost") {
+			if (!allowLocalhost && input.toLowerCase() === "localhost") {
 				const errorMsg = options?.errors?.localhostNotAllowed;
 				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Hostname 'localhost' is not allowed.`;
 				return {
@@ -1156,6 +1318,14 @@ function hostname(options) {
 						error: msg
 					};
 				}
+				if (!allowLocalhost && rest.toLowerCase() === "localhost") {
+					const errorMsg = options?.errors?.localhostNotAllowed;
+					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Hostname 'localhost' is not allowed.`;
+					return {
+						success: false,
+						error: msg
+					};
+				}
 			}
 			if (!allowUnderscore && input.includes("_")) {
 				const errorMsg = options?.errors?.underscoreNotAllowed;
@@ -1191,7 +1361,7 @@ function hostname(options) {
 						error: msg
 					};
 				}
-				if (label === "*") continue;
+				if (label === "*" && allowWildcard && input.startsWith("*.") && label === labels[0]) continue;
 				if (label.startsWith("-") || label.endsWith("-")) {
 					const errorMsg = options?.errors?.invalidHostname;
 					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid hostname, but got ${input}.`;
@@ -1210,6 +1380,14 @@ function hostname(options) {
 					};
 				}
 			}
+			if (labels.length >= 2 && labels.every((l) => /^[0-9]+$/.test(l))) {
+				const errorMsg = options?.errors?.invalidHostname;
+				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a valid hostname, but got ${input}.`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
 			return {
 				success: true,
 				value: input
@@ -1224,18 +1402,37 @@ function email(options) {
 	const metavar = options?.metavar ?? "EMAIL";
 	require_nonempty.ensureNonEmptyString(metavar);
 	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.");
+		if (!allowMultiple && typeof options.placeholder !== "string") throw new TypeError("email() placeholder must be a string when allowMultiple is false.");
+	}
 	const allowDisplayName = options?.allowDisplayName ?? false;
 	const lowercase = options?.lowercase ?? false;
 	const allowedDomains = options?.allowedDomains != null ? Object.freeze([...options.allowedDomains]) : void 0;
+	if (allowedDomains != null) {
+		if (allowedDomains.length === 0) throw new TypeError("allowedDomains must not be empty.");
+		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("\"")) {
@@ -1257,6 +1454,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;
@@ -1266,15 +1464,48 @@ 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",
+		mode: "sync",
 		metavar,
+		placeholder: options?.placeholder ?? (options?.allowMultiple ? [`user@${options?.allowedDomains?.[0] ?? "example.com"}`] : `user@${options?.allowedDomains?.[0] ?? "example.com"}`),
 		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);
@@ -1286,7 +1517,7 @@ function email(options) {
 							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());
@@ -1307,7 +1538,15 @@ function email(options) {
 								},
 								{
 									type: "text",
-									text: ` is not allowed. Allowed domains: ${allowedDomains.join(", ")}.`
+									text: " is not allowed. Allowed domains: "
+								},
+								...require_message.valueSet(allowedDomains, {
+									fallback: "",
+									locale: "en-US"
+								}),
+								{
+									type: "text",
+									text: "."
 								}
 							];
 							return {
@@ -1332,7 +1571,7 @@ function email(options) {
 						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());
@@ -1353,7 +1592,15 @@ function email(options) {
 							},
 							{
 								type: "text",
-								text: ` is not allowed. Allowed domains: ${allowedDomains.join(", ")}.`
+								text: " is not allowed. Allowed domains: "
+							},
+							...require_message.valueSet(allowedDomains, {
+								fallback: "",
+								locale: "en-US"
+							}),
+							{
+								type: "text",
+								text: "."
 							}
 						];
 						return {
@@ -1369,7 +1616,7 @@ function email(options) {
 			}
 		},
 		format(value) {
-			if (Array.isArray(value)) return value.join(",");
+			if (Array.isArray(value)) return value.join(", ");
 			return value;
 		}
 	};
@@ -1386,6 +1633,9 @@ function email(options) {
 *
 * @param options - Options for socket address validation.
 * @returns A value parser for socket addresses.
+* @throws {TypeError} If `separator` is an empty string.
+* @throws {TypeError} If `separator` contains digit characters, since digits
+*   in the separator would cause ambiguous splitting of port input.
 * @since 0.10.0
 *
 * @example
@@ -1406,9 +1656,12 @@ function email(options) {
 * ```
 */
 function socketAddress(options) {
-	const metavar = options?.metavar ?? "HOST:PORT";
-	require_nonempty.ensureNonEmptyString(metavar);
 	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 formatExample = `host${JSON.stringify(separator).slice(1, -1)}port`;
+	const metavar = options?.metavar ?? `HOST${separator}PORT`;
+	require_nonempty.ensureNonEmptyString(metavar);
 	const defaultPort = options?.defaultPort;
 	const requirePort = options?.requirePort ?? false;
 	const hostType = options?.host?.type ?? "both";
@@ -1420,88 +1673,274 @@ function socketAddress(options) {
 		...options?.host?.ip,
 		metavar: "HOST"
 	});
+	const disambiguationParser = hostType === "ip" ? hostname({
+		metavar: "HOST",
+		allowWildcard: true,
+		allowUnderscore: true,
+		maxLength: Math.max(253, options?.host?.hostname?.maxLength ?? 0)
+	}) : hostnameParser;
+	const separatorIsHostChar = /^[a-zA-Z0-9._-]+$/.test(separator);
 	const portParser = port({
 		...options?.port,
 		metavar: "PORT",
 		type: "number"
 	});
+	function looksLikeIpv4(input) {
+		return /^\d+\.\d+\.\d+\.\d+$/.test(input);
+	}
+	function looksLikeAltIpv4Literal(input) {
+		if (/^0[xX][0-9a-fA-F]+$/.test(input)) {
+			const n = parseInt(input.slice(2), 16);
+			return n <= 4294967295;
+		}
+		if (/^0[0-7]+$/.test(input)) {
+			const n = parseInt(input.slice(1), 8);
+			return n <= 4294967295;
+		}
+		const parts = input.split(".");
+		if (parts.length >= 2 && parts.length <= 4) {
+			const numericOrHex = /^(?:[0-9]+|0[xX][0-9a-fA-F]+)$/;
+			if (parts.every((p) => numericOrHex.test(p)) && parts.some((p) => /^0[xX]/i.test(p) || p.length > 1 && p[0] === "0")) {
+				const values = [];
+				for (const p of parts) if (/^0[xX]/i.test(p)) values.push(parseInt(p.slice(2), 16));
+				else if (p.length > 1 && p[0] === "0") {
+					if (/[89]/.test(p)) return false;
+					values.push(parseInt(p, 8));
+				} else values.push(Number(p));
+				const lastMax = 256 ** (5 - parts.length);
+				return values.slice(0, -1).every((v) => v <= 255) && values[values.length - 1] < lastMax;
+			}
+		}
+		return false;
+	}
 	function parseHost(hostInput) {
 		if (hostType === "hostname") {
-			const ipResult = ipParser.parse(hostInput);
-			if (ipResult.success) return null;
-			const result = hostnameParser.parse(hostInput);
-			return result.success ? result.value : null;
-		} else if (hostType === "ip") {
-			const result = ipParser.parse(hostInput);
-			return result.success ? result.value : null;
-		} else {
-			const ipResult = ipParser.parse(hostInput);
-			if (ipResult.success) return ipResult.value;
-			const hostnameResult = hostnameParser.parse(hostInput);
-			return hostnameResult.success ? hostnameResult.value : null;
+			if (looksLikeAltIpv4Literal(hostInput)) return {
+				success: false,
+				error: require_message.message`${hostInput} appears to be a non-standard IPv4 address notation.`
+			};
+			if (looksLikeIpv4(hostInput)) return {
+				success: false,
+				error: require_message.message`Expected a valid hostname, but got ${hostInput}.`
+			};
+			return hostnameParser.parse(hostInput);
+		} else if (hostType === "ip") return ipParser.parse(hostInput);
+		else {
+			if (looksLikeAltIpv4Literal(hostInput)) return {
+				success: false,
+				error: require_message.message`${hostInput} appears to be a non-standard IPv4 address notation.`
+			};
+			if (looksLikeIpv4(hostInput)) return ipParser.parse(hostInput);
+			return hostnameParser.parse(hostInput);
 		}
 	}
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			return {
+				host: hostType === "ip" ? ipParser.placeholder : hostnameParser.placeholder,
+				port: defaultPort ?? portParser.placeholder
+			};
+		},
 		parse(input) {
 			const trimmed = input.trim();
-			const separatorIndex = trimmed.lastIndexOf(separator);
-			let hostPart;
-			let portPart;
-			if (separatorIndex === -1) {
-				hostPart = trimmed;
-				portPart = void 0;
-			} else {
-				hostPart = trimmed.substring(0, separatorIndex);
-				portPart = trimmed.substring(separatorIndex + separator.length);
+			const searchInput = input.trimStart();
+			const canOmitPort = defaultPort !== void 0 && !requirePort;
+			let firstHostError;
+			let validHostInvalidPortError;
+			let trailingSepHost;
+			let trailingSepHostError;
+			let anySeparatorFound = false;
+			let trailingSepInTrimmedRegion = false;
+			let searchFrom = searchInput.length;
+			while (searchFrom > 0) {
+				const separatorIndex = searchInput.lastIndexOf(separator, searchFrom - 1);
+				if (separatorIndex === -1) break;
+				anySeparatorFound = true;
+				const hostPart = searchInput.substring(0, separatorIndex).trim();
+				const portPart = searchInput.substring(separatorIndex + separator.length).trim();
+				if (portPart === "") {
+					if (trailingSepHost === void 0 && trailingSepHostError === void 0) {
+						if (separatorIndex + separator.length > trimmed.length) trailingSepInTrimmedRegion = true;
+						const hostResult = parseHost(hostPart);
+						if (hostResult.success) trailingSepHost = hostResult.value;
+						else trailingSepHostError = {
+							hostPart,
+							error: hostResult.error
+						};
+					}
+				} else {
+					const portResult = portParser.parse(portPart);
+					if (portResult.success) {
+						const hostResult = parseHost(hostPart);
+						if (hostResult.success) return {
+							success: true,
+							value: {
+								host: hostResult.value,
+								port: portResult.value
+							}
+						};
+						if (firstHostError === void 0 || (looksLikeIpv4(hostPart) || looksLikeAltIpv4Literal(hostPart)) && !looksLikeIpv4(firstHostError.hostPart) && !looksLikeAltIpv4Literal(firstHostError.hostPart)) firstHostError = {
+							hostPart,
+							error: hostResult.error
+						};
+					} else if (validHostInvalidPortError === void 0 && hostPart !== "" && /^[0-9]+$/.test(portPart)) if (looksLikeIpv4(hostPart) || looksLikeAltIpv4Literal(hostPart)) {
+						const hostResult = parseHost(hostPart);
+						if (!hostResult.success) {
+							if (firstHostError === void 0 || !looksLikeIpv4(firstHostError.hostPart) && !looksLikeAltIpv4Literal(firstHostError.hostPart)) firstHostError = {
+								hostPart,
+								error: hostResult.error
+							};
+						} else validHostInvalidPortError = portResult.error;
+					} else {
+						validHostInvalidPortError = portResult.error;
+						const hostResult = parseHost(hostPart);
+						if (!hostResult.success && firstHostError === void 0) firstHostError = {
+							hostPart,
+							error: hostResult.error
+						};
+					}
+					else if ((firstHostError === void 0 || !looksLikeIpv4(firstHostError.hostPart) && !looksLikeAltIpv4Literal(firstHostError.hostPart)) && (looksLikeIpv4(hostPart) || looksLikeAltIpv4Literal(hostPart))) {
+						const hostResult = parseHost(hostPart);
+						if (!hostResult.success) firstHostError = {
+							hostPart,
+							error: hostResult.error
+						};
+					}
+				}
+				searchFrom = separatorIndex;
 			}
-			const validatedHost = parseHost(hostPart);
-			if (validatedHost === null) {
-				const errorMsg = options?.errors?.invalidFormat;
-				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a socket address in format host${separator}port, but got ${input}.`;
+			if (validHostInvalidPortError !== void 0) {
+				const errorMsg$1 = options?.errors?.invalidFormat;
+				if (errorMsg$1) {
+					const msg = typeof errorMsg$1 === "function" ? errorMsg$1(input) : errorMsg$1;
+					return {
+						success: false,
+						error: msg
+					};
+				}
+				if (firstHostError !== void 0 && firstHostError.hostPart !== "") {
+					const portSplitHostIsDegenerate = separatorIsHostChar ? firstHostError.hostPart.replaceAll(separator, "") === "" : firstHostError.hostPart.includes(separator);
+					if (portSplitHostIsDegenerate) return {
+						success: false,
+						error: require_message.message`Expected a socket address in format ${require_message.text(formatExample)}, but got ${input}.`
+					};
+					if (!disambiguationParser.parse(trimmed).success) return {
+						success: false,
+						error: firstHostError.error
+					};
+				}
+				if (disambiguationParser.parse(trimmed).success) return {
+					success: false,
+					error: require_message.message`Expected a socket address in format ${require_message.text(formatExample)}, but got ${input}.`
+				};
+				return {
+					success: false,
+					error: validHostInvalidPortError
+				};
+			}
+			if (firstHostError !== void 0) {
+				if (looksLikeIpv4(firstHostError.hostPart) || looksLikeAltIpv4Literal(firstHostError.hostPart)) {
+					const errorMsg$1 = options?.errors?.invalidFormat;
+					if (errorMsg$1) {
+						const msg = typeof errorMsg$1 === "function" ? errorMsg$1(input) : errorMsg$1;
+						return {
+							success: false,
+							error: msg
+						};
+					}
+					return {
+						success: false,
+						error: firstHostError.error
+					};
+				}
+			}
+			let hostOnlyResult;
+			if (!requirePort || trailingSepHost !== void 0 || trailingSepHostError !== void 0) {
+				hostOnlyResult = parseHost(trimmed);
+				if (canOmitPort && hostOnlyResult.success && !trailingSepInTrimmedRegion) return {
+					success: true,
+					value: {
+						host: hostOnlyResult.value,
+						port: defaultPort
+					}
+				};
+			}
+			if (trailingSepHost !== void 0 && hostOnlyResult !== void 0 && (!hostOnlyResult.success || trailingSepInTrimmedRegion)) {
+				const errorMsg$1 = options?.errors?.missingPort;
+				const msg = typeof errorMsg$1 === "function" ? errorMsg$1(input) : errorMsg$1 ?? require_message.message`Port number is required but was not specified.`;
 				return {
 					success: false,
 					error: msg
 				};
 			}
-			let validatedPort;
-			if (portPart === void 0 || portPart === "") {
-				if (requirePort) {
-					const errorMsg = options?.errors?.missingPort;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Port number is required but was not specified.`;
+			if (trailingSepHostError !== void 0 && hostOnlyResult !== void 0 && (!hostOnlyResult.success || trailingSepInTrimmedRegion)) {
+				const errorMsg$1 = options?.errors?.invalidFormat;
+				if (errorMsg$1) {
+					const msg = typeof errorMsg$1 === "function" ? errorMsg$1(input) : errorMsg$1;
 					return {
 						success: false,
 						error: msg
 					};
 				}
-				if (defaultPort !== void 0) validatedPort = defaultPort;
-				else {
-					const errorMsg = options?.errors?.missingPort;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Port number is required but was not specified.`;
+				const trailingHostIsDegenerate = separatorIsHostChar ? trailingSepHostError.hostPart.replaceAll(separator, "") === "" : trailingSepHostError.hostPart.includes(separator);
+				if (trailingSepHostError.hostPart !== "" && !trailingHostIsDegenerate && !disambiguationParser.parse(trimmed).success) return {
+					success: false,
+					error: trailingSepHostError.error
+				};
+			}
+			if (!canOmitPort && !requirePort && hostOnlyResult !== void 0 && hostOnlyResult.success) {
+				const errorMsg$1 = options?.errors?.missingPort;
+				const msg = typeof errorMsg$1 === "function" ? errorMsg$1(input) : errorMsg$1 ?? require_message.message`Port number is required but was not specified.`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (!canOmitPort && !anySeparatorFound) {
+				hostOnlyResult = hostOnlyResult ?? parseHost(trimmed);
+				if (hostOnlyResult.success) {
+					const errorMsg$1 = options?.errors?.missingPort;
+					const msg = typeof errorMsg$1 === "function" ? errorMsg$1(input) : errorMsg$1 ?? require_message.message`Port number is required but was not specified.`;
 					return {
 						success: false,
 						error: msg
 					};
 				}
-			} else {
-				const portResult = portParser.parse(portPart);
-				if (!portResult.success) {
-					const errorMsg = options?.errors?.invalidFormat;
-					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a socket address in format host${separator}port, but got ${input}.`;
+			}
+			if (firstHostError !== void 0) {
+				const errorMsg$1 = options?.errors?.invalidFormat;
+				if (errorMsg$1) {
+					const msg = typeof errorMsg$1 === "function" ? errorMsg$1(input) : errorMsg$1;
 					return {
 						success: false,
 						error: msg
 					};
 				}
-				validatedPort = portResult.value;
+				const hostPartIsDegenerate = separatorIsHostChar ? firstHostError.hostPart.replaceAll(separator, "") === "" : firstHostError.hostPart.includes(separator);
+				if (firstHostError.hostPart !== "" && !hostPartIsDegenerate && !disambiguationParser.parse(trimmed).success) return {
+					success: false,
+					error: firstHostError.error
+				};
+			}
+			const errorMsg = options?.errors?.invalidFormat;
+			if (errorMsg) {
+				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg;
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (hostOnlyResult !== void 0 && !hostOnlyResult.success) {
+				if (looksLikeIpv4(trimmed) || looksLikeAltIpv4Literal(trimmed)) return {
+					success: false,
+					error: hostOnlyResult.error
+				};
 			}
 			return {
-				success: true,
-				value: {
-					host: validatedHost,
-					port: validatedPort
-				}
+				success: false,
+				error: require_message.message`Expected a socket address in format ${require_message.text(formatExample)}, but got ${input}.`
 			};
 		},
 		format(value) {
@@ -1510,11 +1949,14 @@ function socketAddress(options) {
 	};
 }
 function portRange(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?.allowSingle !== void 0 && typeof options.allowSingle !== "boolean") throw new TypeError(`Expected allowSingle to be a boolean, but got ${typeof options.allowSingle}: ${String(options.allowSingle)}.`);
-	const metavar = options?.metavar ?? "PORT-PORT";
-	require_nonempty.ensureNonEmptyString(metavar);
+	checkBooleanOption(options, "disallowWellKnown");
+	checkBooleanOption(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 (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`;
+	require_nonempty.ensureNonEmptyString(metavar);
 	const allowSingle = options?.allowSingle ?? false;
 	const isBigInt = options?.type === "bigint";
 	const portParser = isBigInt ? port({
@@ -1531,8 +1973,17 @@ function portRange(options) {
 		errors: options?.errors
 	});
 	return {
-		$mode: "sync",
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			return isBigInt ? {
+				start: portParser.placeholder,
+				end: portParser.placeholder
+			} : {
+				start: portParser.placeholder,
+				end: portParser.placeholder
+			};
+		},
 		parse(input) {
 			const trimmed = input.trim();
 			const separatorIndex = trimmed.indexOf(separator);
@@ -1631,10 +2082,14 @@ function portRange(options) {
 * Creates a value parser for MAC (Media Access Control) addresses.
 *
 * Validates MAC-48 addresses (6 octets, 12 hex digits) in various formats:
-* - Colon-separated: `00:1A:2B:3C:4D:5E`
-* - Hyphen-separated: `00-1A-2B-3C-4D-5E`
-* - Dot-separated (Cisco): `001A.2B3C.4D5E`
-* - No separator: `001A2B3C4D5E`
+* - Colon-separated: `00:1A:2B:3C:4D:5E` (1–2 hex digits per octet)
+* - Hyphen-separated: `00-1A-2B-3C-4D-5E` (1–2 hex digits per octet)
+* - Dot-separated (Cisco): `001A.2B3C.4D5E` (exactly 4 hex digits per group)
+* - No separator: `001A2B3C4D5E` (exactly 12 hex digits)
+*
+* Colon-separated and hyphen-separated formats accept single-digit octets
+* (e.g., `0:1:2:3:4:5`), which are automatically zero-padded to canonical
+* two-digit form (e.g., `00:01:02:03:04:05`).
 *
 * Returns the MAC address as a formatted string according to `case` and
 * `outputSeparator` options.
@@ -1658,6 +2113,24 @@ function portRange(options) {
 * ```
 */
 function macAddress(options) {
+	checkEnumOption(options, "separator", [
+		":",
+		"-",
+		".",
+		"none",
+		"any"
+	]);
+	checkEnumOption(options, "outputSeparator", [
+		":",
+		"-",
+		".",
+		"none"
+	]);
+	checkEnumOption(options, "case", [
+		"preserve",
+		"upper",
+		"lower"
+	]);
 	const separator = options?.separator ?? "any";
 	const caseOption = options?.case ?? "preserve";
 	const outputSeparator = options?.outputSeparator;
@@ -1666,9 +2139,64 @@ function macAddress(options) {
 	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})$/;
 	const noneRegex = /^([0-9a-fA-F]{12})$/;
-	return {
-		$mode: "sync",
+	function joinOctets(octets, sep) {
+		let formatted = octets;
+		if (caseOption === "upper") formatted = octets.map((o) => o.toUpperCase());
+		else if (caseOption === "lower") formatted = octets.map((o) => o.toLowerCase());
+		if (sep === ".") return [
+			formatted[0] + formatted[1],
+			formatted[2] + formatted[3],
+			formatted[4] + formatted[5]
+		].join(".");
+		if (sep === "none") return formatted.join("");
+		return formatted.join(sep);
+	}
+	function normalizeMac(value) {
+		if (typeof value !== "string") return metavar;
+		let octets;
+		let detectedSep;
+		if (value.includes(":")) {
+			octets = value.split(":");
+			detectedSep = ":";
+		} else if (value.includes("-")) {
+			octets = value.split("-");
+			detectedSep = "-";
+		} else if (value.includes(".")) {
+			const groups = value.split(".");
+			if (groups.length !== 3 || !groups.every((g) => /^[0-9a-fA-F]{4}$/.test(g))) return value;
+			octets = groups.flatMap((g) => [g.slice(0, 2), g.slice(2)]);
+			detectedSep = ".";
+		} else {
+			if (value.length !== 12) return value;
+			octets = [];
+			for (let i = 0; i < value.length; i += 2) octets.push(value.slice(i, i + 2));
+			detectedSep = "none";
+		}
+		if (octets.length !== 6 || !octets.every((o) => /^[0-9a-fA-F]{1,2}$/.test(o))) return value;
+		octets = octets.map((o) => o.padStart(2, "0"));
+		let sep;
+		if (outputSeparator != null) sep = outputSeparator;
+		else if (separator !== "any") sep = separator;
+		else sep = detectedSep;
+		return joinOctets(octets, sep);
+	}
+	const parserObj = {
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			const octets = [
+				"00",
+				"00",
+				"00",
+				"00",
+				"00",
+				"00"
+			];
+			const sep = outputSeparator ?? (separator === "any" ? ":" : separator);
+			if (sep === ".") return `${octets[0]}${octets[1]}.${octets[2]}${octets[3]}.${octets[4]}${octets[5]}`;
+			if (sep === "none") return octets.join("");
+			return octets.join(sep);
+		},
 		parse(input) {
 			let octets = [];
 			let inputSeparator;
@@ -1728,28 +2256,52 @@ function macAddress(options) {
 					error: msg
 				};
 			}
-			let formattedOctets = octets;
-			if (caseOption === "upper") formattedOctets = octets.map((octet) => octet.toUpperCase());
-			else if (caseOption === "lower") formattedOctets = octets.map((octet) => octet.toLowerCase());
+			octets = octets.map((o) => o.padStart(2, "0"));
 			const finalSeparator = outputSeparator ?? inputSeparator ?? ":";
-			let result;
-			if (finalSeparator === ":") result = formattedOctets.join(":");
-			else if (finalSeparator === "-") result = formattedOctets.join("-");
-			else if (finalSeparator === ".") result = [
-				formattedOctets[0] + formattedOctets[1],
-				formattedOctets[2] + formattedOctets[3],
-				formattedOctets[4] + formattedOctets[5]
-			].join(".");
-			else result = formattedOctets.join("");
 			return {
 				success: true,
-				value: result
+				value: joinOctets(octets, finalSeparator)
 			};
 		},
-		format() {
-			return metavar;
-		}
+		format: normalizeMac
 	};
+	const macParser = parserObj;
+	let macParsing = false;
+	Object.defineProperty(parserObj, "format", {
+		value(v) {
+			if (typeof v !== "string") return metavar;
+			if (macParsing) return v;
+			macParsing = true;
+			try {
+				const result = macParser.parse(v);
+				return result.success ? result.value : v;
+			} catch {
+				return v;
+			} finally {
+				macParsing = false;
+			}
+		},
+		configurable: true,
+		enumerable: true
+	});
+	Object.defineProperty(parserObj, "normalize", {
+		value(v) {
+			if (typeof v !== "string") return v;
+			if (macParsing) return v;
+			macParsing = true;
+			try {
+				const result = macParser.parse(v);
+				return result.success ? result.value : v;
+			} catch {
+				return v;
+			} finally {
+				macParsing = false;
+			}
+		},
+		configurable: true,
+		enumerable: true
+	});
+	return parserObj;
 }
 /**
 * Creates a value parser for domain names.
@@ -1760,6 +2312,14 @@ 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 `allowSubdomains` or `lowercase` is not a boolean.
+* @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
@@ -1773,7 +2333,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 }))
@@ -1783,19 +2343,49 @@ function macAddress(options) {
 */
 function domain(options) {
 	const metavar = options?.metavar ?? "DOMAIN";
+	checkBooleanOption(options, "allowSubdomains");
+	checkBooleanOption(options, "lowercase");
 	const allowSubdomains = options?.allowSubdomains ?? true;
-	const allowedTLDs = options?.allowedTLDs != null ? Object.freeze([...options.allowedTLDs]) : void 0;
+	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) {
+		if (allowedTlds.length === 0) throw new TypeError("allowedTlds must not be empty.");
+		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;
+	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;
-	const labelRegex = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/;
-	return {
-		$mode: "sync",
+	const domainParserObj = {
+		mode: "sync",
 		metavar,
+		placeholder: options?.placeholder ?? `example.${allowedTldsLower?.[0] ?? "com"}`,
 		parse(input) {
+			if (input.length > maxLength) {
+				const errorMsg = tooLong;
+				const msg = typeof errorMsg === "function" ? errorMsg(input, maxLength) : errorMsg ?? require_message.message`Domain ${input} is too long (maximum ${require_message.text(maxLength.toString())} characters).`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
 			if (input.length === 0 || input.startsWith(".") || input.endsWith(".")) {
 				const errorMsg = invalidDomain;
 				if (typeof errorMsg === "function") return {
@@ -1872,6 +2462,31 @@ function domain(options) {
 					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)
+				};
+				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 < minLabels) {
 				const errorMsg = tooFewLabels;
 				if (typeof errorMsg === "function") return {
@@ -1922,15 +2537,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)) {
+				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 ?? [
 						{
@@ -1943,7 +2557,15 @@ function domain(options) {
 						},
 						{
 							type: "text",
-							text: ` is not allowed. Allowed TLDs: ${allowedTLDs.join(", ")}.`
+							text: " is not allowed. Allowed TLDs: "
+						},
+						...require_message.valueSet(allowedTlds, {
+							fallback: "",
+							locale: "en-US"
+						}),
+						{
+							type: "text",
+							text: "."
 						}
 					];
 					return {
@@ -1958,10 +2580,51 @@ function domain(options) {
 				value: result
 			};
 		},
-		format() {
-			return metavar;
+		format(value) {
+			if (typeof value !== "string") return metavar;
+			if (!lowercase) return value;
+			return value.split(".").length >= minLabels ? value.toLowerCase() : value;
 		}
 	};
+	if (lowercase) {
+		const domParser = domainParserObj;
+		let domParsing = false;
+		Object.defineProperty(domainParserObj, "format", {
+			value(v) {
+				if (typeof v !== "string") return metavar;
+				if (domParsing) return v;
+				domParsing = true;
+				try {
+					const result = domParser.parse(v);
+					return result.success ? result.value : v;
+				} catch {
+					return v;
+				} finally {
+					domParsing = false;
+				}
+			},
+			configurable: true,
+			enumerable: true
+		});
+		Object.defineProperty(domainParserObj, "normalize", {
+			value(v) {
+				if (typeof v !== "string") return v;
+				if (domParsing) return v;
+				domParsing = true;
+				try {
+					const result = domParser.parse(v);
+					return result.success ? result.value : v;
+				} catch {
+					return v;
+				} finally {
+					domParsing = false;
+				}
+			},
+			configurable: true,
+			enumerable: true
+		});
+	}
+	return domainParserObj;
 }
 /**
 * Creates a value parser for IPv6 addresses.
@@ -1994,9 +2657,10 @@ function ipv6(options) {
 	const allowZero = options?.allowZero ?? true;
 	const errors = options?.errors;
 	const metavar = options?.metavar ?? "IPV6";
-	return {
-		$mode: "sync",
+	const ipv6ParserObj = {
+		mode: "sync",
 		metavar,
+		placeholder: allowZero ? "::" : allowLoopback ? "::1" : "2001:db8::1",
 		parse(input) {
 			const normalized = parseAndNormalizeIpv6(input);
 			if (normalized === null) {
@@ -2146,10 +2810,74 @@ function ipv6(options) {
 				value: normalized
 			};
 		},
-		format() {
-			return metavar;
+		format(value) {
+			if (typeof value !== "string") return metavar;
+			return parseAndNormalizeIpv6(value) ?? value;
 		}
 	};
+	let ipv6Parsing = false;
+	Object.defineProperty(ipv6ParserObj, "format", {
+		value(v) {
+			if (typeof v !== "string") return metavar;
+			if (ipv6Parsing) return v;
+			ipv6Parsing = true;
+			try {
+				const result = ipv6ParserObj.parse(v);
+				return result.success ? result.value : v;
+			} catch {
+				return v;
+			} finally {
+				ipv6Parsing = false;
+			}
+		},
+		configurable: true,
+		enumerable: true
+	});
+	Object.defineProperty(ipv6ParserObj, "normalize", {
+		value(v) {
+			if (typeof v !== "string") return v;
+			if (ipv6Parsing) return v;
+			ipv6Parsing = true;
+			try {
+				const result = ipv6ParserObj.parse(v);
+				return result.success ? result.value : v;
+			} catch {
+				return v;
+			} finally {
+				ipv6Parsing = false;
+			}
+		},
+		configurable: true,
+		enumerable: true
+	});
+	return ipv6ParserObj;
+}
+/**
+* Parses a dotted-decimal IPv4 string into four validated octets.
+* Returns null if the input is not a valid strict IPv4 address
+* (exactly four decimal octets 0–255, no leading zeros, no whitespace,
+* no non-decimal characters).
+*/
+function parseIpv4Octets(input) {
+	const parts = input.split(".");
+	if (parts.length !== 4) return null;
+	const octets = [
+		0,
+		0,
+		0,
+		0
+	];
+	for (let i = 0; i < 4; i++) {
+		const part = parts[i];
+		if (part.length === 0) return null;
+		if (part.trim() !== part) return null;
+		if (part.length > 1 && part[0] === "0") return null;
+		if (!/^[0-9]+$/.test(part)) return null;
+		const octet = Number(part);
+		if (!Number.isInteger(octet) || octet < 0 || octet > 255) return null;
+		octets[i] = octet;
+	}
+	return octets;
 }
 /**
 * Parses and normalizes an IPv6 address to canonical form.
@@ -2161,10 +2889,8 @@ function parseAndNormalizeIpv6(input) {
 	if (ipv4MappedMatch) {
 		const ipv6Part = ipv4MappedMatch[1];
 		const ipv4Part = ipv4MappedMatch[2];
-		const ipv4Octets = ipv4Part.split(".");
-		if (ipv4Octets.length !== 4) return null;
-		const octets = ipv4Octets.map((o) => parseInt(o, 10));
-		if (octets.some((o) => isNaN(o) || o < 0 || o > 255)) return null;
+		const octets = parseIpv4Octets(ipv4Part);
+		if (octets === null) return null;
 		const group1 = octets[0] << 8 | octets[1];
 		const group2 = octets[2] << 8 | octets[3];
 		const fullAddress = `${ipv6Part}:${group1.toString(16)}:${group2.toString(16)}`;
@@ -2258,6 +2984,90 @@ function compressIpv6(groups) {
 	else return before.join(":") + "::" + after.join(":");
 }
 /**
+* Extracts IPv4 octets from an IPv4-mapped IPv6 address.
+* Returns null if the address is not an IPv4-mapped address
+* (i.e., not in the `::ffff:x.x.x.x` range).
+*/
+function extractIpv4FromMapped(normalizedIpv6) {
+	const groups = expandIpv6(normalizedIpv6);
+	if (groups === null) return null;
+	for (let i = 0; i < 5; i++) if (parseInt(groups[i], 16) !== 0) return null;
+	if (parseInt(groups[5], 16) !== 65535) return null;
+	const high = parseInt(groups[6], 16);
+	const low = parseInt(groups[7], 16);
+	return [
+		high >> 8 & 255,
+		high & 255,
+		low >> 8 & 255,
+		low & 255
+	];
+}
+/**
+* Checks IPv4 restrictions against octets extracted from an IPv4-mapped
+* IPv6 address.  The check uses the base address, consistent with how
+* the `ipv4()` parser validates the address part of a regular IPv4 CIDR.
+*
+* Returns an error result if a restriction is violated, or null if all
+* checks pass.
+*/
+function checkIpv4MappedRestrictions(octets, normalizedIpv6, ipv4Opts, errors) {
+	const allowPrivate = ipv4Opts?.allowPrivate ?? true;
+	const allowLoopback = ipv4Opts?.allowLoopback ?? true;
+	const allowLinkLocal = ipv4Opts?.allowLinkLocal ?? true;
+	const allowMulticast = ipv4Opts?.allowMulticast ?? true;
+	const allowBroadcast = ipv4Opts?.allowBroadcast ?? true;
+	const allowZero = ipv4Opts?.allowZero ?? true;
+	if (!allowPrivate && isPrivateIp(octets)) {
+		const errorMsg = errors?.privateNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? require_message.message`${normalizedIpv6} is a private IP address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowLoopback && isLoopbackIp(octets)) {
+		const errorMsg = errors?.loopbackNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? require_message.message`${normalizedIpv6} is a loopback address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowLinkLocal && isLinkLocalIp(octets)) {
+		const errorMsg = errors?.linkLocalNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? require_message.message`${normalizedIpv6} is a link-local address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowMulticast && isMulticastIp(octets)) {
+		const errorMsg = errors?.multicastNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? require_message.message`${normalizedIpv6} is a multicast address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowBroadcast && isBroadcastIp(octets)) {
+		const errorMsg = errors?.broadcastNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? require_message.message`${normalizedIpv6} is the broadcast address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	if (!allowZero && isZeroIp(octets)) {
+		const errorMsg = errors?.zeroNotAllowed;
+		const msg = typeof errorMsg === "function" ? errorMsg(normalizedIpv6) : errorMsg ?? require_message.message`${normalizedIpv6} is the zero address.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	return null;
+}
+/**
 * Creates a value parser that accepts both IPv4 and IPv6 addresses.
 *
 * By default, accepts both IPv4 and IPv6 addresses. Use the `version` option
@@ -2310,9 +3120,26 @@ function ip(options) {
 			zeroNotAllowed: errors?.zeroNotAllowed
 		}
 	}) : null;
-	return {
-		$mode: "sync",
+	const mappedIpv4Opts = version === "both" ? {
+		allowPrivate: options?.ipv4?.allowPrivate,
+		allowLoopback: options?.ipv4?.allowLoopback,
+		allowLinkLocal: options?.ipv4?.allowLinkLocal,
+		allowMulticast: options?.ipv4?.allowMulticast,
+		allowBroadcast: options?.ipv4?.allowBroadcast,
+		allowZero: options?.ipv4?.allowZero
+	} : void 0;
+	const mappedIpv4Errors = version === "both" ? {
+		privateNotAllowed: errors?.privateNotAllowed,
+		loopbackNotAllowed: errors?.loopbackNotAllowed,
+		linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+		multicastNotAllowed: errors?.multicastNotAllowed,
+		broadcastNotAllowed: errors?.broadcastNotAllowed,
+		zeroNotAllowed: errors?.zeroNotAllowed
+	} : void 0;
+	const ipParserObj = {
+		mode: "sync",
 		metavar,
+		placeholder: version === 6 ? ipv6Parser.placeholder : ipv4Parser.placeholder,
 		parse(input) {
 			let ipv4Error = null;
 			let ipv6Error = null;
@@ -2324,7 +3151,16 @@ function ip(options) {
 			}
 			if (ipv6Parser !== null) {
 				const result = ipv6Parser.parse(input);
-				if (result.success) return result;
+				if (result.success) {
+					if (version === "both") {
+						const mappedOctets = extractIpv4FromMapped(result.value);
+						if (mappedOctets !== null) {
+							const restrictionError = checkIpv4MappedRestrictions(mappedOctets, result.value, mappedIpv4Opts, mappedIpv4Errors);
+							if (restrictionError !== null) return restrictionError;
+						}
+					}
+					return result;
+				}
 				ipv6Error = result;
 				if (version === 6) return result;
 			}
@@ -2360,10 +3196,47 @@ function ip(options) {
 				error: msg
 			};
 		},
-		format() {
-			return metavar;
+		format(value) {
+			if (typeof value !== "string") return metavar;
+			return parseAndNormalizeIpv6(value) ?? value;
 		}
 	};
+	let ipParsing = false;
+	Object.defineProperty(ipParserObj, "format", {
+		value(v) {
+			if (typeof v !== "string") return metavar;
+			if (ipParsing) return v;
+			ipParsing = true;
+			try {
+				const result = ipParserObj.parse(v);
+				return result.success ? result.value : v;
+			} catch {
+				return v;
+			} finally {
+				ipParsing = false;
+			}
+		},
+		configurable: true,
+		enumerable: true
+	});
+	Object.defineProperty(ipParserObj, "normalize", {
+		value(v) {
+			if (typeof v !== "string") return v;
+			if (ipParsing) return v;
+			ipParsing = true;
+			try {
+				const result = ipParserObj.parse(v);
+				return result.success ? result.value : v;
+			} catch {
+				return v;
+			} finally {
+				ipParsing = false;
+			}
+		},
+		configurable: true,
+		enumerable: true
+	});
+	return ipParserObj;
 }
 /**
 * Creates a value parser for CIDR notation (IP address with prefix length).
@@ -2391,16 +3264,71 @@ 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;
 	const metavar = options?.metavar ?? "CIDR";
-	const ipv4Parser = version === 4 || version === "both" ? ipv4(options?.ipv4) : null;
-	const ipv6Parser = version === 6 || version === "both" ? ipv6(options?.ipv6) : null;
-	return {
-		$mode: "sync",
+	const genericIpSentinel = [];
+	const ipv4Parser = version === 4 || version === "both" ? ipv4({
+		...options?.ipv4,
+		errors: {
+			invalidIpv4: genericIpSentinel,
+			privateNotAllowed: errors?.privateNotAllowed,
+			loopbackNotAllowed: errors?.loopbackNotAllowed,
+			linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+			multicastNotAllowed: errors?.multicastNotAllowed,
+			broadcastNotAllowed: errors?.broadcastNotAllowed,
+			zeroNotAllowed: errors?.zeroNotAllowed
+		}
+	}) : null;
+	const ipv6Parser = version === 6 || version === "both" ? ipv6({
+		...options?.ipv6,
+		errors: {
+			invalidIpv6: genericIpSentinel,
+			loopbackNotAllowed: errors?.loopbackNotAllowed,
+			linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+			multicastNotAllowed: errors?.multicastNotAllowed,
+			zeroNotAllowed: errors?.zeroNotAllowed,
+			uniqueLocalNotAllowed: errors?.uniqueLocalNotAllowed
+		}
+	}) : null;
+	const mappedIpv4Opts = version === "both" ? {
+		allowPrivate: options?.ipv4?.allowPrivate,
+		allowLoopback: options?.ipv4?.allowLoopback,
+		allowLinkLocal: options?.ipv4?.allowLinkLocal,
+		allowMulticast: options?.ipv4?.allowMulticast,
+		allowBroadcast: options?.ipv4?.allowBroadcast,
+		allowZero: options?.ipv4?.allowZero
+	} : void 0;
+	const mappedIpv4Errors = version === "both" ? {
+		privateNotAllowed: errors?.privateNotAllowed,
+		loopbackNotAllowed: errors?.loopbackNotAllowed,
+		linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+		multicastNotAllowed: errors?.multicastNotAllowed,
+		broadcastNotAllowed: errors?.broadcastNotAllowed,
+		zeroNotAllowed: errors?.zeroNotAllowed
+	} : void 0;
+	const cidrParserObj = {
+		mode: "sync",
 		metavar,
+		get placeholder() {
+			return version === 6 || version === "both" && (minPrefix ?? 0) > 32 ? {
+				address: ipv6Parser.placeholder,
+				prefix: minPrefix ?? 0,
+				version: 6
+			} : {
+				address: ipv4Parser.placeholder,
+				prefix: minPrefix ?? 0,
+				version: 4
+			};
+		},
 		parse(input) {
 			const slashIndex = input.lastIndexOf("/");
 			if (slashIndex === -1) {
@@ -2458,6 +3386,8 @@ function cidr(options) {
 			}
 			let ipVersion = null;
 			let normalizedIp = null;
+			let ipv4Error = null;
+			let ipv6Error = null;
 			if (ipv4Parser !== null) {
 				const result = ipv4Parser.parse(ipPart);
 				if (result.success) {
@@ -2496,7 +3426,7 @@ function cidr(options) {
 							error: msg
 						};
 					}
-				}
+				} else ipv4Error = result;
 			}
 			if (ipVersion === null && ipv6Parser !== null) {
 				const result = ipv6Parser.parse(ipPart);
@@ -2536,9 +3466,120 @@ function cidr(options) {
 							error: msg
 						};
 					}
-				}
+				} else ipv6Error = result;
 			}
 			if (ipVersion === null || normalizedIp === null) {
+				const candidates = [[
+					ipv4Error,
+					4,
+					32
+				], [
+					ipv6Error,
+					6,
+					128
+				]];
+				for (const [err, ver, maxPfx] of candidates) if (err !== null && !err.success && err.error !== genericIpSentinel) {
+					if (prefix > maxPfx) {
+						const errorMsg$1 = errors?.invalidPrefix;
+						if (typeof errorMsg$1 === "function") return {
+							success: false,
+							error: errorMsg$1(prefix, ver)
+						};
+						const msg$1 = errorMsg$1 ?? [
+							{
+								type: "text",
+								text: "Expected a prefix length between 0 and "
+							},
+							{
+								type: "text",
+								text: maxPfx.toString()
+							},
+							{
+								type: "text",
+								text: ` for IPv${ver}, but got `
+							},
+							{
+								type: "text",
+								text: prefix.toString()
+							},
+							{
+								type: "text",
+								text: "."
+							}
+						];
+						return {
+							success: false,
+							error: msg$1
+						};
+					}
+					if (minPrefix !== void 0 && prefix < minPrefix) {
+						const errorMsg$1 = errors?.prefixBelowMinimum;
+						if (typeof errorMsg$1 === "function") return {
+							success: false,
+							error: errorMsg$1(prefix, minPrefix)
+						};
+						const msg$1 = errorMsg$1 ?? [
+							{
+								type: "text",
+								text: "Expected a prefix length greater than or equal to "
+							},
+							{
+								type: "text",
+								text: minPrefix.toString()
+							},
+							{
+								type: "text",
+								text: ", but got "
+							},
+							{
+								type: "text",
+								text: prefix.toString()
+							},
+							{
+								type: "text",
+								text: "."
+							}
+						];
+						return {
+							success: false,
+							error: msg$1
+						};
+					}
+					if (maxPrefix !== void 0 && prefix > maxPrefix) {
+						const errorMsg$1 = errors?.prefixAboveMaximum;
+						if (typeof errorMsg$1 === "function") return {
+							success: false,
+							error: errorMsg$1(prefix, maxPrefix)
+						};
+						const msg$1 = errorMsg$1 ?? [
+							{
+								type: "text",
+								text: "Expected a prefix length less than or equal to "
+							},
+							{
+								type: "text",
+								text: maxPrefix.toString()
+							},
+							{
+								type: "text",
+								text: ", but got "
+							},
+							{
+								type: "text",
+								text: prefix.toString()
+							},
+							{
+								type: "text",
+								text: "."
+							}
+						];
+						return {
+							success: false,
+							error: msg$1
+						};
+					}
+					return err;
+				}
 				const errorMsg = errors?.invalidCidr;
 				if (typeof errorMsg === "function") return {
 					success: false,
@@ -2629,6 +3670,13 @@ function cidr(options) {
 					error: msg
 				};
 			}
+			if (version === "both" && ipVersion === 6 && normalizedIp !== null) {
+				const mappedOctets = extractIpv4FromMapped(normalizedIp);
+				if (mappedOctets !== null) {
+					const restrictionError = checkIpv4MappedRestrictions(mappedOctets, normalizedIp, mappedIpv4Opts, mappedIpv4Errors);
+					if (restrictionError !== null) return restrictionError;
+				}
+			}
 			return {
 				success: true,
 				value: {
@@ -2638,13 +3686,52 @@ function cidr(options) {
 				}
 			};
 		},
-		format() {
-			return metavar;
-		}
+		format: ((_) => metavar)
 	};
+	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 (cidrParsing) return `${value.address}/${value.prefix}`;
+			cidrParsing = true;
+			try {
+				const raw = `${value.address}/${value.prefix}`;
+				const result = cidrParserObj.parse(raw);
+				return result.success && result.value.version === value.version ? `${result.value.address}/${result.value.prefix}` : raw;
+			} catch {
+				return `${value.address}/${value.prefix}`;
+			} finally {
+				cidrParsing = false;
+			}
+		},
+		configurable: true,
+		enumerable: true
+	});
+	Object.defineProperty(cidrParserObj, "normalize", {
+		value(v) {
+			if (typeof v !== "object" || v == null || !("address" in v) || !("prefix" in v) || !("version" in v)) return v;
+			if (cidrParsing) return v;
+			cidrParsing = true;
+			const formatted = `${v.address}/${v.prefix}`;
+			try {
+				const result = cidrParserObj.parse(formatted);
+				if (result.success && result.value.version === v.version) return result.value;
+				return v;
+			} catch {
+				return v;
+			} finally {
+				cidrParsing = false;
+			}
+		},
+		configurable: true,
+		enumerable: true
+	});
+	return cidrParserObj;
 }
 
 //#endregion
+exports.checkBooleanOption = checkBooleanOption;
+exports.checkEnumOption = checkEnumOption;
 exports.choice = choice;
 exports.cidr = cidr;
 exports.domain = domain;