@thomasfosterau/effect-parse 0.1.0 → 0.3.0

package/src/internal/syntax.ts

@@ -0,0 +1,426 @@
+/**
+ * The tree builder behind the `Syntax` module (see `docs/DESIGN.md`,
+ * "Syntax trees").
+ *
+ * Trees are stored as *green* nodes, as in Roslyn and rust-analyzer: a green
+ * node knows its kind, its width and its children's offsets relative to its
+ * own start, but not where it is in the input or who its parent is. A subtree
+ * that an edit doesn't touch can therefore be shared, unchanged, by the tree
+ * before the edit and the tree after it. `Syntax.SyntaxNode` is the *red*
+ * view: a green node, its absolute start and its parent, built lazily while
+ * navigating.
+ *
+ * While parsing, completed nodes wait on a stack until the node around them
+ * completes and adopts them. Nodes built by an attempt that is later
+ * abandoned must not end up in the tree. Every combinator that abandons an
+ * attempt moves the cursor back to (or before) where the attempt started,
+ * and every node has a positive width, so the nodes of an abandoned attempt
+ * are exactly those that end after the position the cursor moves back to:
+ * the `pos` setter of {@link SyntaxState} drops them. This also covers
+ * lookahead (`peek`, `not`) and custom parsers written with `Parser.make`.
+ *
+ * For incremental parsing, every node records how far its parse looked: the
+ * furthest position the cursor reached and the furthest failure recorded
+ * while it was being parsed (its *lookahead*). A node from the previous tree
+ * is reused at a position when it was built by the same `Syntax.node`, and
+ * the input it looked at, plus a margin for the tokens that read a little
+ * past where they stop, is unchanged.
+ */
+import * as Predicate from "effect/Predicate"
+import type * as Context from "effect/Context"
+import type { Encoding } from "../Encoding.js"
+import type { ErrMode, Input, Source } from "../Input.js"
+import { Fail, Failure, State } from "../Input.js"
+
+/** What a failure inside an `ERROR` node was. Offsets are relative to the node. */
+export interface ErrorInfo {
+  readonly failure: Failure
+  readonly mode: ErrMode
+}
+
+/** A position-independent syntax tree node. */
+export class Green {
+  constructor(
+    readonly kind: string,
+    readonly named: boolean,
+    /** The `Syntax.node` that built it; `undefined` for roots and errors, which are never reused alone. */
+    readonly key: object | undefined,
+    readonly width: number,
+    /** How far its parse looked, relative to its start (at least `width`). */
+    readonly lookahead: number,
+    readonly children: ReadonlyArray<Green>,
+    /** The children's starts, relative to this node's start. */
+    readonly offsets: ReadonlyArray<number>,
+    /** The children's field names, when any child has one. */
+    readonly fields: ReadonlyArray<string | undefined> | undefined,
+    readonly value: unknown,
+    /** Set on `ERROR` nodes. */
+    readonly error: ErrorInfo | undefined,
+    /** Whether this node or a descendant is an `ERROR` node. */
+    readonly hasError: boolean,
+    /** What its parse left behind for error reporting, replayed when it is reused. */
+    readonly diagnostics: Diagnostics | undefined
+  ) {}
+}
+
+/**
+ * The error-reporting state a node's parse leaves behind (see
+ * `State.deepest` and `State.setHint`). A reused node replays it, so that
+ * a reparse reports the errors a fresh parse does.
+ */
+export interface Diagnostics {
+  /** The furthest failure, at its offset in the parse that built the node... */
+  readonly deepest: Failure | undefined
+  /** ...which started the node at `base`. */
+  readonly base: number
+  /** Relative to the node's start. */
+  readonly hintOffset: number
+  readonly hintExpected: ReadonlyArray<string> | undefined
+}
+
+/** A completed node waiting for its parent, at an absolute position. */
+class Child {
+  constructor(
+    readonly green: Green,
+    readonly start: number,
+    readonly end: number,
+    public field: string | undefined
+  ) {}
+}
+
+export const errorKind = "ERROR"
+
+const rebase = (f: Failure, start: number): Failure =>
+  new Failure(f.offset - start, f.kind, f.expected, f.context, f.hasCause, f.cause, f.message, f.needed)
+
+/** Moves a failure stored relative to a node back to absolute offsets. */
+export const absolute = (f: Failure, start: number): Failure => rebase(f, -start)
+
+/**
+ * Builds a green node over `[start, end)` from the children waiting on the
+ * stack.
+ */
+const build = (
+  kind: string,
+  named: boolean,
+  key: object | undefined,
+  start: number,
+  end: number,
+  lookahead: number,
+  entries: ReadonlyArray<Child>,
+  value: unknown,
+  error: ErrorInfo | undefined,
+  diagnostics?: Diagnostics
+): Green => {
+  const n = entries.length
+  const children = new Array<Green>(n)
+  const offsets = new Array<number>(n)
+  let fields: Array<string | undefined> | undefined
+  let hasError = error !== undefined
+  for (let i = 0; i < n; i++) {
+    const e = entries[i]
+    children[i] = e.green
+    offsets[i] = e.start - start
+    if (e.green.hasError) hasError = true
+    if (e.field !== undefined) (fields ??= new Array(n).fill(undefined))[i] = e.field
+  }
+  const width = end - start
+  const looked = Math.max(lookahead, end) - start
+  return new Green(kind, named, key, width, looked, children, offsets, fields, value, error, hasError, diagnostics)
+}
+
+/**
+ * A stretch of the new input copied unchanged from the previous one:
+ * `[newStart, newStart + length)` is `[oldStart, oldStart + length)`.
+ */
+export interface Segment {
+  readonly newStart: number
+  readonly oldStart: number
+  readonly length: number
+}
+
+/** What a reparse may reuse. */
+export interface Previous {
+  readonly root: Green
+  readonly oldLength: number
+  readonly newLength: number
+  readonly segments: ReadonlyArray<Segment>
+  readonly input: Input
+  /** How far past its lookahead a parser may have read, besides a token at the lookahead. */
+  readonly extra: number
+  readonly encoding: Encoding<any> | undefined
+}
+
+/** The hooks that `Syntax` combinators and `Parser.resumeAfter`/`retryAfter` call. */
+export interface Builder {
+  node(state: State<any>, step: (state: State<any>) => unknown, key: object, kind: string, named: boolean): unknown
+  field(state: State<any>, step: (state: State<any>) => unknown, name: string): unknown
+  /** After error recovery: `[start, pos)` was skipped after `failure`. */
+  skipped(start: number, failure: Failure, mode: ErrMode): void
+  /**
+   * Called by token parsers that read input up to `end` (exclusive) beyond
+   * where they leave the cursor or record a failure.
+   */
+  read(end: number): void
+}
+
+/** The parse state of a `Syntax` parse. */
+export class SyntaxState<I extends Input = Input> extends State<I> implements Builder {
+  // Declared, not defined: `State`'s constructor sets `pos` through the
+  // accessor below before these could be initialized
+  declare cursor: number
+  /** The furthest position the cursor reached, or failure recorded, since the innermost open node started. */
+  declare highWater: number
+  /** Completed nodes waiting for their parent, in input order. */
+  declare stack: Array<Child>
+  declare previous: Previous | undefined
+  /** How many nodes were reused from the previous tree. */
+  declare reused: number
+  /** Where {@link find} found the last node it found. */
+  declare lastParent: Green | undefined
+  declare lastParentStart: number
+
+  static {
+    Object.defineProperty(this.prototype, "pos", {
+      get(this: SyntaxState) {
+        return this.cursor
+      },
+      set(this: SyntaxState, p: number) {
+        if (p < this.cursor) {
+          // An attempt was abandoned (or a lookahead finished): drop its nodes
+          const stack = this.stack
+          while (stack.length > 0 && stack[stack.length - 1].end > p) stack.pop()
+        }
+        if (p > this.highWater) this.highWater = p
+        this.cursor = p
+      },
+      configurable: true,
+      enumerable: true
+    })
+  }
+
+  constructor(
+    source: I | Source<I>,
+    options: {
+      readonly context?: Context.Context<never> | undefined
+    },
+    previous: Previous | undefined
+  ) {
+    super(source, { context: options.context })
+    this.highWater = this.cursor
+    this.stack = []
+    this.previous = previous
+    this.reused = 0
+    this.lastParent = undefined
+    this.lastParentStart = 0
+    this.syntax = this
+    // Error recovery is always on: like Tree-sitter, a syntax parse always produces a tree
+    this.recovered = []
+  }
+
+  override failWith(mode: ErrMode, failure: Failure): Fail {
+    if (failure.offset > this.highWater) this.highWater = failure.offset
+    return super.failWith(mode, failure)
+  }
+
+  override failTies(head: Failure, tie1: Failure, tie2: Failure | undefined): Fail {
+    if (head.offset > this.highWater) this.highWater = head.offset
+    return super.failTies(head, tie1, tie2)
+  }
+
+  override setHint(offset: number, expected: ReadonlyArray<string>): void {
+    if (offset > this.highWater) this.highWater = offset
+    super.setHint(offset, expected)
+  }
+
+  node(state: State<any>, step: (state: State<any>) => unknown, key: object, kind: string, named: boolean): unknown {
+    const start = this.cursor
+    const stack = this.stack
+    if (this.previous !== undefined) {
+      const green = this.reusable(this.previous, key, start)
+      if (green !== undefined) {
+        this.reused++
+        const end = start + green.width
+        state.pos = end
+        const looked = start + green.lookahead
+        if (looked > this.highWater) this.highWater = looked
+        const d = green.diagnostics
+        if (d !== undefined) {
+          if (d.deepest !== undefined) this.deepen(start === d.base ? d.deepest : rebase(d.deepest, d.base - start))
+          if (d.hintExpected !== undefined) this.setHint(start + d.hintOffset, d.hintExpected)
+        }
+        stack.push(new Child(green, start, end, undefined))
+        return green.value
+      }
+    }
+    const mark = stack.length
+    const outer = this.highWater
+    const outerDeepest = this.deepest
+    const hintOffset = this.hintOffset
+    const hintExpected = this.hintExpected
+    this.highWater = start
+    // Collect the furthest failure of this node alone, then merge it as `failWith` would have
+    this.deepest = undefined
+    const a = step(state)
+    const looked = this.highWater
+    if (outer > looked) this.highWater = outer
+    const deepest = this.deepest as Failure | undefined
+    this.deepest = outerDeepest
+    if (deepest !== undefined) this.deepen(deepest)
+    if (a === Fail) {
+      if (stack.length > mark) stack.length = mark
+      return a
+    }
+    const end = this.cursor
+    // Like Tree-sitter's rules, nodes are never empty: an empty match adds nothing to the tree
+    if (end === start) return a
+    const hinted = this.hintOffset !== hintOffset || this.hintExpected !== hintExpected
+    const diagnostics: Diagnostics | undefined =
+      deepest === undefined && !hinted
+        ? undefined
+        : {
+            deepest,
+            base: start,
+            hintOffset: this.hintOffset - start,
+            hintExpected: hinted ? this.hintExpected : undefined
+          }
+    const entries = stack.splice(mark)
+    stack.push(
+      new Child(build(kind, named, key, start, end, looked, entries, a, undefined, diagnostics), start, end, undefined)
+    )
+    return a
+  }
+
+  read(end: number): void {
+    // `highWater` is the last position looked at, `end` is exclusive
+    if (end - 1 > this.highWater) this.highWater = end - 1
+  }
+
+  /** Records `failure` as the furthest failure if it is, as `failWith` does. */
+  private deepen(failure: Failure): void {
+    if (this.deepest === undefined || failure.offset >= this.deepest.offset) this.deepest = failure
+  }
+
+  field(state: State<any>, step: (state: State<any>) => unknown, name: string): unknown {
+    const stack = this.stack
+    const mark = stack.length
+    const a = step(state)
+    if (a !== Fail) for (let i = mark; i < stack.length; i++) stack[i].field = name
+    return a
+  }
+
+  skipped(start: number, failure: Failure, mode: ErrMode): void {
+    const stack = this.stack
+    let i = stack.length
+    while (i > 0 && stack[i - 1].start >= start && stack[i - 1].end > start) i--
+    const end = this.cursor
+    const green = build(errorKind, true, undefined, start, end, this.highWater, stack.splice(i), undefined, {
+      failure: rebase(failure, start),
+      mode
+    })
+    stack.push(new Child(green, start, end, undefined))
+  }
+
+  /**
+   * Builds the root over the whole input from the nodes left on the stack.
+   * When the parse failed, or stopped before the end, the rest of the input
+   * becomes an `ERROR` node.
+   */
+  finish(kind: string, value: unknown, fatal: ErrorInfo | undefined, errorStart: number): Green {
+    const entries = this.stack.splice(0)
+    const end = this.end
+    if (fatal !== undefined) {
+      const last = entries.length > 0 ? entries[entries.length - 1].end : 0
+      const start = Math.max(Math.min(errorStart, end), last)
+      const error = build(errorKind, true, undefined, start, end, end, [], undefined, {
+        failure: rebase(fatal.failure, start),
+        mode: fatal.mode
+      })
+      entries.push(new Child(error, start, end, undefined))
+    }
+    return build(kind, true, undefined, 0, end, Math.max(end, this.highWater), entries, value, undefined)
+  }
+
+  /**
+   * The outermost node of the previous tree built by `key` that starts at
+   * `offset`. Reused nodes are mostly siblings, found one after the other,
+   * so the search starts from the parent of the last one found when
+   * `offset` lies inside it: no ancestor of that parent can start there.
+   */
+  private find(root: Green, offset: number, key: object): Green | undefined {
+    let node = root
+    let start = 0
+    const last = this.lastParent
+    if (last !== undefined && offset > this.lastParentStart && offset < this.lastParentStart + last.width) {
+      node = last
+      start = this.lastParentStart
+    }
+    while (true) {
+      const offsets = node.offsets
+      // The last child starting at or before `offset`
+      let lo = 0
+      let hi = offsets.length - 1
+      let found = -1
+      while (lo <= hi) {
+        const mid = (lo + hi) >> 1
+        if (start + offsets[mid] <= offset) {
+          found = mid
+          lo = mid + 1
+        } else {
+          hi = mid - 1
+        }
+      }
+      if (found < 0) return undefined
+      const child = node.children[found]
+      const childStart = start + offsets[found]
+      if (offset >= childStart + child.width) return undefined
+      if (childStart === offset && child.key === key) {
+        this.lastParent = node
+        this.lastParentStart = start
+        return child
+      }
+      node = child
+      start = childStart
+    }
+  }
+
+  /** The node of the previous tree built by `key` at `pos` (in the new input), if it can be reused. */
+  private reusable(previous: Previous, key: object, pos: number): Green | undefined {
+    const segments = previous.segments
+    // The segment containing `pos`
+    let lo = 0
+    let hi = segments.length - 1
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1
+      const seg = segments[mid]
+      if (pos < seg.newStart) hi = mid - 1
+      else if (pos >= seg.newStart + seg.length) lo = mid + 1
+      else {
+        const old = seg.oldStart + (pos - seg.newStart)
+        const green = this.find(previous.root, old, key)
+        if (green === undefined) return undefined
+        const segEnd = seg.oldStart + seg.length
+        // The input it looked at must be unchanged; past the end of both inputs counts as unchanged
+        if (old + green.lookahead + tokenWidth(previous.input, old + green.lookahead) + previous.extra <= segEnd) {
+          return green
+        }
+        if (segEnd === previous.oldLength && seg.newStart + seg.length === previous.newLength) return green
+        return undefined
+      }
+    }
+    return undefined
+  }
+}
+
+/**
+ * How many units a token parser may read at `offset`, where a parse
+ * stopped looking: one code point. Of a string, that is two units at a high
+ * surrogate. Of bytes in an unknown encoding, up to four.
+ */
+const tokenWidth = (input: Input, offset: number): number => {
+  if (Predicate.isString(input)) {
+    const c = input.charCodeAt(offset)
+    return c >= 0xd800 && c <= 0xdbff ? 2 : 1
+  }
+  return input instanceof Uint8Array ? 4 : 1
+}

