@optique/core 0.10.0-dev.333 → 0.10.0-dev.342

package/dist/valueparser.js

@@ -649,6 +649,1844 @@ function uuid(options = {}) {
 		}
 	};
 }
+/**
+* Creates a ValueParser for TCP/UDP port numbers.
+*
+* This parser validates that the input is a valid port number (1-65535 by default)
+* and optionally enforces range constraints and well-known port restrictions.
+*
+* Port numbers are validated according to the following rules:
+* - Must be a valid integer (no decimals, no scientific notation)
+* - Must be within the range `[min, max]` (default `[1, 65535]`)
+* - If `disallowWellKnown` is `true`, ports 1-1023 are rejected
+*
+* The parser provides two modes of operation:
+* - Regular mode: Returns JavaScript numbers (safe for all port values)
+* - `bigint` mode: Returns `bigint` values for consistency with other numeric types
+*
+* @example
+* ```typescript
+* // Basic port parser (1-65535)
+* option("--port", port())
+*
+* // Custom range (non-privileged ports only)
+* option("--port", port({ min: 1024, max: 65535 }))
+*
+* // Disallow well-known ports (reject 1-1023)
+* option("--port", port({ disallowWellKnown: true }))
+*
+* // Development ports only
+* option("--dev-port", port({ min: 3000, max: 9000 }))
+*
+* // Using bigint type
+* option("--port", port({ type: "bigint" }))
+* ```
+*
+* @param options Configuration options specifying the type and constraints.
+* @returns A {@link ValueParser} that converts string input to port numbers.
+* @since 0.10.0
+*/
+function port(options) {
+	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;
+		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 (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}.`
+				};
+				if (value > max$1) return {
+					success: false,
+					error: options.errors?.aboveMaximum ? typeof options.errors.aboveMaximum === "function" ? options.errors.aboveMaximum(value, max$1) : options.errors.aboveMaximum : message`Expected a port number less than or equal to ${text(max$1.toLocaleString("en"))}, but got ${input}.`
+				};
+				if (options.disallowWellKnown && value >= 1n && value <= 1023n) return {
+					success: false,
+					error: options.errors?.wellKnownNotAllowed ? typeof options.errors.wellKnownNotAllowed === "function" ? options.errors.wellKnownNotAllowed(value) : options.errors.wellKnownNotAllowed : message`Port ${value.toLocaleString("en")} is a well-known port (1-1023) and may require elevated privileges.`
+				};
+				return {
+					success: true,
+					value
+				};
+			},
+			format(value) {
+				return value.toString();
+			}
+		};
+	}
+	const metavar = options?.metavar ?? "PORT";
+	ensureNonEmptyString(metavar);
+	const min = options?.min ?? 1;
+	const max = options?.max ?? 65535;
+	return {
+		$mode: "sync",
+		metavar,
+		parse(input) {
+			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 = Number.parseInt(input);
+			if (value < min) return {
+				success: false,
+				error: options?.errors?.belowMinimum ? typeof options.errors.belowMinimum === "function" ? options.errors.belowMinimum(value, min) : options.errors.belowMinimum : message`Expected a port number greater than or equal to ${text(min.toLocaleString("en"))}, but got ${input}.`
+			};
+			if (value > max) return {
+				success: false,
+				error: options?.errors?.aboveMaximum ? typeof options.errors.aboveMaximum === "function" ? options.errors.aboveMaximum(value, max) : options.errors.aboveMaximum : message`Expected a port number less than or equal to ${text(max.toLocaleString("en"))}, but got ${input}.`
+			};
+			if (options?.disallowWellKnown && value >= 1 && value <= 1023) return {
+				success: false,
+				error: options.errors?.wellKnownNotAllowed ? typeof options.errors.wellKnownNotAllowed === "function" ? options.errors.wellKnownNotAllowed(value) : options.errors.wellKnownNotAllowed : message`Port ${value.toLocaleString("en")} is a well-known port (1-1023) and may require elevated privileges.`
+			};
+			return {
+				success: true,
+				value
+			};
+		},
+		format(value) {
+			return value.toString();
+		}
+	};
+}
+function isPrivateIp(octets) {
+	if (octets[0] === 10) return true;
+	if (octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31) return true;
+	if (octets[0] === 192 && octets[1] === 168) return true;
+	return false;
+}
+function isLoopbackIp(octets) {
+	return octets[0] === 127;
+}
+function isLinkLocalIp(octets) {
+	return octets[0] === 169 && octets[1] === 254;
+}
+function isMulticastIp(octets) {
+	return octets[0] >= 224 && octets[0] <= 239;
+}
+function isBroadcastIp(octets) {
+	return octets.every((o) => o === 255);
+}
+function isZeroIp(octets) {
+	return octets.every((o) => o === 0);
+}
+/**
+* Creates a value parser for IPv4 addresses.
+*
+* This parser validates IPv4 addresses in dotted-decimal notation (e.g.,
+* "192.168.1.1") and provides options to filter specific IP address types
+* such as private, loopback, link-local, multicast, broadcast, and zero
+* addresses.
+*
+* @param options The parser options.
+* @returns A value parser for IPv4 addresses.
+* @throws {TypeError} If the metavar is an empty string.
+* @since 0.10.0
+* @example
+* ```typescript
+* import { ipv4 } from "@optique/core/valueparser";
+*
+* // Basic IPv4 parser (allows all types)
+* const address = ipv4();
+*
+* // Public IPs only (no private/loopback)
+* const publicIp = ipv4({
+*   allowPrivate: false,
+*   allowLoopback: false
+* });
+*
+* // Server binding (allow 0.0.0.0 and private IPs)
+* const bindAddress = ipv4({
+*   allowZero: true,
+*   allowPrivate: true
+* });
+* ```
+*/
+function ipv4(options) {
+	const metavar = options?.metavar ?? "IPV4";
+	ensureNonEmptyString(metavar);
+	const allowPrivate = options?.allowPrivate ?? true;
+	const allowLoopback = options?.allowLoopback ?? true;
+	const allowLinkLocal = options?.allowLinkLocal ?? true;
+	const allowMulticast = options?.allowMulticast ?? true;
+	const allowBroadcast = options?.allowBroadcast ?? true;
+	const allowZero = options?.allowZero ?? true;
+	return {
+		$mode: "sync",
+		metavar,
+		parse(input) {
+			const parts = input.split(".");
+			if (parts.length !== 4) {
+				const errorMsg = options?.errors?.invalidIpv4;
+				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid IPv4 address, but got ${input}.`;
+				return {
+					success: false,
+					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 ?? 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 ?? 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 ?? 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 ?? 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;
+				const msg = typeof errorMsg === "function" ? errorMsg(ipAddress) : errorMsg ?? message`${ipAddress} is a private IP address.`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (!allowLoopback && isLoopbackIp(octets)) {
+				const errorMsg = options?.errors?.loopbackNotAllowed;
+				const msg = typeof errorMsg === "function" ? errorMsg(ipAddress) : errorMsg ?? message`${ipAddress} is a loopback address.`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (!allowLinkLocal && isLinkLocalIp(octets)) {
+				const errorMsg = options?.errors?.linkLocalNotAllowed;
+				const msg = typeof errorMsg === "function" ? errorMsg(ipAddress) : errorMsg ?? message`${ipAddress} is a link-local address.`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (!allowMulticast && isMulticastIp(octets)) {
+				const errorMsg = options?.errors?.multicastNotAllowed;
+				const msg = typeof errorMsg === "function" ? errorMsg(ipAddress) : errorMsg ?? message`${ipAddress} is a multicast address.`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (!allowBroadcast && isBroadcastIp(octets)) {
+				const errorMsg = options?.errors?.broadcastNotAllowed;
+				const msg = typeof errorMsg === "function" ? errorMsg(ipAddress) : errorMsg ?? message`${ipAddress} is the broadcast address.`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (!allowZero && isZeroIp(octets)) {
+				const errorMsg = options?.errors?.zeroNotAllowed;
+				const msg = typeof errorMsg === "function" ? errorMsg(ipAddress) : errorMsg ?? message`${ipAddress} is the zero address.`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			return {
+				success: true,
+				value: ipAddress
+			};
+		},
+		format(value) {
+			return value;
+		}
+	};
+}
+/**
+* Creates a value parser for DNS hostnames.
+*
+* Validates hostnames according to RFC 1123:
+* - Labels separated by dots
+* - Each label: 1-63 characters
+* - Labels can contain alphanumeric characters and hyphens
+* - Labels cannot start or end with a hyphen
+* - Total length ≤ 253 characters (default)
+*
+* @param options - Options for hostname validation.
+* @returns A value parser for hostnames.
+* @since 0.10.0
+*
+* @example
+* ```typescript
+* import { hostname } from "@optique/core/valueparser";
+*
+* // Basic hostname parser
+* const host = hostname();
+*
+* // Allow wildcards for certificate validation
+* const domain = hostname({ allowWildcard: true });
+*
+* // Reject localhost
+* const remoteHost = hostname({ allowLocalhost: false });
+* ```
+*/
+function hostname(options) {
+	const metavar = options?.metavar ?? "HOST";
+	ensureNonEmptyString(metavar);
+	const allowWildcard = options?.allowWildcard ?? false;
+	const allowUnderscore = options?.allowUnderscore ?? false;
+	const allowLocalhost = options?.allowLocalhost ?? true;
+	const maxLength = options?.maxLength ?? 253;
+	return {
+		$mode: "sync",
+		metavar,
+		parse(input) {
+			if (input.length > maxLength) {
+				const errorMsg = options?.errors?.tooLong;
+				const msg = typeof errorMsg === "function" ? errorMsg(input, maxLength) : errorMsg ?? message`Hostname ${input} is too long (maximum ${text(maxLength.toString())} characters).`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (!allowLocalhost && input === "localhost") {
+				const errorMsg = options?.errors?.localhostNotAllowed;
+				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Hostname 'localhost' is not allowed.`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (input.startsWith("*.")) {
+				if (!allowWildcard) {
+					const errorMsg = options?.errors?.wildcardNotAllowed;
+					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Wildcard hostname ${input} is not allowed.`;
+					return {
+						success: false,
+						error: msg
+					};
+				}
+				const rest = input.slice(2);
+				if (!rest || rest.includes("*")) {
+					const errorMsg = options?.errors?.invalidHostname;
+					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid hostname, but got ${input}.`;
+					return {
+						success: false,
+						error: msg
+					};
+				}
+			}
+			if (!allowUnderscore && input.includes("_")) {
+				const errorMsg = options?.errors?.underscoreNotAllowed;
+				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Hostname ${input} contains underscore, which is not allowed.`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (input.length === 0) {
+				const errorMsg = options?.errors?.invalidHostname;
+				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid hostname, but got ${input}.`;
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			const labels = input.split(".");
+			for (const label of labels) {
+				if (label.length === 0) {
+					const errorMsg = options?.errors?.invalidHostname;
+					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid hostname, but got ${input}.`;
+					return {
+						success: false,
+						error: msg
+					};
+				}
+				if (label.length > 63) {
+					const errorMsg = options?.errors?.invalidHostname;
+					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid hostname, but got ${input}.`;
+					return {
+						success: false,
+						error: msg
+					};
+				}
+				if (label === "*") continue;
+				if (label.startsWith("-") || label.endsWith("-")) {
+					const errorMsg = options?.errors?.invalidHostname;
+					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid hostname, but got ${input}.`;
+					return {
+						success: false,
+						error: msg
+					};
+				}
+				const allowedPattern = allowUnderscore ? /^[a-zA-Z0-9_-]+$/ : /^[a-zA-Z0-9-]+$/;
+				if (!allowedPattern.test(label)) {
+					const errorMsg = options?.errors?.invalidHostname;
+					const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a valid hostname, but got ${input}.`;
+					return {
+						success: false,
+						error: msg
+					};
+				}
+			}
+			return {
+				success: true,
+				value: input
+			};
+		},
+		format(value) {
+			return value;
+		}
+	};
+}
+function email(options) {
+	const metavar = options?.metavar ?? "EMAIL";
+	ensureNonEmptyString(metavar);
+	const allowMultiple = options?.allowMultiple ?? false;
+	const allowDisplayName = options?.allowDisplayName ?? false;
+	const lowercase = options?.lowercase ?? false;
+	const allowedDomains = options?.allowedDomains;
+	const atextRegex = /^[a-zA-Z0-9._+-]+$/;
+	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();
+		}
+		let atIndex = -1;
+		if (emailAddr.startsWith("\"")) {
+			const closingQuoteIndex = emailAddr.indexOf("\"", 1);
+			if (closingQuoteIndex === -1) return null;
+			atIndex = emailAddr.indexOf("@", closingQuoteIndex);
+		} else atIndex = emailAddr.indexOf("@");
+		if (atIndex === -1) return null;
+		const lastAtIndex = emailAddr.lastIndexOf("@");
+		if (atIndex !== lastAtIndex) return null;
+		const localPart = emailAddr.substring(0, atIndex);
+		const domain$1 = emailAddr.substring(atIndex + 1);
+		if (!localPart || localPart.length === 0) return null;
+		let isValidLocal = false;
+		if (localPart.startsWith("\"") && localPart.endsWith("\"")) isValidLocal = localPart.length >= 2;
+		else {
+			const localParts = localPart.split(".");
+			if (localPart.startsWith(".") || localPart.endsWith(".")) return null;
+			isValidLocal = localParts.length > 0 && localParts.every((part) => part.length > 0 && atextRegex.test(part));
+		}
+		if (!isValidLocal) 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;
+		const domainLabels = domain$1.split(".");
+		for (const label of domainLabels) {
+			if (label.length === 0 || label.length > 63) return null;
+			if (label.startsWith("-") || label.endsWith("-")) return null;
+			if (!/^[a-zA-Z0-9-]+$/.test(label)) return null;
+		}
+		const resultEmail = emailAddr;
+		return lowercase ? resultEmail.toLowerCase() : resultEmail;
+	}
+	return {
+		$mode: "sync",
+		metavar,
+		parse(input) {
+			if (allowMultiple) {
+				const emails = input.split(",").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 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) {
+						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;
+							if (typeof errorMsg === "function") return {
+								success: false,
+								error: errorMsg(validated, allowedDomains)
+							};
+							const msg = errorMsg ?? [
+								{
+									type: "text",
+									text: "Email domain "
+								},
+								{
+									type: "value",
+									value: domain$1
+								},
+								{
+									type: "text",
+									text: ` is not allowed. Allowed domains: ${allowedDomains.join(", ")}.`
+								}
+							];
+							return {
+								success: false,
+								error: msg
+							};
+						}
+					}
+					validatedEmails.push(validated);
+				}
+				return {
+					success: true,
+					value: validatedEmails
+				};
+			} else {
+				const validated = validateEmail(input);
+				if (validated === null) {
+					const errorMsg = options?.errors?.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) {
+					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;
+						if (typeof errorMsg === "function") return {
+							success: false,
+							error: errorMsg(validated, allowedDomains)
+						};
+						const msg = errorMsg ?? [
+							{
+								type: "text",
+								text: "Email domain "
+							},
+							{
+								type: "value",
+								value: domain$1
+							},
+							{
+								type: "text",
+								text: ` is not allowed. Allowed domains: ${allowedDomains.join(", ")}.`
+							}
+						];
+						return {
+							success: false,
+							error: msg
+						};
+					}
+				}
+				return {
+					success: true,
+					value: validated
+				};
+			}
+		},
+		format(value) {
+			if (Array.isArray(value)) return value.join(",");
+			return value;
+		}
+	};
+}
+/**
+* Creates a value parser for socket addresses in "host:port" format.
+*
+* Validates socket addresses with support for:
+* - Hostnames and IPv4 addresses (IPv6 support coming in future versions)
+* - Configurable host:port separator
+* - Optional default port
+* - Host type filtering (hostname only, IP only, or both)
+* - Port range validation
+*
+* @param options - Options for socket address validation.
+* @returns A value parser for socket addresses.
+* @since 0.10.0
+*
+* @example
+* ```typescript
+* import { socketAddress } from "@optique/core/valueparser";
+*
+* // Basic socket address parser
+* const endpoint = socketAddress({ requirePort: true });
+*
+* // With default port
+* const server = socketAddress({ defaultPort: 80 });
+*
+* // IP addresses only
+* const bind = socketAddress({
+*   defaultPort: 8080,
+*   host: { type: "ip" }
+* });
+* ```
+*/
+function socketAddress(options) {
+	const metavar = options?.metavar ?? "HOST:PORT";
+	ensureNonEmptyString(metavar);
+	const separator = options?.separator ?? ":";
+	const defaultPort = options?.defaultPort;
+	const requirePort = options?.requirePort ?? false;
+	const hostType = options?.host?.type ?? "both";
+	const hostnameParser = hostname({
+		...options?.host?.hostname,
+		metavar: "HOST"
+	});
+	const ipParser = ipv4({
+		...options?.host?.ip,
+		metavar: "HOST"
+	});
+	const portParser = port({
+		...options?.port,
+		metavar: "PORT",
+		type: "number"
+	});
+	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;
+		}
+	}
+	return {
+		$mode: "sync",
+		metavar,
+		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 validatedHost = parseHost(hostPart);
+			if (validatedHost === null) {
+				const errorMsg = options?.errors?.invalidFormat;
+				const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a socket address in format host${separator}port, but got ${input}.`;
+				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 ?? message`Port number is required but was not specified.`;
+					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 ?? 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 ?? message`Expected a socket address in format host${separator}port, but got ${input}.`;
+					return {
+						success: false,
+						error: msg
+					};
+				}
+				validatedPort = portResult.value;
+			}
+			return {
+				success: true,
+				value: {
+					host: validatedHost,
+					port: validatedPort
+				}
+			};
+		},
+		format(value) {
+			return `${value.host}${separator}${value.port}`;
+		}
+	};
+}
+function portRange(options) {
+	const metavar = options?.metavar ?? "PORT-PORT";
+	ensureNonEmptyString(metavar);
+	const separator = options?.separator ?? "-";
+	const allowSingle = options?.allowSingle ?? false;
+	const isBigInt = options?.type === "bigint";
+	const portParser = isBigInt ? port({
+		type: "bigint",
+		min: options.min,
+		max: options.max,
+		disallowWellKnown: options.disallowWellKnown,
+		errors: options.errors
+	}) : port({
+		type: "number",
+		min: options?.min,
+		max: options?.max,
+		disallowWellKnown: options?.disallowWellKnown,
+		errors: options?.errors
+	});
+	return {
+		$mode: "sync",
+		metavar,
+		parse(input) {
+			const trimmed = input.trim();
+			const separatorIndex = trimmed.indexOf(separator);
+			if (separatorIndex === -1) {
+				if (!allowSingle) {
+					const errorMsg = options?.errors?.invalidFormat;
+					if (typeof errorMsg === "function") return {
+						success: false,
+						error: errorMsg(input)
+					};
+					const msg = errorMsg ?? [
+						{
+							type: "text",
+							text: `Expected a port range in format start${separator}end, but got `
+						},
+						{
+							type: "value",
+							value: input
+						},
+						{
+							type: "text",
+							text: "."
+						}
+					];
+					return {
+						success: false,
+						error: msg
+					};
+				}
+				const portResult = portParser.parse(trimmed);
+				if (!portResult.success) return portResult;
+				const portValue = portResult.value;
+				return {
+					success: true,
+					value: isBigInt ? {
+						start: portValue,
+						end: portValue
+					} : {
+						start: portValue,
+						end: portValue
+					}
+				};
+			}
+			const startPart = trimmed.substring(0, separatorIndex);
+			const endPart = trimmed.substring(separatorIndex + separator.length);
+			const startResult = portParser.parse(startPart);
+			if (!startResult.success) return startResult;
+			const endResult = portParser.parse(endPart);
+			if (!endResult.success) return endResult;
+			const startValue = startResult.value;
+			const endValue = endResult.value;
+			if (isBigInt) {
+				const start = startValue;
+				const end = endValue;
+				if (start > end) {
+					const errorMsg = options.errors?.invalidRange;
+					const msg = typeof errorMsg === "function" ? errorMsg(start, end) : errorMsg ?? message`Start port ${startPart} must be less than or equal to end port ${endPart}.`;
+					return {
+						success: false,
+						error: msg
+					};
+				}
+				return {
+					success: true,
+					value: {
+						start,
+						end
+					}
+				};
+			} else {
+				const start = startValue;
+				const end = endValue;
+				if (start > end) {
+					const errorMsg = options?.errors?.invalidRange;
+					const msg = typeof errorMsg === "function" ? errorMsg(start, end) : errorMsg ?? message`Start port ${startPart} must be less than or equal to end port ${endPart}.`;
+					return {
+						success: false,
+						error: msg
+					};
+				}
+				return {
+					success: true,
+					value: {
+						start,
+						end
+					}
+				};
+			}
+		},
+		format(value) {
+			return `${value.start}${separator}${value.end}`;
+		}
+	};
+}
+/**
+* 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`
+*
+* Returns the MAC address as a formatted string according to `case` and
+* `outputSeparator` options.
+*
+* @param options Configuration options for the MAC address parser.
+* @returns A parser that validates MAC addresses and returns formatted strings.
+* @since 0.10.0
+*
+* @example
+* ```typescript
+* import { macAddress } from "@optique/core/valueparser";
+*
+* // Accept any format
+* const mac = macAddress();
+*
+* // Normalize to uppercase colon-separated
+* const normalizedMac = macAddress({
+*   outputSeparator: ":",
+*   case: "upper"
+* });
+* ```
+*/
+function macAddress(options) {
+	const separator = options?.separator ?? "any";
+	const caseOption = options?.case ?? "preserve";
+	const outputSeparator = options?.outputSeparator;
+	const metavar = options?.metavar ?? "MAC";
+	const colonRegex = /^([0-9a-fA-F]{1,2}):([0-9a-fA-F]{1,2}):([0-9a-fA-F]{1,2}):([0-9a-fA-F]{1,2}):([0-9a-fA-F]{1,2}):([0-9a-fA-F]{1,2})$/;
+	const hyphenRegex = /^([0-9a-fA-F]{1,2})-([0-9a-fA-F]{1,2})-([0-9a-fA-F]{1,2})-([0-9a-fA-F]{1,2})-([0-9a-fA-F]{1,2})-([0-9a-fA-F]{1,2})$/;
+	const dotRegex = /^([0-9a-fA-F]{4})\.([0-9a-fA-F]{4})\.([0-9a-fA-F]{4})$/;
+	const noneRegex = /^([0-9a-fA-F]{12})$/;
+	return {
+		$mode: "sync",
+		metavar,
+		parse(input) {
+			let octets = [];
+			let inputSeparator;
+			if (separator === ":" || separator === "any") {
+				const match = colonRegex.exec(input);
+				if (match) {
+					octets = match.slice(1, 7);
+					inputSeparator = ":";
+				}
+			}
+			if (octets.length === 0 && (separator === "-" || separator === "any")) {
+				const match = hyphenRegex.exec(input);
+				if (match) {
+					octets = match.slice(1, 7);
+					inputSeparator = "-";
+				}
+			}
+			if (octets.length === 0 && (separator === "." || separator === "any")) {
+				const match = dotRegex.exec(input);
+				if (match) {
+					const groups = match.slice(1, 4);
+					octets = groups.flatMap((group) => [group.slice(0, 2), group.slice(2, 4)]);
+					inputSeparator = ".";
+				}
+			}
+			if (octets.length === 0 && (separator === "none" || separator === "any")) {
+				const match = noneRegex.exec(input);
+				if (match) {
+					const hex = match[1];
+					octets = [];
+					for (let i = 0; i < 12; i += 2) octets.push(hex.slice(i, i + 2));
+					inputSeparator = "none";
+				}
+			}
+			if (octets.length === 0) {
+				const errorMsg = options?.errors?.invalidMacAddress;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(input)
+				};
+				const msg = errorMsg ?? [
+					{
+						type: "text",
+						text: "Expected a valid MAC address, but got "
+					},
+					{
+						type: "value",
+						value: input
+					},
+					{
+						type: "text",
+						text: "."
+					}
+				];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			let formattedOctets = octets;
+			if (caseOption === "upper") formattedOctets = octets.map((octet) => octet.toUpperCase());
+			else if (caseOption === "lower") formattedOctets = octets.map((octet) => octet.toLowerCase());
+			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
+			};
+		},
+		format() {
+			return metavar;
+		}
+	};
+}
+/**
+* Creates a value parser for domain names.
+*
+* Validates domain names according to RFC 1035 with configurable options for
+* subdomain filtering, TLD restrictions, minimum label requirements, and case
+* normalization.
+*
+* @param options Parser options for domain validation.
+* @returns A parser that accepts valid domain names as strings.
+*
+* @example
+* ``` typescript
+* import { option } from "@optique/core/primitives";
+* import { domain } from "@optique/core/valueparser";
+*
+* // Accept any valid domain
+* option("--domain", domain())
+*
+* // Root domains only (no subdomains)
+* option("--root", domain({ allowSubdomains: false }))
+*
+* // Restrict to specific TLDs
+* option("--domain", domain({ allowedTLDs: ["com", "org", "net"] }))
+*
+* // Normalize to lowercase
+* option("--domain", domain({ lowercase: true }))
+* ```
+*
+* @since 0.10.0
+*/
+function domain(options) {
+	const metavar = options?.metavar ?? "DOMAIN";
+	const allowSubdomains = options?.allowSubdomains ?? true;
+	const allowedTLDs = options?.allowedTLDs;
+	const minLabels = options?.minLabels ?? 2;
+	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])?$/;
+	return {
+		$mode: "sync",
+		metavar,
+		parse(input) {
+			if (input.length === 0 || input.startsWith(".") || input.endsWith(".")) {
+				const errorMsg = errors?.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 (input.includes("..")) {
+				const errorMsg = errors?.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
+				};
+			}
+			const labels = input.split(".");
+			for (const label of labels) if (!labelRegex.test(label)) {
+				const errorMsg = errors?.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 = errors?.tooFewLabels;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(input, minLabels)
+				};
+				const msg = errorMsg ?? [
+					{
+						type: "text",
+						text: "Domain "
+					},
+					{
+						type: "value",
+						value: input
+					},
+					{
+						type: "text",
+						text: ` must have at least ${minLabels} labels.`
+					}
+				];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (!allowSubdomains && labels.length > 2) {
+				const errorMsg = errors?.subdomainsNotAllowed;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(input)
+				};
+				const msg = errorMsg ?? [
+					{
+						type: "text",
+						text: "Subdomains are not allowed, but got "
+					},
+					{
+						type: "value",
+						value: input
+					},
+					{
+						type: "text",
+						text: "."
+					}
+				];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (allowedTLDs !== 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 (typeof errorMsg === "function") return {
+						success: false,
+						error: errorMsg(tld, allowedTLDs)
+					};
+					const msg = errorMsg ?? [
+						{
+							type: "text",
+							text: "Top-level domain "
+						},
+						{
+							type: "value",
+							value: tld
+						},
+						{
+							type: "text",
+							text: ` is not allowed. Allowed TLDs: ${allowedTLDs.join(", ")}.`
+						}
+					];
+					return {
+						success: false,
+						error: msg
+					};
+				}
+			}
+			const result = lowercase ? input.toLowerCase() : input;
+			return {
+				success: true,
+				value: result
+			};
+		},
+		format() {
+			return metavar;
+		}
+	};
+}
+/**
+* Creates a value parser for IPv6 addresses.
+*
+* Validates and normalizes IPv6 addresses to canonical form (lowercase,
+* compressed using `::` notation where appropriate).
+*
+* @param options Configuration options for IPv6 validation.
+* @returns A value parser that validates IPv6 addresses.
+*
+* @example
+* ```typescript
+* // Basic IPv6 parser
+* option("--ipv6", ipv6())
+*
+* // Global unicast only (no link-local, no unique local)
+* option("--public-ipv6", ipv6({
+*   allowLinkLocal: false,
+*   allowUniqueLocal: false
+* }))
+* ```
+*
+* @since 0.10.0
+*/
+function ipv6(options) {
+	const allowLoopback = options?.allowLoopback ?? true;
+	const allowLinkLocal = options?.allowLinkLocal ?? true;
+	const allowUniqueLocal = options?.allowUniqueLocal ?? true;
+	const allowMulticast = options?.allowMulticast ?? true;
+	const allowZero = options?.allowZero ?? true;
+	const errors = options?.errors;
+	const metavar = options?.metavar ?? "IPV6";
+	return {
+		$mode: "sync",
+		metavar,
+		parse(input) {
+			const normalized = parseAndNormalizeIpv6(input);
+			if (normalized === null) {
+				const errorMsg = errors?.invalidIpv6;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(input)
+				};
+				const msg = errorMsg ?? [
+					{
+						type: "text",
+						text: "Expected a valid IPv6 address, but got "
+					},
+					{
+						type: "value",
+						value: input
+					},
+					{
+						type: "text",
+						text: "."
+					}
+				];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (!allowZero && normalized === "::") {
+				const errorMsg = errors?.zeroNotAllowed;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(normalized)
+				};
+				const msg = errorMsg ?? [{
+					type: "value",
+					value: normalized
+				}, {
+					type: "text",
+					text: " is the zero address."
+				}];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (!allowLoopback && normalized === "::1") {
+				const errorMsg = errors?.loopbackNotAllowed;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(normalized)
+				};
+				const msg = errorMsg ?? [{
+					type: "value",
+					value: normalized
+				}, {
+					type: "text",
+					text: " is a loopback address."
+				}];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			const groups = expandIpv6(normalized);
+			if (groups === null) {
+				const errorMsg = errors?.invalidIpv6;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(input)
+				};
+				const msg = errorMsg ?? [
+					{
+						type: "text",
+						text: "Expected a valid IPv6 address, but got "
+					},
+					{
+						type: "value",
+						value: input
+					},
+					{
+						type: "text",
+						text: "."
+					}
+				];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			const firstGroup = parseInt(groups[0], 16);
+			if (!allowLinkLocal && (firstGroup & 65472) === 65152) {
+				const errorMsg = errors?.linkLocalNotAllowed;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(normalized)
+				};
+				const msg = errorMsg ?? [{
+					type: "value",
+					value: normalized
+				}, {
+					type: "text",
+					text: " is a link-local address."
+				}];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (!allowUniqueLocal && (firstGroup & 65024) === 64512) {
+				const errorMsg = errors?.uniqueLocalNotAllowed;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(normalized)
+				};
+				const msg = errorMsg ?? [{
+					type: "value",
+					value: normalized
+				}, {
+					type: "text",
+					text: " is a unique local address."
+				}];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (!allowMulticast && (firstGroup & 65280) === 65280) {
+				const errorMsg = errors?.multicastNotAllowed;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(normalized)
+				};
+				const msg = errorMsg ?? [{
+					type: "value",
+					value: normalized
+				}, {
+					type: "text",
+					text: " is a multicast address."
+				}];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			return {
+				success: true,
+				value: normalized
+			};
+		},
+		format() {
+			return metavar;
+		}
+	};
+}
+/**
+* Parses and normalizes an IPv6 address to canonical form.
+* Returns null if the input is not a valid IPv6 address.
+*/
+function parseAndNormalizeIpv6(input) {
+	if (input.length === 0) return null;
+	const ipv4MappedMatch = input.match(/^(.+):(\d+\.\d+\.\d+\.\d+)$/);
+	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 group1 = octets[0] << 8 | octets[1];
+		const group2 = octets[2] << 8 | octets[3];
+		const fullAddress = `${ipv6Part}:${group1.toString(16)}:${group2.toString(16)}`;
+		return parseAndNormalizeIpv6(fullAddress);
+	}
+	const compressionCount = (input.match(/::/g) || []).length;
+	if (compressionCount > 1) return null;
+	let groups;
+	if (input.includes("::")) {
+		const parts = input.split("::");
+		if (parts.length > 2) return null;
+		const leftGroups = parts[0] ? parts[0].split(":") : [];
+		const rightGroups = parts[1] ? parts[1].split(":") : [];
+		const totalGroups = leftGroups.length + rightGroups.length;
+		if (totalGroups > 8) return null;
+		const zeroCount = 8 - totalGroups;
+		const zeros = Array(zeroCount).fill("0");
+		groups = [
+			...leftGroups,
+			...zeros,
+			...rightGroups
+		];
+	} else {
+		groups = input.split(":");
+		if (groups.length !== 8) return null;
+	}
+	for (let i = 0; i < groups.length; i++) {
+		const group = groups[i];
+		if (group.length === 0 || group.length > 4) return null;
+		if (!/^[0-9a-fA-F]+$/.test(group)) return null;
+		groups[i] = parseInt(group, 16).toString(16);
+	}
+	return compressIpv6(groups);
+}
+/**
+* Expands a compressed IPv6 address to 8 groups of 4 hex digits.
+* Returns null if the input is invalid.
+*/
+function expandIpv6(input) {
+	if (input.includes("::")) {
+		const parts = input.split("::");
+		if (parts.length > 2) return null;
+		const leftGroups = parts[0] ? parts[0].split(":").filter((g) => g) : [];
+		const rightGroups = parts[1] ? parts[1].split(":").filter((g) => g) : [];
+		const totalGroups = leftGroups.length + rightGroups.length;
+		if (totalGroups > 8) return null;
+		const zeroCount = 8 - totalGroups;
+		const zeros = Array(zeroCount).fill("0");
+		const groups = [
+			...leftGroups,
+			...zeros,
+			...rightGroups
+		];
+		return groups.map((g) => g.padStart(4, "0"));
+	} else {
+		const groups = input.split(":");
+		if (groups.length !== 8) return null;
+		return groups.map((g) => g.padStart(4, "0"));
+	}
+}
+/**
+* Compresses an IPv6 address by replacing the longest sequence of zeros with ::.
+*/
+function compressIpv6(groups) {
+	let longestStart = -1;
+	let longestLength = 0;
+	let currentStart = -1;
+	let currentLength = 0;
+	for (let i = 0; i < groups.length; i++) if (groups[i] === "0") if (currentStart === -1) {
+		currentStart = i;
+		currentLength = 1;
+	} else currentLength++;
+	else {
+		if (currentLength > longestLength) {
+			longestStart = currentStart;
+			longestLength = currentLength;
+		}
+		currentStart = -1;
+		currentLength = 0;
+	}
+	if (currentLength > longestLength) {
+		longestStart = currentStart;
+		longestLength = currentLength;
+	}
+	if (longestLength < 2) return groups.join(":");
+	const before = groups.slice(0, longestStart);
+	const after = groups.slice(longestStart + longestLength);
+	if (before.length === 0 && after.length === 0) return "::";
+	else if (before.length === 0) return "::" + after.join(":");
+	else if (after.length === 0) return before.join(":") + "::";
+	else return before.join(":") + "::" + after.join(":");
+}
+/**
+* Creates a value parser that accepts both IPv4 and IPv6 addresses.
+*
+* By default, accepts both IPv4 and IPv6 addresses. Use the `version` option
+* to restrict to a specific IP version.
+*
+* @param options Configuration options for IP validation.
+* @returns A value parser that validates IP addresses.
+*
+* @example
+* ```typescript
+* // Accept both IPv4 and IPv6
+* option("--ip", ip())
+*
+* // IPv4 only
+* option("--ipv4", ip({ version: 4 }))
+*
+* // Public IPs only (both versions)
+* option("--public-ip", ip({
+*   ipv4: { allowPrivate: false, allowLoopback: false },
+*   ipv6: { allowLinkLocal: false, allowUniqueLocal: false }
+* }))
+* ```
+*
+* @since 0.10.0
+*/
+function ip(options) {
+	const version = options?.version ?? "both";
+	const metavar = options?.metavar ?? "IP";
+	const errors = options?.errors;
+	const ipv4Parser = version === 4 || version === "both" ? ipv4({
+		...options?.ipv4,
+		errors: {
+			invalidIpv4: errors?.invalidIP,
+			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: errors?.invalidIP,
+			loopbackNotAllowed: errors?.loopbackNotAllowed,
+			linkLocalNotAllowed: errors?.linkLocalNotAllowed,
+			uniqueLocalNotAllowed: errors?.uniqueLocalNotAllowed,
+			multicastNotAllowed: errors?.multicastNotAllowed,
+			zeroNotAllowed: errors?.zeroNotAllowed
+		}
+	}) : null;
+	return {
+		$mode: "sync",
+		metavar,
+		parse(input) {
+			let ipv4Error = null;
+			let ipv6Error = null;
+			if (ipv4Parser !== null) {
+				const result = ipv4Parser.parse(input);
+				if (result.success) return result;
+				ipv4Error = result;
+				if (version === 4) return result;
+			}
+			if (ipv6Parser !== null) {
+				const result = ipv6Parser.parse(input);
+				if (result.success) return result;
+				ipv6Error = result;
+				if (version === 6) return result;
+			}
+			if (ipv4Error !== null && !ipv4Error.success) {
+				const isGeneric = ipv4Error.error.some((term) => term.type === "text" && term.text.includes("Expected"));
+				if (!isGeneric) return ipv4Error;
+			}
+			if (ipv6Error !== null && !ipv6Error.success) {
+				const isGeneric = ipv6Error.error.some((term) => term.type === "text" && term.text.includes("Expected"));
+				if (!isGeneric) return ipv6Error;
+			}
+			const errorMsg = errors?.invalidIP;
+			if (typeof errorMsg === "function") return {
+				success: false,
+				error: errorMsg(input)
+			};
+			const msg = errorMsg ?? [
+				{
+					type: "text",
+					text: "Expected a valid IP address, but got "
+				},
+				{
+					type: "value",
+					value: input
+				},
+				{
+					type: "text",
+					text: "."
+				}
+			];
+			return {
+				success: false,
+				error: msg
+			};
+		},
+		format() {
+			return metavar;
+		}
+	};
+}
+/**
+* Creates a value parser for CIDR notation (IP address with prefix length).
+*
+* Parses and validates CIDR notation like `192.168.0.0/24` or `2001:db8::/32`.
+* Returns a structured object with the normalized IP address, prefix length,
+* and IP version.
+*
+* @param options Configuration options for CIDR validation.
+* @returns A value parser that validates CIDR notation.
+*
+* @example
+* ```typescript
+* // Accept both IPv4 and IPv6 CIDR
+* option("--network", cidr())
+*
+* // IPv4 CIDR only with prefix constraints
+* option("--subnet", cidr({
+*   version: 4,
+*   minPrefix: 16,
+*   maxPrefix: 24
+* }))
+* ```
+*
+* @since 0.10.0
+*/
+function cidr(options) {
+	const version = options?.version ?? "both";
+	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",
+		metavar,
+		parse(input) {
+			const slashIndex = input.lastIndexOf("/");
+			if (slashIndex === -1) {
+				const errorMsg = errors?.invalidCidr;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(input)
+				};
+				const msg = errorMsg ?? [
+					{
+						type: "text",
+						text: "Expected a valid CIDR notation, but got "
+					},
+					{
+						type: "value",
+						value: input
+					},
+					{
+						type: "text",
+						text: "."
+					}
+				];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			const ipPart = input.slice(0, slashIndex);
+			const prefixPart = input.slice(slashIndex + 1);
+			const prefix = parseInt(prefixPart, 10);
+			if (!Number.isInteger(prefix) || prefixPart !== prefix.toString() || prefix < 0) {
+				const errorMsg = errors?.invalidCidr;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(input)
+				};
+				const msg = errorMsg ?? [
+					{
+						type: "text",
+						text: "Expected a valid CIDR notation, but got "
+					},
+					{
+						type: "value",
+						value: input
+					},
+					{
+						type: "text",
+						text: "."
+					}
+				];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			let ipVersion = null;
+			let normalizedIp = null;
+			if (ipv4Parser !== null) {
+				const result = ipv4Parser.parse(ipPart);
+				if (result.success) {
+					ipVersion = 4;
+					normalizedIp = result.value;
+					if (prefix > 32) {
+						const errorMsg = errors?.invalidPrefix;
+						if (typeof errorMsg === "function") return {
+							success: false,
+							error: errorMsg(prefix, 4)
+						};
+						const msg = errorMsg ?? [
+							{
+								type: "text",
+								text: "Expected a prefix length between 0 and "
+							},
+							{
+								type: "text",
+								text: "32"
+							},
+							{
+								type: "text",
+								text: " for IPv4, but got "
+							},
+							{
+								type: "text",
+								text: prefix.toString()
+							},
+							{
+								type: "text",
+								text: "."
+							}
+						];
+						return {
+							success: false,
+							error: msg
+						};
+					}
+				}
+			}
+			if (ipVersion === null && ipv6Parser !== null) {
+				const result = ipv6Parser.parse(ipPart);
+				if (result.success) {
+					ipVersion = 6;
+					normalizedIp = result.value;
+					if (prefix > 128) {
+						const errorMsg = errors?.invalidPrefix;
+						if (typeof errorMsg === "function") return {
+							success: false,
+							error: errorMsg(prefix, 6)
+						};
+						const msg = errorMsg ?? [
+							{
+								type: "text",
+								text: "Expected a prefix length between 0 and "
+							},
+							{
+								type: "text",
+								text: "128"
+							},
+							{
+								type: "text",
+								text: " for IPv6, but got "
+							},
+							{
+								type: "text",
+								text: prefix.toString()
+							},
+							{
+								type: "text",
+								text: "."
+							}
+						];
+						return {
+							success: false,
+							error: msg
+						};
+					}
+				}
+			}
+			if (ipVersion === null || normalizedIp === null) {
+				const errorMsg = errors?.invalidCidr;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(input)
+				};
+				const msg = errorMsg ?? [
+					{
+						type: "text",
+						text: "Expected a valid CIDR notation, but got "
+					},
+					{
+						type: "value",
+						value: input
+					},
+					{
+						type: "text",
+						text: "."
+					}
+				];
+				return {
+					success: false,
+					error: msg
+				};
+			}
+			if (minPrefix !== void 0 && prefix < minPrefix) {
+				const errorMsg = errors?.prefixBelowMinimum;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(prefix, minPrefix)
+				};
+				const msg = errorMsg ?? [
+					{
+						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
+				};
+			}
+			if (maxPrefix !== void 0 && prefix > maxPrefix) {
+				const errorMsg = errors?.prefixAboveMaximum;
+				if (typeof errorMsg === "function") return {
+					success: false,
+					error: errorMsg(prefix, maxPrefix)
+				};
+				const msg = errorMsg ?? [
+					{
+						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
+				};
+			}
+			return {
+				success: true,
+				value: {
+					address: normalizedIp,
+					prefix,
+					version: ipVersion
+				}
+			};
+		},
+		format() {
+			return metavar;
+		}
+	};
+}
 
 //#endregion
-export { choice, ensureNonEmptyString, float, integer, isNonEmptyString, isValueParser, locale, string, url, uuid };
+export { choice, cidr, domain, email, ensureNonEmptyString, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid };