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

package/dist/constructs.cjs

@@ -9,6 +9,43 @@ const require_suggestion = require('./suggestion.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
 
 //#region src/constructs.ts
+/**
+* A shared empty set used as the `leadingNames` value for parsers that
+* do not match any specific name at the first buffer position.
+*/
+const EMPTY_LEADING_NAMES = /* @__PURE__ */ new Set();
+/**
+* Computes the union of `leadingNames` from all given parsers.
+* Used for alternative combinators (`or()`, `longestMatch()`) where all
+* branches compete independently.
+*/
+function unionLeadingNames(parsers) {
+	const names = /* @__PURE__ */ new Set();
+	for (const p of parsers) for (const name of p.leadingNames) names.add(name);
+	return names.size === 0 ? EMPTY_LEADING_NAMES : names;
+}
+/**
+* Computes `leadingNames` for shared-buffer compositions (`tuple()`,
+* `object()`, `merge()`, `concat()`).
+*
+* Children are processed in descending priority order (matching the
+* round-robin parse loop).  Once a child with `acceptingAnyToken` is
+* encountered, no lower-priority children can match at position 0, so
+* their names are excluded.
+*/
+function sharedBufferLeadingNames(parsers) {
+	const sorted = parsers.toSorted((a, b) => b.priority - a.priority);
+	const names = /* @__PURE__ */ new Set();
+	let positionalBlocked = false;
+	for (const p of sorted) {
+		if (p.leadingNames) for (const name of p.leadingNames) {
+			if (positionalBlocked && !name.startsWith("-")) continue;
+			names.add(name);
+		}
+		if (p.acceptingAnyToken) positionalBlocked = true;
+	}
+	return names.size === 0 ? EMPTY_LEADING_NAMES : names;
+}
 const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
 /**
 * Internal symbol for exposing field-level parser pairs from `object()`
@@ -454,7 +491,7 @@ function or(...args) {
 			success: false
 		};
 	};
-	return {
+	const singleResult = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -463,6 +500,8 @@ function or(...args) {
 			type: "exclusive",
 			terms: parsers.map((p) => p.usage)
 		}],
+		leadingNames: unionLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
 		complete: createExclusiveComplete(parsers, options, noMatchContext, combinedMode),
 		parse(context) {
@@ -496,6 +535,7 @@ function or(...args) {
 			};
 		}
 	};
+	return singleResult;
 }
 /**
 * @since 0.5.0
@@ -591,7 +631,7 @@ function longestMatch(...args) {
 			success: false
 		};
 	};
-	return {
+	const multiResult = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -600,6 +640,8 @@ function longestMatch(...args) {
 			type: "exclusive",
 			terms: parsers.map((p) => p.usage)
 		}],
+		leadingNames: unionLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
 		complete: createExclusiveComplete(parsers, options, noMatchContext, combinedMode),
 		parse(context) {
@@ -640,6 +682,7 @@ function longestMatch(...args) {
 			};
 		}
 	};
+	return multiResult;
 }
 /**
 * Internal sync helper for object suggest functionality.
@@ -1178,13 +1221,15 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			success: false
 		};
 	};
-	return {
+	const objectParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: parserPairs,
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
 		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
+		leadingNames: sharedBufferLeadingNames(parserPairs.map(([_, p]) => p)),
+		acceptingAnyToken: parserPairs.some(([_, p]) => p.acceptingAnyToken),
 		get initialState() {
 			return createInitialState();
 		},
@@ -1380,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 = [];
@@ -1551,11 +1618,13 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			consumed: allConsumed
 		};
 	};
-	return {
+	const tupleParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		usage: parsers.toSorted((a, b) => b.priority - a.priority).flatMap((p) => p.usage),
+		leadingNames: sharedBufferLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
 		initialState: parsers.map((parser) => parser.initialState),
 		parse(context) {
@@ -1723,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;
@@ -1870,13 +1964,15 @@ function merge(...args) {
 		};
 	};
 	const mergedFieldParsers = collectChildFieldParsers(parsers);
-	return {
+	const mergeParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: mergedFieldParsers,
 		priority: Math.max(...parsers.map((p) => p.priority)),
 		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
+		leadingNames: sharedBufferLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);
@@ -2087,6 +2183,7 @@ function merge(...args) {
 			};
 		}
 	};
+	return mergeParser;
 }
 /**
 * Builds a dependency registry from the pre-parsed context state and returns
@@ -2415,6 +2512,8 @@ function concat(...parsers) {
 		$stateType: [],
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
 		usage: parsers.flatMap((p) => p.usage),
+		leadingNames: sharedBufferLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);
@@ -2492,6 +2591,8 @@ function group(label, parser, options = {}) {
 		$stateType: parser.$stateType,
 		priority: parser.priority,
 		usage: applyHiddenToUsage(parser.usage, options.hidden),
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
 		...fieldParsersKey in parser ? { [fieldParsersKey]: parser[fieldParsersKey] } : {},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
@@ -2546,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;
 }
 /**
@@ -2976,6 +3082,8 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		$stateType: [],
 		priority: maxPriority,
 		usage,
+		leadingNames: defaultBranch ? unionLeadingNames([discriminator, defaultBranch]) : discriminator.leadingNames,
+		acceptingAnyToken: defaultBranch?.acceptingAnyToken ?? false,
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);

package/dist/constructs.js

@@ -9,6 +9,43 @@ import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggest
 import { collectLeadingCandidates } from "./usage-internals.js";
 
 //#region src/constructs.ts
+/**
+* A shared empty set used as the `leadingNames` value for parsers that
+* do not match any specific name at the first buffer position.
+*/
+const EMPTY_LEADING_NAMES = /* @__PURE__ */ new Set();
+/**
+* Computes the union of `leadingNames` from all given parsers.
+* Used for alternative combinators (`or()`, `longestMatch()`) where all
+* branches compete independently.
+*/
+function unionLeadingNames(parsers) {
+	const names = /* @__PURE__ */ new Set();
+	for (const p of parsers) for (const name of p.leadingNames) names.add(name);
+	return names.size === 0 ? EMPTY_LEADING_NAMES : names;
+}
+/**
+* Computes `leadingNames` for shared-buffer compositions (`tuple()`,
+* `object()`, `merge()`, `concat()`).
+*
+* Children are processed in descending priority order (matching the
+* round-robin parse loop).  Once a child with `acceptingAnyToken` is
+* encountered, no lower-priority children can match at position 0, so
+* their names are excluded.
+*/
+function sharedBufferLeadingNames(parsers) {
+	const sorted = parsers.toSorted((a, b) => b.priority - a.priority);
+	const names = /* @__PURE__ */ new Set();
+	let positionalBlocked = false;
+	for (const p of sorted) {
+		if (p.leadingNames) for (const name of p.leadingNames) {
+			if (positionalBlocked && !name.startsWith("-")) continue;
+			names.add(name);
+		}
+		if (p.acceptingAnyToken) positionalBlocked = true;
+	}
+	return names.size === 0 ? EMPTY_LEADING_NAMES : names;
+}
 const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
 /**
 * Internal symbol for exposing field-level parser pairs from `object()`
@@ -454,7 +491,7 @@ function or(...args) {
 			success: false
 		};
 	};
-	return {
+	const singleResult = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -463,6 +500,8 @@ function or(...args) {
 			type: "exclusive",
 			terms: parsers.map((p) => p.usage)
 		}],
+		leadingNames: unionLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
 		complete: createExclusiveComplete(parsers, options, noMatchContext, combinedMode),
 		parse(context) {
@@ -496,6 +535,7 @@ function or(...args) {
 			};
 		}
 	};
+	return singleResult;
 }
 /**
 * @since 0.5.0
@@ -591,7 +631,7 @@ function longestMatch(...args) {
 			success: false
 		};
 	};
-	return {
+	const multiResult = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -600,6 +640,8 @@ function longestMatch(...args) {
 			type: "exclusive",
 			terms: parsers.map((p) => p.usage)
 		}],
+		leadingNames: unionLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState: void 0,
 		complete: createExclusiveComplete(parsers, options, noMatchContext, combinedMode),
 		parse(context) {
@@ -640,6 +682,7 @@ function longestMatch(...args) {
 			};
 		}
 	};
+	return multiResult;
 }
 /**
 * Internal sync helper for object suggest functionality.
@@ -1178,13 +1221,15 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			success: false
 		};
 	};
-	return {
+	const objectParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: parserPairs,
 		priority: Math.max(...parserKeys.map((k) => parsers[k].priority)),
 		usage: applyHiddenToUsage(parserPairs.flatMap(([_, p]) => p.usage), options.hidden),
+		leadingNames: sharedBufferLeadingNames(parserPairs.map(([_, p]) => p)),
+		acceptingAnyToken: parserPairs.some(([_, p]) => p.acceptingAnyToken),
 		get initialState() {
 			return createInitialState();
 		},
@@ -1380,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 = [];
@@ -1551,11 +1618,13 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			consumed: allConsumed
 		};
 	};
-	return {
+	const tupleParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		usage: parsers.toSorted((a, b) => b.priority - a.priority).flatMap((p) => p.usage),
+		leadingNames: sharedBufferLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
 		initialState: parsers.map((parser) => parser.initialState),
 		parse(context) {
@@ -1723,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;
@@ -1870,13 +1964,15 @@ function merge(...args) {
 		};
 	};
 	const mergedFieldParsers = collectChildFieldParsers(parsers);
-	return {
+	const mergeParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: mergedFieldParsers,
 		priority: Math.max(...parsers.map((p) => p.priority)),
 		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
+		leadingNames: sharedBufferLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);
@@ -2087,6 +2183,7 @@ function merge(...args) {
 			};
 		}
 	};
+	return mergeParser;
 }
 /**
 * Builds a dependency registry from the pre-parsed context state and returns
@@ -2415,6 +2512,8 @@ function concat(...parsers) {
 		$stateType: [],
 		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
 		usage: parsers.flatMap((p) => p.usage),
+		leadingNames: sharedBufferLeadingNames(parsers),
+		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);
@@ -2492,6 +2591,8 @@ function group(label, parser, options = {}) {
 		$stateType: parser.$stateType,
 		priority: parser.priority,
 		usage: applyHiddenToUsage(parser.usage, options.hidden),
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
 		...fieldParsersKey in parser ? { [fieldParsersKey]: parser[fieldParsersKey] } : {},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
@@ -2546,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;
 }
 /**
@@ -2976,6 +3082,8 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		$stateType: [],
 		priority: maxPriority,
 		usage,
+		leadingNames: defaultBranch ? unionLeadingNames([discriminator, defaultBranch]) : discriminator.leadingNames,
+		acceptingAnyToken: defaultBranch?.acceptingAnyToken ?? false,
 		initialState,
 		parse(context) {
 			if (isAsync) return parseAsync(context);

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/facade.cjs

@@ -196,6 +196,8 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 			$stateType: [],
 			priority: 200,
 			usage: helpParsers.helpOption.usage,
+			leadingNames: helpParsers.helpOption.leadingNames,
+			acceptingAnyToken: false,
 			initialState: null,
 			parse(context) {
 				const { buffer, optionsTerminated } = context;
@@ -275,6 +277,8 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 			$stateType: [],
 			priority: 200,
 			usage: versionParsers.versionOption.usage,
+			leadingNames: versionParsers.versionOption.leadingNames,
+			acceptingAnyToken: false,
 			initialState: null,
 			parse(context) {
 				const { buffer, optionsTerminated } = context;
@@ -620,9 +624,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		completionCommandNames
 	]);
 	require_validate.validateMetaNameCollisions({
-		leadingOptions: require_usage.extractLeadingOptionNames(parser.usage, true),
-		leadingCommands: require_usage.extractLeadingCommandNames(parser.usage, true),
-		leadingLiterals: require_usage.extractLeadingLiteralValues(parser.usage),
+		leadingNames: parser.leadingNames,
 		allOptions: require_usage.extractOptionNames(parser.usage, true),
 		allCommands: require_usage.extractCommandNames(parser.usage, true),
 		allLiterals: require_usage.extractLiteralValues(parser.usage)