@thomasfosterau/effect-parse 0.2.0 → 0.4.0

package/dist/Expression.js

@@ -1,6 +1,44 @@
-import { Fail, mergeFailures } from "./Input.js";
+import * as Predicate from "effect/Predicate";
+import { Fail } from "./Input.js";
 import { make as make$1 } from "./Parser.js";
-//#region src/Expression.ts
+import { TiedFailures } from "./internal/ties.js";
+// src/Expression.ts
+/**
+* Operator-precedence expression parsing with a Pratt parser (from
+* `nom-language`'s `precedence`, and winnow's expression parser).
+*
+* Describe the operand parser and a table of prefix, postfix and infix
+* operators with their precedence (higher binds tighter) and associativity.
+* Each operator carries a function that folds its operands into a result.
+*
+* @example
+* ```ts
+* import { Ascii, Expression, Parser, Token } from "@thomasfosterau/effect-parse"
+*
+* const op = (s: string) => Parser.delimited(Ascii.space0, Token.literal(s), Ascii.space0)
+*
+* const arithmetic: Parser.Parser<number, string> = Expression.make({
+*   operand: Parser.alt(
+*     Ascii.decInt,
+*     Parser.delimited(op("("), Parser.suspend(() => arithmetic), op(")"))
+*   ),
+*   operators: [
+*     Expression.prefix(op("-"), 4, (_, x) => -x),
+*     Expression.postfix(op("!"), 5, (x) => factorial(x)),
+*     Expression.infixRight(op("^"), 3, (l, _, r) => l ** r),
+*     Expression.infixLeft(op("*"), 2, (l, _, r) => l * r),
+*     Expression.infixLeft(op("/"), 2, (l, _, r) => l / r),
+*     Expression.infixLeft(op("+"), 1, (l, _, r) => l + r),
+*     Expression.infixLeft(op("-"), 1, (l, _, r) => l - r)
+*   ]
+* })
+*
+* declare const factorial: (n: number) => number
+* Parser.parse(arithmetic, "1 + 2 * 3 ^ 2") // Result.succeed(19)
+* ```
+*
+* @since 0.1.0
+*/
 /**
 * A prefix operator, e.g. unary minus.
 *
@@ -66,11 +104,11 @@ const infixRight = (parser, precedence, fold) => ({
 */
 const make = (options) => {
 	const operand = options.operand.step;
-	const prefixes = options.operators.filter((o) => o._tag === "Prefix");
-	const postfixes = options.operators.filter((o) => o._tag === "Postfix");
-	const infixes = options.operators.filter((o) => o._tag === "Infix");
+	const prefixes = options.operators.filter((o) => Predicate.isTagged(o, "Prefix"));
+	const postfixes = options.operators.filter((o) => Predicate.isTagged(o, "Postfix"));
+	const infixes = options.operators.filter((o) => Predicate.isTagged(o, "Infix"));
 	let matched;
-	let failure;
+	const failures = new TiedFailures();
 	const tryOps = (state, ops, mustConsume) => {
 		const start = state.pos;
 		for (let i = 0; i < ops.length; i++) {
@@ -84,14 +122,14 @@ const make = (options) => {
 				return i;
 			}
 			if (state.mode !== "Backtrack") return -2;
-			failure = failure === void 0 ? state.failure : mergeFailures(failure, state.failure);
-			state.pos = start;
+			state.rewind(start);
+			failures.add(state);
 		}
 		return -1;
 	};
 	const expr = (state, minPower) => {
 		let lhs;
-		failure = void 0;
+		failures.clear();
 		const p = tryOps(state, prefixes, true);
 		if (p === -2) return Fail;
 		if (p >= 0) {
@@ -101,39 +139,45 @@ const make = (options) => {
 			if (operandValue === Fail) return Fail;
 			lhs = op.fold(opOut, operandValue);
 		} else {
-			const prefixFailure = failure;
+			const prefixFailure = failures.failure;
+			const prefixTie1 = failures.tie1;
+			const prefixTie2 = failures.tie2;
 			lhs = operand(state);
 			if (lhs === Fail) {
-				if (prefixFailure !== void 0 && state.mode === "Backtrack") state.failWith("Backtrack", mergeFailures(prefixFailure, state.failure));
+				if (prefixFailure !== void 0 && state.mode === "Backtrack") {
+					failures.failure = prefixFailure;
+					failures.tie1 = prefixTie1;
+					failures.tie2 = prefixTie2;
+					failures.add(state);
+					failures.fail(state);
+				}
 				return Fail;
 			}
 		}
 		while (true) {
 			const start = state.pos;
-			failure = void 0;
+			failures.clear();
 			const q = tryOps(state, postfixes, true);
 			if (q === -2) return Fail;
 			if (q >= 0) {
 				const op = postfixes[q];
 				if (op.precedence * 2 < minPower) {
-					state.pos = start;
+					state.rewind(start);
 					break;
 				}
 				lhs = op.fold(lhs, matched);
 				continue;
 			}
-			const postfixFailure = failure;
 			const i = tryOps(state, infixes, false);
 			if (i === -2) return Fail;
 			if (i < 0) {
-				const f = postfixFailure === void 0 ? failure : failure === void 0 ? postfixFailure : mergeFailures(postfixFailure, failure);
-				if (f !== void 0 && f.offset === state.pos) state.setHint(f.offset, f.expected);
+				failures.hint(state);
 				break;
 			}
 			const op = infixes[i];
 			const leftPower = op.precedence * 2;
 			if (leftPower < minPower) {
-				state.pos = start;
+				state.rewind(start);
 				break;
 			}
 			const opOut = matched;
@@ -145,7 +189,6 @@ const make = (options) => {
 	};
 	return make$1((state) => expr(state, 0), "expression");
 };
-//#endregion
 export { infixLeft, infixRight, make, postfix, prefix };
 
 //# sourceMappingURL=Expression.js.map

package/dist/Expression.js.map

@@ -1 +1 @@
-{"version":3,"file":"Expression.js","names":["makeParser"],"sources":["../src/Expression.ts"],"sourcesContent":["/**\n * Operator-precedence expression parsing with a Pratt parser (from\n * `nom-language`'s `precedence`, and winnow's expression parser).\n *\n * Describe the operand parser and a table of prefix, postfix and infix\n * operators with their precedence (higher binds tighter) and associativity.\n * Each operator carries a function that folds its operands into a result.\n *\n * @example\n * ```ts\n * import { Ascii, Expression, Parser, Token } from \"@thomasfosterau/effect-parse\"\n *\n * const op = (s: string) => Parser.delimited(Ascii.space0, Token.literal(s), Ascii.space0)\n *\n * const arithmetic: Parser.Parser<number, string> = Expression.make({\n *   operand: Parser.alt(\n *     Ascii.decInt,\n *     Parser.delimited(op(\"(\"), Parser.suspend(() => arithmetic), op(\")\"))\n *   ),\n *   operators: [\n *     Expression.prefix(op(\"-\"), 4, (_, x) => -x),\n *     Expression.postfix(op(\"!\"), 5, (x) => factorial(x)),\n *     Expression.infixRight(op(\"^\"), 3, (l, _, r) => l ** r),\n *     Expression.infixLeft(op(\"*\"), 2, (l, _, r) => l * r),\n *     Expression.infixLeft(op(\"/\"), 2, (l, _, r) => l / r),\n *     Expression.infixLeft(op(\"+\"), 1, (l, _, r) => l + r),\n *     Expression.infixLeft(op(\"-\"), 1, (l, _, r) => l - r)\n *   ]\n * })\n *\n * declare const factorial: (n: number) => number\n * Parser.parse(arithmetic, \"1 + 2 * 3 ^ 2\") // Result.succeed(19)\n * ```\n *\n * @since 0.1.0\n */\nimport type { Input, State } from \"./Input.js\"\nimport { Fail, mergeFailures } from \"./Input.js\"\nimport type { Failure } from \"./Input.js\"\nimport type { Parser } from \"./Parser.js\"\nimport { make as makeParser } from \"./Parser.js\"\n\n/**\n * An operator in an expression grammar.\n *\n * @since 0.1.0\n * @category models\n */\nexport type Operator<A, E = never, R = never, I extends Input = string> =\n  | Prefix<A, E, R, I>\n  | Postfix<A, E, R, I>\n  | Infix<A, E, R, I>\n\ninterface OperatorBase<E, R, I extends Input> {\n  readonly parser: Parser<unknown, E, R, I>\n  readonly precedence: number\n}\n\n/**\n * @since 0.1.0\n * @category models\n */\nexport interface Prefix<A, E = never, R = never, I extends Input = string> extends OperatorBase<E, R, I> {\n  readonly _tag: \"Prefix\"\n  readonly fold: (op: any, operand: A) => A\n}\n\n/**\n * @since 0.1.0\n * @category models\n */\nexport interface Postfix<A, E = never, R = never, I extends Input = string> extends OperatorBase<E, R, I> {\n  readonly _tag: \"Postfix\"\n  readonly fold: (operand: A, op: any) => A\n}\n\n/**\n * @since 0.1.0\n * @category models\n */\nexport interface Infix<A, E = never, R = never, I extends Input = string> extends OperatorBase<E, R, I> {\n  readonly _tag: \"Infix\"\n  readonly associativity: \"left\" | \"right\"\n  readonly fold: (left: A, op: any, right: A) => A\n}\n\n/**\n * A prefix operator, e.g. unary minus.\n *\n * @since 0.1.0\n * @category operators\n */\nexport const prefix = <O, E, R, I extends Input, A>(\n  parser: Parser<O, E, R, I>,\n  precedence: number,\n  fold: (op: O, operand: A) => A\n): Prefix<A, E, R, I> => ({ _tag: \"Prefix\", parser, precedence, fold })\n\n/**\n * A postfix operator, e.g. factorial or a function call suffix.\n *\n * @since 0.1.0\n * @category operators\n */\nexport const postfix = <O, E, R, I extends Input, A>(\n  parser: Parser<O, E, R, I>,\n  precedence: number,\n  fold: (operand: A, op: O) => A\n): Postfix<A, E, R, I> => ({ _tag: \"Postfix\", parser, precedence, fold })\n\n/**\n * A left-associative infix operator: `a - b - c` is `(a - b) - c`.\n *\n * @since 0.1.0\n * @category operators\n */\nexport const infixLeft = <O, E, R, I extends Input, A>(\n  parser: Parser<O, E, R, I>,\n  precedence: number,\n  fold: (left: A, op: O, right: A) => A\n): Infix<A, E, R, I> => ({ _tag: \"Infix\", associativity: \"left\", parser, precedence, fold })\n\n/**\n * A right-associative infix operator: `a ^ b ^ c` is `a ^ (b ^ c)`.\n *\n * @since 0.1.0\n * @category operators\n */\nexport const infixRight = <O, E, R, I extends Input, A>(\n  parser: Parser<O, E, R, I>,\n  precedence: number,\n  fold: (left: A, op: O, right: A) => A\n): Infix<A, E, R, I> => ({ _tag: \"Infix\", associativity: \"right\", parser, precedence, fold })\n\ntype OpError<Op> = Op extends OperatorBase<infer E, infer _R, infer _I> ? E : never\ntype OpServices<Op> = Op extends OperatorBase<infer _E, infer R, infer _I> ? R : never\ntype OpInput<Op> = [Op] extends [never] ? Input : [Op] extends [OperatorBase<infer _E, infer _R, infer I>] ? I : never\n\n/**\n * Builds an expression parser from an operand parser and an operator table.\n *\n * Precedences are compared numerically: higher binds tighter. A prefix\n * operator applies to everything that binds tighter than it, so with `-`\n * at precedence 4 and `^` at 3, `-2 ^ 2` parses as `(-2) ^ 2`.\n *\n * When several operators of the same kind match, the first one in the\n * table wins, so list longer operators (`<=`) before their prefixes (`<`).\n *\n * @since 0.1.0\n * @category constructors\n */\nexport const make = <A, E, R, I extends Input, const Ops extends ReadonlyArray<Operator<A, any, any, any>>>(options: {\n  readonly operand: Parser<A, E, R, I>\n  readonly operators: Ops\n}): Parser<A, E | OpError<Ops[number]>, R | OpServices<Ops[number]>, I & OpInput<Ops[number]>> => {\n  const operand = options.operand.step\n  const prefixes = options.operators.filter((o): o is Prefix<A, any, any, any> => o._tag === \"Prefix\")\n  const postfixes = options.operators.filter((o): o is Postfix<A, any, any, any> => o._tag === \"Postfix\")\n  const infixes = options.operators.filter((o): o is Infix<A, any, any, any> => o._tag === \"Infix\")\n\n  // Attempts each operator in turn. Returns the index of the first match\n  // (with its output in `matched`), -1 if none matched, or -2 on a fatal\n  // failure. Expectations of failed attempts are accumulated in `failure`.\n  let matched: unknown\n  let failure: Failure | undefined\n  const tryOps = (state: State<any>, ops: ReadonlyArray<OperatorBase<any, any, any>>, mustConsume: boolean): number => {\n    const start = state.pos\n    for (let i = 0; i < ops.length; i++) {\n      const out = ops[i].parser.step(state)\n      if (out !== Fail) {\n        // A prefix or postfix operator matching nothing would apply forever\n        if (mustConsume && state.pos === start) {\n          state.failMessage(\"Cut\", \"Assert\", \"prefix and postfix operators must always consume\")\n          return -2\n        }\n        matched = out\n        return i\n      }\n      if (state.mode !== \"Backtrack\") return -2\n      failure = failure === undefined ? state.failure : mergeFailures(failure, state.failure)\n      state.pos = start\n    }\n    return -1\n  }\n\n  const expr = (state: State<any>, minPower: number): A | Fail => {\n    let lhs: A | Fail\n    failure = undefined\n    const p = tryOps(state, prefixes, true)\n    if (p === -2) return Fail\n    if (p >= 0) {\n      const op = prefixes[p]\n      const opOut = matched\n      const operandValue = expr(state, op.precedence * 2)\n      if (operandValue === Fail) return Fail\n      lhs = op.fold(opOut, operandValue)\n    } else {\n      const prefixFailure = failure\n      lhs = operand(state)\n      if (lhs === Fail) {\n        if (prefixFailure !== undefined && state.mode === \"Backtrack\") {\n          state.failWith(\"Backtrack\", mergeFailures(prefixFailure, state.failure))\n        }\n        return Fail\n      }\n    }\n\n    while (true) {\n      const start = state.pos\n      failure = undefined\n      const q = tryOps(state, postfixes, true)\n      if (q === -2) return Fail\n      if (q >= 0) {\n        const op = postfixes[q]\n        if (op.precedence * 2 < minPower) {\n          state.pos = start\n          break\n        }\n        lhs = op.fold(lhs, matched)\n        continue\n      }\n      const postfixFailure = failure\n      const i = tryOps(state, infixes, false)\n      if (i === -2) return Fail\n      if (i < 0) {\n        const f =\n          postfixFailure === undefined\n            ? failure\n            : failure === undefined\n              ? postfixFailure\n              : mergeFailures(postfixFailure, failure)\n        if (f !== undefined && f.offset === state.pos) state.setHint(f.offset, f.expected)\n        break\n      }\n      const op = infixes[i]\n      const leftPower = op.precedence * 2\n      if (leftPower < minPower) {\n        state.pos = start\n        break\n      }\n      const opOut = matched\n      const rhs = expr(state, op.associativity === \"left\" ? leftPower + 1 : leftPower)\n      if (rhs === Fail) return Fail\n      lhs = op.fold(lhs, opOut, rhs)\n    }\n    return lhs\n  }\n\n  return makeParser((state: State<any>) => expr(state, 0), \"expression\")\n}\n"],"mappings":"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"}
+{"version":3,"file":"Expression.js","names":["makeParser"],"sources":["../src/Expression.ts"],"sourcesContent":["/**\n * Operator-precedence expression parsing with a Pratt parser (from\n * `nom-language`'s `precedence`, and winnow's expression parser).\n *\n * Describe the operand parser and a table of prefix, postfix and infix\n * operators with their precedence (higher binds tighter) and associativity.\n * Each operator carries a function that folds its operands into a result.\n *\n * @example\n * ```ts\n * import { Ascii, Expression, Parser, Token } from \"@thomasfosterau/effect-parse\"\n *\n * const op = (s: string) => Parser.delimited(Ascii.space0, Token.literal(s), Ascii.space0)\n *\n * const arithmetic: Parser.Parser<number, string> = Expression.make({\n *   operand: Parser.alt(\n *     Ascii.decInt,\n *     Parser.delimited(op(\"(\"), Parser.suspend(() => arithmetic), op(\")\"))\n *   ),\n *   operators: [\n *     Expression.prefix(op(\"-\"), 4, (_, x) => -x),\n *     Expression.postfix(op(\"!\"), 5, (x) => factorial(x)),\n *     Expression.infixRight(op(\"^\"), 3, (l, _, r) => l ** r),\n *     Expression.infixLeft(op(\"*\"), 2, (l, _, r) => l * r),\n *     Expression.infixLeft(op(\"/\"), 2, (l, _, r) => l / r),\n *     Expression.infixLeft(op(\"+\"), 1, (l, _, r) => l + r),\n *     Expression.infixLeft(op(\"-\"), 1, (l, _, r) => l - r)\n *   ]\n * })\n *\n * declare const factorial: (n: number) => number\n * Parser.parse(arithmetic, \"1 + 2 * 3 ^ 2\") // Result.succeed(19)\n * ```\n *\n * @since 0.1.0\n */\nimport * as Predicate from \"effect/Predicate\"\nimport type { Input, State } from \"./Input.js\"\nimport { Fail } from \"./Input.js\"\nimport type { Parser } from \"./Parser.js\"\nimport { make as makeParser } from \"./Parser.js\"\nimport { TiedFailures } from \"./internal/ties.js\"\n\n/**\n * An operator in an expression grammar.\n *\n * @since 0.1.0\n * @category models\n */\nexport type Operator<A, E = never, R = never, I extends Input = string> =\n  | Prefix<A, E, R, I>\n  | Postfix<A, E, R, I>\n  | Infix<A, E, R, I>\n\ninterface OperatorBase<E, R, I extends Input> {\n  readonly parser: Parser<unknown, E, R, I>\n  readonly precedence: number\n}\n\n/**\n * @since 0.1.0\n * @category models\n */\nexport interface Prefix<A, E = never, R = never, I extends Input = string> extends OperatorBase<E, R, I> {\n  readonly _tag: \"Prefix\"\n  readonly fold: (op: any, operand: A) => A\n}\n\n/**\n * @since 0.1.0\n * @category models\n */\nexport interface Postfix<A, E = never, R = never, I extends Input = string> extends OperatorBase<E, R, I> {\n  readonly _tag: \"Postfix\"\n  readonly fold: (operand: A, op: any) => A\n}\n\n/**\n * @since 0.1.0\n * @category models\n */\nexport interface Infix<A, E = never, R = never, I extends Input = string> extends OperatorBase<E, R, I> {\n  readonly _tag: \"Infix\"\n  readonly associativity: \"left\" | \"right\"\n  readonly fold: (left: A, op: any, right: A) => A\n}\n\n/**\n * A prefix operator, e.g. unary minus.\n *\n * @since 0.1.0\n * @category operators\n */\nexport const prefix = <O, E, R, I extends Input, A>(\n  parser: Parser<O, E, R, I>,\n  precedence: number,\n  fold: (op: O, operand: A) => A\n): Prefix<A, E, R, I> => ({ _tag: \"Prefix\", parser, precedence, fold })\n\n/**\n * A postfix operator, e.g. factorial or a function call suffix.\n *\n * @since 0.1.0\n * @category operators\n */\nexport const postfix = <O, E, R, I extends Input, A>(\n  parser: Parser<O, E, R, I>,\n  precedence: number,\n  fold: (operand: A, op: O) => A\n): Postfix<A, E, R, I> => ({ _tag: \"Postfix\", parser, precedence, fold })\n\n/**\n * A left-associative infix operator: `a - b - c` is `(a - b) - c`.\n *\n * @since 0.1.0\n * @category operators\n */\nexport const infixLeft = <O, E, R, I extends Input, A>(\n  parser: Parser<O, E, R, I>,\n  precedence: number,\n  fold: (left: A, op: O, right: A) => A\n): Infix<A, E, R, I> => ({ _tag: \"Infix\", associativity: \"left\", parser, precedence, fold })\n\n/**\n * A right-associative infix operator: `a ^ b ^ c` is `a ^ (b ^ c)`.\n *\n * @since 0.1.0\n * @category operators\n */\nexport const infixRight = <O, E, R, I extends Input, A>(\n  parser: Parser<O, E, R, I>,\n  precedence: number,\n  fold: (left: A, op: O, right: A) => A\n): Infix<A, E, R, I> => ({ _tag: \"Infix\", associativity: \"right\", parser, precedence, fold })\n\ntype OpError<Op> = Op extends OperatorBase<infer E, infer _R, infer _I> ? E : never\ntype OpServices<Op> = Op extends OperatorBase<infer _E, infer R, infer _I> ? R : never\ntype OpInput<Op> = [Op] extends [never] ? Input : [Op] extends [OperatorBase<infer _E, infer _R, infer I>] ? I : never\n\n/**\n * Builds an expression parser from an operand parser and an operator table.\n *\n * Precedences are compared numerically: higher binds tighter. A prefix\n * operator applies to everything that binds tighter than it, so with `-`\n * at precedence 4 and `^` at 3, `-2 ^ 2` parses as `(-2) ^ 2`.\n *\n * When several operators of the same kind match, the first one in the\n * table wins, so list longer operators (`<=`) before their prefixes (`<`).\n *\n * @since 0.1.0\n * @category constructors\n */\nexport const make = <A, E, R, I extends Input, const Ops extends ReadonlyArray<Operator<A, any, any, any>>>(options: {\n  readonly operand: Parser<A, E, R, I>\n  readonly operators: Ops\n}): Parser<A, E | OpError<Ops[number]>, R | OpServices<Ops[number]>, I & OpInput<Ops[number]>> => {\n  const operand = options.operand.step\n  const prefixes = options.operators.filter((o): o is Prefix<A, any, any, any> => Predicate.isTagged(o, \"Prefix\"))\n  const postfixes = options.operators.filter((o): o is Postfix<A, any, any, any> => Predicate.isTagged(o, \"Postfix\"))\n  const infixes = options.operators.filter((o): o is Infix<A, any, any, any> => Predicate.isTagged(o, \"Infix\"))\n\n  // Attempts each operator in turn. Returns the index of the first match\n  // (with its output in `matched`), -1 if none matched, or -2 on a fatal\n  // failure. Failed attempts are folded into `failures`, merged only when\n  // read (#44): a round in which an operator matches discards them unmerged.\n  // Like `matched`, it is shared by nested expressions, which clear it.\n  let matched: unknown\n  const failures = new TiedFailures()\n  const tryOps = (state: State<any>, ops: ReadonlyArray<OperatorBase<any, any, any>>, mustConsume: boolean): number => {\n    const start = state.pos\n    for (let i = 0; i < ops.length; i++) {\n      const out = ops[i].parser.step(state)\n      if (out !== Fail) {\n        // A prefix or postfix operator matching nothing would apply forever\n        if (mustConsume && state.pos === start) {\n          state.failMessage(\"Cut\", \"Assert\", \"prefix and postfix operators must always consume\")\n          return -2\n        }\n        matched = out\n        return i\n      }\n      if (state.mode !== \"Backtrack\") return -2\n      state.rewind(start)\n      failures.add(state)\n    }\n    return -1\n  }\n\n  const expr = (state: State<any>, minPower: number): A | Fail => {\n    let lhs: A | Fail\n    failures.clear()\n    const p = tryOps(state, prefixes, true)\n    if (p === -2) return Fail\n    if (p >= 0) {\n      const op = prefixes[p]\n      const opOut = matched\n      const operandValue = expr(state, op.precedence * 2)\n      if (operandValue === Fail) return Fail\n      lhs = op.fold(opOut, operandValue)\n    } else {\n      const prefixFailure = failures.failure\n      const prefixTie1 = failures.tie1\n      const prefixTie2 = failures.tie2\n      lhs = operand(state)\n      if (lhs === Fail) {\n        if (prefixFailure !== undefined && state.mode === \"Backtrack\") {\n          // The operand may have parsed nested expressions, which reuse `failures`\n          failures.failure = prefixFailure\n          failures.tie1 = prefixTie1\n          failures.tie2 = prefixTie2\n          failures.add(state)\n          failures.fail(state)\n        }\n        return Fail\n      }\n    }\n\n    while (true) {\n      const start = state.pos\n      failures.clear()\n      const q = tryOps(state, postfixes, true)\n      if (q === -2) return Fail\n      if (q >= 0) {\n        const op = postfixes[q]\n        if (op.precedence * 2 < minPower) {\n          state.rewind(start)\n          break\n        }\n        lhs = op.fold(lhs, matched)\n        continue\n      }\n      // The infix attempts are folded on top of the postfix ones\n      const i = tryOps(state, infixes, false)\n      if (i === -2) return Fail\n      if (i < 0) {\n        failures.hint(state)\n        break\n      }\n      const op = infixes[i]\n      const leftPower = op.precedence * 2\n      if (leftPower < minPower) {\n        state.rewind(start)\n        break\n      }\n      const opOut = matched\n      const rhs = expr(state, op.associativity === \"left\" ? leftPower + 1 : leftPower)\n      if (rhs === Fail) return Fail\n      lhs = op.fold(lhs, opOut, rhs)\n    }\n    return lhs\n  }\n\n  return makeParser((state: State<any>) => expr(state, 0), \"expression\")\n}\n"],"mappings":"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"}

package/dist/Input.d.ts

@@ -2,7 +2,6 @@ import * as Context from "effect/Context";
 import { ErrorKind } from "./ParseError.js";
 import { Builder } from "./internal/syntax.js";
 import { Encoding } from "./Encoding.js";
-//#region src/Input.d.ts
 /**
  * The kinds of input a parser can consume.
  *
@@ -161,7 +160,10 @@ export interface TraceEvent {
 export declare class State<I extends Input = Input> {
   /** The full input being parsed. */
   readonly input: I;
-  /** The current offset. Advanced by parsers, rewound on backtracking. */
+  /**
+   * The current offset. Parsers advance it by assigning it; moving it back
+   * (backtracking, or after a lookahead) goes through {@link rewind}.
+   */
   pos: number;
   /** The end offset (the input's length; in bits inside `Bits.bits`). */
   end: number;
@@ -173,8 +175,31 @@ export declare class State<I extends Input = Input> {
   context: Context.Context<never>;
   /** Mode of the latest failure. Only meaningful after a step returned {@link Fail}. */
   mode: ErrMode;
-  /** Details of the latest failure. Only meaningful after a step returned {@link Fail}. */
-  failure: Failure;
+  /**
+   * The latest failure, kept unmerged: the failure is `failureHead` merged
+   * (as `mergeFailures` does) with `failureTie1` and then `failureTie2`, all
+   * at the same offset. `Parser.alt` records its tied branch failures here
+   * with {@link failTies} instead of merging them, so that an enclosing `alt`
+   * whose next branch succeeds never pays for the merge. Reading
+   * {@link failure} performs the merge, once.
+   *
+   * @internal
+   */
+  failureHead: Failure;
+  /** @internal */
+  failureTie1: Failure | undefined;
+  /** @internal */
+  failureTie2: Failure | undefined;
+  /** Backs {@link deepest}. @internal */
+  deepestFailure: Failure | undefined;
+  /**
+   * Whether the furthest failure is the latest failure, still unmerged, so
+   * that {@link deepest} is that failure once merged. Only set while
+   * `failureTie1` is.
+   *
+   * @internal
+   */
+  deepestIsLatest: boolean;
   /**
    * The offset of a recoverable failure that occurred without consuming
    * input (for example the last attempt of a `repeat`). Its
@@ -193,7 +218,8 @@ export declare class State<I extends Input = Input> {
    * recorded inside it when it commits, and `Parser.peek` and `Parser.not`
    * forget the failures of a lookahead that succeeded.
    */
-  deepest: Failure | undefined;
+  get deepest(): Failure | undefined;
+  set deepest(failure: Failure | undefined);
   /** When defined, `Parser.resumeAfter`/`retryAfter` record failures here. */
   recovered: Array<Failure> | undefined;
   /** When defined, `Parser.trace` reports events here. */
@@ -213,7 +239,8 @@ export declare class State<I extends Input = Input> {
    */
   resume: Map<object, Map<number, unknown>> | undefined;
   /**
-   * The tree builder of a `Syntax` parse; `undefined` otherwise.
+   * The tree builder of a `Syntax` parse; `undefined` otherwise. A builder
+   * rather than a subclass of `State`, so that every state has one shape.
    *
    * @internal
    */
@@ -223,6 +250,11 @@ export declare class State<I extends Input = Input> {
     readonly context?: Context.Context<never> | undefined;
     readonly offset?: number | undefined;
   });
+  /** Details of the latest failure. Only meaningful after a step returned {@link Fail}. */
+  get failure(): Failure;
+  set failure(failure: Failure);
+  /** Merges the latest failure's ties into it (see {@link failureHead}). */
+  private settleFailure;
   /**
    * Prepares the state for another run over the same input, starting at
    * `offset`: afterwards it behaves exactly like
@@ -255,6 +287,32 @@ export declare class State<I extends Input = Input> {
     readonly partial?: boolean | undefined;
     readonly context?: Context.Context<never> | undefined;
   }): this;
+  /**
+   * Moves the cursor back to `offset`, abandoning what was parsed after it:
+   * how a parser backtracks, or returns to where a lookahead started. A step
+   * that moves the cursor backwards must use this rather than assigning
+   * {@link pos}, so that a `Syntax` parse drops the nodes the abandoned
+   * attempt built. Moving forward is an assignment.
+   *
+   * @example
+   * ```ts
+   * import { Input, Parser } from "@thomasfosterau/effect-parse"
+   *
+   * // Like `Parser.opt`, for one parser
+   * const optional = <A>(p: Parser.Parser<A>) =>
+   *   Parser.make<A | undefined>((state) => {
+   *     const start = state.pos
+   *     const a = p.step(state)
+   *     if (a !== Input.Fail) return a
+   *     if (state.mode !== "Backtrack") return Input.Fail
+   *     state.rewind(start)
+   *     return undefined
+   *   })
+   * ```
+   *
+   * @since 0.4.0
+   */
+  rewind(offset: number): void;
   /**
    * The number of input units (code units, bytes or elements) remaining.
    */
@@ -297,6 +355,14 @@ export declare class State<I extends Input = Input> {
    * Records the given failure and returns {@link Fail}.
    */
   failWith(mode: ErrMode, failure: Failure): Fail;
+  /**
+   * Records a recoverable failure made of tied failures, merged only when
+   * read: `failWith("Backtrack", f)` where `f` merges `head` with `tie1`
+   * and then `tie2` (all at the same offset), as `mergeFailures` would.
+   *
+   * @internal
+   */
+  failTies(head: Failure, tie1: Failure, tie2: Failure | undefined): Fail;
   /**
    * Replaces the details of the current failure (for example to add context),
    * keeping the record of the furthest failure consistent.
@@ -326,5 +392,12 @@ export declare const mergeExpected: (a: ReadonlyArray<string>, b: ReadonlyArray<
  * @internal
  */
 export declare const mergeFailures: (a: Failure, b: Failure) => Failure;
-//#endregion
+/**
+ * {@link mergeFailures} for two failures at the same offset, given their
+ * merged expectations (`mergeExpected(a.expected, b.expected)`, possibly
+ * memoised by the caller).
+ *
+ * @internal
+ */
+export declare const mergeTiedFailures: (a: Failure, b: Failure, expected: ReadonlyArray<string>) => Failure;
 //# sourceMappingURL=Input.d.ts.map

package/dist/Input.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Input.d.ts","names":["SyntaxBuilder"],"sources":["../src/Input.ts"],"mappings":";;;;;;;;;;;;;;;;YAgCY,iBAAiB,aAAa;;;;;;;;;;;;;YAc9B,cAAc,kBAAkB;;;;;;;;YAShC,OAAO,KAAK,MAAM,YAAY,cAAc;;;;;;;;;;;;;;;qBAgB3C;GACV,QAAQ,cAAc;GACtB,UAAU,OAAO,QAAQ,OAAO,KAAK;;;;;;;;YAkB5B,MAAM,KAAK,4BAEnB,UAAU,sBAER,UAAU,oBAAoB,KAC5B;;;;;;;YASI,MAAM,KAAK,4BAEnB,UAAU,aACR,aACA,UAAU,oBAAoB,KAC5B,cAAc;;;;;;;;qBAUT;;;;;YAMD,cAAc;;;;;;;;;;;YAYd;;;;;;;qBAQC;;WAGA;;WAEA,MAAM;;WAEN,UAAU;;WAEV,SAAS;;WAET;;WAEA;;WAEA;;WAEA;;;EAdA;;EAEA,MAAM;;EAEN,UAAU;;EAEV,SAAS;;EAET;;EAEA;;EAEA;;EAEA;;;qBAUA;;;;;;;iBAQI;WACN;WACA;WACA;WACA;;WAEA,gBAAgB;;WAEhB;WACA,OAAO;;;;;;;;qBASL,MAAM,UAAU,QAAQ;;WAE1B,OAAO;;EAGR;;EAER;;WAES;;EAET;;EAEA,SAAS,QAAQ;;EAEjB,MAAM;;EAEN,SAAS;;;;;;;EAOT;;EAEA,cAAc;;;;;;;;;;EAUd,SAAS;;EAET,WAAW,MAAM;;EAEjB,UAAU,OAAO;;EAEjB;;;;;EAKA,UAAU;;;;;;;EAOV,QAAQ,YAAY;;;;;;EAMpB,QAAQA;EAGN,YAAA,QAAQ,IAAI,OAAO,IACnB;aACW;aACA,UAAU,QAAQ;aAClB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyCb,MACE,iBACA;aACW;aACA,UAAU,QAAQ;;;;;EAuB/B;;;;EAOA;;;;EAOA,MAAM,eAAe,cAAc,MAAM;;;;EAezC,UAAU,MAAM,WAAW,WAAU,uBAA+B,kBAA4B;;;;EAOhG,IAAI,MAAM,WAAW,WAAU,uBAA+B,kBAA4B;;;;;EAQ1F,WAAW,gBAAgB,WAAU,wBAAgC;;;;;EAWrE,IAAI,MAAM,WAAW,UAAU,uBAAuB,iBAAiB;;;;EAOvE,UAAU,MAAM,SAAS,MAAM,WAAW,gBAAgB,kBAA4B;;;;EAOtF,YAAY,MAAM,SAAS,MAAM,WAAW,iBAAiB,kBAA4B;;;;EAOzF,SAAS,MAAM,SAAS,SAAS,UAAU;;;;;EAa3C,eAAe,SAAS;;;;;;EAUxB,mBAAmB;;;;;;EAuBnB,QAAQ,gBAAgB,UAAU;;EAUlC,YAAY,gBAAgB,MAAM,WAAW,UAAU,wBAAwB;;;qBASpE,gBAAiB,GAAG,uBAAuB,GAAG,0BAAwB;;;;;;;qBAgBtE,gBAAiB,GAAG,SAAS,GAAG,YAAU"}
+{"version":3,"file":"Input.d.ts","names":["SyntaxBuilder"],"sources":["../src/Input.ts"],"mappings":";;;;;;;;;;;;;;;YAiCY,iBAAiB,aAAa;;;;;;;;;;;;;YAc9B,cAAc,kBAAkB;;;;;;;;YAShC,OAAO,KAAK,MAAM,YAAY,cAAc;;;;;;;;;;;;;;;qBAgB3C;GACV,QAAQ,cAAc;GACtB,UAAU,OAAO,QAAQ,OAAO,KAAK;;;;;;;;YAkB5B,MAAM,KAAK,4BAEnB,UAAU,sBAER,UAAU,oBAAoB,KAC5B;;;;;;;YASI,MAAM,KAAK,4BAEnB,UAAU,aACR,aACA,UAAU,oBAAoB,KAC5B,cAAc;;;;;;;;qBAUT;;;;;YAMD,cAAc;;;;;;;;;;;YAYd;;;;;;;qBAQC;;WAGA;;WAEA,MAAM;;WAEN,UAAU;;WAEV,SAAS;;WAET;;WAEA;;WAEA;;WAEA;;;EAdA;;EAEA,MAAM;;EAEN,UAAU;;EAEV,SAAS;;EAET;;EAEA;;EAEA;;EAEA;;;qBAUA;;;;;;;iBAQI;WACN;WACA;WACA;WACA;;WAEA,gBAAgB;;WAEhB;WACA,OAAO;;;;;;;;qBASL,MAAM,UAAU,QAAQ;;WAE1B,OAAO;;;;;EAKhB;;EAEA;;WAES;;EAET;;EAEA,SAAS,QAAQ;;EAEjB,MAAM;;;;;;;;;;;EAWN,aAAa;;EAEb,aAAa;;EAEb,aAAa;;EAEb,gBAAgB;;;;;;;;EAQhB;;;;;;;EAOA;;EAEA,cAAc;;;;;;;;;;MAUV,WAAW;MAIX,QAAQ,SAAS;;EAKrB,WAAW,MAAM;;EAEjB,UAAU,OAAO;;EAEjB;;;;;EAKA,UAAU;;;;;;;EAOV,QAAQ,YAAY;;;;;;;EAOpB,QAAQA;EAGN,YAAA,QAAQ,IAAI,OAAO,IACnB;aACW;aACA,UAAU,QAAQ;aAClB;;;MAcT,WAAW;MAIX,QAAQ,SAAS;;UAQb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6CR,MACE,iBACA;aACW;aACA,UAAU,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgD/B,OAAO;;;;EASP;;;;EAOA;;;;EAOA,MAAM,eAAe,cAAc,MAAM;;;;EAezC,UAAU,MAAM,WAAW,WAAU,uBAA+B,kBAA4B;;;;EAOhG,IAAI,MAAM,WAAW,WAAU,uBAA+B,kBAA4B;;;;;EAQ1F,WAAW,gBAAgB,WAAU,wBAAgC;;;;;EAWrE,IAAI,MAAM,WAAW,UAAU,uBAAuB,iBAAiB;;;;EAOvE,UAAU,MAAM,SAAS,MAAM,WAAW,gBAAgB,kBAA4B;;;;EAOtF,YAAY,MAAM,SAAS,MAAM,WAAW,iBAAiB,kBAA4B;;;;EAOzF,SAAS,MAAM,SAAS,SAAS,UAAU;;;;;;;;EAwB3C,SAAS,MAAM,SAAS,MAAM,SAAS,MAAM,sBAAsB;;;;;EAenE,eAAe,SAAS;;;;;;EAUxB,mBAAmB;;;;;;EAwBnB,QAAQ,gBAAgB,UAAU;;EAWlC,YAAY,gBAAgB,MAAM,WAAW,UAAU,wBAAwB;;;qBASpE,gBAAiB,GAAG,uBAAuB,GAAG,0BAAwB;;;;;;;qBAgBtE,gBAAiB,GAAG,SAAS,GAAG,YAAU;;;;;;;;qBAa1C,oBAAqB,GAAG,SAAS,GAAG,SAAS,UAAU,0BAAwB"}

package/dist/Input.js

@@ -1,6 +1,7 @@
 import * as Predicate from "effect/Predicate";
+import * as Arr from "effect/Array";
 import * as Context from "effect/Context";
-//#region src/Input.ts
+// src/Input.ts
 /**
 * Input types and the mutable parse {@link State} cursor.
 *
@@ -85,6 +86,11 @@ const emptyStrings = empty;
 var State = class {
 	/** The full input being parsed. */
 	input;
+	/**
+	* The current offset. Parsers advance it by assigning it; moving it back
+	* (backtracking, or after a lookahead) goes through {@link rewind}.
+	*/
+	pos;
 	/** The end offset (the input's length; in bits inside `Bits.bits`). */
 	end;
 	/** 0 = string, 1 = Uint8Array, 2 = array. */
@@ -95,8 +101,31 @@ var State = class {
 	context;
 	/** Mode of the latest failure. Only meaningful after a step returned {@link Fail}. */
 	mode = "Backtrack";
-	/** Details of the latest failure. Only meaningful after a step returned {@link Fail}. */
-	failure;
+	/**
+	* The latest failure, kept unmerged: the failure is `failureHead` merged
+	* (as `mergeFailures` does) with `failureTie1` and then `failureTie2`, all
+	* at the same offset. `Parser.alt` records its tied branch failures here
+	* with {@link failTies} instead of merging them, so that an enclosing `alt`
+	* whose next branch succeeds never pays for the merge. Reading
+	* {@link failure} performs the merge, once.
+	*
+	* @internal
+	*/
+	failureHead;
+	/** @internal */
+	failureTie1 = void 0;
+	/** @internal */
+	failureTie2 = void 0;
+	/** Backs {@link deepest}. @internal */
+	deepestFailure = void 0;
+	/**
+	* Whether the furthest failure is the latest failure, still unmerged, so
+	* that {@link deepest} is that failure once merged. Only set while
+	* `failureTie1` is.
+	*
+	* @internal
+	*/
+	deepestIsLatest = false;
 	/**
 	* The offset of a recoverable failure that occurred without consuming
 	* input (for example the last attempt of a `repeat`). Its
@@ -115,7 +144,14 @@ var State = class {
 	* recorded inside it when it commits, and `Parser.peek` and `Parser.not`
 	* forget the failures of a lookahead that succeeded.
 	*/
-	deepest = void 0;
+	get deepest() {
+		if (this.deepestIsLatest) this.settleFailure();
+		return this.deepestFailure;
+	}
+	set deepest(failure) {
+		this.deepestIsLatest = false;
+		this.deepestFailure = failure;
+	}
 	/** When defined, `Parser.resumeAfter`/`retryAfter` record failures here. */
 	recovered = void 0;
 	/** When defined, `Parser.trace` reports events here. */
@@ -135,7 +171,8 @@ var State = class {
 	*/
 	resume = void 0;
 	/**
-	* The tree builder of a `Syntax` parse; `undefined` otherwise.
+	* The tree builder of a `Syntax` parse; `undefined` otherwise. A builder
+	* rather than a subclass of `State`, so that every state has one shape.
 	*
 	* @internal
 	*/
@@ -148,7 +185,35 @@ var State = class {
 		this.partial = options?.partial ?? false;
 		this.context = options?.context ?? Context.empty();
 		this.inputKind = Predicate.isString(input) ? 0 : input instanceof Uint8Array ? 1 : 2;
-		this.failure = initialFailure;
+		this.failureHead = initialFailure;
+	}
+	/** Details of the latest failure. Only meaningful after a step returned {@link Fail}. */
+	get failure() {
+		if (this.failureTie1 !== void 0) this.settleFailure();
+		return this.failureHead;
+	}
+	set failure(failure) {
+		if (this.deepestIsLatest) this.settleFailure();
+		this.failureHead = failure;
+		this.failureTie1 = void 0;
+		this.failureTie2 = void 0;
+	}
+	/** Merges the latest failure's ties into it (see {@link failureHead}). */
+	settleFailure() {
+		let failure = this.failureHead;
+		const tie1 = this.failureTie1;
+		if (tie1 !== void 0) {
+			failure = mergeTiedFailures(failure, tie1, mergeExpected(failure.expected, tie1.expected));
+			const tie2 = this.failureTie2;
+			if (tie2 !== void 0) failure = mergeTiedFailures(failure, tie2, mergeExpected(failure.expected, tie2.expected));
+			this.failureHead = failure;
+			this.failureTie1 = void 0;
+			this.failureTie2 = void 0;
+		}
+		if (this.deepestIsLatest) {
+			this.deepestFailure = failure;
+			this.deepestIsLatest = false;
+		}
 	}
 	/**
 	* Prepares the state for another run over the same input, starting at
@@ -184,10 +249,13 @@ var State = class {
 		this.partial = options?.partial ?? false;
 		this.context = options?.context ?? Context.empty();
 		this.mode = "Backtrack";
-		this.failure = initialFailure;
+		this.failureHead = initialFailure;
+		this.failureTie1 = void 0;
+		this.failureTie2 = void 0;
 		this.hintOffset = -1;
 		this.hintExpected = empty;
-		this.deepest = void 0;
+		this.deepestFailure = void 0;
+		this.deepestIsLatest = false;
 		this.recovered = void 0;
 		this.tracer = void 0;
 		this.depth = 0;
@@ -196,6 +264,36 @@ var State = class {
 		return this;
 	}
 	/**
+	* Moves the cursor back to `offset`, abandoning what was parsed after it:
+	* how a parser backtracks, or returns to where a lookahead started. A step
+	* that moves the cursor backwards must use this rather than assigning
+	* {@link pos}, so that a `Syntax` parse drops the nodes the abandoned
+	* attempt built. Moving forward is an assignment.
+	*
+	* @example
+	* ```ts
+	* import { Input, Parser } from "@thomasfosterau/effect-parse"
+	*
+	* // Like `Parser.opt`, for one parser
+	* const optional = <A>(p: Parser.Parser<A>) =>
+	*   Parser.make<A | undefined>((state) => {
+	*     const start = state.pos
+	*     const a = p.step(state)
+	*     if (a !== Input.Fail) return a
+	*     if (state.mode !== "Backtrack") return Input.Fail
+	*     state.rewind(start)
+	*     return undefined
+	*   })
+	* ```
+	*
+	* @since 0.4.0
+	*/
+	rewind(offset) {
+		const syntax = this.syntax;
+		if (syntax !== void 0 && offset < this.pos) syntax.rewound(this.pos, offset);
+		this.pos = offset;
+	}
+	/**
 	* The number of input units (code units, bytes or elements) remaining.
 	*/
 	remaining() {
@@ -261,8 +359,32 @@ var State = class {
 	*/
 	failWith(mode, failure) {
 		this.mode = mode;
-		this.failure = failure;
-		if (mode === "Backtrack" && (this.deepest === void 0 || failure.offset >= this.deepest.offset)) this.deepest = failure;
+		if (this.deepestIsLatest) {
+			if (mode === "Backtrack" && failure.offset >= this.failureHead.offset) this.deepestIsLatest = false;
+			else this.settleFailure();
+		}
+		this.failureHead = failure;
+		this.failureTie1 = void 0;
+		this.failureTie2 = void 0;
+		if (mode === "Backtrack" && (this.deepestFailure === void 0 || failure.offset >= this.deepestFailure.offset)) this.deepestFailure = failure;
+		if (this.syntax !== void 0) this.syntax.reach(failure.offset);
+		return Fail;
+	}
+	/**
+	* Records a recoverable failure made of tied failures, merged only when
+	* read: `failWith("Backtrack", f)` where `f` merges `head` with `tie1`
+	* and then `tie2` (all at the same offset), as `mergeFailures` would.
+	*
+	* @internal
+	*/
+	failTies(head, tie1, tie2) {
+		this.mode = "Backtrack";
+		if (this.deepestIsLatest && head.offset < this.failureHead.offset) this.settleFailure();
+		this.failureHead = head;
+		this.failureTie1 = tie1;
+		this.failureTie2 = tie2;
+		this.deepestIsLatest = this.deepestFailure === void 0 || head.offset >= this.deepestFailure.offset;
+		if (this.syntax !== void 0) this.syntax.reach(head.offset);
 		return Fail;
 	}
 	/**
@@ -282,7 +404,7 @@ var State = class {
 		const f = this.failure;
 		const d = this.deepest;
 		if (d === void 0 || d === f || d.offset <= f.offset || this.mode === "Incomplete" || f.hasCause || f.message !== void 0) return f;
-		const context = d.context.length === 0 ? f.context : [...d.context, ...f.context.filter((l) => !d.context.includes(l))];
+		const context = Arr.isReadonlyArrayEmpty(d.context) ? f.context : [...d.context, ...f.context.filter((l) => !d.context.includes(l))];
 		return new Failure(d.offset, d.kind, d.expected, context, d.hasCause, d.cause, d.message, d.needed);
 	}
 	/**
@@ -291,6 +413,7 @@ var State = class {
 	* `repeat` and `Ascii.digit1`.
 	*/
 	setHint(offset, expected) {
+		if (this.syntax !== void 0) this.syntax.reach(offset);
 		if (this.hintOffset === offset) this.hintExpected = mergeExpected(this.hintExpected, expected);
 		else {
 			this.hintOffset = offset;
@@ -299,14 +422,14 @@ var State = class {
 	}
 	/** @internal */
 	makeFailure(offset, kind, expected) {
-		if (this.hintOffset === offset && this.hintExpected.length > 0) expected = mergeExpected(this.hintExpected, expected);
+		if (this.hintOffset === offset && Arr.isReadonlyArrayNonEmpty(this.hintExpected)) expected = mergeExpected(this.hintExpected, expected);
 		return new Failure(offset, kind, expected, empty, false, void 0, void 0, 0);
 	}
 };
 /** @internal */
 const mergeExpected = (a, b) => {
-	if (a.length === 0) return b;
-	if (b.length === 0) return a;
+	if (Arr.isReadonlyArrayEmpty(a)) return b;
+	if (Arr.isReadonlyArrayEmpty(b)) return a;
 	const out = a.slice();
 	for (const e of b) if (!out.includes(e)) out.push(e);
 	return out;
@@ -320,11 +443,19 @@ const mergeExpected = (a, b) => {
 const mergeFailures = (a, b) => {
 	if (a.offset > b.offset) return a;
 	if (b.offset > a.offset) return b;
-	const expected = mergeExpected(a.expected, b.expected);
+	return mergeTiedFailures(a, b, mergeExpected(a.expected, b.expected));
+};
+/**
+* {@link mergeFailures} for two failures at the same offset, given their
+* merged expectations (`mergeExpected(a.expected, b.expected)`, possibly
+* memoised by the caller).
+*
+* @internal
+*/
+const mergeTiedFailures = (a, b, expected) => {
 	if (expected === b.expected) return b;
-	return new Failure(b.offset, b.kind, expected, b.context.length > 0 ? b.context : a.context, b.hasCause || a.hasCause, b.hasCause ? b.cause : a.cause, b.message ?? a.message, b.needed);
+	return new Failure(b.offset, b.kind, expected, Arr.isReadonlyArrayNonEmpty(b.context) ? b.context : a.context, b.hasCause || a.hasCause, b.hasCause ? b.cause : a.cause, b.message ?? a.message, b.needed);
 };
-//#endregion
-export { Fail, Failure, State, emptyStrings, fromSource, mergeExpected, mergeFailures };
+export { Fail, Failure, State, emptyStrings, fromSource, mergeExpected, mergeFailures, mergeTiedFailures };
 
 //# sourceMappingURL=Input.js.map