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

package/dist/constructs.cjs

@@ -13,6 +13,7 @@ const require_usage_internals = require('./usage-internals.cjs');
 const require_short_option = require('./short-option.cjs');
 const require_passthrough = require('./internal/passthrough.cjs');
 const require_command_alias = require('./internal/command-alias.cjs');
+const require_failure = require('./internal/failure.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_suggestion = require('./suggestion.cjs');
@@ -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 = require_message.message`Unexpected option or subcommand: ${require_message.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 require_failure.createDeferredFailure(0, () => noMatch != null ? noMatch(noMatchContext) : generateNoMatchError(noMatchContext));
+		}
+		if (unexpectedInput != null && typeof unexpectedInput !== "function") return {
+			success: false,
+			consumed: 0,
+			error: unexpectedInput
+		};
+		return require_failure.createDeferredFailure(0, () => {
+			if (unexpectedInput != null) return unexpectedInput.call(errors, token);
+			return createUnexpectedInputErrorWithScopedSuggestions(require_message.message`Unexpected option or subcommand: ${require_message.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 = require_message.message`Unexpected option or subcommand: ${require_message.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 require_failure.createDeferredFailure(0, () => noMatch != null ? noMatch(noMatchContext) : generateNoMatchError(noMatchContext));
+		}
+		if (unexpectedInput != null && typeof unexpectedInput !== "function") return {
+			success: false,
+			consumed: 0,
+			error: unexpectedInput
+		};
+		return require_failure.createDeferredFailure(0, () => {
+			if (unexpectedInput != null) return unexpectedInput.call(errors, token);
+			return createUnexpectedInputErrorWithScopedSuggestions(require_message.message`Unexpected option or subcommand: ${require_message.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 require_failure.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 = require_message.message`Unexpected option or argument: ${token}.`;
-	return {
+	if (unexpectedInput != null && typeof unexpectedInput !== "function") return {
+		success: false,
 		consumed: 0,
-		error: require_suggestion.createErrorWithSuggestions(baseError, token, context.usage, "both", errors?.suggestions)
+		error: unexpectedInput
 	};
+	return require_failure.createDeferredFailure(0, () => {
+		if (unexpectedInput != null) return unexpectedInput(token);
+		return require_suggestion.createErrorWithSuggestions(require_message.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: require_message.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: require_message.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) => require_failure.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: require_message.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: require_message.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 require_failure.createDeferredFailure(0, () => {
+			const context = analyzeNoMatchContext([discriminator, ...allBranchParsers]);
+			return customNoMatch != null ? customNoMatch.call(errors, context) : generateNoMatchError(context);
+		});
+	};
 	const optionScope = require_short_option.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/constructs.d.cts

@@ -62,6 +62,8 @@ interface OrErrorOptions {
    * Custom error message when no parser matches.
    * Can be a static message or a function that receives context about what
    * types of inputs are expected, allowing for more precise error messages.
+   * The callback may be skipped for discarded parse failures. Completion
+   * can invoke it separately, so it should not have side effects.
    *
    * @example
    * ```typescript
@@ -797,6 +799,8 @@ interface LongestMatchErrorOptions {
    * Custom error message when no parser matches.
    * Can be a static message or a function that receives context about what
    * types of inputs are expected, allowing for more precise error messages.
+   * The callback may be skipped for discarded parse failures. Completion
+   * can invoke it separately, so it should not have side effects.
    *
    * @example
    * ```typescript
@@ -948,12 +952,15 @@ interface ObjectOptions {
 interface ObjectErrorOptions {
   /**
    * Error message when an unexpected option or argument is encountered.
+   * The callback may be skipped when another parser accepts the input.
    */
   readonly unexpectedInput?: Message | ((token: string) => Message);
   /**
    * Error message when end of input is reached unexpectedly.
    * Can be a static message or a function that receives context about what
    * types of inputs are expected, allowing for more precise error messages.
+   * The callback may be skipped for discarded parse failures. Completion
+   * can invoke it separately, so it should not have side effects.
    *
    * @example
    * ```typescript
@@ -978,6 +985,7 @@ interface ObjectErrorOptions {
    * If provided, this will be used instead of the default "Did you mean?"
    * formatting. The function receives an array of similar valid options/commands
    * and should return a formatted message to append to the error.
+   * It is skipped when that initial error is discarded.
    *
    * @param suggestions Array of similar valid option/command names
    * @returns Formatted message to append to the error (can be empty array for no suggestions)

package/dist/constructs.d.ts

@@ -62,6 +62,8 @@ interface OrErrorOptions {
    * Custom error message when no parser matches.
    * Can be a static message or a function that receives context about what
    * types of inputs are expected, allowing for more precise error messages.
+   * The callback may be skipped for discarded parse failures. Completion
+   * can invoke it separately, so it should not have side effects.
    *
    * @example
    * ```typescript
@@ -797,6 +799,8 @@ interface LongestMatchErrorOptions {
    * Custom error message when no parser matches.
    * Can be a static message or a function that receives context about what
    * types of inputs are expected, allowing for more precise error messages.
+   * The callback may be skipped for discarded parse failures. Completion
+   * can invoke it separately, so it should not have side effects.
    *
    * @example
    * ```typescript
@@ -948,12 +952,15 @@ interface ObjectOptions {
 interface ObjectErrorOptions {
   /**
    * Error message when an unexpected option or argument is encountered.
+   * The callback may be skipped when another parser accepts the input.
    */
   readonly unexpectedInput?: Message | ((token: string) => Message);
   /**
    * Error message when end of input is reached unexpectedly.
    * Can be a static message or a function that receives context about what
    * types of inputs are expected, allowing for more precise error messages.
+   * The callback may be skipped for discarded parse failures. Completion
+   * can invoke it separately, so it should not have side effects.
    *
    * @example
    * ```typescript
@@ -978,6 +985,7 @@ interface ObjectErrorOptions {
    * If provided, this will be used instead of the default "Did you mean?"
    * formatting. The function receives an array of similar valid options/commands
    * and should return a formatted message to append to the error.
+   * It is skipped when that initial error is discarded.
    *
    * @param suggestions Array of similar valid option/command names
    * @returns Formatted message to append to the error (can be empty array for no suggestions)