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

package/dist/constructs.cjs

@@ -491,7 +491,7 @@ function or(...args) {
 			success: false
 		};
 	};
-	return {
+	const singleResult = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -535,6 +535,7 @@ function or(...args) {
 			};
 		}
 	};
+	return singleResult;
 }
 /**
 * @since 0.5.0
@@ -630,7 +631,7 @@ function longestMatch(...args) {
 			success: false
 		};
 	};
-	return {
+	const multiResult = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -681,6 +682,7 @@ function longestMatch(...args) {
 			};
 		}
 	};
+	return multiResult;
 }
 /**
 * Internal sync helper for object suggest functionality.
@@ -1219,7 +1221,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			success: false
 		};
 	};
-	return {
+	const objectParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -1423,6 +1425,28 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			})) };
 		}
 	};
+	const fieldNormalizers = [];
+	for (const [key, fieldParser] of parserPairs) if (typeof fieldParser.normalizeValue === "function") fieldNormalizers.push([key, fieldParser.normalizeValue.bind(fieldParser)]);
+	if (fieldNormalizers.length > 0) Object.defineProperty(objectParser, "normalizeValue", {
+		value(obj) {
+			if (typeof obj !== "object" || obj == null) return obj;
+			let changed = false;
+			let result;
+			for (const [key, normalize] of fieldNormalizers) if (Object.hasOwn(obj, key)) try {
+				const original = obj[key];
+				const normalized = normalize(original);
+				if (normalized !== original) {
+					if (!result) result = { ...obj };
+					result[key] = normalized;
+					changed = true;
+				}
+			} catch {}
+			return changed ? result : obj;
+		},
+		configurable: true,
+		enumerable: false
+	});
+	return objectParser;
 }
 function suggestTupleSync(context, prefix, parsers) {
 	const suggestions = [];
@@ -1594,7 +1618,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			consumed: allConsumed
 		};
 	};
-	return {
+	const tupleParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -1768,6 +1792,31 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			return label ? `tuple(${JSON.stringify(label)}, ${parsersStr})` : `tuple(${parsersStr})`;
 		}
 	};
+	const tupleNormalizers = [];
+	for (let i = 0; i < parsers.length; i++) {
+		const p = parsers[i];
+		if (typeof p.normalizeValue === "function") tupleNormalizers.push([i, p.normalizeValue.bind(p)]);
+	}
+	if (tupleNormalizers.length > 0) Object.defineProperty(tupleParser, "normalizeValue", {
+		value(arr) {
+			if (!Array.isArray(arr)) return arr;
+			let changed = false;
+			let result;
+			for (const [idx, normalize] of tupleNormalizers) if (idx < arr.length && Object.hasOwn(arr, idx)) try {
+				const original = arr[idx];
+				const normalized = normalize(original);
+				if (normalized !== original) {
+					if (!result) result = [...arr];
+					result[idx] = normalized;
+					changed = true;
+				}
+			} catch {}
+			return changed ? result : arr;
+		},
+		configurable: true,
+		enumerable: false
+	});
+	return tupleParser;
 }
 function merge(...args) {
 	const label = typeof args[0] === "string" ? args[0] : void 0;
@@ -1915,7 +1964,7 @@ function merge(...args) {
 		};
 	};
 	const mergedFieldParsers = collectChildFieldParsers(parsers);
-	return {
+	const mergeParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -2134,6 +2183,7 @@ function merge(...args) {
 			};
 		}
 	};
+	return mergeParser;
 }
 /**
 * Builds a dependency registry from the pre-parsed context state and returns
@@ -2597,6 +2647,11 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(groupParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return groupParser;
 }
 /**

package/dist/constructs.js

@@ -491,7 +491,7 @@ function or(...args) {
 			success: false
 		};
 	};
-	return {
+	const singleResult = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -535,6 +535,7 @@ function or(...args) {
 			};
 		}
 	};
+	return singleResult;
 }
 /**
 * @since 0.5.0
@@ -630,7 +631,7 @@ function longestMatch(...args) {
 			success: false
 		};
 	};
-	return {
+	const multiResult = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -681,6 +682,7 @@ function longestMatch(...args) {
 			};
 		}
 	};
+	return multiResult;
 }
 /**
 * Internal sync helper for object suggest functionality.
@@ -1219,7 +1221,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			success: false
 		};
 	};
-	return {
+	const objectParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -1423,6 +1425,28 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			})) };
 		}
 	};
+	const fieldNormalizers = [];
+	for (const [key, fieldParser] of parserPairs) if (typeof fieldParser.normalizeValue === "function") fieldNormalizers.push([key, fieldParser.normalizeValue.bind(fieldParser)]);
+	if (fieldNormalizers.length > 0) Object.defineProperty(objectParser, "normalizeValue", {
+		value(obj) {
+			if (typeof obj !== "object" || obj == null) return obj;
+			let changed = false;
+			let result;
+			for (const [key, normalize] of fieldNormalizers) if (Object.hasOwn(obj, key)) try {
+				const original = obj[key];
+				const normalized = normalize(original);
+				if (normalized !== original) {
+					if (!result) result = { ...obj };
+					result[key] = normalized;
+					changed = true;
+				}
+			} catch {}
+			return changed ? result : obj;
+		},
+		configurable: true,
+		enumerable: false
+	});
+	return objectParser;
 }
 function suggestTupleSync(context, prefix, parsers) {
 	const suggestions = [];
@@ -1594,7 +1618,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			consumed: allConsumed
 		};
 	};
-	return {
+	const tupleParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -1768,6 +1792,31 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			return label ? `tuple(${JSON.stringify(label)}, ${parsersStr})` : `tuple(${parsersStr})`;
 		}
 	};
+	const tupleNormalizers = [];
+	for (let i = 0; i < parsers.length; i++) {
+		const p = parsers[i];
+		if (typeof p.normalizeValue === "function") tupleNormalizers.push([i, p.normalizeValue.bind(p)]);
+	}
+	if (tupleNormalizers.length > 0) Object.defineProperty(tupleParser, "normalizeValue", {
+		value(arr) {
+			if (!Array.isArray(arr)) return arr;
+			let changed = false;
+			let result;
+			for (const [idx, normalize] of tupleNormalizers) if (idx < arr.length && Object.hasOwn(arr, idx)) try {
+				const original = arr[idx];
+				const normalized = normalize(original);
+				if (normalized !== original) {
+					if (!result) result = [...arr];
+					result[idx] = normalized;
+					changed = true;
+				}
+			} catch {}
+			return changed ? result : arr;
+		},
+		configurable: true,
+		enumerable: false
+	});
+	return tupleParser;
 }
 function merge(...args) {
 	const label = typeof args[0] === "string" ? args[0] : void 0;
@@ -1915,7 +1964,7 @@ function merge(...args) {
 		};
 	};
 	const mergedFieldParsers = collectChildFieldParsers(parsers);
-	return {
+	const mergeParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -2134,6 +2183,7 @@ function merge(...args) {
 			};
 		}
 	};
+	return mergeParser;
 }
 /**
 * Builds a dependency registry from the pre-parsed context state and returns
@@ -2597,6 +2647,11 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(groupParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return groupParser;
 }
 /**

package/dist/dependency.cjs

@@ -199,6 +199,25 @@ function deriveFromAsync(options) {
 function isAsyncModeParser(parser) {
 	return parser.$mode === "async";
 }
+/**
+* Shared helper for derived value parser `normalize()` implementations.
+* Builds the inner parser from the factory and delegates to its
+* `normalize()` if available, falling back to the original value on error.
+*/
+function normalizeWithDerivedParser(value, getParser) {
+	let derivedParser;
+	try {
+		derivedParser = getParser();
+	} catch {
+		return value;
+	}
+	if (derivedParser && typeof derivedParser.normalize === "function") try {
+		return derivedParser.normalize(value);
+	} catch {
+		return value;
+	}
+	return value;
+}
 function createSyncDerivedFromParser(sourceId, options) {
 	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
 	return {
@@ -271,6 +290,9 @@ function createSyncDerivedFromParser(sourceId, options) {
 			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
 			yield* derivedParser.suggest(prefix);
 		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(...options.defaultValues()));
+		},
 		*[suggestWithDependency](prefix, dependencyValue) {
 			let derivedParser;
 			try {
@@ -345,6 +367,9 @@ function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
 			}
 			return derivedParser.format(value);
 		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(...options.defaultValues()));
+		},
 		async *suggest(prefix) {
 			let derivedParser;
 			try {
@@ -428,6 +453,9 @@ function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
 			}
 			return derivedParser.format(value);
 		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(...options.defaultValues()));