package/src/internal/text.ts

@@ -20,17 +20,24 @@ export const End = -3
  * Units below this value decode to themselves with width 1, so hot loops can
  * skip `decode`. Defaults to 0x80 for ASCII compatible encodings.
  */
-const FastLimit: unique symbol = Symbol.for("effect-parse/Encoding/FastLimit")
+const FastLimit: unique symbol = /*#__PURE__*/ Symbol.for("effect-parse/Encoding/FastLimit")
 
 /** @internal */
 export const fastLimit = (enc: Encoding<any>): number =>
   (enc as any)[FastLimit] ?? (enc.asciiCompatible && enc.unit === 1 ? 0x80 : 0)
 
-const asciiChars: ReadonlyArray<string> = Array.from({ length: 128 }, (_, i) => String.fromCharCode(i))
+const asciiChars: ReadonlyArray<string> = /*#__PURE__*/ Array.from({ length: 128 }, (_, i) => String.fromCharCode(i))
+
+/**
+ * The code point that starts `s`: for a string known to hold one, such as
+ * one element of `Array.from(string)`. On an empty string it is `NaN`, which,
+ * like the `undefined` of `codePointAt(0)`, matches no code point.
+ */
+export const firstCodePoint = (s: string): number => s.codePointAt(0) ?? Number.NaN
 
 /** `String.fromCodePoint`, with the ASCII characters cached. */
 export const charOf = (cp: number): string =>
