@optique/core 1.4.0-dev.2664 → 1.4.0-dev.2667

package/dist/constructs.js

@@ -13,6 +13,7 @@ import { collectLeadingCandidates } from "./usage-internals.js";
 import { adoptOptionScope, combinedOptionScope, conditionalOptionScope, forkOptionScope, restoreOptionScope, scopeParser, selectableOptionScope, withOptionScope, withParserOptionScope } from "./short-option.js";
 import { defineReachableChildren, delegateKnownCompletion, getKnownCompletion, getOptionMatch, getPassThroughFailureHint, getPassThroughPriority, hasPassThroughUsage, matchesOptionToken, retainConsumingFailure, retainConsumingFailureHint, withPassThroughFailure, withReturnedConsumingFailure } from "./internal/passthrough.js";
 import { allowDuplicateLeadingCommandNamesKey } from "./internal/command-alias.js";
+import { createDeferredFailure, withConsumedDepth } from "./internal/failure.js";
 import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
 import { fluent } from "./modifiers.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar } from "./suggestion.js";
@@ -1467,15 +1468,31 @@ function or(...args) {
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
-	const getInitialError = (context) => ({
-		consumed: 0,
-		error: context.buffer.length < 1 ? getNoMatchError(options, noMatchContext) : (() => {
-			const token = context.buffer[0];
-			const defaultMsg = message`Unexpected option or subcommand: ${optionName(token)}.`;
-			if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
-			return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
-		})()
-	});
+	const getInitialError = (context) => {
+		const empty = context.buffer.length < 1;
+		const token = context.buffer[0];
+		const errors = options?.errors;
+		const noMatch = errors?.noMatch;
+		const unexpectedInput = errors?.unexpectedInput;
+		const suggestions = errors?.suggestions;
+		if (empty) {
+			if (noMatch != null && typeof noMatch !== "function") return {
+				success: false,
+				consumed: 0,
+				error: noMatch
+			};
+			return createDeferredFailure(0, () => noMatch != null ? noMatch(noMatchContext) : generateNoMatchError(noMatchContext));
+		}
+		if (unexpectedInput != null && typeof unexpectedInput !== "function") return {
+			success: false,
+			consumed: 0,
+			error: unexpectedInput
+		};
+		return createDeferredFailure(0, () => {
+			if (unexpectedInput != null) return unexpectedInput.call(errors, token);
+			return createUnexpectedInputErrorWithScopedSuggestions(message`Unexpected option or subcommand: ${optionName(token)}.`, token, parsers, suggestions);
+		});
+	};
 	const parseSync = (context) => {
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
@@ -1683,10 +1700,7 @@ function or(...args) {
 			}
 		}
 		if (optionsTerminatorResult != null) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorResult);
-		return {
-			...error,
-			success: false
-		};
+		return error;
 	};
 	const parseAsync = async (context) => {
 		let error = getInitialError(context);
@@ -1898,10 +1912,7 @@ function or(...args) {
 			}
 		}
 		if (optionsTerminatorResult != null) return preserveExclusiveStateAfterOptionsTerminator(context, optionsTerminatorResult);
