@optique/core 1.1.0-dev.2148 → 1.1.0-dev.2152

package/dist/valueparser.cjs

@@ -3088,7 +3088,7 @@ function email(options) {
 * 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)
+* - Hostnames, IPv4 addresses, and IPv6 addresses
 * - Configurable host:port separator
 * - Optional default port
 * - Host type filtering (hostname only, IP only, or both)
@@ -3099,6 +3099,8 @@ function email(options) {
 * @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.
+* @throws {TypeError} If `host.version` is provided but is not `4`, `6`, or
+*   `"both"`.
 * @since 0.10.0
 *
 * @example
@@ -3128,12 +3130,25 @@ function socketAddress(options) {
 	const defaultPort = options?.defaultPort;
 	const requirePort = options?.requirePort ?? false;
 	const hostType = options?.host?.type ?? "both";
+	const rawHostVersion = options?.host?.version;
+	if (rawHostVersion !== void 0 && rawHostVersion !== 4 && rawHostVersion !== 6 && rawHostVersion !== "both") throw new TypeError(`Expected host.version to be 4, 6, or "both", but got ${Array.isArray(rawHostVersion) ? "array" : typeof rawHostVersion}: ${String(rawHostVersion)}.`);
+	const hasLegacyIpOptions = options?.host?.ip !== void 0;
+	const hasNewIpOptions = rawHostVersion !== void 0 || options?.host?.ipv4 !== void 0 || options?.host?.ipv6 !== void 0;
+	const hostVersion = rawHostVersion ?? (hasLegacyIpOptions && !hasNewIpOptions ? 4 : "both");
 	const hostnameParser = hostname({
 		...options?.host?.hostname,
 		metavar: "HOST"
 	});
-	const ipParser = ipv4({
+	const ipv4Options = {
 		...options?.host?.ip,
+		...options?.host?.ipv4
+	};
+	const ipv4Parser = ipv4({
+		...ipv4Options,
+		metavar: "HOST"
+	});
+	const ipv6Parser = ipv6({
+		...options?.host?.ipv6,
 		metavar: "HOST"
 	});
 	const disambiguationParser = hostType === "ip" ? hostname({
@@ -3151,6 +3166,15 @@ function socketAddress(options) {
 	function looksLikeIpv4(input) {
 		return /^\d+\.\d+\.\d+\.\d+$/.test(input);
 	}
+	function looksLikeIpv6(input) {
+		const colonCount = input.match(/:/g)?.length ?? 0;
+		return colonCount >= 2 && (input.includes("::") || /^[0-9a-fA-F:.]+$/.test(input));
+	}
+	function looksLikeBareIpv6(input) {
+		if (!looksLikeIpv6(input)) return false;
+		if (parseAndNormalizeIpv6(input) !== null) return true;
+		return input.includes("::") || !input.includes(".");
+	}
 	function looksLikeAltIpv4Literal(input) {
 		if (/^0[xX][0-9a-fA-F]+$/.test(input)) {
 			const n = parseInt(input.slice(2), 16);
@@ -3176,6 +3200,22 @@ function socketAddress(options) {
 		}
 		return false;
 	}
+	function parseIpHost(hostInput) {
+		if (hostVersion === 4) return ipv4Parser.parse(hostInput);
+		if (hostVersion === 6) return ipv6Parser.parse(hostInput);
+		if (looksLikeIpv6(hostInput)) {
+			const result = ipv6Parser.parse(hostInput);
+			if (result.success) {
+				const mappedOctets = extractIpv4FromMapped(result.value);
+				if (mappedOctets !== null) {
+					const restrictionError = checkIpv4MappedRestrictions(mappedOctets, result.value, ipv4Options, void 0);
+					if (restrictionError !== null) return restrictionError;
+				}
+			}
+			return result;
+		}
+		return ipv4Parser.parse(hostInput);
+	}
 	function parseHost(hostInput) {
 		if (hostType === "hostname") {
 			if (looksLikeAltIpv4Literal(hostInput)) return {
@@ -3187,22 +3227,106 @@ function socketAddress(options) {
 				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 (hostType === "ip") return parseIpHost(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);
+			if (looksLikeIpv4(hostInput)) return parseIpHost(hostInput);
+			if (looksLikeIpv6(hostInput)) return parseIpHost(hostInput);
 			return hostnameParser.parse(hostInput);
 		}
 	}
-	return {
+	function makeInvalidFormatError(input) {
+		const errorMsg = options?.errors?.invalidFormat;
+		const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Expected a socket address in format ${require_message.text(formatExample)}, but got ${input}.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	function makeMissingPortError(input) {
+		const errorMsg = options?.errors?.missingPort;
+		const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? require_message.message`Port number is required but was not specified.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	function parseBracketedHost(input, trimmed, canOmitPort) {
+		if (!trimmed.startsWith("[")) return void 0;
+		const closingBracket = trimmed.indexOf("]");
+		if (closingBracket === -1) return makeInvalidFormatError(input);
+		const hostInput = trimmed.slice(1, closingBracket);
+		if (!looksLikeBareIpv6(hostInput)) return makeInvalidFormatError(input);
+		const rest = trimmed.slice(closingBracket + 1).trimStart();
+		const hostResult = parseHost(hostInput);
+		if (rest === "") {
+			if (!hostResult.success) {
+				if (options?.errors?.invalidFormat) return makeInvalidFormatError(input);
+				return {
+					success: false,
+					error: hostResult.error
+				};
+			}
+			if (canOmitPort) return {
+				success: true,
+				value: {
+					host: hostResult.value,
+					port: defaultPort
+				}
+			};
+			return makeMissingPortError(input);
+		}
+		if (!rest.startsWith(separator)) return makeInvalidFormatError(input);
+		const portPart = rest.slice(separator.length).trim();
+		if (portPart === "") {
+			if (!hostResult.success) {
+				if (options?.errors?.invalidFormat) return makeInvalidFormatError(input);
+				return {
+					success: false,
+					error: hostResult.error
+				};
+			}
+			return makeMissingPortError(input);
+		}
+		const portResult = portParser.parse(portPart);
+		if (!hostResult.success) {
+			if (options?.errors?.invalidFormat) return makeInvalidFormatError(input);
+			return {
+				success: false,
+				error: hostResult.error
+			};
+		}
+		if (portResult.success) return {
+			success: true,
+			value: {
+				host: hostResult.value,
+				port: portResult.value
+			}
+		};
+		if (options?.errors?.invalidFormat) return makeInvalidFormatError(input);
+		if (/^[0-9]+$/.test(portPart)) return {
+			success: false,
+			error: portResult.error
+		};
+		return makeInvalidFormatError(input);
+	}
+	function isSocketAddressValue(value) {
+		return typeof value === "object" && value !== null && "host" in value && typeof value.host === "string" && "port" in value && typeof value.port === "number";
+	}
+	function formatSocketAddressValue(value) {
+		const ipv6Host = parseAndNormalizeIpv6(value.host);
+		if (separator === ":" && ipv6Host !== null) return `[${ipv6Host}]${separator}${value.port}`;
+		return `${value.host}${separator}${value.port}`;
+	}
+	const parser = {
 		mode: "sync",
 		metavar: metavar$1,
 		get placeholder() {
 			return {
-				host: hostType === "ip" ? ipParser.placeholder : hostnameParser.placeholder,
+				host: hostType === "ip" ? hostVersion === 6 ? ipv6Parser.placeholder : ipv4Parser.placeholder : hostnameParser.placeholder,
 				port: defaultPort ?? portParser.placeholder
 			};
 		},
@@ -3210,6 +3334,28 @@ function socketAddress(options) {
 			const trimmed = input.trim();
 			const searchInput = input.trimStart();
 			const canOmitPort = defaultPort !== void 0 && !requirePort;
+			if (separator === ":") {
+				const bracketedResult = parseBracketedHost(input, trimmed, canOmitPort);
+				if (bracketedResult !== void 0) return bracketedResult;
+				if (looksLikeBareIpv6(trimmed)) {
+					const hostResult = parseHost(trimmed);
+					if (hostResult.success) {
+						if (canOmitPort) return {
+							success: true,
+							value: {
+								host: hostResult.value,
+								port: defaultPort
+							}
+						};
+						return makeMissingPortError(input);
+					}
+					if (options?.errors?.invalidFormat) return makeInvalidFormatError(input);
+					return {
+						success: false,
+						error: hostResult.error
+					};
+				}
+			}
 			let firstHostError;
 			let validHostInvalidPortError;
 			let trailingSepHost;
@@ -3407,9 +3553,19 @@ function socketAddress(options) {
 			};
 		},
 		format(value) {
-			return `${value.host}${separator}${value.port}`;
+			return formatSocketAddressValue(value);
+		},
+		normalize(value) {
+			if (!isSocketAddressValue(value)) return value;
+			try {
+				const result = parser.parse(formatSocketAddressValue(value));
+				return result.success ? result.value : value;
+			} catch {
+				return value;
+			}
 		}
 	};
+	return parser;
 }
 function portRange(options) {
 	checkBooleanOption(options, "disallowWellKnown");
@@ -4323,7 +4479,7 @@ function parseAndNormalizeIpv6(input) {
 		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;
+		if (totalGroups >= 8) return null;
 		const zeroCount = 8 - totalGroups;
 		const zeros = Array(zeroCount).fill("0");
 		groups = [
@@ -4354,7 +4510,7 @@ function expandIpv6(input) {
 		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;
+		if (totalGroups >= 8) return null;
 		const zeroCount = 8 - totalGroups;
 		const zeros = Array(zeroCount).fill("0");
 		const groups = [

package/dist/valueparser.d.cts

@@ -1572,10 +1572,34 @@ interface SocketAddressOptions {
      */
     readonly hostname?: Omit<HostnameOptions, "metavar" | "errors">;
     /**
-     * Options for IP validation (when type is "ip" or "both").
-     * Currently only supports IPv4.
+     * IP version to accept when `type` is `"ip"` or `"both"`.
+     * - `4`: IPv4 only
+     * - `6`: IPv6 only
+     * - `"both"`: Accept both IPv4 and IPv6
+     *
+     * @default `"both"` unless only the legacy {@link ip} field is set, in
+     * which case the default is `4` to preserve IPv4-only compatibility.
+     * @since 1.1.0
+     */
+    readonly version?: 4 | 6 | "both";
+    /**
+     * Options for IPv4 validation (when type is "ip" or "both").
+     * This is kept for backwards compatibility; prefer {@link ipv4} for
+     * new code.
      */
     readonly ip?: Omit<Ipv4Options, "metavar" | "errors">;
+    /**
+     * Options for IPv4 validation (when type is "ip" or "both").
+     *
+     * @since 1.1.0
+     */
+    readonly ipv4?: Omit<Ipv4Options, "metavar" | "errors">;
+    /**
+     * Options for IPv6 validation (when type is "ip" or "both").
+     *
+     * @since 1.1.0
+     */
+    readonly ipv6?: Omit<Ipv6Options, "metavar" | "errors">;
   };
   /**
    * Options for port validation.
@@ -1601,7 +1625,7 @@ interface SocketAddressOptions {
  * 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)
+ * - Hostnames, IPv4 addresses, and IPv6 addresses
  * - Configurable host:port separator
  * - Optional default port
  * - Host type filtering (hostname only, IP only, or both)
@@ -1612,6 +1636,8 @@ interface SocketAddressOptions {
  * @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.
+ * @throws {TypeError} If `host.version` is provided but is not `4`, `6`, or
+ *   `"both"`.
  * @since 0.10.0
  *
  * @example

package/dist/valueparser.d.ts

@@ -1572,10 +1572,34 @@ interface SocketAddressOptions {
      */
     readonly hostname?: Omit<HostnameOptions, "metavar" | "errors">;
     /**
-     * Options for IP validation (when type is "ip" or "both").
-     * Currently only supports IPv4.
+     * IP version to accept when `type` is `"ip"` or `"both"`.
+     * - `4`: IPv4 only
+     * - `6`: IPv6 only
+     * - `"both"`: Accept both IPv4 and IPv6
+     *
+     * @default `"both"` unless only the legacy {@link ip} field is set, in
+     * which case the default is `4` to preserve IPv4-only compatibility.
+     * @since 1.1.0
+     */
+    readonly version?: 4 | 6 | "both";
+    /**
+     * Options for IPv4 validation (when type is "ip" or "both").
+     * This is kept for backwards compatibility; prefer {@link ipv4} for
+     * new code.
      */
     readonly ip?: Omit<Ipv4Options, "metavar" | "errors">;
+    /**
+     * Options for IPv4 validation (when type is "ip" or "both").
+     *
+     * @since 1.1.0
+     */
+    readonly ipv4?: Omit<Ipv4Options, "metavar" | "errors">;
+    /**
+     * Options for IPv6 validation (when type is "ip" or "both").
+     *
+     * @since 1.1.0
+     */
+    readonly ipv6?: Omit<Ipv6Options, "metavar" | "errors">;
   };
   /**
    * Options for port validation.
@@ -1601,7 +1625,7 @@ interface SocketAddressOptions {
  * 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)
+ * - Hostnames, IPv4 addresses, and IPv6 addresses
  * - Configurable host:port separator
  * - Optional default port
  * - Host type filtering (hostname only, IP only, or both)
@@ -1612,6 +1636,8 @@ interface SocketAddressOptions {
  * @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.
+ * @throws {TypeError} If `host.version` is provided but is not `4`, `6`, or
+ *   `"both"`.
  * @since 0.10.0
  *
  * @example

package/dist/valueparser.js

@@ -3088,7 +3088,7 @@ function email(options) {
 * 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)
+* - Hostnames, IPv4 addresses, and IPv6 addresses
 * - Configurable host:port separator
 * - Optional default port
 * - Host type filtering (hostname only, IP only, or both)
@@ -3099,6 +3099,8 @@ function email(options) {
 * @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.
+* @throws {TypeError} If `host.version` is provided but is not `4`, `6`, or
+*   `"both"`.
 * @since 0.10.0
 *
 * @example
@@ -3128,12 +3130,25 @@ function socketAddress(options) {
 	const defaultPort = options?.defaultPort;
 	const requirePort = options?.requirePort ?? false;
 	const hostType = options?.host?.type ?? "both";
+	const rawHostVersion = options?.host?.version;
+	if (rawHostVersion !== void 0 && rawHostVersion !== 4 && rawHostVersion !== 6 && rawHostVersion !== "both") throw new TypeError(`Expected host.version to be 4, 6, or "both", but got ${Array.isArray(rawHostVersion) ? "array" : typeof rawHostVersion}: ${String(rawHostVersion)}.`);
+	const hasLegacyIpOptions = options?.host?.ip !== void 0;
+	const hasNewIpOptions = rawHostVersion !== void 0 || options?.host?.ipv4 !== void 0 || options?.host?.ipv6 !== void 0;
+	const hostVersion = rawHostVersion ?? (hasLegacyIpOptions && !hasNewIpOptions ? 4 : "both");
 	const hostnameParser = hostname({
 		...options?.host?.hostname,
 		metavar: "HOST"
 	});
-	const ipParser = ipv4({
+	const ipv4Options = {
 		...options?.host?.ip,
+		...options?.host?.ipv4
+	};
+	const ipv4Parser = ipv4({
+		...ipv4Options,
+		metavar: "HOST"
+	});
+	const ipv6Parser = ipv6({
+		...options?.host?.ipv6,
 		metavar: "HOST"
 	});
 	const disambiguationParser = hostType === "ip" ? hostname({
@@ -3151,6 +3166,15 @@ function socketAddress(options) {
 	function looksLikeIpv4(input) {
 		return /^\d+\.\d+\.\d+\.\d+$/.test(input);
 	}
+	function looksLikeIpv6(input) {
+		const colonCount = input.match(/:/g)?.length ?? 0;
+		return colonCount >= 2 && (input.includes("::") || /^[0-9a-fA-F:.]+$/.test(input));
+	}
+	function looksLikeBareIpv6(input) {
+		if (!looksLikeIpv6(input)) return false;
+		if (parseAndNormalizeIpv6(input) !== null) return true;
+		return input.includes("::") || !input.includes(".");
+	}
 	function looksLikeAltIpv4Literal(input) {
 		if (/^0[xX][0-9a-fA-F]+$/.test(input)) {
 			const n = parseInt(input.slice(2), 16);
@@ -3176,6 +3200,22 @@ function socketAddress(options) {
 		}
 		return false;
 	}
+	function parseIpHost(hostInput) {
+		if (hostVersion === 4) return ipv4Parser.parse(hostInput);
+		if (hostVersion === 6) return ipv6Parser.parse(hostInput);
+		if (looksLikeIpv6(hostInput)) {
+			const result = ipv6Parser.parse(hostInput);
+			if (result.success) {
+				const mappedOctets = extractIpv4FromMapped(result.value);
+				if (mappedOctets !== null) {
+					const restrictionError = checkIpv4MappedRestrictions(mappedOctets, result.value, ipv4Options, void 0);
+					if (restrictionError !== null) return restrictionError;
+				}
+			}
+			return result;
+		}
+		return ipv4Parser.parse(hostInput);
+	}
 	function parseHost(hostInput) {
 		if (hostType === "hostname") {
 			if (looksLikeAltIpv4Literal(hostInput)) return {
@@ -3187,22 +3227,106 @@ function socketAddress(options) {
 				error: message`Expected a valid hostname, but got ${hostInput}.`
 			};
 			return hostnameParser.parse(hostInput);
-		} else if (hostType === "ip") return ipParser.parse(hostInput);
+		} else if (hostType === "ip") return parseIpHost(hostInput);
 		else {
 			if (looksLikeAltIpv4Literal(hostInput)) return {
 				success: false,
 				error: message`${hostInput} appears to be a non-standard IPv4 address notation.`
 			};
-			if (looksLikeIpv4(hostInput)) return ipParser.parse(hostInput);
+			if (looksLikeIpv4(hostInput)) return parseIpHost(hostInput);
+			if (looksLikeIpv6(hostInput)) return parseIpHost(hostInput);
 			return hostnameParser.parse(hostInput);
 		}
 	}
-	return {
+	function makeInvalidFormatError(input) {
+		const errorMsg = options?.errors?.invalidFormat;
+		const msg = typeof errorMsg === "function" ? errorMsg(input) : errorMsg ?? message`Expected a socket address in format ${text(formatExample)}, but got ${input}.`;
+		return {
+			success: false,
+			error: msg
+		};
+	}
+	function makeMissingPortError(input) {
+		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
+		};
+	}
+	function parseBracketedHost(input, trimmed, canOmitPort) {
+		if (!trimmed.startsWith("[")) return void 0;
+		const closingBracket = trimmed.indexOf("]");
+		if (closingBracket === -1) return makeInvalidFormatError(input);
+		const hostInput = trimmed.slice(1, closingBracket);
+		if (!looksLikeBareIpv6(hostInput)) return makeInvalidFormatError(input);
+		const rest = trimmed.slice(closingBracket + 1).trimStart();
+		const hostResult = parseHost(hostInput);
+		if (rest === "") {
+			if (!hostResult.success) {
+				if (options?.errors?.invalidFormat) return makeInvalidFormatError(input);
+				return {
+					success: false,
+					error: hostResult.error
+				};
+			}
+			if (canOmitPort) return {
+				success: true,
+				value: {
+					host: hostResult.value,
+					port: defaultPort
+				}
+			};
+			return makeMissingPortError(input);
+		}
+		if (!rest.startsWith(separator)) return makeInvalidFormatError(input);
+		const portPart = rest.slice(separator.length).trim();
+		if (portPart === "") {
+			if (!hostResult.success) {
+				if (options?.errors?.invalidFormat) return makeInvalidFormatError(input);
+				return {
+					success: false,
+					error: hostResult.error
+				};
+			}
+			return makeMissingPortError(input);
+		}
+		const portResult = portParser.parse(portPart);
+		if (!hostResult.success) {
+			if (options?.errors?.invalidFormat) return makeInvalidFormatError(input);
+			return {
+				success: false,
+				error: hostResult.error
+			};
+		}
+		if (portResult.success) return {
+			success: true,
+			value: {
+				host: hostResult.value,
+				port: portResult.value
+			}
+		};
+		if (options?.errors?.invalidFormat) return makeInvalidFormatError(input);
+		if (/^[0-9]+$/.test(portPart)) return {
+			success: false,
+			error: portResult.error
+		};
+		return makeInvalidFormatError(input);
+	}
+	function isSocketAddressValue(value) {
+		return typeof value === "object" && value !== null && "host" in value && typeof value.host === "string" && "port" in value && typeof value.port === "number";
+	}
+	function formatSocketAddressValue(value) {
+		const ipv6Host = parseAndNormalizeIpv6(value.host);
+		if (separator === ":" && ipv6Host !== null) return `[${ipv6Host}]${separator}${value.port}`;
+		return `${value.host}${separator}${value.port}`;
+	}
+	const parser = {
 		mode: "sync",
 		metavar: metavar$1,
 		get placeholder() {
 			return {
-				host: hostType === "ip" ? ipParser.placeholder : hostnameParser.placeholder,
+				host: hostType === "ip" ? hostVersion === 6 ? ipv6Parser.placeholder : ipv4Parser.placeholder : hostnameParser.placeholder,
 				port: defaultPort ?? portParser.placeholder
 			};
 		},
@@ -3210,6 +3334,28 @@ function socketAddress(options) {
 			const trimmed = input.trim();
 			const searchInput = input.trimStart();
 			const canOmitPort = defaultPort !== void 0 && !requirePort;
+			if (separator === ":") {
+				const bracketedResult = parseBracketedHost(input, trimmed, canOmitPort);
+				if (bracketedResult !== void 0) return bracketedResult;
+				if (looksLikeBareIpv6(trimmed)) {
+					const hostResult = parseHost(trimmed);
+					if (hostResult.success) {
+						if (canOmitPort) return {
+							success: true,
+							value: {
+								host: hostResult.value,
+								port: defaultPort
+							}
+						};
+						return makeMissingPortError(input);
+					}
+					if (options?.errors?.invalidFormat) return makeInvalidFormatError(input);
+					return {
+						success: false,
+						error: hostResult.error
+					};
+				}
+			}
 			let firstHostError;
 			let validHostInvalidPortError;
 			let trailingSepHost;
@@ -3407,9 +3553,19 @@ function socketAddress(options) {
 			};
 		},
 		format(value) {
-			return `${value.host}${separator}${value.port}`;
+			return formatSocketAddressValue(value);
+		},
+		normalize(value) {
+			if (!isSocketAddressValue(value)) return value;
+			try {
+				const result = parser.parse(formatSocketAddressValue(value));
+				return result.success ? result.value : value;
+			} catch {
+				return value;
+			}
 		}
 	};
+	return parser;
 }
 function portRange(options) {
 	checkBooleanOption(options, "disallowWellKnown");
@@ -4323,7 +4479,7 @@ function parseAndNormalizeIpv6(input) {
 		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;
+		if (totalGroups >= 8) return null;
 		const zeroCount = 8 - totalGroups;
 		const zeros = Array(zeroCount).fill("0");
 		groups = [
@@ -4354,7 +4510,7 @@ function expandIpv6(input) {
 		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;
+		if (totalGroups >= 8) return null;
 		const zeroCount = 8 - totalGroups;
 		const zeros = Array(zeroCount).fill("0");
 		const groups = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.1.0-dev.2148",
+  "version": "1.1.0-dev.2152",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -200,7 +200,7 @@
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
-    "@optique/env": "1.1.0-dev.2148+ab56ac96"
+    "@optique/env": "1.1.0-dev.2152+cc0a0741"
   },
   "scripts": {
     "build": "tsdown",