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

package/dist/modifiers.js

@@ -118,7 +118,7 @@ function optional(parser) {
 	const wrappedDependencyMarker = innerHasWrappedDependency ? { [wrappedDependencySourceMarker]: parser[wrappedDependencySourceMarker] } : innerHasDirectDependency ? { [wrappedDependencySourceMarker]: syncParser.initialState } : {};
 	const hasWrappedDependencySource = wrappedDependencySourceMarker in wrappedDependencyMarker;
 	const wrappedPendingState = hasWrappedDependencySource ? wrappedDependencyMarker[wrappedDependencySourceMarker] : void 0;
-	return {
+	const optionalParser = {
 		$mode: parser.$mode,
 		$valueType: [],
 		$stateType: [],
@@ -175,6 +175,18 @@ function optional(parser) {
 			return syncParser.getDocFragments(innerState, defaultValue);
 		}
 	};
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(optionalParser, "normalizeValue", {
+			value(v) {
+				if (v == null) return v;
+				return innerNormalize(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	return optionalParser;
 }
 /**
 * Error type for structured error messages in {@link withDefault} default value callbacks.
@@ -257,12 +269,19 @@ function withDefault(parser, defaultValue, options) {
 			return dispatchByMode(parser.$mode, () => parseOptionalStyleSync(context, syncParser), () => parseOptionalStyleAsync(context, parser));
 		},
 		complete(state) {
+			function evaluateDefault() {
+				const raw = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+				if (typeof parser.normalizeValue === "function") try {
+					return parser.normalizeValue(raw);
+				} catch {}
+				return raw;
+			}
 			if (!Array.isArray(state)) {
 				if (transformsDependencyValue(parser)) {
 					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
 					const handleInnerResult = (res) => {
 						if (isDependencySourceState(res)) try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return createDependencySourceState({
 								success: true,
 								value
@@ -274,7 +293,7 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 						try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return {
 								success: true,
 								value
@@ -289,7 +308,7 @@ function withDefault(parser, defaultValue, options) {
 					return mapModeValue(parser.$mode, innerResult, handleInnerResult);
 				}
 				if (isWrappedDependencySource(parser)) try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					const pendingState = parser[wrappedDependencySourceMarker];
 					return createDependencySourceState({
 						success: true,
@@ -306,7 +325,7 @@ function withDefault(parser, defaultValue, options) {
 					return innerResult;
 				}
 				try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					return {
 						success: true,
 						value
@@ -323,7 +342,7 @@ function withDefault(parser, defaultValue, options) {
 					const innerResult = dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
 					const handleInnerResult = (res) => {
 						if (isDependencySourceState(res)) try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return createDependencySourceState({
 								success: true,
 								value
@@ -335,7 +354,7 @@ function withDefault(parser, defaultValue, options) {
 							};
 						}
 						try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return {
 								success: true,
 								value
@@ -350,7 +369,7 @@ function withDefault(parser, defaultValue, options) {
 					return mapModeValue(parser.$mode, innerResult, handleInnerResult);
 				}
 				try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					return createDependencySourceState({
 						success: true,
 						value
@@ -373,7 +392,11 @@ function withDefault(parser, defaultValue, options) {
 				kind: "available",
 				state: state.state[0]
 			};
-			const fragments = syncParser.getDocFragments(innerState, getDocDefaultValue(upperDefaultValue));
+			let docDefault = getDocDefaultValue(upperDefaultValue);
+			if (docDefault != null && typeof parser.normalizeValue === "function") try {
+				docDefault = parser.normalizeValue(docDefault);
+			} catch {}
+			const fragments = syncParser.getDocFragments(innerState, docDefault);
 			if (options?.message) {
 				const modifiedFragments = fragments.fragments.map((fragment) => {
 					if (fragment.type === "entry") return {
@@ -397,6 +420,20 @@ function withDefault(parser, defaultValue, options) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(withDefaultParser, "normalizeValue", {
+			value(v) {
+				try {
+					return innerNormalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	return withDefaultParser;
 }
 /**
@@ -510,6 +547,7 @@ function map(parser, transform) {
 			return parser.getDocFragments(state, void 0);
 		}
 	};
+	delete mappedParser.normalizeValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
 		get() {
 			try {
@@ -828,6 +866,27 @@ function multiple(parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") {
+		const innerNormalize = parser.normalizeValue.bind(parser);
+		Object.defineProperty(resultParser, "normalizeValue", {
+			value(values) {
+				if (!Array.isArray(values)) return values;
+				let changed = false;
+				const result = values.map((v) => {
+					try {
+						const n = innerNormalize(v);
+						if (n !== v) changed = true;
+						return n;
+					} catch {
+						return v;
+					}
+				});
+				return changed ? result : values;
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	return resultParser;
 }
 /**
@@ -916,6 +975,11 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(nonEmptyParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return nonEmptyParser;
 }
 

package/dist/parser.d.cts

@@ -225,6 +225,26 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   shouldDeferCompletion?(state: TState): boolean;
+  /**
+   * Normalizes a parsed value according to the underlying value parser's
+   * configuration.  When present, {@link withDefault} calls this method
+   * on default values so that runtime defaults match the representation
+   * that the value parser's `parse()` would produce.
+   *
+   * Primitive parsers ({@link option}, {@link argument}) implement this
+   * by delegating to {@link ValueParser.normalize}.  Combinator wrappers
+   * ({@link optional}, {@link withDefault}) forward it from inner parsers.
+   *
+   * Exclusive combinators ({@link or}, `longestMatch()`) and
+   * multi-source combinators (`merge()`) intentionally do *not*
+   * implement this method because the active branch or key ownership
+   * is unknown at default time.
+   *
+   * @param value The value to normalize.
+   * @returns The normalized value.
+   * @since 1.0.0
+   */
+  normalizeValue?(value: TValue): TValue;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.

package/dist/parser.d.ts

@@ -225,6 +225,26 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   shouldDeferCompletion?(state: TState): boolean;
+  /**
+   * Normalizes a parsed value according to the underlying value parser's
+   * configuration.  When present, {@link withDefault} calls this method
+   * on default values so that runtime defaults match the representation
+   * that the value parser's `parse()` would produce.
+   *
+   * Primitive parsers ({@link option}, {@link argument}) implement this
+   * by delegating to {@link ValueParser.normalize}.  Combinator wrappers
+   * ({@link optional}, {@link withDefault}) forward it from inner parsers.
+   *
+   * Exclusive combinators ({@link or}, `longestMatch()`) and
+   * multi-source combinators (`merge()`) intentionally do *not*
+   * implement this method because the active branch or key ownership
+   * is unknown at default time.
+   *
+   * @param value The value to normalize.
+   * @returns The normalized value.
+   * @since 1.0.0
+   */
+  normalizeValue?(value: TValue): TValue;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.

package/dist/primitives.cjs

@@ -564,6 +564,20 @@ function option(...args) {
 			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
 		}
 	};
+	if (valueParser != null && typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (valueParser != null) Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -918,6 +932,20 @@ function argument(valueParser, options = {}) {
 			return `argument()`;
 		}
 	};
+	if (typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -1136,6 +1164,11 @@ function command(name, parser, options = {}) {
 			return `command(${JSON.stringify(name)})`;
 		}
 	};
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(result, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**

package/dist/primitives.js

@@ -564,6 +564,20 @@ function option(...args) {
 			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
 		}
 	};
+	if (valueParser != null && typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (valueParser != null) Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -918,6 +932,20 @@ function argument(valueParser, options = {}) {
 			return `argument()`;
 		}
 	};
+	if (typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -1136,6 +1164,11 @@ function command(name, parser, options = {}) {
 			return `command(${JSON.stringify(name)})`;
 		}
 	};
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(result, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**

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