-		return {
-			...error,
-			success: false
-		};
+		return error;
 	};
 	const singleResult = {
 		mode: combinedMode,
@@ -1998,15 +2009,31 @@ function createLongestMatch(...args) {
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
-	const getInitialError = (context) => ({
-		consumed: 0,
-		error: context.buffer.length < 1 ? getNoMatchError(options, noMatchContext) : (() => {
-			const token = context.buffer[0];
-			const defaultMsg = message`Unexpected option or subcommand: ${optionName(token)}.`;
-			if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
-			return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
-		})()
-	});
+	const getInitialError = (context) => {
+		const empty = context.buffer.length < 1;
+		const token = context.buffer[0];
+		const errors = options?.errors;
+		const noMatch = errors?.noMatch;
+		const unexpectedInput = errors?.unexpectedInput;
+		const suggestions = errors?.suggestions;
+		if (empty) {
+			if (noMatch != null && typeof noMatch !== "function") return {
+				success: false,
+				consumed: 0,
+				error: noMatch
+			};
+			return createDeferredFailure(0, () => noMatch != null ? noMatch(noMatchContext) : generateNoMatchError(noMatchContext));
+		}
+		if (unexpectedInput != null && typeof unexpectedInput !== "function") return {
+			success: false,
+			consumed: 0,
+			error: unexpectedInput
+		};
+		return createDeferredFailure(0, () => {
+			if (unexpectedInput != null) return unexpectedInput.call(errors, token);
+			return createUnexpectedInputErrorWithScopedSuggestions(message`Unexpected option or subcommand: ${optionName(token)}.`, token, parsers, suggestions);
+		});
+	};
 	const commitLongestMatch = (context, match, optionsTerminatorResult, consumingFailure) => {
 		const selectedResult = optionsTerminatorResult == null ? match.result : {
 			...match.result,
@@ -2094,10 +2121,7 @@ function createLongestMatch(...args) {
 		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
 		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
 		if (bestMatch != null) return commitLongestMatch(context, bestMatch, void 0, consumingFailure);
-		return {
-			...error,
-			success: false
-		};
+		return error;
 	};
 	const parseAsyncBranches = async (context) => {
 		let bestMatch = null;
@@ -2136,10 +2160,7 @@ function createLongestMatch(...args) {
 		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
 		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
 		if (bestMatch != null) return commitLongestMatch(context, bestMatch, void 0, consumingFailure);
-		return {
-			...error,
-			success: false
-		};
+		return error;
 	};
 	const multiResult = {
 		mode: combinedMode,
@@ -2219,24 +2240,29 @@ function createLongestMatch(...args) {
 * @returns A zero-consumption parse error.
 */
 function createObjectLikeInitialError(context, noMatchContext, errors) {
-	if (context.buffer.length < 1) {
-		const customEndOfInput = errors?.endOfInput;
-		return {
+	const empty = context.buffer.length < 1;
+	const token = context.buffer[0];
+	const usage = context.usage;
+	const endOfInput = errors?.endOfInput;
+	const unexpectedInput = errors?.unexpectedInput;
+	const suggestions = errors?.suggestions;
+	if (empty) {
+		if (endOfInput != null && typeof endOfInput !== "function") return {
+			success: false,
 			consumed: 0,
-			error: customEndOfInput ? typeof customEndOfInput === "function" ? customEndOfInput(noMatchContext) : customEndOfInput : generateNoMatchError(noMatchContext)
+			error: endOfInput
 		};
+		return createDeferredFailure(0, () => endOfInput != null ? endOfInput(noMatchContext) : generateNoMatchError(noMatchContext));
 	}
-	const token = context.buffer[0];
-	const customMessage = errors?.unexpectedInput;
-	if (customMessage) return {
-		consumed: 0,
-		error: typeof customMessage === "function" ? customMessage(token) : customMessage
-	};
-	const baseError = message`Unexpected option or argument: ${token}.`;
-	return {
+	if (unexpectedInput != null && typeof unexpectedInput !== "function") return {
+		success: false,
 		consumed: 0,
-		error: createErrorWithSuggestions(baseError, token, context.usage, "both", errors?.suggestions)
+		error: unexpectedInput
 	};
+	return createDeferredFailure(0, () => {
+		if (unexpectedInput != null) return unexpectedInput(token);
+		return createErrorWithSuggestions(message`Unexpected option or argument: ${token}.`, token, usage, "both", suggestions);
+	});
 }
 /**
 * Internal sync helper for object suggest functionality.
@@ -2810,10 +2836,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				success: false
 			};
 		}
-		return {
-			...error,
-			success: false
-		};
+		return error;
 	};
 	const parseAsync = async (context) => {
 		let error = getInitialError(context);
@@ -2929,10 +2952,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				success: false
 			};
 		}
-		return {
-			...error,
-			success: false
-		};
+		return error;
 	};
 	const objectParser = {
 		mode: combinedMode,
@@ -3902,6 +3922,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		while (matchedParsers.size < syncParsers.length) {
 			let foundMatch = false;
 			let error = {
+				success: false,
 				consumed: 0,
 				error: message`No remaining parsers could match the input.`
 			};
@@ -3960,10 +3981,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					break;
 				}
 			}
-			if (!foundMatch) return {
-				...error,
-				success: false
-			};
+			if (!foundMatch) return error;
 		}
 		return {
 			success: true,
@@ -3979,6 +3997,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		while (matchedParsers.size < parsers.length) {
 			let foundMatch = false;
 			let error = {
+				success: false,
 				consumed: 0,
 				error: message`No remaining parsers could match the input.`
 			};
@@ -4039,10 +4058,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					break;
 				}
 			}
-			if (!foundMatch) return {
-				...error,
-				success: false
-			};
+			if (!foundMatch) return error;
 		}
 		return {
 			success: true,
@@ -4337,10 +4353,7 @@ function seq(...rawArgs) {
 	const syncParsers = parsers;
 	if (!options.allowDuplicates) checkSequentialDuplicateOptionNames(parsers);
 	const initialState = createSeqState(void 0, 0, parsers.map((parser) => parser.initialState));
-	const withSeqConsumedDepth = (result, consumed) => ({
-		...result,
-		consumed: consumed.length + result.consumed
-	});
+	const withSeqConsumedDepth = (result, consumed) => withConsumedDepth(result, consumed.length + result.consumed);
 	const reachableSeqScope = (context) => {
 		let end = Math.min(context.state.index + 1, parsers.length);
 		while (end < parsers.length) {
@@ -4984,10 +4997,7 @@ function merge(...args) {
 			next: zeroConsumedSuccess.context,
 			consumed: zeroConsumedSuccess.consumed
 		};
-		return {
-			success: false,
-			...createObjectLikeInitialError(context, noMatchContext)
-		};
+		return createObjectLikeInitialError(context, noMatchContext);
 	};
 	const parseChildrenAsync = async (context) => {
 		let currentContext = context;
@@ -5030,10 +5040,7 @@ function merge(...args) {
 			next: zeroConsumedSuccess.context,
 			consumed: zeroConsumedSuccess.consumed
 		};
-		return {
-			success: false,
-			...createObjectLikeInitialError(context, noMatchContext)
-		};
+		return createObjectLikeInitialError(context, noMatchContext);
 	};
 	const parseSync = (context) => {
 		let currentContext = context;
@@ -5089,16 +5096,10 @@ function merge(...args) {
 		if (allConsumed.length === 0) {
 			if (attemptedLane) {
 				const settled = settleZeroConsumptionLanes(context, laneResults);
-				return settled ?? {
-					...error,
-					success: false
-				};
+				return settled ?? error;
 			}
 			const fallback = parseChildrenSync(context);
-			if (!fallback.success && fallback.consumed < error.consumed) return {
-				...error,
-				success: false
-			};
+			if (!fallback.success && fallback.consumed < error.consumed) return error;
 			return fallback;
 		}
 		for (const lane of mergeParseLanes) {
@@ -5166,16 +5167,10 @@ function merge(...args) {
 		if (allConsumed.length === 0) {
 			if (attemptedLane) {
 				const settled = settleZeroConsumptionLanes(context, laneResults);
-				return settled ?? {
-					...error,
-					success: false
-				};
+				return settled ?? error;
 			}
 			const fallback = await parseChildrenAsync(context);
-			if (!fallback.success && fallback.consumed < error.consumed) return {
-				...error,
-				success: false
-			};
+			if (!fallback.success && fallback.consumed < error.consumed) return error;
 			return fallback;
 		}
 		for (const lane of mergeParseLanes) {
@@ -5979,6 +5974,7 @@ function concat(...parsers) {
 		while (matchedParsers.size < syncParsers.length) {
 			let foundMatch = false;
 			let error = {
+				success: false,
 				consumed: 0,
 				error: message`No remaining parsers could match the input.`
 			};
@@ -6037,10 +6033,7 @@ function concat(...parsers) {
 					break;
 				}
 			}
-			if (!foundMatch) return {
-				...error,
-				success: false
-			};
+			if (!foundMatch) return error;
 		}
 		return {
 			success: true,
@@ -6056,6 +6049,7 @@ function concat(...parsers) {
 		while (matchedParsers.size < parsers.length) {
 			let foundMatch = false;
 			let error = {
+				success: false,
 				consumed: 0,
 				error: message`No remaining parsers could match the input.`
 			};
@@ -6114,10 +6108,7 @@ function concat(...parsers) {
 					break;
 				}
 			}
-			if (!foundMatch) return {
-				...error,
-				success: false
-			};
+			if (!foundMatch) return error;
 		}
 		return {
 			success: true,
@@ -6628,6 +6619,19 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		const noMatchContext = analyzeNoMatchContext([discriminator, ...allBranchParsers]);
 		return options?.errors?.noMatch ? typeof options.errors.noMatch === "function" ? options.errors.noMatch(noMatchContext) : options.errors.noMatch : generateNoMatchError(noMatchContext);
 	};
+	const createNoMatchFailure = () => {
+		const errors = options?.errors;
+		const customNoMatch = errors?.noMatch;
+		if (customNoMatch != null && typeof customNoMatch !== "function") return {
+			success: false,
+			consumed: 0,
+			error: customNoMatch
+		};
+		return createDeferredFailure(0, () => {
+			const context = analyzeNoMatchContext([discriminator, ...allBranchParsers]);
+			return customNoMatch != null ? customNoMatch.call(errors, context) : generateNoMatchError(context);
+		});
+	};
 	const optionScope = conditionalOptionScope(discriminator, defaultBranch, branchParsers.map(([, p]) => p));
 	const selectBranch = (selected, table, fallback) => selected.kind === "default" ? fallback : table[selected.key];
 	const parseSync = (context) => {
@@ -6768,11 +6772,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			}
 			if (!defaultResult.success && defaultResult.consumed > 0) return defaultResult;
 		}
-		return {
-			success: false,
-			consumed: 0,
-			error: getNoMatchError$1()
-		};
+		return createNoMatchFailure();
 	};
 	const parseAsync = async (context) => {
 		const state = context.state ?? initialState;
@@ -7028,11 +7028,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			}
 			if (!defaultResult.success && defaultResult.consumed > 0) return defaultResult;
 		}
-		return {
-			success: false,
-			consumed: 0,
-			error: getNoMatchError$1()
-		};
+		return createNoMatchFailure();
 	};
 	const completeSync = (state, exec) => {
 		const syncDiscriminator = discriminator;

package/dist/internal/failure.cjs

@@ -0,0 +1,68 @@
+
+//#region src/internal/failure.ts
+/**
+* Creates a parse failure without constructing its diagnostic during probing.
+* The getter remains attached to the original failure so descriptor-preserving
+* wrappers and frozen failures share the same result, including thrown values.
+* @internal
+*/
+function createDeferredFailure(consumed, createError) {
+	let settled;
+	return {
+		success: false,
+		consumed,
+		get error() {
+			if (settled == null) try {
+				settled = {
+					kind: "value",
+					value: createError()
+				};
+			} catch (error) {
+				settled = {
+					kind: "throw",
+					error
+				};
+			}
+			if (settled.kind === "throw") throw settled.error;
+			return settled.value;
+		}
+	};
+}
+/**
+* Adjusts a failure's consumed depth without reading a deferred diagnostic.
+* Other enumerable properties retain the same copying behavior as object
+* spread, including accessors that depend on the original receiver.
+* @internal
+*/
+function withConsumedDepth(result, consumed) {
+	if (consumed === result.consumed) return result;
+	const copy = {
+		success: false,
+		consumed,
+		get error() {
+			return result.error;
+		}
+	};
+	for (const key of Reflect.ownKeys(result)) {
+		if (key === "success" || key === "consumed") continue;
+		const descriptor = Object.getOwnPropertyDescriptor(result, key);
+		if (!descriptor?.enumerable) continue;
+		if (key === "error" && "value" in descriptor) Object.defineProperty(copy, "error", {
+			value: descriptor.value,
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+		else if (key !== "error") Object.defineProperty(copy, key, {
+			value: Reflect.get(result, key),
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+	}
+	return copy;
+}
+
+//#endregion
+exports.createDeferredFailure = createDeferredFailure;
+exports.withConsumedDepth = withConsumedDepth;

package/dist/internal/failure.js

@@ -0,0 +1,66 @@
+//#region src/internal/failure.ts
+/**
+* Creates a parse failure without constructing its diagnostic during probing.
+* The getter remains attached to the original failure so descriptor-preserving
+* wrappers and frozen failures share the same result, including thrown values.
+* @internal
+*/
+function createDeferredFailure(consumed, createError) {
+	let settled;
+	return {
+		success: false,
+		consumed,
+		get error() {
+			if (settled == null) try {
+				settled = {
+					kind: "value",
+					value: createError()
+				};
+			} catch (error) {
+				settled = {
+					kind: "throw",
+					error
+				};
+			}
+			if (settled.kind === "throw") throw settled.error;
+			return settled.value;
+		}
+	};
+}
+/**
+* Adjusts a failure's consumed depth without reading a deferred diagnostic.
+* Other enumerable properties retain the same copying behavior as object
+* spread, including accessors that depend on the original receiver.
+* @internal
+*/
+function withConsumedDepth(result, consumed) {
+	if (consumed === result.consumed) return result;
+	const copy = {
+		success: false,
+		consumed,
+		get error() {
+			return result.error;
+		}
+	};
+	for (const key of Reflect.ownKeys(result)) {
+		if (key === "success" || key === "consumed") continue;
+		const descriptor = Object.getOwnPropertyDescriptor(result, key);
+		if (!descriptor?.enumerable) continue;
+		if (key === "error" && "value" in descriptor) Object.defineProperty(copy, "error", {
+			value: descriptor.value,
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+		else if (key !== "error") Object.defineProperty(copy, key, {
+			value: Reflect.get(result, key),
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+	}
+	return copy;
+}
+
+//#endregion
+export { createDeferredFailure, withConsumedDepth };