@thomasfosterau/effect-parse 0.1.0 → 0.2.0

package/src/Binary.ts

@@ -17,6 +17,7 @@
  *
  * @since 0.1.0
  */
+import * as Predicate from "effect/Predicate"
 import type { Input, Slice, State } from "./Input.js"
 import { Fail } from "./Input.js"
 import type { Parser } from "./Parser.js"
@@ -41,9 +42,13 @@ export {
  */
 export type Endianness = "big" | "little" | "native"
 
-const nativeLittle = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1
+const nativeLittle = /*#__PURE__*/ new Uint8Array(/*#__PURE__*/ new Uint16Array([1]).buffer)[0] === 1
 
-const fixed = <A>(size: number, name: string, read: (view: DataView, offset: number) => A): Parser<A, never, never, Uint8Array> => {
+const fixed = <A>(
+  size: number,
+  name: string,
+  read: (view: DataView, offset: number) => A
+): Parser<A, never, never, Uint8Array> => {
   const expected = [`${size} byte${size === 1 ? "" : "s"}`]
   return P.make((state: State<Uint8Array>) => {
     const pos = state.pos
@@ -86,7 +91,7 @@ const readI128 = (little: boolean) => {
  * @since 0.1.0
  * @category integers
  */
-export const u8: Parser<number, never, never, Uint8Array> = fixed(1, "u8", (v, o) => v.getUint8(o))
+export const u8: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(1, "u8", (v, o) => v.getUint8(o))
 
 /**
  * A signed byte.
@@ -94,60 +99,126 @@ export const u8: Parser<number, never, never, Uint8Array> = fixed(1, "u8", (v, o
  * @since 0.1.0
  * @category integers
  */
-export const i8: Parser<number, never, never, Uint8Array> = fixed(1, "i8", (v, o) => v.getInt8(o))
+export const i8: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(1, "i8", (v, o) => v.getInt8(o))
 
 /** @since 0.1.0 @category integers */
-export const beU16: Parser<number, never, never, Uint8Array> = fixed(2, "beU16", (v, o) => v.getUint16(o, false))
+export const beU16: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(2, "beU16", (v, o) =>
+  v.getUint16(o, false)
+)
 /** @since 0.1.0 @category integers */
-export const leU16: Parser<number, never, never, Uint8Array> = fixed(2, "leU16", (v, o) => v.getUint16(o, true))
+export const leU16: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(2, "leU16", (v, o) =>
+  v.getUint16(o, true)
+)
 /** @since 0.1.0 @category integers */
-export const beI16: Parser<number, never, never, Uint8Array> = fixed(2, "beI16", (v, o) => v.getInt16(o, false))
+export const beI16: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(2, "beI16", (v, o) =>
+  v.getInt16(o, false)
+)
 /** @since 0.1.0 @category integers */
-export const leI16: Parser<number, never, never, Uint8Array> = fixed(2, "leI16", (v, o) => v.getInt16(o, true))
+export const leI16: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(2, "leI16", (v, o) =>
+  v.getInt16(o, true)
+)
 /** @since 0.1.0 @category integers */
-export const beU24: Parser<number, never, never, Uint8Array> = fixed(3, "beU24", readU24(false))
+export const beU24: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(
+  3,
+  "beU24",
+  /*#__PURE__*/ readU24(false)
+)
 /** @since 0.1.0 @category integers */
-export const leU24: Parser<number, never, never, Uint8Array> = fixed(3, "leU24", readU24(true))
+export const leU24: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(
+  3,
+  "leU24",
+  /*#__PURE__*/ readU24(true)
+)
 /** @since 0.1.0 @category integers */
-export const beI24: Parser<number, never, never, Uint8Array> = fixed(3, "beI24", readI24(false))
+export const beI24: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(
+  3,
+  "beI24",
+  /*#__PURE__*/ readI24(false)
+)
 /** @since 0.1.0 @category integers */
-export const leI24: Parser<number, never, never, Uint8Array> = fixed(3, "leI24", readI24(true))
+export const leI24: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(
+  3,
+  "leI24",
+  /*#__PURE__*/ readI24(true)
+)
 /** @since 0.1.0 @category integers */
-export const beU32: Parser<number, never, never, Uint8Array> = fixed(4, "beU32", (v, o) => v.getUint32(o, false))
+export const beU32: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(4, "beU32", (v, o) =>
+  v.getUint32(o, false)
+)
 /** @since 0.1.0 @category integers */
-export const leU32: Parser<number, never, never, Uint8Array> = fixed(4, "leU32", (v, o) => v.getUint32(o, true))
+export const leU32: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(4, "leU32", (v, o) =>
+  v.getUint32(o, true)
+)
 /** @since 0.1.0 @category integers */
-export const beI32: Parser<number, never, never, Uint8Array> = fixed(4, "beI32", (v, o) => v.getInt32(o, false))
+export const beI32: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(4, "beI32", (v, o) =>
+  v.getInt32(o, false)
+)
 /** @since 0.1.0 @category integers */
-export const leI32: Parser<number, never, never, Uint8Array> = fixed(4, "leI32", (v, o) => v.getInt32(o, true))
+export const leI32: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(4, "leI32", (v, o) =>
+  v.getInt32(o, true)
+)
 /** @since 0.1.0 @category integers */
-export const beU64: Parser<bigint, never, never, Uint8Array> = fixed(8, "beU64", (v, o) => v.getBigUint64(o, false))
+export const beU64: Parser<bigint, never, never, Uint8Array> = /*#__PURE__*/ fixed(8, "beU64", (v, o) =>
+  v.getBigUint64(o, false)
+)
 /** @since 0.1.0 @category integers */
-export const leU64: Parser<bigint, never, never, Uint8Array> = fixed(8, "leU64", (v, o) => v.getBigUint64(o, true))
+export const leU64: Parser<bigint, never, never, Uint8Array> = /*#__PURE__*/ fixed(8, "leU64", (v, o) =>
+  v.getBigUint64(o, true)
+)
 /** @since 0.1.0 @category integers */
-export const beI64: Parser<bigint, never, never, Uint8Array> = fixed(8, "beI64", (v, o) => v.getBigInt64(o, false))
+export const beI64: Parser<bigint, never, never, Uint8Array> = /*#__PURE__*/ fixed(8, "beI64", (v, o) =>
+  v.getBigInt64(o, false)
+)
 /** @since 0.1.0 @category integers */
-export const leI64: Parser<bigint, never, never, Uint8Array> = fixed(8, "leI64", (v, o) => v.getBigInt64(o, true))
+export const leI64: Parser<bigint, never, never, Uint8Array> = /*#__PURE__*/ fixed(8, "leI64", (v, o) =>
+  v.getBigInt64(o, true)
+)
 /** @since 0.1.0 @category integers */
-export const beU128: Parser<bigint, never, never, Uint8Array> = fixed(16, "beU128", readU128(false))
+export const beU128: Parser<bigint, never, never, Uint8Array> = /*#__PURE__*/ fixed(
+  16,
+  "beU128",
+  /*#__PURE__*/ readU128(false)
+)
 /** @since 0.1.0 @category integers */
-export const leU128: Parser<bigint, never, never, Uint8Array> = fixed(16, "leU128", readU128(true))
+export const leU128: Parser<bigint, never, never, Uint8Array> = /*#__PURE__*/ fixed(
+  16,
+  "leU128",
+  /*#__PURE__*/ readU128(true)
+)
 /** @since 0.1.0 @category integers */
-export const beI128: Parser<bigint, never, never, Uint8Array> = fixed(16, "beI128", readI128(false))
+export const beI128: Parser<bigint, never, never, Uint8Array> = /*#__PURE__*/ fixed(
+  16,
+  "beI128",
+  /*#__PURE__*/ readI128(false)
+)
 /** @since 0.1.0 @category integers */
-export const leI128: Parser<bigint, never, never, Uint8Array> = fixed(16, "leI128", readI128(true))
+export const leI128: Parser<bigint, never, never, Uint8Array> = /*#__PURE__*/ fixed(
+  16,
+  "leI128",
+  /*#__PURE__*/ readI128(true)
+)
 
 /** @since 0.1.0 @category floats */
-export const beF32: Parser<number, never, never, Uint8Array> = fixed(4, "beF32", (v, o) => v.getFloat32(o, false))
+export const beF32: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(4, "beF32", (v, o) =>
+  v.getFloat32(o, false)
+)
 /** @since 0.1.0 @category floats */
-export const leF32: Parser<number, never, never, Uint8Array> = fixed(4, "leF32", (v, o) => v.getFloat32(o, true))
+export const leF32: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(4, "leF32", (v, o) =>
+  v.getFloat32(o, true)
+)
 /** @since 0.1.0 @category floats */
-export const beF64: Parser<number, never, never, Uint8Array> = fixed(8, "beF64", (v, o) => v.getFloat64(o, false))
+export const beF64: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(8, "beF64", (v, o) =>
+  v.getFloat64(o, false)
+)
 /** @since 0.1.0 @category floats */
-export const leF64: Parser<number, never, never, Uint8Array> = fixed(8, "leF64", (v, o) => v.getFloat64(o, true))
+export const leF64: Parser<number, never, never, Uint8Array> = /*#__PURE__*/ fixed(8, "leF64", (v, o) =>
+  v.getFloat64(o, true)
+)
 
-const byEndian = <A>(big: A, little: A) => (endian: Endianness): A =>
-  endian === "big" ? big : endian === "little" ? little : nativeLittle ? little : big
+const byEndian =
+  <A>(big: A, little: A) =>
+  (endian: Endianness): A =>
+    endian === "big" ? big : endian === "little" ? little : nativeLittle ? little : big
 
 /**
  * An unsigned 16-bit integer in the given byte order (winnow's `u16`).
@@ -155,32 +226,67 @@ const byEndian = <A>(big: A, little: A) => (endian: Endianness): A =>
  * @since 0.1.0
  * @category integers
  */
-export const u16: (endian: Endianness) => Parser<number, never, never, Uint8Array> = byEndian(beU16, leU16)
+export const u16: (endian: Endianness) => Parser<number, never, never, Uint8Array> = /*#__PURE__*/ byEndian(
+  beU16,
+  leU16
+)
 /** @since 0.1.0 @category integers */
-export const i16: (endian: Endianness) => Parser<number, never, never, Uint8Array> = byEndian(beI16, leI16)
+export const i16: (endian: Endianness) => Parser<number, never, never, Uint8Array> = /*#__PURE__*/ byEndian(
+  beI16,
+  leI16
+)
 /** @since 0.1.0 @category integers */
-export const u24: (endian: Endianness) => Parser<number, never, never, Uint8Array> = byEndian(beU24, leU24)
+export const u24: (endian: Endianness) => Parser<number, never, never, Uint8Array> = /*#__PURE__*/ byEndian(
+  beU24,
+  leU24
+)
 /** @since 0.1.0 @category integers */
-export const i24: (endian: Endianness) => Parser<number, never, never, Uint8Array> = byEndian(beI24, leI24)
+export const i24: (endian: Endianness) => Parser<number, never, never, Uint8Array> = /*#__PURE__*/ byEndian(
+  beI24,
+  leI24
+)
 /** @since 0.1.0 @category integers */
-export const u32: (endian: Endianness) => Parser<number, never, never, Uint8Array> = byEndian(beU32, leU32)
+export const u32: (endian: Endianness) => Parser<number, never, never, Uint8Array> = /*#__PURE__*/ byEndian(
+  beU32,
+  leU32
+)
 /** @since 0.1.0 @category integers */
-export const i32: (endian: Endianness) => Parser<number, never, never, Uint8Array> = byEndian(beI32, leI32)
+export const i32: (endian: Endianness) => Parser<number, never, never, Uint8Array> = /*#__PURE__*/ byEndian(
+  beI32,
+  leI32
+)
 /** @since 0.1.0 @category integers */
-export const u64: (endian: Endianness) => Parser<bigint, never, never, Uint8Array> = byEndian(beU64, leU64)
+export const u64: (endian: Endianness) => Parser<bigint, never, never, Uint8Array> = /*#__PURE__*/ byEndian(
+  beU64,
+  leU64
+)
 /** @since 0.1.0 @category integers */
-export const i64: (endian: Endianness) => Parser<bigint, never, never, Uint8Array> = byEndian(beI64, leI64)
+export const i64: (endian: Endianness) => Parser<bigint, never, never, Uint8Array> = /*#__PURE__*/ byEndian(
+  beI64,
+  leI64
+)
 /** @since 0.1.0 @category integers */
-export const u128: (endian: Endianness) => Parser<bigint, never, never, Uint8Array> = byEndian(beU128, leU128)
+export const u128: (endian: Endianness) => Parser<bigint, never, never, Uint8Array> = /*#__PURE__*/ byEndian(
+  beU128,
+  leU128
+)
 /** @since 0.1.0 @category integers */
-export const i128: (endian: Endianness) => Parser<bigint, never, never, Uint8Array> = byEndian(beI128, leI128)
+export const i128: (endian: Endianness) => Parser<bigint, never, never, Uint8Array> = /*#__PURE__*/ byEndian(
+  beI128,
+  leI128
+)
 /** @since 0.1.0 @category floats */
-export const f32: (endian: Endianness) => Parser<number, never, never, Uint8Array> = byEndian(beF32, leF32)
+export const f32: (endian: Endianness) => Parser<number, never, never, Uint8Array> = /*#__PURE__*/ byEndian(
+  beF32,
+  leF32
+)
 /** @since 0.1.0 @category floats */
-export const f64: (endian: Endianness) => Parser<number, never, never, Uint8Array> = byEndian(beF64, leF64)
+export const f64: (endian: Endianness) => Parser<number, never, never, Uint8Array> = /*#__PURE__*/ byEndian(
+  beF64,
+  leF64
+)
 
-
-const toCount = (n: number | bigint): number => typeof n === "bigint" ? Number(n) : n
+const toCount = (n: number | bigint): number => (Predicate.isBigInt(n) ? Number(n) : n)
 
 /**
  * Parses a length with `count`, then takes that many tokens (winnow's

package/src/Bits.ts

@@ -68,9 +68,12 @@ const inUnits = <A>(state: State<any>, factor: number, step: (state: State<any>)
     state.pos = factor > 1 ? Math.floor(state.pos / factor) : state.pos / factor
     const f = state.failure
     state.failure = scale(f, 1 / factor)
+    // A committed failure keeps only the failures recorded after the commit
+    // (see `Parser.cut`), so none from before these units
+    if (state.mode === "Cut") state.deepest = undefined
     if (inner !== undefined) {
       const d = inner === f ? state.failure : scale(inner, 1 / factor)
-      if (deepest === undefined || d.offset >= deepest.offset) state.deepest = d
+      if (state.deepest === undefined || d.offset >= state.deepest.offset) state.deepest = d
     }
     return Fail
   }
@@ -111,7 +114,7 @@ const readBits = (state: State<any>, count: number): number => {
   let pos = state.pos
   let value = 0
   for (let i = 0; i < count; i++) {
-    const byte = input[pos >>> 3]!
+    const byte = input[pos >>> 3]
     value = value * 2 + ((byte >>> (7 - (pos & 7))) & 1)
     pos++
   }
@@ -186,7 +189,7 @@ export const pattern = (pattern: number, count: number): Parser<number, never, n
  * @since 0.1.0
  * @category parsers
  */
-export const bool: Parser<boolean, never, never, BitInput> = make((state: State<any>) => {
+export const bool: Parser<boolean, never, never, BitInput> = /*#__PURE__*/ make((state: State<any>) => {
   if (state.pos >= state.end) return state.eoi("Bits", ["1 bit"], 1)
   return readBits(state, 1) === 1
 }, "bool")

package/src/Compiler.ts

@@ -0,0 +1,98 @@
+/**
+ * Compiles parsers into fused, specialized code. Grammars are written as
+ * usual; compiling the root of a grammar only makes `Parser.parse`,
+ * `Parser.parseSync`, `Parser.parsePeek`, `Parser.parsePartial` and
+ * `Parser.parseEffect` faster, from any `offset`.
+ *
+ * There are two compilers, one function each, so a program bundles only the
+ * one it uses, and a program that compiles nothing bundles neither:
+ *
+ * - {@link jit} generates code with `new Function` where it is allowed, and
+ *   otherwise uses the closure compiler. It is the fastest.
+ * - {@link closure} builds specialized closures only. It never generates
+ *   code, and a bundle that uses only it contains no `new Function`, so it
+ *   is the choice under a Content Security Policy, where even probing for
+ *   `new Function` is reported as a violation.
+ *
+ * ```ts
+ * import { Ascii, Compiler, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * export const list = Compiler.jit(
+ *   Parser.separated(Ascii.decInt, Token.literal(","))
+ * )
+ * Parser.parse(list, "1,2,3") // Result.succeed([1, 2, 3]), compiled
+ * ```
+ *
+ * Both return the same parser, so they also work in a pipe:
+ * `p.pipe(Compiler.closure)`. The code is built lazily on the first run, for
+ * each kind of input (string, bytes or array), and cached with the parser.
+ * Compiling a parser again, with either function, replaces its compiled
+ * form.
+ *
+ * **Results and errors are unchanged.** Compiled code records no
+ * diagnostics. When it fails, the parser runs again, interpreted, from the
+ * same offset, so every `ParseError` (offset, expected, context, cause and
+ * message) is exactly the one the interpreter reports.
+ *
+ * **Callbacks should be pure.** On an input that fails, the callbacks given
+ * to `map`, `filter`, `tryMap`, `tap`, `fold`, ... may run twice, once
+ * compiled and once interpreted. Callbacks whose results are discarded
+ * (a `map` inside `taken` or `preceded`, for example) may not run at all,
+ * nor those of a branch that is certain to fail, and token-set predicates
+ * may be called once per character code and cached.
+ *
+ * `Parser.parsePartial` and `ParserStream.parseAll` run a build that
+ * handles partial input. `ParserStream.parseMany`, `Parser.parseRecoverable`
+ * and runs with the `trace` option are always interpreted. Parsers that
+ * can't be described, such as `Parser.make` and `Parser.gen`, run
+ * interpreted inside compiled code.
+ *
+ * @since 0.2.0
+ */
+import type { Input } from "./Input.js"
+import type { Parser } from "./Parser.js"
+import { backend as closureBackend } from "./internal/compiler/closure.js"
+import { backend as jitBackend } from "./internal/compiler/jit.js"
+import { register } from "./internal/compiler/registry.js"
+
+/**
+ * Compiles a parser with the JIT: generated code where `new Function` is
+ * allowed, otherwise specialized closures (see {@link closure}). Returns the
+ * same parser.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Compiler, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const list = Compiler.jit(Parser.separated(Ascii.decInt, Token.literal(",")))
+ * Parser.parse(list, "1,2,3") // Result.succeed([1, 2, 3])
+ * ```
+ *
+ * @since 0.2.0
+ * @category compilation
+ */
+export const jit = <A, E, R, I extends Input>(self: Parser<A, E, R, I>): Parser<A, E, R, I> => {
+  register(self, jitBackend)
+  return self
+}
+
+/**
+ * Compiles a parser into specialized closures. Returns the same parser.
+ * Nothing is generated, so it works under a Content Security Policy, and a
+ * bundle that compiles only with `closure` contains no `new Function`.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Compiler, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const list = Compiler.closure(Parser.separated(Ascii.decInt, Token.literal(",")))
+ * Parser.parse(list, "1,2,3") // Result.succeed([1, 2, 3])
+ * ```
+ *
+ * @since 0.2.0
+ * @category compilation
+ */
+export const closure = <A, E, R, I extends Input>(self: Parser<A, E, R, I>): Parser<A, E, R, I> => {
+  register(self, closureBackend)
+  return self
+}

package/src/Expression.ts

@@ -166,7 +166,7 @@ export const make = <A, E, R, I extends Input, const Ops extends ReadonlyArray<O
   const tryOps = (state: State<any>, ops: ReadonlyArray<OperatorBase<any, any, any>>, mustConsume: boolean): number => {
     const start = state.pos
     for (let i = 0; i < ops.length; i++) {
-      const out = ops[i]!.parser.step(state)
+      const out = ops[i].parser.step(state)
       if (out !== Fail) {
         // A prefix or postfix operator matching nothing would apply forever
         if (mustConsume && state.pos === start) {
@@ -189,7 +189,7 @@ export const make = <A, E, R, I extends Input, const Ops extends ReadonlyArray<O
     const p = tryOps(state, prefixes, true)
     if (p === -2) return Fail
     if (p >= 0) {
-      const op = prefixes[p]!
+      const op = prefixes[p]
       const opOut = matched
       const operandValue = expr(state, op.precedence * 2)
       if (operandValue === Fail) return Fail
@@ -211,7 +211,7 @@ export const make = <A, E, R, I extends Input, const Ops extends ReadonlyArray<O
       const q = tryOps(state, postfixes, true)
       if (q === -2) return Fail
       if (q >= 0) {
-        const op = postfixes[q]!
+        const op = postfixes[q]
         if (op.precedence * 2 < minPower) {
           state.pos = start
           break
@@ -223,11 +223,16 @@ export const make = <A, E, R, I extends Input, const Ops extends ReadonlyArray<O
       const i = tryOps(state, infixes, false)
       if (i === -2) return Fail
       if (i < 0) {
-        const f = postfixFailure === undefined ? failure : failure === undefined ? postfixFailure : mergeFailures(postfixFailure, failure)
+        const f =
+          postfixFailure === undefined
+            ? failure
+            : failure === undefined
+              ? postfixFailure
+              : mergeFailures(postfixFailure, failure)
         if (f !== undefined && f.offset === state.pos) state.setHint(f.offset, f.expected)
         break
       }
-      const op = infixes[i]!
+      const op = infixes[i]
       const leftPower = op.precedence * 2
       if (leftPower < minPower) {
         state.pos = start

package/src/Input.ts

@@ -8,13 +8,16 @@
  * failure.
  *
  * Most users never touch `State` directly. It is exposed for writing custom
- * low-level parsers with `Parser.make`.
+ * low-level parsers with `Parser.make`, and for drivers that run a parser's
+ * `step` many times over one input, reusing a state with {@link State.reset}.
  *
  * @since 0.1.0
  */
+import * as Predicate from "effect/Predicate"
 import * as Context from "effect/Context"
 import type { Encoding } from "./Encoding.js"
 import type { ErrorKind } from "./ParseError.js"
+import type { Builder as SyntaxBuilder } from "./internal/syntax.js"
 
 /**
  * The kinds of input a parser can consume.
@@ -70,7 +73,7 @@ export const fromSource: {
   (source: BinaryInput): Uint8Array
   <I extends Input>(source: Source<I>): I
 } = (source: Input | BinaryInput): any => {
-  if (typeof source === "string" || source instanceof Uint8Array || Array.isArray(source)) return source
+  if (Predicate.isString(source) || source instanceof Uint8Array || Array.isArray(source)) return source
   if (ArrayBuffer.isView(source)) return new Uint8Array(source.buffer, source.byteOffset, source.byteLength)
   // An explicit length fixes the view's size even for a resizable buffer
   if (isArrayBufferLike(source)) return new Uint8Array(source, 0, source.byteLength)
@@ -78,7 +81,7 @@ export const fromSource: {
 }
 
 const isArrayBufferLike = (u: unknown): u is ArrayBufferLike =>
-  u instanceof ArrayBuffer || (typeof SharedArrayBuffer !== "undefined" && u instanceof SharedArrayBuffer)
+  u instanceof ArrayBuffer || (globalThis.SharedArrayBuffer !== undefined && u instanceof SharedArrayBuffer)
 
 /**
  * The type of a single token of an input.
@@ -86,10 +89,13 @@ const isArrayBufferLike = (u: unknown): u is ArrayBufferLike =>
  * @since 0.1.0
  * @category models
  */
-export type Token<I> = I extends string ? string
-  : I extends Uint8Array ? number
-  : I extends ReadonlyArray<infer T> ? T
-  : never
+export type Token<I> = I extends string
+  ? string
+  : I extends Uint8Array
+    ? number
+    : I extends ReadonlyArray<infer T>
+      ? T
+      : never
 
 /**
  * The type of a contiguous slice of an input.
@@ -97,10 +103,13 @@ export type Token<I> = I extends string ? string
  * @since 0.1.0
  * @category models
  */
-export type Slice<I> = I extends string ? string
-  : I extends Uint8Array ? Uint8Array
-  : I extends ReadonlyArray<infer T> ? ReadonlyArray<T>
-  : never
+export type Slice<I> = I extends string
+  ? string
+  : I extends Uint8Array
+    ? Uint8Array
+    : I extends ReadonlyArray<infer T>
+      ? ReadonlyArray<T>
+      : never
 
 /**
  * Sentinel returned by a parser step to signal failure. The failure details
@@ -109,7 +118,7 @@ export type Slice<I> = I extends string ? string
  * @since 0.1.0
  * @category failure
  */
-export const Fail: unique symbol = Symbol.for("effect-parse/Fail")
+export const Fail: unique symbol = /*#__PURE__*/ Symbol.for("effect-parse/Fail")
 
 /**
  * @since 0.1.0
@@ -158,6 +167,9 @@ export class Failure {
 
 const empty: ReadonlyArray<string> = []
 
+/** The failure a {@link State} starts with, before any step has failed. */
+const initialFailure = /*#__PURE__*/ new Failure(0, "Fail", empty, empty, false, undefined, undefined, 0)
+
 /** @internal */
 export const emptyStrings = empty
 
@@ -189,7 +201,8 @@ export class State<I extends Input = Input> {
   /** The full input being parsed. */
   readonly input: I
   /** The current offset. Advanced by parsers, rewound on backtracking. */
-  pos: number
+  // Declared, not defined, so that a subclass can make it an accessor
+  declare pos: number
   /** The end offset (the input's length; in bits inside `Bits.bits`). */
   end: number
   /** 0 = string, 1 = Uint8Array, 2 = array. */
@@ -216,7 +229,9 @@ export class State<I extends Input = Input> {
    * were later swallowed by backtracking (for example a trailing separator
    * followed by an invalid element). It is reported instead of the final
    * failure when it lies further into the input. This is the classic PEG
-   * "farthest failure" heuristic.
+   * "farthest failure" heuristic. `Parser.cut` keeps only the failures
+   * recorded inside it when it commits, and `Parser.peek` and `Parser.not`
+   * forget the failures of a lookahead that succeeded.
    */
   deepest: Failure | undefined = undefined
   /** When defined, `Parser.resumeAfter`/`retryAfter` record failures here. */
@@ -237,20 +252,81 @@ export class State<I extends Input = Input> {
    * @internal
    */
   resume: Map<object, Map<number, unknown>> | undefined = undefined
+  /**
+   * The tree builder of a `Syntax` parse; `undefined` otherwise.
+   *
+   * @internal
+   */
+  syntax: SyntaxBuilder | undefined = undefined
 
-  constructor(source: I | Source<I>, options?: {
-    readonly partial?: boolean | undefined
-    readonly context?: Context.Context<never> | undefined
-    readonly offset?: number | undefined
-  }) {
+  constructor(
+    source: I | Source<I>,
+    options?: {
+      readonly partial?: boolean | undefined
+      readonly context?: Context.Context<never> | undefined
+      readonly offset?: number | undefined
+    }
+  ) {
     const input = fromSource(source as Input) as I
     this.input = input
     this.end = input.length
     this.pos = options?.offset ?? 0
     this.partial = options?.partial ?? false
     this.context = options?.context ?? Context.empty()
-    this.inputKind = typeof input === "string" ? 0 : input instanceof Uint8Array ? 1 : 2
-    this.failure = new Failure(0, "Fail", empty, empty, false, undefined, undefined, 0)
+    this.inputKind = Predicate.isString(input) ? 0 : input instanceof Uint8Array ? 1 : 2
+    this.failure = initialFailure
+  }
+
+  /**
+   * Prepares the state for another run over the same input, starting at
+   * `offset`: afterwards it behaves exactly like
+   * `new State(state.input, { ...options, offset })`, without allocating a
+   * new state.
+   *
+   * Every per-run field is reset: the cursor and end, the latest failure,
+   * hints and furthest failure, recorded recoveries, the tracer and tracing
+   * depth, the recorded encoding and streaming checkpoints. Like the
+   * constructor, `partial` defaults to `false` and `context` to the empty
+   * context, so pass them again on every reset.
+   *
+   * Use it to run many small parses over one buffer, for example one per
+   * token, with `parser.step`. A state can be reused after any run,
+   * including one that failed, returned `Incomplete` or threw.
+   *
+   * @example
+   * ```ts
+   * import { Ascii, Input } from "@thomasfosterau/effect-parse"
+   *
+   * const state = new Input.State("12 34")
+   * Ascii.decUint.step(state) // 12
+   * state.reset(3)
+   * Ascii.decUint.step(state) // 34
+   * ```
+   *
+   * @since 0.2.0
+   */
+  reset(
+    offset: number = 0,
+    options?: {
+      readonly partial?: boolean | undefined
+      readonly context?: Context.Context<never> | undefined
+    }
+  ): this {
+    this.pos = offset
+    this.end = this.input.length
+    this.partial = options?.partial ?? false
+    this.context = options?.context ?? Context.empty()
+    this.mode = "Backtrack"
+    this.failure = initialFailure
+    this.hintOffset = -1
+    this.hintExpected = empty
+    this.deepest = undefined
+    this.recovered = undefined
+    this.tracer = undefined
+    this.depth = 0
+    this.encoding = undefined
+    this.resume = undefined
+    return this
   }
 
   /**
@@ -359,12 +435,17 @@ export class State<I extends Input = Input> {
     const f = this.failure
     const d = this.deepest
     if (
-      d === undefined || d === f || d.offset <= f.offset || this.mode === "Incomplete" ||
-      f.hasCause || f.message !== undefined
+      d === undefined ||
+      d === f ||
+      d.offset <= f.offset ||
+      this.mode === "Incomplete" ||
+      f.hasCause ||
+      f.message !== undefined
     ) {
       return f
     }
-    const context = d.context.length === 0 ? f.context : [...d.context, ...f.context.filter((l) => !d.context.includes(l))]
+    const context =
+      d.context.length === 0 ? 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)
   }
 
@@ -392,10 +473,7 @@ export class State<I extends Input = Input> {
 }
 
 /** @internal */
-export const mergeExpected = (
-  a: ReadonlyArray<string>,
-  b: ReadonlyArray<string>
-): ReadonlyArray<string> => {
+export const mergeExpected = (a: ReadonlyArray<string>, b: ReadonlyArray<string>): ReadonlyArray<string> => {
   if (a.length === 0) return b
   if (b.length === 0) return a
   const out = a.slice()