+		},
 		async *suggest(prefix) {
 			let derivedParser;
 			try {
@@ -521,6 +549,9 @@ function createSyncDerivedParser(sourceId, options) {
 			}
 			return derivedParser.format(value);
 		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(options.defaultValue()));
+		},
 		*suggest(prefix) {
 			let derivedParser;
 			try {
@@ -681,6 +712,9 @@ function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
 			}
 			return derivedParser.format(value);
 		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(options.defaultValue()));
+		},
 		async *suggest(prefix) {
 			let derivedParser;
 			try {

package/dist/dependency.js

@@ -199,6 +199,25 @@ function deriveFromAsync(options) {
 function isAsyncModeParser(parser) {
 	return parser.$mode === "async";
 }
+/**
+* Shared helper for derived value parser `normalize()` implementations.
+* Builds the inner parser from the factory and delegates to its
+* `normalize()` if available, falling back to the original value on error.
+*/
+function normalizeWithDerivedParser(value, getParser) {
+	let derivedParser;
+	try {
+		derivedParser = getParser();
+	} catch {
+		return value;
+	}
+	if (derivedParser && typeof derivedParser.normalize === "function") try {
+		return derivedParser.normalize(value);
+	} catch {
+		return value;
+	}
+	return value;
+}
 function createSyncDerivedFromParser(sourceId, options) {
 	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
 	return {
@@ -271,6 +290,9 @@ function createSyncDerivedFromParser(sourceId, options) {
 			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
 			yield* derivedParser.suggest(prefix);
 		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(...options.defaultValues()));
+		},
 		*[suggestWithDependency](prefix, dependencyValue) {
 			let derivedParser;
 			try {
@@ -345,6 +367,9 @@ function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
 			}
 			return derivedParser.format(value);
 		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(...options.defaultValues()));
+		},
 		async *suggest(prefix) {
 			let derivedParser;
 			try {
@@ -428,6 +453,9 @@ function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
 			}
 			return derivedParser.format(value);
 		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(...options.defaultValues()));
+		},
 		async *suggest(prefix) {
 			let derivedParser;
 			try {
@@ -521,6 +549,9 @@ function createSyncDerivedParser(sourceId, options) {
 			}
 			return derivedParser.format(value);
 		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(options.defaultValue()));
+		},
 		*suggest(prefix) {
 			let derivedParser;
 			try {
@@ -681,6 +712,9 @@ function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
 			}
 			return derivedParser.format(value);
 		},
+		normalize(value) {
+			return normalizeWithDerivedParser(value, () => options.factory(options.defaultValue()));
+		},
 		async *suggest(prefix) {
 			let derivedParser;
 			try {

package/dist/modifiers.cjs

@@ -118,7 +118,7 @@ function optional(parser) {
 	const wrappedDependencyMarker = innerHasWrappedDependency ? { [require_dependency.wrappedDependencySourceMarker]: parser[require_dependency.wrappedDependencySourceMarker] } : innerHasDirectDependency ? { [require_dependency.wrappedDependencySourceMarker]: syncParser.initialState } : {};
 	const hasWrappedDependencySource = require_dependency.wrappedDependencySourceMarker in wrappedDependencyMarker;
 	const wrappedPendingState = hasWrappedDependencySource ? wrappedDependencyMarker[require_dependency.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 require_mode_dispatch.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 (require_dependency.transformsDependencyValue(parser)) {
 					const innerResult = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(void 0), () => parser.complete(void 0));
 					const handleInnerResult = (res) => {
 						if (require_dependency.isDependencySourceState(res)) try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return require_dependency.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 require_mode_dispatch.mapModeValue(parser.$mode, innerResult, handleInnerResult);
 				}
 				if (require_dependency.isWrappedDependencySource(parser)) try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					const pendingState = parser[require_dependency.wrappedDependencySourceMarker];
 					return require_dependency.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 = require_mode_dispatch.dispatchByMode(parser.$mode, () => syncParser.complete(state), () => parser.complete(state));
 					const handleInnerResult = (res) => {
 						if (require_dependency.isDependencySourceState(res)) try {
-							const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+							const value = evaluateDefault();
 							return require_dependency.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 require_mode_dispatch.mapModeValue(parser.$mode, innerResult, handleInnerResult);
 				}
 				try {
-					const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+					const value = evaluateDefault();
 					return require_dependency.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;
 }