-  cp < 128 ? asciiChars[cp]! : cp < 0x10000 ? String.fromCharCode(cp) : String.fromCodePoint(cp)
+  cp < 128 ? asciiChars[cp] : cp < 0x10000 ? String.fromCharCode(cp) : String.fromCodePoint(cp)
 
 const decodeString = (s: string, i: number, end: number): number => {
   const c = s.charCodeAt(i)
@@ -52,40 +59,40 @@ export const string: Encoding<string> = {
   unit: 1,
   asciiCompatible: true,
   decode: decodeString,
-  width: (cp) => cp > 0xffff ? 2 : 1,
+  width: (cp) => (cp > 0xffff ? 2 : 1),
   encode: (text) => text,
   text: (s, start, end) => s.slice(start, end),
   [FastLimit]: 0xd800
 } as Encoding<string>
 
 const decodeUtf8 = (b: Uint8Array, i: number, end: number): number => {
-  const c = b[i]!
+  const c = b[i]
   if (c < 0x80) return c
   if (c < 0xc2) return Invalid
   if (c < 0xe0) {
     if (i + 1 >= end) return Truncated
-    const d = b[i + 1]!
+    const d = b[i + 1]
     return (d & 0xc0) === 0x80 ? ((c & 0x1f) << 6) | (d & 0x3f) : Invalid
   }
   if (c < 0xf0) {
     if (i + 1 >= end) return Truncated
-    const d = b[i + 1]!
+    const d = b[i + 1]
     // Reject overlong encodings (E0 80..9F) and surrogates (ED A0..BF)
     if (c === 0xe0 ? d < 0xa0 || d > 0xbf : c === 0xed ? d < 0x80 || d > 0x9f : (d & 0xc0) !== 0x80) return Invalid
     if (i + 2 >= end) return Truncated
-    const e = b[i + 2]!
+    const e = b[i + 2]
     return (e & 0xc0) === 0x80 ? ((c & 0x0f) << 12) | ((d & 0x3f) << 6) | (e & 0x3f) : Invalid
   }
   if (c < 0xf5) {
     if (i + 1 >= end) return Truncated
-    const d = b[i + 1]!
+    const d = b[i + 1]
     // Reject overlong encodings (F0 80..8F) and code points above U+10FFFF (F4 90..BF)
     if (c === 0xf0 ? d < 0x90 || d > 0xbf : c === 0xf4 ? d < 0x80 || d > 0x8f : (d & 0xc0) !== 0x80) return Invalid
     if (i + 2 >= end) return Truncated
-    const e = b[i + 2]!
+    const e = b[i + 2]
     if ((e & 0xc0) !== 0x80) return Invalid
     if (i + 3 >= end) return Truncated
-    const f = b[i + 3]!
+    const f = b[i + 3]
     return (f & 0xc0) === 0x80 ? ((c & 0x07) << 18) | ((d & 0x3f) << 12) | ((e & 0x3f) << 6) | (f & 0x3f) : Invalid
   }
   return Invalid
@@ -95,7 +102,7 @@ const decodeUtf8 = (b: Uint8Array, i: number, end: number): number => {
 // `TextDecoder` call, which has a high fixed cost.
 const SHORT = 24
 
-const utf8Decoder = new TextDecoder("utf-8", { ignoreBOM: true })
+const utf8Decoder = /*#__PURE__*/ new TextDecoder("utf-8", { ignoreBOM: true })
 
 /**
  * Decodes `b[start, end)`. Some platforms' `TextDecoder` rejects views of a
@@ -105,7 +112,7 @@ const decodeRange = (decoder: TextDecoder, b: Uint8Array, start: number, end: nu
   const view = b.subarray(start, end)
   return decoder.decode(b.buffer instanceof ArrayBuffer ? view : view.slice())
 }
-const utf8Encoder = new TextEncoder()
+const utf8Encoder = /*#__PURE__*/ new TextEncoder()
 
 /** UTF-8 bytes. */
 export const utf8: Encoding<Uint8Array> = {
@@ -113,13 +120,13 @@ export const utf8: Encoding<Uint8Array> = {
   unit: 1,
   asciiCompatible: true,
   decode: decodeUtf8,
-  width: (cp) => cp < 0x80 ? 1 : cp < 0x800 ? 2 : cp < 0x10000 ? 3 : 4,
+  width: (cp) => (cp < 0x80 ? 1 : cp < 0x800 ? 2 : cp < 0x10000 ? 3 : 4),
   encode: (text) => utf8Encoder.encode(text),
   text: (b, start, end) => {
     if (end - start > SHORT) return decodeRange(utf8Decoder, b, start, end)
     let out = ""
     for (let i = start; i < end;) {
-      const c = b[i]!
+      const c = b[i]
       if (c < 0x80) {
         out += asciiChars[c]
         i++
@@ -143,14 +150,14 @@ const makeUtf16 = (littleEndian: boolean): Encoding<Uint8Array> => {
     asciiCompatible: false,
     decode: (b, i, end) => {
       if (i + 1 >= end) return Truncated
-      const c = b[i + lo]! | (b[i + hi]! << 8)
+      const c = b[i + lo] | (b[i + hi] << 8)
       if ((c & 0xf800) !== 0xd800) return c
       if (c > 0xdbff) return Invalid
       if (i + 3 >= end) return Truncated
-      const d = b[i + 2 + lo]! | (b[i + 2 + hi]! << 8)
+      const d = b[i + 2 + lo] | (b[i + 2 + hi] << 8)
       return (d & 0xfc00) === 0xdc00 ? ((c - 0xd800) << 10) + (d - 0xdc00) + 0x10000 : Invalid
     },
-    width: (cp) => cp > 0xffff ? 4 : 2,
+    width: (cp) => (cp > 0xffff ? 4 : 2),
     encode: (text) => {
       const out = new Uint8Array(text.length * 2)
       for (let i = 0; i < text.length; i++) {
@@ -164,7 +171,7 @@ const makeUtf16 = (littleEndian: boolean): Encoding<Uint8Array> => {
       if (end - start <= SHORT * 2) {
         // The range is well formed, so surrogate pairs can be copied unit by unit
         let out = ""
-        for (let i = start; i < end; i += 2) out += String.fromCharCode(b[i + lo]! | (b[i + hi]! << 8))
+        for (let i = start; i < end; i += 2) out += String.fromCharCode(b[i + lo] | (b[i + hi] << 8))
         return out
       }
       decoder ??= new TextDecoder(littleEndian ? "utf-16le" : "utf-16be", { ignoreBOM: true })
@@ -174,17 +181,17 @@ const makeUtf16 = (littleEndian: boolean): Encoding<Uint8Array> => {
 }
 
 /** UTF-16 bytes, little endian. */
-export const utf16le: Encoding<Uint8Array> = makeUtf16(true)
+export const utf16le: Encoding<Uint8Array> = /*#__PURE__*/ makeUtf16(true)
 
 /** UTF-16 bytes, big endian. */
-export const utf16be: Encoding<Uint8Array> = makeUtf16(false)
+export const utf16be: Encoding<Uint8Array> = /*#__PURE__*/ makeUtf16(false)
 
 /** ISO-8859-1: every byte is the code point of the same value. */
 export const latin1: Encoding<Uint8Array> = {
   name: "ISO-8859-1",
   unit: 1,
   asciiCompatible: true,
-  decode: (b, i) => b[i]!,
+  decode: (b, i) => b[i],
   width: () => 1,
   encode: (text) => {
     const out = new Uint8Array(text.length)
@@ -303,7 +310,7 @@ export const scan = (
         stop = End
         break
       }
-      const c = b[i]!
+      const c = b[i]
       if (c < fast) {
         if (test(c) === negate) break
         i++
@@ -345,10 +352,10 @@ export const validate = (enc: Encoding<any>, state: State<any>, start: number, e
 // Case folding
 // -----------------------------------------------------------------------------
 
-const foldCache = new Map<number, number>()
+const foldCache = /*#__PURE__*/ new Map<number, number>()
 
 const single = (s: string): number => {
-  const cp = s.codePointAt(0)!
+  const cp = firstCodePoint(s)
   return s.length === (cp > 0xffff ? 2 : 1) ? cp : -1
 }
 

package/src/internal/ties.ts

@@ -0,0 +1,83 @@
+/**
+ * Tied failures, merged only when read.
+ *
+ * A combinator that tries several parsers at the same position (an
+ * alternation, a permutation round, an operator table) reports the merge
+ * of their failures, left to right, as `mergeFailures` would. Most of the
+ * time one of the later attempts succeeds and the merge is thrown away, so
+ * {@link TiedFailures} keeps the last two failures tied with the running
+ * one unmerged, and {@link TiedFailures.fail} hands them to the state with
+ * `State.failTies`, which merges them on first read (#38, #44).
+ *
+ * `Parser.alt` does the same fold in locals, since it is the hottest
+ * combinator and cannot afford an accumulator per call.
+ */
+import type { Failure, Fail, Input, State } from "../Input.js"
+import { mergeExpected, mergeTiedFailures } from "../Input.js"
+
+/** The failures of a round of attempts, folded lazily. */
+export class TiedFailures {
+  /** The running failure, before the pending ties are merged into it. */
+  failure: Failure | undefined = undefined
+  /** The oldest pending tie, at `failure`'s offset. */
+  tie1: Failure | undefined = undefined
+  /** The newest pending tie, at `failure`'s offset. */
+  tie2: Failure | undefined = undefined
+
+  /** Forgets every failure, for a new round. */
+  clear(): void {
+    this.failure = undefined
+    this.tie1 = undefined
+    this.tie2 = undefined
+  }
+
+  /**
+   * Folds in the failure the latest attempt left on `state`, taking over
+   * its own unmerged ties when it is the furthest.
+   */
+  add<I extends Input>(state: State<I>): void {
+    const head = state.failureHead
+    const running = this.failure
+    if (running === undefined || head.offset > running.offset) {
+      this.failure = head
+      this.tie1 = state.failureTie1
+      this.tie2 = state.failureTie2
+      return
+    }
+    if (head.offset < running.offset) return
+    const failure = state.failure
+    const tie1 = this.tie1
+    if (tie1 === undefined) this.tie1 = failure
+    else if (this.tie2 === undefined) this.tie2 = failure
+    else {
+      // A third tie: fold the oldest pending one in, keeping the order
+      this.failure = mergeTiedFailures(running, tie1, mergeExpected(running.expected, tie1.expected))
+      this.tie1 = this.tie2
+      this.tie2 = failure
+    }
+  }
+
+  /**
+   * Fails `state` with the folded failure (recoverably), or with its
+   * current failure when nothing was folded.
+   */
+  fail<I extends Input>(state: State<I>): Fail {
+    const failure = this.failure
+    if (failure === undefined) return state.failWith("Backtrack", state.failure)
+    const tie1 = this.tie1
+    return tie1 === undefined ? state.failWith("Backtrack", failure) : state.failTies(failure, tie1, this.tie2)
+  }
+
+  /**
+   * Records the folded expectations as a hint when the folded failure lies
+   * where `state` stopped (an attempt that fails without consuming input).
+   */
+  hint<I extends Input>(state: State<I>): void {
+    const failure = this.failure
+    if (failure === undefined || failure.offset !== state.pos) return
+    let expected = failure.expected
+    if (this.tie1 !== undefined) expected = mergeExpected(expected, this.tie1.expected)
+    if (this.tie2 !== undefined) expected = mergeExpected(expected, this.tie2.expected)
+    state.setHint(failure.offset, expected)
+  }
+}