@thomasfosterau/effect-parse 0.0.0-stage → 0.0.0

package/dist/Parser.js

@@ -0,0 +1,1936 @@
+/**
+ * The `Parser` data type and its general-purpose combinators.
+ *
+ * A `Parser<A, E, R, I>` consumes input of type `I` and produces a value of
+ * type `A`. It may fail with a `ParseError<E>`, where `E` is the type of
+ * user supplied error causes, and it may require services `R` from an Effect
+ * `Context`.
+ *
+ * Under the hood a parser is a function over a mutable cursor (`Input.State`),
+ * as in winnow. Failure is cheap and backtracking is a matter of resetting an
+ * offset. On the surface the API follows Effect's conventions: parsers are
+ * pipeable, combinators are dual (data-first or data-last), and parsers can
+ * be written with generators:
+ *
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const point = Parser.gen(function*() {
+ *   yield* Token.literal("(")
+ *   const x = yield* Ascii.decInt
+ *   yield* Token.literal(",")
+ *   const y = yield* Ascii.decInt
+ *   yield* Token.literal(")")
+ *   return { x, y }
+ * })
+ *
+ * Parser.parse(point, "(1,-2)") // Result.succeed({ x: 1, y: -2 })
+ * ```
+ *
+ * @since 0.1.0
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import { dual } from "effect/Function";
+import { NodeInspectSymbol } from "effect/Inspectable";
+import * as Option from "effect/Option";
+import { pipeArguments } from "effect/Pipeable";
+import * as Result from "effect/Result";
+import { Fail, Failure, mergeExpected, mergeFailures, State } from "./Input.js";
+import * as ParseError from "./ParseError.js";
+import * as Compiler from "./internal/compiler/registry.js";
+import * as Entries from "./internal/entries.js";
+import * as Resume from "./internal/resume.js";
+import { bounds, NodeId } from "./internal/node.js";
+// -----------------------------------------------------------------------------
+// Models
+// -----------------------------------------------------------------------------
+/**
+ * @since 0.1.0
+ * @category type ids
+ */
+export const TypeId = "~effect-parse/Parser";
+// -----------------------------------------------------------------------------
+// Internals
+// -----------------------------------------------------------------------------
+const variance = {
+    _A: (_) => _,
+    _E: (_) => _,
+    _R: (_) => _,
+    _I: (_) => { }
+};
+class SingleShotGen {
+    self;
+    called = false;
+    constructor(self) {
+        this.self = self;
+    }
+    next(a) {
+        if (this.called)
+            return { value: a, done: true };
+        this.called = true;
+        return { value: this.self, done: false };
+    }
+    return(a) {
+        return { value: a, done: true };
+    }
+    throw(e) {
+        throw e;
+    }
+    [Symbol.iterator]() {
+        return new SingleShotGen(this.self);
+    }
+}
+class ParserImpl {
+    step;
+    name;
+    [TypeId] = variance;
+    /** The description used by the compiler; `undefined` for `Opaque`. */
+    [NodeId];
+    constructor(step, name, node) {
+        this.step = step;
+        this.name = name;
+        this[NodeId] = node;
+    }
+    pipe() {
+        return pipeArguments(this, arguments);
+    }
+    [Symbol.iterator]() {
+        return new SingleShotGen(this);
+    }
+    toString() {
+        return this.name === undefined ? "Parser" : `Parser(${this.name})`;
+    }
+    toJSON() {
+        return { _id: "Parser", name: this.name };
+    }
+    [NodeInspectSymbol]() {
+        return this.toJSON();
+    }
+}
+/**
+ * Tests whether a value is a `Parser`.
+ *
+ * @since 0.1.0
+ * @category guards
+ */
+export const isParser = (u) => typeof u === "object" && u !== null && TypeId in u;
+const isParserArg = (args) => isParser(args[0]);
+const isTwoParserArgs = (args) => isParser(args[0]) && isParser(args[1]);
+// -----------------------------------------------------------------------------
+// Constructors
+// -----------------------------------------------------------------------------
+/**
+ * Creates a parser from a step function over the mutable {@link State}
+ * cursor. This is the escape hatch for writing low-level parsers, much like
+ * passing a plain function as a parser in winnow.
+ *
+ * The step function must either return the parsed value, having advanced
+ * `state.pos` past the consumed input, or return the result of one of
+ * `state.backtrack`, `state.cut`, `state.incomplete`, ... to signal failure.
+ *
+ * @example
+ * ```ts
+ * import { Parser } from "@thomasfosterau/effect-parse"
+ *
+ * // Parses a single ASCII uppercase letter
+ * const upper = Parser.make<string>((state) => {
+ *   const c = state.input.charCodeAt(state.pos)
+ *   if (state.pos < state.end && c >= 65 && c <= 90) {
+ *     state.pos++
+ *     return String.fromCharCode(c)
+ *   }
+ *   return state.pos >= state.end
+ *     ? state.eoi("Token", ["uppercase letter"], 1)
+ *     : state.backtrack("Token", ["uppercase letter"])
+ * })
+ * ```
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const make = (step, name) => new ParserImpl(step, name, undefined);
+/**
+ * Creates a parser together with its description, used by the compiler.
+ *
+ * @internal
+ */
+export const described = (step, name, node) => new ParserImpl(step, name, node);
+const nodeOfParser = (p) => p[NodeId];
+/**
+ * Gives a parser a name, used by `toString`.
+ *
+ * @since 0.1.0
+ * @category utils
+ */
+export const named = dual(2, (self, name) => new ParserImpl(self.step, name, nodeOfParser(self)));
+/**
+ * A parser that consumes nothing and succeeds with the given value.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const succeed = (value) => described(() => value, "succeed", { _tag: "Succeed", value });
+/**
+ * A parser that consumes nothing and succeeds with the result of a thunk.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const sync = (evaluate) => described(() => evaluate(), "sync", { _tag: "Sync", evaluate });
+/**
+ * A parser that consumes nothing and succeeds with `undefined` (winnow's
+ * `empty`, nom's `success(())`).
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const empty = described(() => undefined, "empty", {
+    _tag: "Succeed",
+    value: undefined
+});
+/**
+ * Alias of {@link empty}, following Effect's `Effect.void`.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const void_ = empty;
+export { 
+/**
+ * @since 0.1.0
+ * @category constructors
+ */
+void_ as void };
+/**
+ * A parser that always fails (backtracks) with the given user error as its
+ * cause.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const fail = (error) => described((state) => state.failCause("Backtrack", "Fail", error), "fail", failBacktrack);
+const failBacktrack = { _tag: "Fail", mode: "Backtrack" };
+/**
+ * A parser that always fails (backtracks) without a cause. This is winnow's
+ * `fail` and nom's `fail()`.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const reject = described((state) => state.backtrack("Fail"), "reject", failBacktrack);
+/**
+ * A parser that always fails with a message.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const failMessage = (message) => described((state) => state.failMessage("Backtrack", "Fail", message), "failMessage", failBacktrack);
+/**
+ * A placeholder parser that fails with an unrecoverable error (winnow's
+ * `todo`).
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const todo = described((state) => state.failMessage("Cut", "Assert", "`todo` parser reached"), "todo", { _tag: "Fail", mode: "Cut" });
+/**
+ * Lazily constructs a parser, which is needed to define recursive grammars.
+ * The thunk is evaluated once, on first use.
+ *
+ * @example
+ * ```ts
+ * import { Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * type Nested = ReadonlyArray<Nested>
+ * const nested: Parser.Parser<Nested> = Parser.delimited(
+ *   Token.literal("["),
+ *   Parser.repeat(Parser.suspend(() => nested)),
+ *   Token.literal("]")
+ * )
+ * ```
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const suspend = (evaluate) => {
+    let parser;
+    return described((state) => (parser ??= evaluate()).step(state), "suspend", {
+        _tag: "Suspend",
+        resolve: () => parser ??= evaluate()
+    });
+};
+/**
+ * The current offset into the input (winnow's `Location`).
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const location = described((state) => state.pos, "location", {
+    _tag: "Location"
+});
+/**
+ * Succeeds (with `undefined`) only at the end of the input; nom's and
+ * winnow's `eof`. On partial input, reaching the end of the available data
+ * is reported as `Incomplete` since more data may follow.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export const eof = described((state) => {
+    if (state.pos < state.end)
+        return state.backtrack("Eof", expectedEof);
+    if (state.partial)
+        return state.incomplete(1, expectedEof);
+    return undefined;
+}, "eof", { _tag: "Eof" });
+const expectedEof = ["end of input"];
+// -----------------------------------------------------------------------------
+// Mapping
+// -----------------------------------------------------------------------------
+/**
+ * Transforms the output of a parser.
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export const map = dual(2, (self, f) => {
+    const step = self.step;
+    return described((state) => {
+        const a = step(state);
+        return a === Fail ? Fail : f(a);
+    }, self.name, { _tag: "Map", self, f });
+});
+/**
+ * Builds an object from the `[key, value]` entries a parser returns, as
+ * `Object.fromEntries` does: `fromEntries(self)` is
+ * `map(self, Object.fromEntries)`.
+ *
+ * Compiled parsers build the object directly when `self` repeats a pair
+ * (`separated` or `repeat` of `separatedPair` or a two-element `seq`,
+ * possibly inside `preceded`, `terminated`, `delimited` or `cut`), without
+ * the pairs and the array. They do the same for `map(Object.fromEntries)`.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const entry = Parser.separatedPair(Ascii.alpha1, Token.literal("="), Ascii.decUint)
+ * const record = Parser.fromEntries(Parser.separated(entry, Token.literal(",")))
+ * Parser.parse(record, "a=1,b=2") // Result.succeed({ a: 1, b: 2 })
+ * ```
+ *
+ * @since 0.2.0
+ * @category mapping
+ */
+export const fromEntries = (self) => map(self, Entries.fromEntries);
+/**
+ * Replaces the output of a parser with a constant (winnow's `value`, nom's
+ * `value`).
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export const as = dual(2, (self, value) => {
+    const step = self.step;
+    return described((state) => step(state) === Fail ? Fail : value, self.name, { _tag: "As", self, value });
+});
+/**
+ * Discards the output of a parser (winnow's `void`).
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export const asVoid = (self) => as(self, undefined);
+/**
+ * Replaces the output of a parser with `Option.some(output)`.
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export const asSome = (self) => map(self, Option.some);
+/**
+ * Runs a side effect on the output of a parser, keeping the output.
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export const tap = dual(2, (self, f) => {
+    const step = self.step;
+    return described((state) => {
+        const a = step(state);
+        if (a !== Fail)
+            f(a);
+        return a;
+    }, self.name, { _tag: "Tap", self, f });
+});
+/**
+ * Uses the output of a parser to choose the parser that consumes the rest
+ * of the input (winnow's `flat_map`, nom's `flat_map`).
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const flatMap = dual(2, (self, f) => {
+    const step = self.step;
+    return described((state) => {
+        const a = step(state);
+        return a === Fail ? Fail : f(a).step(state);
+    }, undefined, { _tag: "FlatMap", self, f });
+});
+/**
+ * Applies a second parser to the *output* of the first (winnow's
+ * `and_then`, nom's `map_parser`). The output of the first parser must
+ * itself be an input, e.g. a slice produced by {@link taken} or
+ * `Token.take`.
+ *
+ * Error offsets reported by the inner parser are translated relative to the
+ * start of the outer parser.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * // Take exactly 4 characters, then require them all to be digits
+ * const year = Token.take(4).pipe(Parser.mapParser(Parser.allConsuming(Ascii.decUint)))
+ * ```
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const mapParser = dual(2, (self, inner) => {
+    const step = self.step;
+    return make((state) => {
+        const start = state.pos;
+        const a = step(state);
+        if (a === Fail)
+            return Fail;
+        const sub = new State(a, { context: state.context });
+        sub.tracer = state.tracer;
+        sub.depth = state.depth;
+        sub.recovered = state.recovered;
+        const b = inner.step(sub);
+        if (b === Fail) {
+            const f = sub.failure;
+            if (sub.encoding !== undefined)
+                state.encoding = sub.encoding;
+            // The inner input is usually a slice ending where the outer parser stopped
+            const base = Math.max(start, state.pos - a.length);
+            const offset = Math.min(base + f.offset, state.pos);
+            return state.failWith(sub.mode === "Incomplete" ? "Backtrack" : sub.mode, new Failure(offset, f.kind, f.expected, f.context, f.hasCause, f.cause, f.message, 0));
+        }
+        return b;
+    });
+});
+/**
+ * Transforms the output of a parser with a function that may fail with a
+ * `Result` (winnow's `try_map`, nom's `map_res`). On failure the parser
+ * backtracks to where it started and the error becomes the `cause` of the
+ * `ParseError`.
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export const tryMap = dual(2, (self, f) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        const a = step(state);
+        if (a === Fail)
+            return Fail;
+        const r = f(a);
+        if (Result.isSuccess(r))
+            return r.success;
+        state.pos = start;
+        return state.failCause("Backtrack", "Verify", r.failure);
+    }, self.name, { _tag: "TryMap", self, f });
+});
+/**
+ * Like {@link tryMap}, but the function may throw. Thrown values become the
+ * `cause` of the error.
+ *
+ * @since 0.1.0
+ * @category mapping
+ */
+export const tryMapUnknown = dual(2, (self, f) => tryMap(self, (a) => {
+    try {
+        return Result.succeed(f(a));
+    }
+    catch (e) {
+        return Result.fail(e);
+    }
+}));
+/**
+ * Transforms the output of a parser with a function returning an `Option`;
+ * `None` makes the parser backtrack (winnow's `verify_map`, nom's
+ * `map_opt`).
+ *
+ * @since 0.1.0
+ * @category filtering
+ */
+export const filterMap = dual(2, (self, f) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        const a = step(state);
+        if (a === Fail)
+            return Fail;
+        const o = f(a);
+        if (Option.isSome(o))
+            return o.value;
+        state.pos = start;
+        return state.backtrack("Verify");
+    }, self.name, { _tag: "FilterMap", self, f });
+});
+/**
+ * Keeps the output of a parser only if it satisfies a predicate, otherwise
+ * backtracks (winnow's and nom's `verify`).
+ *
+ * @since 0.1.0
+ * @category filtering
+ */
+export const filter = dual(2, (self, predicate) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        const a = step(state);
+        if (a === Fail)
+            return Fail;
+        if (predicate(a))
+            return a;
+        state.pos = start;
+        return state.backtrack("Verify");
+    }, self.name, { _tag: "Filter", self, predicate });
+});
+/**
+ * Keeps the output of a parser only if it satisfies a predicate, otherwise
+ * backtracks with the given user error.
+ *
+ * @since 0.1.0
+ * @category filtering
+ */
+export const filterOrFail = dual(3, (self, predicate, orFailWith) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        const a = step(state);
+        if (a === Fail)
+            return Fail;
+        if (predicate(a))
+            return a;
+        state.pos = start;
+        return state.failCause("Backtrack", "Verify", orFailWith(a));
+    }, self.name, { _tag: "Filter", self, predicate });
+});
+// -----------------------------------------------------------------------------
+// Consumed input
+// -----------------------------------------------------------------------------
+/**
+ * Returns the slice of input consumed by a parser instead of its output
+ * (winnow's `take`, nom's `recognize`).
+ *
+ * @since 0.1.0
+ * @category consumed input
+ */
+export const taken = (self) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        return step(state) === Fail ? Fail : state.slice(start, state.pos);
+    }, self.name, { _tag: "Taken", self, encoding: undefined });
+};
+/**
+ * Returns both the output of a parser and the slice of input it consumed
+ * (winnow's `with_taken`; nom's `consumed` returns them in the other order).
+ *
+ * @since 0.1.0
+ * @category consumed input
+ */
+export const withTaken = (self) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        const a = step(state);
+        return a === Fail ? Fail : [a, state.slice(start, state.pos)];
+    }, self.name, { _tag: "WithTaken", self });
+};
+/**
+ * Returns the span (`[start, end)` offsets) consumed by a parser instead of
+ * its output (winnow's `span`).
+ *
+ * @since 0.1.0
+ * @category consumed input
+ */
+export const span = (self) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        return step(state) === Fail ? Fail : { start, end: state.pos };
+    }, self.name, { _tag: "Span", self });
+};
+/**
+ * Returns both the output of a parser and the span it consumed (winnow's
+ * `with_span`).
+ *
+ * @since 0.1.0
+ * @category consumed input
+ */
+export const withSpan = (self) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        const a = step(state);
+        return a === Fail ? Fail : [a, { start, end: state.pos }];
+    }, self.name, { _tag: "WithSpan", self });
+};
+// -----------------------------------------------------------------------------
+// Error management
+// -----------------------------------------------------------------------------
+const changeMode = (self, from, to) => {
+    const step = self.step;
+    return described((state) => {
+        const a = step(state);
+        if (a === Fail && state.mode === from)
+            state.mode = to;
+        return a;
+    }, self.name, { _tag: "Mode", self, from, to });
+};
+/**
+ * Commits to the current branch: recoverable failures of the parser become
+ * unrecoverable, so enclosing `alt`, `opt`, `repeat`, ... do not try
+ * alternatives (winnow's `cut_err`, nom's `cut`).
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * // Once we have seen "-", a number must follow
+ * const negative = Parser.preceded(Token.literal("-"), Parser.cut(Ascii.decUint))
+ * ```
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export const cut = (self) => changeMode(self, "Backtrack", "Cut");
+/**
+ * Turns unrecoverable failures back into recoverable ones (winnow's
+ * `backtrack_err`).
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export const backtrack = (self) => changeMode(self, "Cut", "Backtrack");
+/**
+ * Turns `Incomplete` failures into recoverable ones, treating the input as
+ * complete for this parser (winnow's `complete_err`, nom's `complete`).
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export const complete = (self) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        const a = step(state);
+        if (a === Fail && state.mode === "Incomplete") {
+            state.pos = start;
+            return state.backtrack("Complete");
+        }
+        return a;
+    }, self.name, { _tag: "Mode", self, from: "Incomplete", to: "Backtrack" });
+};
+/**
+ * Adds a context label to failures of a parser (winnow's
+ * `context(StrContext::Label(..))`, nom's `context`). Labels are rendered as
+ * "while parsing <label>" in the error message.
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export const context = dual(2, (self, label) => {
+    const step = self.step;
+    return described((state) => {
+        const a = step(state);
+        if (a === Fail && state.mode !== "Incomplete") {
+            const f = state.failure;
+            state.replaceFailure(new Failure(f.offset, f.kind, f.expected, [...f.context, label], f.hasCause, f.cause, f.message, f.needed));
+        }
+        return a;
+    }, self.name ?? label, { _tag: "Context", self, label });
+});
+/**
+ * Names what a parser expects. When the parser fails without consuming any
+ * input, its expectations are replaced with `description`, so a failure is
+ * reported as `expected <description>` rather than in terms of the parser's
+ * internals (Parsec's `<?>`, winnow's `StrContext::Expected`).
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export const expected = dual(2, (self, description) => {
+    const step = self.step;
+    const desc = [description];
+    return described((state) => {
+        const start = state.pos;
+        const hintOffset = state.hintOffset;
+        const hintExpected = state.hintExpected;
+        const a = step(state);
+        if (a === Fail && state.failure.offset === start) {
+            const f = state.failure;
+            const expected = hintOffset === start ? mergeExpected(hintExpected, desc) : desc;
+            state.replaceFailure(new Failure(f.offset, f.kind, expected, f.context, f.hasCause, f.cause, f.message, f.needed));
+        }
+        return a;
+    }, description, { _tag: "Expected", self, description });
+});
+/**
+ * Transforms the user error (cause) of a parser's failures.
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export const mapError = dual(2, (self, f) => {
+    const step = self.step;
+    return described((state) => {
+        const a = step(state);
+        if (a === Fail && state.failure.hasCause) {
+            const x = state.failure;
+            state.replaceFailure(new Failure(x.offset, x.kind, x.expected, x.context, true, f(x.cause), x.message, x.needed));
+        }
+        return a;
+    }, self.name, { _tag: "MapError", self });
+});
+/**
+ * Replaces any failure of a parser with the given user error, keeping the
+ * failure's position and mode.
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export const orFail = dual(2, (self, error) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        const a = step(state);
+        if (a === Fail && state.mode !== "Incomplete") {
+            const x = state.failure;
+            state.replaceFailure(new Failure(start, x.kind, [], x.context, true, error(), undefined, 0));
+        }
+        return a;
+    }, self.name, { _tag: "OrFail", self });
+});
+/**
+ * If the parser fails recoverably, tries `that` from the same position.
+ * `p.pipe(Parser.orElse(() => q))` is equivalent to `Parser.alt(p, q)`.
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export const orElse = dual(2, (self, that) => alt(self, suspend(that)));
+/**
+ * If the parser fails recoverably, succeeds with the given value without
+ * consuming input.
+ *
+ * @since 0.1.0
+ * @category error management
+ */
+export const orElseSucceed = dual(2, (self, value) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        const a = step(state);
+        if (a !== Fail)
+            return a;
+        if (state.mode !== "Backtrack")
+            return Fail;
+        recover(state, start);
+        return value();
+    }, self.name, { _tag: "OrElseSucceed", self, value });
+});
+/** Rewinds after a recoverable failure, remembering it as a hint. */
+const recover = (state, start) => {
+    state.pos = start;
+    const f = state.failure;
+    if (f.offset === start) {
+        state.hintOffset = start;
+        state.hintExpected = f.expected;
+    }
+};
+// -----------------------------------------------------------------------------
+// Control
+// -----------------------------------------------------------------------------
+/**
+ * Makes a parser optional: returns `Option.none()` without consuming input if
+ * it fails recoverably (winnow's and nom's `opt`).
+ *
+ * @since 0.1.0
+ * @category control
+ */
+export const opt = (self) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        const a = step(state);
+        if (a !== Fail)
+            return Option.some(a);
+        if (state.mode !== "Backtrack")
+            return Fail;
+        recover(state, start);
+        return Option.none();
+    }, self.name, { _tag: "Opt", self });
+};
+/**
+ * Like {@link opt}, but returns `undefined` instead of `None`.
+ *
+ * @since 0.1.0
+ * @category control
+ */
+export const optional = (self) => orElseSucceed(self, () => undefined);
+/**
+ * Runs the parser only if `condition` holds, otherwise succeeds with
+ * `Option.none()` (winnow's and nom's `cond`).
+ *
+ * @since 0.1.0
+ * @category control
+ */
+export const cond = (condition, self) => condition ? asSome(self) : succeed(Option.none());
+/**
+ * Runs a parser without consuming input (winnow's and nom's `peek`).
+ *
+ * @since 0.1.0
+ * @category control
+ */
+export const peek = (self) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        const hintOffset = state.hintOffset;
+        const hintExpected = state.hintExpected;
+        const a = step(state);
+        if (a !== Fail) {
+            state.pos = start;
+            state.hintOffset = hintOffset;
+            state.hintExpected = hintExpected;
+        }
+        return a;
+    }, self.name, { _tag: "Peek", self });
+};
+/**
+ * Succeeds, without consuming input, only if the parser fails recoverably
+ * (winnow's and nom's `not`).
+ *
+ * @since 0.1.0
+ * @category control
+ */
+export const not = (self) => {
+    const step = self.step;
+    return described((state) => {
+        const start = state.pos;
+        const hintOffset = state.hintOffset;
+        const hintExpected = state.hintExpected;
+        const a = step(state);
+        if (a !== Fail) {
+            state.pos = start;
+            return state.backtrack("Not");
+        }
+        if (state.mode !== "Backtrack")
+            return Fail;
+        state.pos = start;
+        state.hintOffset = hintOffset;
+        state.hintExpected = hintExpected;
+        return undefined;
+    }, self.name, { _tag: "Not", self });
+};
+/**
+ * Requires the parser to consume the whole input (nom's `all_consuming`).
+ *
+ * @since 0.1.0
+ * @category control
+ */
+export const allConsuming = (self) => terminated(self, eof);
+// -----------------------------------------------------------------------------
+// Sequencing
+// -----------------------------------------------------------------------------
+/**
+ * Runs parsers in sequence, collecting their outputs in a tuple (winnow's
+ * and nom's tuple parsers, winnow's `seq!`).
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const seq = (...parsers) => {
+    const steps = parsers.map((p) => p.step);
+    const n = steps.length;
+    return described((state) => {
+        const out = new Array(n);
+        for (let i = 0; i < n; i++) {
+            const a = steps[i](state);
+            if (a === Fail)
+                return Fail;
+            out[i] = a;
+        }
+        return out;
+    }, "seq", { _tag: "Seq", parsers, output: "tuple" });
+};
+/**
+ * Runs a record of parsers in sequence (in key order), collecting their
+ * outputs in a record. This is the Effect counterpart to winnow's
+ * `seq!(Struct { .. })`.
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const struct = (fields) => {
+    const keys = Object.keys(fields);
+    const steps = keys.map((k) => fields[k].step);
+    const n = keys.length;
+    return described((state) => {
+        const out = {};
+        for (let i = 0; i < n; i++) {
+            const a = steps[i](state);
+            if (a === Fail)
+                return Fail;
+            out[keys[i]] = a;
+        }
+        return out;
+    }, "struct", { _tag: "Struct", keys, parsers: keys.map((k) => fields[k]) });
+};
+/**
+ * Runs two parsers in sequence and returns both outputs.
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const zip = dual(2, (self, that) => zipWith(self, that, (a, b) => [a, b]));
+/**
+ * Runs two parsers in sequence and combines their outputs.
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const zipWith = dual(3, (self, that, f) => {
+    const s1 = self.step;
+    const s2 = that.step;
+    return described((state) => {
+        const a = s1(state);
+        if (a === Fail)
+            return Fail;
+        const b = s2(state);
+        if (b === Fail)
+            return Fail;
+        return f(a, b);
+    }, undefined, { _tag: "ZipWith", self, that, f });
+});
+/**
+ * Runs two parsers in sequence, keeping the output of the first.
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const zipLeft = dual(2, (self, that) => terminated(self, that));
+/**
+ * Runs two parsers in sequence, keeping the output of the second.
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const zipRight = dual(2, (self, that) => preceded(self, that));
+/**
+ * Runs `prefix` then `parser`, keeping the output of `parser` (winnow's and
+ * nom's `preceded`).
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const preceded = (prefix, parser) => {
+    const s1 = prefix.step;
+    const s2 = parser.step;
+    return described((state) => s1(state) === Fail ? Fail : s2(state), parser.name, {
+        _tag: "Seq",
+        parsers: [prefix, parser],
+        output: 1
+    });
+};
+/**
+ * Runs `parser` then `suffix`, keeping the output of `parser` (winnow's and
+ * nom's `terminated`).
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const terminated = (parser, suffix) => {
+    const s1 = parser.step;
+    const s2 = suffix.step;
+    return described((state) => {
+        const a = s1(state);
+        if (a === Fail)
+            return Fail;
+        return s2(state) === Fail ? Fail : a;
+    }, parser.name, { _tag: "Seq", parsers: [parser, suffix], output: 0 });
+};
+/**
+ * Runs `open`, `parser` and `close`, keeping the output of `parser`
+ * (winnow's and nom's `delimited`).
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const delimited = (open, parser, close) => {
+    const s1 = open.step;
+    const s2 = parser.step;
+    const s3 = close.step;
+    return described((state) => {
+        if (s1(state) === Fail)
+            return Fail;
+        const a = s2(state);
+        if (a === Fail)
+            return Fail;
+        return s3(state) === Fail ? Fail : a;
+    }, parser.name, { _tag: "Seq", parsers: [open, parser, close], output: 1 });
+};
+/**
+ * Runs `first`, `separator` and `second`, keeping the outputs of `first` and
+ * `second` (winnow's and nom's `separated_pair`).
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const separatedPair = (first, separator, second) => {
+    const s1 = first.step;
+    const s2 = separator.step;
+    const s3 = second.step;
+    return described((state) => {
+        const a = s1(state);
+        if (a === Fail)
+            return Fail;
+        if (s2(state) === Fail)
+            return Fail;
+        const b = s3(state);
+        return b === Fail ? Fail : [a, b];
+    }, undefined, { _tag: "Seq", parsers: [first, separator, second], output: [0, 2] });
+};
+/**
+ * Writes a parser in imperative style with a generator, Effect style:
+ * `yield*` a parser to run it and get its output.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const keyValue = Parser.gen(function*() {
+ *   const key = yield* Ascii.alpha1
+ *   yield* Token.literal("=")
+ *   const value = yield* Ascii.decInt
+ *   return [key, value] as const
+ * })
+ * ```
+ *
+ * @since 0.1.0
+ * @category sequencing
+ */
+export const gen = (f) => make((state) => {
+    const iterator = f();
+    let next = iterator.next();
+    while (!next.done) {
+        const a = next.value.step(state);
+        if (a === Fail) {
+            iterator.return?.(undefined);
+            return Fail;
+        }
+        next = iterator.next(a);
+    }
+    return next.value;
+}, "gen");
+/**
+ * The starting point for Do notation.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const range = Parser.Do.pipe(
+ *   Parser.bind("start", () => Ascii.decUint),
+ *   Parser.zipLeft(Token.literal("..")),
+ *   Parser.bind("end", () => Ascii.decUint)
+ * )
+ * ```
+ *
+ * @since 0.1.0
+ * @category do notation
+ */
+export const Do = succeed({});
+/**
+ * Binds the output of a parser to a field of the Do record.
+ *
+ * @since 0.1.0
+ * @category do notation
+ */
+export const bind = dual(3, (self, name, f) => flatMap(self, (a) => map(f(a), (b) => ({ ...a, [name]: b }))));
+/**
+ * Wraps the output of a parser in a record with a single field.
+ *
+ * @since 0.1.0
+ * @category do notation
+ */
+export const bindTo = dual(2, (self, name) => map(self, (a) => ({ [name]: a })));
+const let_ = dual(3, (self, name, f) => map(self, (a) => ({ ...a, [name]: f(a) })));
+export { 
+/**
+ * Adds a computed field to the Do record.
+ *
+ * @since 0.1.0
+ * @category do notation
+ */
+let_ as let };
+// -----------------------------------------------------------------------------
+// Choice
+// -----------------------------------------------------------------------------
+/**
+ * Tries each parser in turn and returns the output of the first that
+ * succeeds (winnow's and nom's `alt`).
+ *
+ * Unrecoverable (`Cut`) and `Incomplete` failures stop the search
+ * immediately. If every alternative fails recoverably, the failures are
+ * merged: the one that got furthest wins, and failures at the same offset
+ * combine their expectations, e.g. `expected "true", "false" or "null"`.
+ *
+ * @since 0.1.0
+ * @category choice
+ */
+export const alt = (...parsers) => {
+    const steps = parsers.map((p) => p.step);
+    const n = steps.length;
+    if (n === 0)
+        return reject;
+    if (n === 1)
+        return parsers[0];
+    return described((state) => {
+        const start = state.pos;
+        let failure;
+        for (let i = 0; i < n; i++) {
+            const a = steps[i](state);
+            if (a !== Fail) {
+                if (failure !== undefined && failure.offset === state.pos)
+                    state.setHint(failure.offset, failure.expected);
+                return a;
+            }
+            if (state.mode !== "Backtrack")
+                return Fail;
+            failure = failure === undefined ? state.failure : mergeFailures(failure, state.failure);
+            state.pos = start;
+        }
+        return state.failWith("Backtrack", failure);
+    }, "alt", { _tag: "Alt", parsers });
+};
+/**
+ * Selects the parser to run next based on the output of `selector`, like a
+ * `match` over the input (winnow's `dispatch!`). If no case matches, the
+ * parser backtracks to where it started.
+ *
+ * Cases are given either as a record keyed by the selector's output (with
+ * an optional `otherwise` parser for unlisted keys, like winnow's `_ =>`
+ * arm), or as a function returning a parser (or `undefined` for no match).
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const escape = Parser.preceded(
+ *   Token.literal("\\"),
+ *   Parser.dispatch(Token.any, {
+ *     n: Parser.succeed("\n"),
+ *     t: Parser.succeed("\t"),
+ *     u: Parser.preceded(Token.literal("{"), Ascii.hexUint).pipe(
+ *       Parser.zipLeft(Token.literal("}")),
+ *       Parser.map((cp) => String.fromCodePoint(cp))
+ *     )
+ *   })
+ * )
+ * ```
+ *
+ * @since 0.1.0
+ * @category choice
+ */
+export const dispatch = (selector, cases, otherwise) => {
+    const choose = typeof cases === "function" ? cases : (key) => Object.prototype.hasOwnProperty.call(cases, key) ? cases[key] : otherwise;
+    const step = selector.step;
+    return described((state) => {
+        const start = state.pos;
+        const key = step(state);
+        if (key === Fail)
+            return Fail;
+        const parser = choose(key);
+        if (parser === undefined) {
+            state.pos = start;
+            return state.backtrack("Dispatch");
+        }
+        return parser.step(state);
+    }, "dispatch", {
+        _tag: "Dispatch",
+        selector,
+        cases: typeof cases === "function" ? undefined : cases,
+        otherwise: typeof cases === "function" ? undefined : otherwise,
+        choose
+    });
+};
+/**
+ * Applies every parser exactly once, in whatever order they match, and
+ * returns their outputs in the order the parsers were given (winnow's and
+ * nom's `permutation`).
+ *
+ * @since 0.1.0
+ * @category choice
+ */
+export const permutation = (...parsers) => {
+    const steps = parsers.map((p) => p.step);
+    const n = steps.length;
+    return make((state) => {
+        const out = new Array(n);
+        const done = new Array(n).fill(false);
+        let remaining = n;
+        while (remaining > 0) {
+            let failure;
+            let matched = false;
+            for (let i = 0; i < n; i++) {
+                if (done[i])
+                    continue;
+                const start = state.pos;
+                const a = steps[i](state);
+                if (a !== Fail) {
+                    out[i] = a;
+                    done[i] = true;
+                    remaining--;
+                    matched = true;
+                    break;
+                }
+                if (state.mode !== "Backtrack")
+                    return Fail;
+                failure = failure === undefined ? state.failure : mergeFailures(failure, state.failure);
+                state.pos = start;
+            }
+            if (!matched)
+                return state.failWith("Backtrack", failure);
+        }
+        return out;
+    }, "permutation");
+};
+// -----------------------------------------------------------------------------
+// Repetition
+// -----------------------------------------------------------------------------
+const normalizeRange = (range) => {
+    if (range === undefined)
+        return [0, Infinity];
+    if (typeof range === "number")
+        return [range, range];
+    const min = range.min ?? 0;
+    const max = range.max ?? Infinity;
+    if (min > max)
+        throw new RangeError(`invalid range: min (${min}) > max (${max})`);
+    return [min, max];
+};
+const assertConsumes = (state, name) => state.failMessage("Cut", "Assert", `\`${name}\` parsers must always consume`);
+const saveFold = (state, key, entry, acc, pos) => Resume.save(state, key, entry, { acc, count: 0, pos });
+const foldImpl = (self, range, init, f, name, node) => {
+    const [min, max] = normalizeRange(range);
+    const step = self.step;
+    const checkLoop = max === Infinity;
+    const key = {};
+    return described((state) => {
+        const entry = state.pos;
+        let acc;
+        let count = 0;
+        const resumed = state.resume === undefined ? undefined : Resume.take(state, key, entry);
+        if (resumed instanceof Resume.Done) {
+            state.pos = resumed.pos;
+            return resumed.value;
+        }
+        if (resumed !== undefined) {
+            acc = resumed.acc;
+            count = resumed.count;
+            state.pos = resumed.pos;
+        }
+        else {
+            acc = init();
+        }
+        for (; count < max; count++) {
+            const start = state.pos;
+            const a = step(state);
+            if (a === Fail) {
+                if (state.mode === "Incomplete" && state.resume !== undefined) {
+                    Resume.save(state, key, entry, { acc, count, pos: start });
+                }
+                if (state.mode !== "Backtrack" || count < min)
+                    return Fail;
+                recover(state, start);
+                return Resume.done(state, key, entry, resumed !== undefined, acc);
+            }
+            if (checkLoop && state.pos === start)
+                return assertConsumes(state, name);
+            acc = f(acc, a);
+        }
+        return Resume.done(state, key, entry, resumed !== undefined, acc);
+    }, name, node ?? { _tag: "Fold", self, init, f, name, ...bounds(range) });
+};
+/**
+ * Applies a parser repeatedly, collecting the outputs in an array (winnow's
+ * `repeat`, nom's `many0`, `many1`, `many_m_n` and `count`).
+ *
+ * The range defaults to `{ min: 0 }` (zero or more). A number repeats
+ * exactly that many times. With a literal positive `min`, the output is
+ * typed as a non-empty array.
+ *
+ * As in winnow, an unbounded repetition of a parser that succeeds without
+ * consuming input fails with an unrecoverable assertion instead of looping
+ * forever.
+ *
+ * @example
+ * ```ts
+ * import { Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const abs = Parser.repeat(Token.literal("ab"), { min: 1 })
+ * Parser.parse(abs, "ababab") // Result.succeed(["ab", "ab", "ab"])
+ * ```
+ *
+ * @since 0.1.0
+ * @category repetition
+ */
+export const repeat = dual(isParserArg, (self, range) => foldImpl(self, range, () => [], (acc, a) => {
+    acc.push(a);
+    return acc;
+}, "repeat", { _tag: "Repeat", self, ...bounds(range) }));
+/**
+ * Applies a parser repeatedly, folding the outputs into an accumulator
+ * (winnow's `repeat(..).fold(..)`, nom's `fold_many0`/`fold_many1`/
+ * `fold_many_m_n`).
+ *
+ * @since 0.1.0
+ * @category repetition
+ */
+export const fold = dual(2, (self, options) => foldImpl(self, options.range, options.init, options.f, "fold"));
+/**
+ * Applies `self` repeatedly until `end` succeeds, returning the collected
+ * outputs and the output of `end` (winnow's `repeat_till`, nom's
+ * `many_till`).
+ *
+ * @since 0.1.0
+ * @category repetition
+ */
+export const repeatTill = dual(isTwoParserArgs, (self, end, range) => {
+    const [min, max] = normalizeRange(range);
+    const step = self.step;
+    const endStep = end.step;
+    return described((state) => {
+        const acc = [];
+        while (true) {
+            const start = state.pos;
+            let endFailure;
+            if (acc.length >= min) {
+                const b = endStep(state);
+                if (b !== Fail)
+                    return [acc, b];
+                if (state.mode !== "Backtrack")
+                    return Fail;
+                endFailure = state.failure;
+                state.pos = start;
+                if (acc.length >= max)
+                    return Fail;
+            }
+            const a = step(state);
+            if (a === Fail) {
+                if (endFailure !== undefined && state.mode === "Backtrack") {
+                    state.failWith("Backtrack", mergeFailures(endFailure, state.failure));
+                }
+                return Fail;
+            }
+            if (state.pos === start)
+                return assertConsumes(state, "repeatTill");
+            acc.push(a);
+        }
+    }, "repeatTill", { _tag: "RepeatTill", self, end, ...bounds(range) });
+});
+export const separated = dual(isTwoParserArgs, (self, separator, range) => {
+    const [min, max] = normalizeRange(range);
+    const step = self.step;
+    const sepStep = separator.step;
+    const checkLoop = max === Infinity;
+    const key = {};
+    return described((state) => {
+        const entry = state.pos;
+        let acc;
+        const resumed = state.resume === undefined ? undefined : Resume.take(state, key, entry);
+        if (resumed instanceof Resume.Done) {
+            state.pos = resumed.pos;
+            return resumed.value;
+        }
+        if (resumed !== undefined) {
+            acc = resumed.acc;
+            state.pos = resumed.pos;
+        }
+        else {
+            acc = [];
+            if (max === 0)
+                return acc;
+            const start = state.pos;
+            const first = step(state);
+            if (first === Fail) {
+                if (state.mode !== "Backtrack" || min > 0)
+                    return Fail;
+                recover(state, start);
+                return acc;
+            }
+            acc.push(first);
+        }
+        while (acc.length < max) {
+            const start = state.pos;
+            if (sepStep(state) === Fail) {
+                if (state.mode === "Incomplete" && state.resume !== undefined) {
+                    Resume.save(state, key, entry, { acc, pos: start });
+                }
+                if (state.mode !== "Backtrack" || acc.length < min)
+                    return Fail;
+                recover(state, start);
+                return Resume.done(state, key, entry, resumed !== undefined, acc);
+            }
+            if (checkLoop && state.pos === start)
+                return assertConsumes(state, "separated");
+            const a = step(state);
+            if (a === Fail) {
+                if (state.mode === "Incomplete" && state.resume !== undefined) {
+                    Resume.save(state, key, entry, { acc, pos: start });
+                }
+                if (state.mode !== "Backtrack" || acc.length < min)
+                    return Fail;
+                state.pos = start;
+                return Resume.done(state, key, entry, resumed !== undefined, acc);
+            }
+            acc.push(a);
+        }
+        return Resume.done(state, key, entry, resumed !== undefined, acc);
+    }, "separated", { _tag: "Separated", self, separator, ...bounds(range) });
+});
+/**
+ * Parses one or more `self` separated by `separator`, folding them from the
+ * left with the separator's output: `((a op b) op c)` (winnow's
+ * `separated_foldl1`). This is the classic way to parse left-associative
+ * binary operators.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const sum = Parser.separatedFoldl1(
+ *   Ascii.decInt,
+ *   Parser.alt(Token.literal("+"), Token.literal("-")),
+ *   (l, op, r) => op === "+" ? l + r : l - r
+ * )
+ * Parser.parse(sum, "10-3+2") // Result.succeed(9)
+ * ```
+ *
+ * @since 0.1.0
+ * @category repetition
+ */
+export const separatedFoldl1 = (self, separator, op) => {
+    const step = self.step;
+    const sepStep = separator.step;
+    const key = {};
+    return described((state) => {
+        const entry = state.pos;
+        const resumed = state.resume === undefined ? undefined : Resume.take(state, key, entry);
+        let acc;
+        if (resumed instanceof Resume.Done) {
+            state.pos = resumed.pos;
+            return resumed.value;
+        }
+        if (resumed !== undefined) {
+            acc = resumed.acc;
+            state.pos = resumed.pos;
+        }
+        else {
+            acc = step(state);
+            if (acc === Fail)
+                return Fail;
+        }
+        while (true) {
+            const start = state.pos;
+            const s = sepStep(state);
+            if (s === Fail) {
+                if (state.mode === "Incomplete" && state.resume !== undefined)
+                    saveFold(state, key, entry, acc, start);
+                if (state.mode !== "Backtrack")
+                    return Fail;
+                recover(state, start);
+                return Resume.done(state, key, entry, resumed !== undefined, acc);
+            }
+            if (state.pos === start)
+                return assertConsumes(state, "separatedFoldl1");
+            const a = step(state);
+            if (a === Fail) {
+                if (state.mode === "Incomplete" && state.resume !== undefined)
+                    saveFold(state, key, entry, acc, start);
+                if (state.mode !== "Backtrack")
+                    return Fail;
+                state.pos = start;
+                return Resume.done(state, key, entry, resumed !== undefined, acc);
+            }
+            acc = op(acc, s, a);
+        }
+    }, "separatedFoldl1", { _tag: "SeparatedFold", self, separator, op, right: false });
+};
+/**
+ * Parses one or more `self` separated by `separator`, folding them from the
+ * right with the separator's output: `(a op (b op c))` (winnow's
+ * `separated_foldr1`). Useful for right-associative operators such as
+ * exponentiation.
+ *
+ * @since 0.1.0
+ * @category repetition
+ */
+export const separatedFoldr1 = (self, separator, op) => {
+    const step = self.step;
+    const sepStep = separator.step;
+    return described((state) => {
+        const first = step(state);
+        if (first === Fail)
+            return Fail;
+        const values = [first];
+        const seps = [];
+        while (true) {
+            const start = state.pos;
+            const s = sepStep(state);
+            if (s === Fail) {
+                if (state.mode !== "Backtrack")
+                    return Fail;
+                recover(state, start);
+                break;
+            }
+            if (state.pos === start)
+                return assertConsumes(state, "separatedFoldr1");
+            const a = step(state);
+            if (a === Fail) {
+                if (state.mode !== "Backtrack")
+                    return Fail;
+                state.pos = start;
+                break;
+            }
+            seps.push(s);
+            values.push(a);
+        }
+        let acc = values[values.length - 1];
+        for (let i = seps.length - 1; i >= 0; i--) {
+            acc = op(values[i], seps[i], acc);
+        }
+        return acc;
+    }, "separatedFoldr1", { _tag: "SeparatedFold", self, separator, op, right: true });
+};
+// -----------------------------------------------------------------------------
+// Services
+// -----------------------------------------------------------------------------
+/**
+ * Accesses a service from the parser's context. Services take the place of
+ * winnow's `Stateful` input: they can hold configuration, or mutable state
+ * such as an indentation stack or a symbol table.
+ *
+ * Services are provided with {@link provideService} / {@link provide}, with
+ * the `context` option of the runners, or taken from the surrounding Effect
+ * by {@link parseEffect}.
+ *
+ * Mutations made to a service's state are not undone on backtracking (as
+ * with winnow's `Stateful`).
+ *
+ * @example
+ * ```ts
+ * import { Context } from "effect"
+ * import { Ascii, Parser } from "@thomasfosterau/effect-parse"
+ *
+ * class Radix extends Context.Service<Radix, number>()("Radix") {}
+ *
+ * const number = Parser.service(Radix).pipe(
+ *   Parser.flatMap((radix) =>
+ *     Ascii.alphanumeric1.pipe(Parser.map((digits) => parseInt(digits, radix)))
+ *   )
+ * )
+ *
+ * Parser.parse(Parser.provideService(number, Radix, 16), "ff") // Result.succeed(255)
+ * ```
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export const service = (key) => described((state) => Context.getUnsafe(state.context, key), "service", serviceNode);
+const serviceNode = { _tag: "Service" };
+/**
+ * Provides a service to a parser.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export const provideService = dual(3, (self, key, service) => {
+    const step = self.step;
+    return described((state) => {
+        const prev = state.context;
+        state.context = Context.add(prev, key, service);
+        try {
+            return step(state);
+        }
+        finally {
+            state.context = prev;
+        }
+    }, self.name, { _tag: "Provide", self });
+});
+/**
+ * Provides a context of services to a parser.
+ *
+ * @since 0.1.0
+ * @category services
+ */
+export const provide = dual(2, (self, context) => {
+    const step = self.step;
+    return described((state) => {
+        const prev = state.context;
+        state.context = Context.merge(prev, context);
+        try {
+            return step(state);
+        }
+        finally {
+            state.context = prev;
+        }
+    }, self.name, { _tag: "Provide", self });
+});
+// -----------------------------------------------------------------------------
+// Error recovery
+// -----------------------------------------------------------------------------
+/**
+ * Error recovery: if the parser fails, record the failure, skip input with
+ * `recover`, and continue with `Option.none()` (winnow's `resume_after`).
+ *
+ * Recovery is only active when running with {@link parseRecoverable}. Under
+ * the other runners the parser behaves like `Parser.asSome(self)`.
+ *
+ * @since 0.1.0
+ * @category error recovery
+ */
+export const resumeAfter = dual(2, (self, recover) => {
+    const step = self.step;
+    const recoverStep = recover.step;
+    return described((state) => {
+        const start = state.pos;
+        const a = step(state);
+        if (a !== Fail)
+            return Option.some(a);
+        if (state.recovered === undefined || state.mode === "Incomplete")
+            return Fail;
+        const failure = state.failure;
+        const mode = state.mode;
+        state.pos = start;
+        if (recoverStep(state) === Fail)
+            return state.failWith(mode, failure);
+        state.recovered.push(failure);
+        return Option.none();
+    }, self.name, { _tag: "ResumeAfter", self, recover });
+});
+/**
+ * Error recovery: if the parser fails, record the failure, skip input with
+ * `recover`, and try the parser again (winnow's `retry_after`).
+ *
+ * Recovery is only active when running with {@link parseRecoverable}. Under
+ * the other runners the parser behaves like `self`.
+ *
+ * @since 0.1.0
+ * @category error recovery
+ */
+export const retryAfter = dual(2, (self, recover) => {
+    const step = self.step;
+    const recoverStep = recover.step;
+    return described((state) => {
+        while (true) {
+            const start = state.pos;
+            const a = step(state);
+            if (a !== Fail)
+                return a;
+            if (state.recovered === undefined || state.mode === "Incomplete")
+                return Fail;
+            const failure = state.failure;
+            const mode = state.mode;
+            state.pos = start;
+            if (recoverStep(state) === Fail || state.pos === start)
+                return state.failWith(mode, failure);
+            state.recovered.push(failure);
+        }
+    }, self.name, { _tag: "RetryAfter", self, recover });
+});
+// -----------------------------------------------------------------------------
+// Debugging
+// -----------------------------------------------------------------------------
+/**
+ * Traces the execution of a parser (winnow's `trace`). When a tracer is
+ * installed (see the `trace` option of {@link parse}), `Enter` and `Exit`
+ * events are reported for each traced parser; otherwise tracing has no
+ * effect.
+ *
+ * @since 0.1.0
+ * @category debugging
+ */
+export const trace = dual(2, (self, name) => {
+    const step = self.step;
+    return described((state) => {
+        const tracer = state.tracer;
+        if (tracer === undefined)
+            return step(state);
+        const start = state.pos;
+        const depth = state.depth;
+        tracer({ _tag: "Enter", name, depth, offset: start, state });
+        state.depth = depth + 1;
+        const a = step(state);
+        state.depth = depth;
+        tracer({
+            _tag: "Exit",
+            name,
+            depth,
+            offset: start,
+            endOffset: state.pos,
+            result: a === Fail ? state.mode : "Ok",
+            state
+        });
+        return a;
+    }, name, { _tag: "Trace", self, name });
+});
+const preview = (state, offset) => {
+    const input = state.input;
+    if (typeof input === "string") {
+        const s = input.slice(offset, offset + 24);
+        return JSON.stringify(s) + (offset + 24 < input.length ? "…" : "∅");
+    }
+    if (input instanceof Uint8Array) {
+        return Array.from(input.subarray(offset, offset + 12), (b) => b.toString(16).padStart(2, "0")).join(" ");
+    }
+    return `[${offset}/${input.length}]`;
+};
+/**
+ * A tracer that writes an indented trace to `console.log`, similar to
+ * winnow's `debug` feature.
+ *
+ * @since 0.1.0
+ * @category debugging
+ */
+export const consoleTracer = (event) => {
+    const indent = "  ".repeat(event.depth);
+    if (event._tag === "Enter") {
+        console.log(`${indent}> ${event.name} @${event.offset} | ${preview(event.state, event.offset)}`);
+    }
+    else {
+        const consumed = (event.endOffset ?? event.offset) - event.offset;
+        console.log(`${indent}< ${event.name} | ${event.result === "Ok" ? `+${consumed}` : event.result}`);
+    }
+};
+/**
+ * Compiles a parser into fused, specialized code, and returns the same
+ * parser. Grammars are written as usual; compilation only makes
+ * {@link parse}, {@link parseSync}, {@link parsePeek} and
+ * {@link parseEffect} faster. Compile the root of a grammar once, where it
+ * is defined:
+ *
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * export const list = Parser.compile(
+ *   Parser.separated(Ascii.decInt, Token.literal(","))
+ * )
+ * Parser.parse(list, "1,2,3") // Result.succeed([1, 2, 3]), compiled
+ * ```
+ *
+ * The code is generated lazily on the first run, for each kind of input
+ * (string, bytes or array), and cached with the parser.
+ *
+ * **Results and errors are unchanged.** Compiled code records no
+ * diagnostics. When it fails, the parser runs again, interpreted, from the
+ * start, 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.
+ *
+ * Runs on partial input ({@link parsePartial}, `ParserStream`), with
+ * {@link parseRecoverable} or with the `trace` option are always
+ * interpreted. Parsers that can't be described, such as {@link make} and
+ * {@link gen}, run interpreted inside compiled code.
+ *
+ * @since 0.1.0
+ * @category compilation
+ */
+export const compile = dual(isParserArg, (self, options) => {
+    Compiler.register(self, options?.backend ?? "auto");
+    return self;
+});
+/** Returned by {@link runCompiled} when there is no compiled form to run. */
+const NotCompiled = Symbol("NotCompiled");
+/**
+ * Runs the compiled form of `self`, if it has one: returns its value, or
+ * `Fail` when it failed (or, with `whole`, did not consume the whole
+ * input), in which case the state must be thrown away.
+ */
+const runCompiled = (self, state, whole) => {
+    if (state.tracer !== undefined || state.recovered !== undefined)
+        return NotCompiled;
+    const step = Compiler.stepFor(self, state);
+    if (step === undefined)
+        return NotCompiled;
+    const a = step(state);
+    if (a === Fail || (whole && state.pos < state.end))
+        return Fail;
+    return a;
+};
+const makeState = (input, options, partial) => {
+    const state = new State(input, { partial, context: options?.context });
+    const t = options?.trace;
+    if (t !== undefined && t !== false)
+        state.tracer = t === true ? consoleTracer : t;
+    return state;
+};
+const toError = (state) => ParseError.fromFailure(state.input, state.reportedFailure(), state.mode, state.encoding);
+/** Runs a parser against a complete input, compiled when possible. */
+const parseComplete = (self, input, options) => {
+    const state = makeState(input, options, false);
+    const a = runCompiled(self, state, true);
+    if (a === NotCompiled)
+        return runComplete(self, state);
+    if (a !== Fail)
+        return Result.succeed(a);
+    // Re-run interpreted for the diagnostics
+    return runComplete(self, makeState(input, options, false));
+};
+const runComplete = (self, state) => {
+    const a = self.step(state);
+    if (a === Fail)
+        return Result.fail(toError(state));
+    if (state.pos < state.end) {
+        state.backtrack("Eof", expectedEof);
+        return Result.fail(toError(state));
+    }
+    return Result.succeed(a);
+};
+/**
+ * Runs a parser against a complete input, requiring the whole input to be
+ * consumed (winnow's `Parser::parse`).
+ *
+ * @example
+ * ```ts
+ * import { Result } from "effect"
+ * import { Ascii, Parser } from "@thomasfosterau/effect-parse"
+ *
+ * Parser.parse(Ascii.decInt, "-42") // Result.succeed(-42)
+ * Result.isFailure(Parser.parse(Ascii.decInt, "42x")) // true
+ * ```
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export const parse = (self, input, options) => parseComplete(self, input, options);
+/**
+ * Like {@link parse}, but throws the `ParseError` on failure.
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export const parseSync = (self, input, options) => {
+    const result = parseComplete(self, input, options);
+    if (Result.isSuccess(result))
+        return result.success;
+    throw result.failure;
+};
+/**
+ * Runs a parser against the start of an input, returning the remaining
+ * input along with the output, nom-style (winnow's `parse_peek`, nom's
+ * `IResult`).
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export const parsePeek = (self, input, options) => {
+    let state = makeState(input, options, false);
+    const compiled = runCompiled(self, state, false);
+    if (compiled !== NotCompiled && compiled !== Fail) {
+        return Result.succeed([state.slice(state.pos, state.end), compiled]);
+    }
+    if (compiled === Fail)
+        state = makeState(input, options, false);
+    const a = self.step(state);
+    if (a === Fail)
+        return Result.fail(toError(state));
+    return Result.succeed([state.slice(state.pos, state.end), a]);
+};
+/**
+ * Runs a parser against a *partial* input, i.e. a chunk of a stream that may
+ * be followed by more data (winnow's `Partial`, nom's `streaming` parsers).
+ * Token parsers that reach the end of the chunk report `Incomplete` instead
+ * of failing or succeeding early.
+ *
+ * The parser does not have to consume the whole input; the returned
+ * `offset` says how much was consumed.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser } from "@thomasfosterau/effect-parse"
+ *
+ * Parser.parsePartial(Ascii.digit1, "123")
+ * // Result.succeed({ _tag: "Incomplete", needed: Option.some(1) })
+ * Parser.parsePartial(Ascii.digit1, "123;")
+ * // Result.succeed({ _tag: "Done", value: "123", offset: 3 })
+ * ```
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export const parsePartial = (self, input, options) => {
+    const state = makeState(input, options, true);
+    const a = self.step(state);
+    if (a !== Fail)
+        return Result.succeed({ _tag: "Done", value: a, offset: state.pos });
+    if (state.mode === "Incomplete") {
+        const needed = state.failure.needed;
+        return Result.succeed({ _tag: "Incomplete", needed: needed > 0 ? Option.some(needed) : Option.none() });
+    }
+    return Result.fail(toError(state));
+};
+/**
+ * Runs a parser against a complete input as an `Effect`. Services required
+ * by the parser are taken from the Effect's context.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { Ascii, Parser } from "@thomasfosterau/effect-parse"
+ *
+ * const program = Effect.gen(function*() {
+ *   const n = yield* Parser.parseEffect(Ascii.decInt, "42")
+ *   return n + 1
+ * })
+ * ```
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export const parseEffect = (self, input, options) => Effect.flatMap(Effect.context(), (context) => Effect.fromResult(parseComplete(self, input, { ...options, context })));
+/**
+ * Runs a parser with error recovery enabled (winnow's `Recoverable`
+ * stream). Failures handled by {@link resumeAfter} and {@link retryAfter}
+ * are collected instead of aborting the parse.
+ *
+ * @since 0.1.0
+ * @category running
+ */
+export const parseRecoverable = (self, input, options) => {
+    const state = makeState(input, options, false);
+    const recovered = [];
+    state.recovered = recovered;
+    const result = runComplete(self, state);
+    const errors = recovered.map((f) => ParseError.fromFailure(state.input, f, "Backtrack", state.encoding));
+    if (Result.isSuccess(result))
+        return { value: Option.some(result.success), errors };
+    errors.push(result.failure);
+    return { value: Option.none(), errors };
+};
+//# sourceMappingURL=Parser.js.map