@optique/core 1.0.0-dev.1547 → 1.0.0-dev.1555

package/dist/valueparser.cjs

@@ -2144,7 +2144,48 @@ 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 {
+	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() {
@@ -2221,28 +2262,51 @@ function macAddress(options) {
 				};
 			}
 			octets = octets.map((o) => o.padStart(2, "0"));
-			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
+				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.
@@ -2314,7 +2378,7 @@ function domain(options) {
 	const tooFewLabels = options?.errors?.tooFewLabels;
 	const subdomainsNotAllowed = options?.errors?.subdomainsNotAllowed;
 	const tldNotAllowed = options?.errors?.tldNotAllowed;
-	return {
+	const domainParserObj = {
 		$mode: "sync",
 		metavar,
 		placeholder: options?.placeholder ?? `example.${allowedTldsLower?.[0] ?? "com"}`,
@@ -2518,10 +2582,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.
@@ -2554,7 +2659,7 @@ function ipv6(options) {
 	const allowZero = options?.allowZero ?? true;
 	const errors = options?.errors;
 	const metavar = options?.metavar ?? "IPV6";
-	return {
+	const ipv6ParserObj = {
 		$mode: "sync",
 		metavar,
 		placeholder: allowZero ? "::" : allowLoopback ? "::1" : "2001:db8::1",
@@ -2707,10 +2812,47 @@ 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 and normalizes an IPv6 address to canonical form.
@@ -2971,7 +3113,7 @@ function ip(options) {
 		broadcastNotAllowed: errors?.broadcastNotAllowed,
 		zeroNotAllowed: errors?.zeroNotAllowed
 	} : void 0;
-	return {
+	const ipParserObj = {
 		$mode: "sync",
 		metavar,
 		placeholder: version === 6 ? ipv6Parser.placeholder : ipv4Parser.placeholder,
@@ -3031,10 +3173,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).
@@ -3113,7 +3292,7 @@ function cidr(options) {
 		broadcastNotAllowed: errors?.broadcastNotAllowed,
 		zeroNotAllowed: errors?.zeroNotAllowed
 	} : void 0;
-	return {
+	const cidrParserObj = {
 		$mode: "sync",
 		metavar,
 		get placeholder() {
@@ -3484,10 +3663,47 @@ 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

package/dist/valueparser.d.cts

@@ -49,6 +49,33 @@ interface ValueParser<M extends Mode = "sync", T = unknown> {
    * @returns A string representation of the value.
    */
   format(value: T): string;
+  /**
+   * Normalizes a value of type {@link T} according to this parser's
+   * configuration.  This applies the same canonicalization that
+   * {@link parse} would apply (e.g., case conversion, separator
+   * normalization).  Built-in implementations delegate to {@link parse}
+   * internally, so values that would fail validation are returned
+   * unchanged rather than being canonicalized.
+   *
+   * When present, combinators like `withDefault()` call this method on
+   * default values so that runtime defaults match the representation
+   * that {@link parse} would produce.
+   *
+   * Parsers that do not apply any normalization during parsing do not
+   * need to implement this method.
+   *
+   * **Limitation:** For dependency-derived value parsers (created via
+   * `deriveFrom()` or `dependency().derive()`), this method uses the
+   * default dependency value to build the inner parser, not the
+   * dependency value resolved during the current parse.  This is the
+   * same trade-off that {@link format} makes.  As a result, defaults
+   * may not be normalized according to a non-default dependency value.
+   *
+   * @param value The value to normalize.
+   * @returns The normalized value.
+   * @since 1.0.0
+   */
+  normalize?(value: T): T;
   /**
    * Provides completion suggestions for values of this type.
    * This is optional and used for shell completion functionality.

package/dist/valueparser.d.ts

@@ -49,6 +49,33 @@ interface ValueParser<M extends Mode = "sync", T = unknown> {
    * @returns A string representation of the value.
    */
   format(value: T): string;
+  /**
+   * Normalizes a value of type {@link T} according to this parser's
+   * configuration.  This applies the same canonicalization that
+   * {@link parse} would apply (e.g., case conversion, separator
+   * normalization).  Built-in implementations delegate to {@link parse}
+   * internally, so values that would fail validation are returned
+   * unchanged rather than being canonicalized.
+   *
+   * When present, combinators like `withDefault()` call this method on
+   * default values so that runtime defaults match the representation
+   * that {@link parse} would produce.
+   *
+   * Parsers that do not apply any normalization during parsing do not
+   * need to implement this method.
+   *
+   * **Limitation:** For dependency-derived value parsers (created via
+   * `deriveFrom()` or `dependency().derive()`), this method uses the
+   * default dependency value to build the inner parser, not the
+   * dependency value resolved during the current parse.  This is the
+   * same trade-off that {@link format} makes.  As a result, defaults
+   * may not be normalized according to a non-default dependency value.
+   *
+   * @param value The value to normalize.
+   * @returns The normalized value.
+   * @since 1.0.0
+   */
+  normalize?(value: T): T;
   /**
    * Provides completion suggestions for values of this type.
    * This is optional and used for shell completion functionality.