@thomasfosterau/effect-parse 0.1.0 → 0.3.0

package/dist/Parser.d.ts

@@ -1,45 +1,14 @@
-/**
- * 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 Result from "effect/Result";
+import { Fail, Input, Slice, Source, State, TraceEvent } from "./Input.js";
+import * as Option from "effect/Option";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
-import * as Option from "effect/Option";
-import type { Pipeable } from "effect/Pipeable";
-import * as Result from "effect/Result";
-import type { Contravariant, Covariant, Simplify } from "effect/Types";
-import type { Input, Slice, Source, TraceEvent } from "./Input.js";
-import { Fail, State } from "./Input.js";
-import type { ErrorKind } from "./ParseError.js";
+import { Pipeable } from "effect/Pipeable";
 import * as ParseError from "./ParseError.js";
-import type { Node } from "./internal/node.js";
+import { ErrorKind } from "./ParseError.js";
+import { Node } from "./internal/node.js";
+import { Contravariant, Covariant, Simplify } from "effect/Types";
+//#region src/Parser.d.ts
 /**
  * @since 0.1.0
  * @category type ids
@@ -53,18 +22,18 @@ export declare const TypeId: "~effect-parse/Parser";
  * @category models
  */
 export interface Parser<out A, out E = never, out R = never, in I extends Input = string> extends Pipeable {
-    readonly [TypeId]: Parser.Variance<A, E, R, I>;
-    /**
-     * Runs one parsing step against a cursor. Returns the parsed value, or the
-     * `Fail` sentinel after recording the failure on the state.
-     *
-     * Calling `step` directly is how custom combinators built with
-     * {@link make} invoke other parsers.
-     */
-    readonly step: (state: State<I>) => A | Fail;
-    /** A human-readable name, used by `toString` and tracing. */
-    readonly name: string | undefined;
-    [Symbol.iterator](): ParserIterator<Parser<A, E, R, I>>;
+  readonly [TypeId]: Parser.Variance<A, E, R, I>;
+  /**
+   * Runs one parsing step against a cursor. Returns the parsed value, or the
+   * `Fail` sentinel after recording the failure on the state.
+   *
+   * Calling `step` directly is how custom combinators built with
+   * {@link make} invoke other parsers.
+   */
+  readonly step: (state: State<I>) => A | Fail;
+  /** A human-readable name, used by `toString` and tracing. */
+  readonly name: string | undefined;
+  [Symbol.iterator](): ParserIterator<Parser<A, E, R, I>>;
 }
 /**
  * The iterator used by `yield*` inside {@link gen}.
@@ -73,53 +42,53 @@ export interface Parser<out A, out E = never, out R = never, in I extends Input
  * @category models
  */
 export interface ParserIterator<P extends Parser.Any> {
-    next(...args: ReadonlyArray<any>): IteratorResult<P, Parser.Success<P>>;
+  next(...args: ReadonlyArray<any>): IteratorResult<P, Parser.Success<P>>;
 }
 /**
  * @since 0.1.0
  * @category models
  */
 export declare namespace Parser {
-    /**
-     * @since 0.1.0
-     */
-    interface Variance<A, E, R, I> {
-        readonly _A: Covariant<A>;
-        readonly _E: Covariant<E>;
-        readonly _R: Covariant<R>;
-        readonly _I: Contravariant<I>;
-    }
-    /**
-     * Any parser.
-     *
-     * @since 0.1.0
-     */
-    type Any = Parser<any, any, any, any>;
-    /**
-     * The output type of a parser.
-     *
-     * @since 0.1.0
-     */
-    type Success<P> = P extends Parser<infer A, infer _E, infer _R, infer _I> ? A : never;
-    /**
-     * The user error type of a parser.
-     *
-     * @since 0.1.0
-     */
-    type Error<P> = P extends Parser<infer _A, infer E, infer _R, infer _I> ? E : never;
-    /**
-     * The services required by a parser.
-     *
-     * @since 0.1.0
-     */
-    type Services<P> = P extends Parser<infer _A, infer _E, infer R, infer _I> ? R : never;
-    /**
-     * The input accepted by a parser (or by every member of a union of
-     * parsers).
-     *
-     * @since 0.1.0
-     */
-    type InputOf<P> = [P] extends [never] ? Input : [P] extends [Parser<infer _A, infer _E, infer _R, infer I>] ? I : never;
+  /**
+   * @since 0.1.0
+   */
+  interface Variance<A, E, R, I> {
+    readonly _A: Covariant<A>;
+    readonly _E: Covariant<E>;
+    readonly _R: Covariant<R>;
+    readonly _I: Contravariant<I>;
+  }
+  /**
+   * Any parser.
+   *
+   * @since 0.1.0
+   */
+  type Any = Parser<any, any, any, any>;
+  /**
+   * The output type of a parser.
+   *
+   * @since 0.1.0
+   */
+  type Success<P> = P extends Parser<infer A, infer _E, infer _R, infer _I> ? A : never;
+  /**
+   * The user error type of a parser.
+   *
+   * @since 0.1.0
+   */
+  type Error<P> = P extends Parser<infer _A, infer E, infer _R, infer _I> ? E : never;
+  /**
+   * The services required by a parser.
+   *
+   * @since 0.1.0
+   */
+  type Services<P> = P extends Parser<infer _A, infer _E, infer R, infer _I> ? R : never;
+  /**
+   * The input accepted by a parser (or by every member of a union of
+   * parsers).
+   *
+   * @since 0.1.0
+   */
+  type InputOf<P> = [P] extends [never] ? Input : [P] extends [Parser<infer _A, infer _E, infer _R, infer I>] ? I : never;
 }
 /**
  * A repetition range, in the spirit of winnow's `impl Into<Range>`:
@@ -132,8 +101,8 @@ export declare namespace Parser {
  * @category models
  */
 export type Range = number | {
-    readonly min?: number | undefined;
-    readonly max?: number | undefined;
+  readonly min?: number | undefined;
+  readonly max?: number | undefined;
 };
 /**
  * The output of a repetition: a non-empty array when the range has a literal
@@ -143,7 +112,7 @@ export type Range = number | {
  * @category models
  */
 export type Repeated<A, Rg> = Rg extends number ? number extends Rg ? Array<A> : Rg extends 0 ? Array<A> : NonEmpty<A> : Rg extends {
-    readonly min: infer M extends number;
+  readonly min: infer M extends number;
 } ? number extends M ? Array<A> : M extends 0 ? Array<A> : NonEmpty<A> : Array<A>;
 type NonEmpty<A> = [A, ...Array<A>];
 /**
@@ -153,8 +122,8 @@ type NonEmpty<A> = [A, ...Array<A>];
  * @category models
  */
 export interface Span {
-    readonly start: number;
-    readonly end: number;
+  readonly start: number;
+  readonly end: number;
 }
 /**
  * Tests whether a value is a `Parser`.
@@ -206,8 +175,8 @@ export declare const described: <A, E = never, R = never, I extends Input = stri
  * @category utils
  */
 export declare const named: {
-    (name: string): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
-    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, name: string): Parser<A, E, R, I>;
+  (name: string): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, name: string): Parser<A, E, R, I>;
 };
 /**
  * A parser that consumes nothing and succeeds with the given value.
@@ -238,12 +207,6 @@ export declare const empty: Parser<void, never, never, Input>;
  * @category constructors
  */
 export declare const void_: Parser<void, never, never, Input>;
-export { 
-/**
- * @since 0.1.0
- * @category constructors
- */
-void_ as void };
 /**
  * A parser that always fails (backtracks) with the given user error as its
  * cause.
@@ -279,6 +242,11 @@ export declare const todo: Parser<never, never, never, Input>;
  * Lazily constructs a parser, which is needed to define recursive grammars.
  * The thunk is evaluated once, on first use.
  *
+ * Each level of recursion uses some of the call stack, interpreted or
+ * compiled, so input nested a few thousand levels deep exhausts it. The
+ * runners catch the overflow and fail with an unrecoverable `ParseError` of
+ * kind `"TooDeep"` at the offset reached, instead of throwing.
+ *
  * @example
  * ```ts
  * import { Parser, Token } from "@thomasfosterau/effect-parse"
@@ -318,8 +286,8 @@ export declare const eof: Parser<void, never, never, Input>;
  * @category mapping
  */
 export declare const map: {
-    <A, B>(f: (a: A) => B): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
-    <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, f: (a: A) => B): Parser<B, E, R, I>;
+  <A, B>(f: (a: A) => B): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
+  <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, f: (a: A) => B): Parser<B, E, R, I>;
 };
 /**
  * Builds an object from the `[key, value]` entries a parser returns, as
@@ -352,8 +320,8 @@ export declare const fromEntries: <K extends PropertyKey, V, E, R, I extends Inp
  * @category mapping
  */
 export declare const as: {
-    <B>(value: B): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
-    <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, value: B): Parser<B, E, R, I>;
+  <B>(value: B): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
+  <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, value: B): Parser<B, E, R, I>;
 };
 /**
  * Discards the output of a parser (winnow's `void`).
@@ -376,8 +344,8 @@ export declare const asSome: <A, E, R, I extends Input>(self: Parser<A, E, R, I>
  * @category mapping
  */
 export declare const tap: {
-    <A>(f: (a: A) => void): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
-    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, f: (a: A) => void): Parser<A, E, R, I>;
+  <A>(f: (a: A) => void): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, f: (a: A) => void): Parser<A, E, R, I>;
 };
 /**
  * Uses the output of a parser to choose the parser that consumes the rest
@@ -387,8 +355,8 @@ export declare const tap: {
  * @category sequencing
  */
 export declare const flatMap: {
-    <A, B, E2, R2, I2 extends Input>(f: (a: A) => Parser<B, E2, R2, I2>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R | R2, I & I2>;
-    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, f: (a: A) => Parser<B, E2, R2, I2>): Parser<B, E | E2, R | R2, I & I2>;
+  <A, B, E2, R2, I2 extends Input>(f: (a: A) => Parser<B, E2, R2, I2>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R | R2, I & I2>;
+  <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, f: (a: A) => Parser<B, E2, R2, I2>): Parser<B, E | E2, R | R2, I & I2>;
 };
 /**
  * Applies a second parser to the *output* of the first (winnow's
@@ -411,8 +379,8 @@ export declare const flatMap: {
  * @category sequencing
  */
 export declare const mapParser: {
-    <A extends Input, B, E2, R2>(inner: Parser<B, E2, R2, A>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R | R2, I>;
-    <A extends Input, E, R, I extends Input, B, E2, R2>(self: Parser<A, E, R, I>, inner: Parser<B, E2, R2, A>): Parser<B, E | E2, R | R2, I>;
+  <A extends Input, B, E2, R2>(inner: Parser<B, E2, R2, A>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R | R2, I>;
+  <A extends Input, E, R, I extends Input, B, E2, R2>(self: Parser<A, E, R, I>, inner: Parser<B, E2, R2, A>): Parser<B, E | E2, R | R2, I>;
 };
 /**
  * Transforms the output of a parser with a function that may fail with a
@@ -424,8 +392,8 @@ export declare const mapParser: {
  * @category mapping
  */
 export declare const tryMap: {
-    <A, B, E2>(f: (a: A) => Result.Result<B, E2>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R, I>;
-    <A, E, R, I extends Input, B, E2>(self: Parser<A, E, R, I>, f: (a: A) => Result.Result<B, E2>): Parser<B, E | E2, R, I>;
+  <A, B, E2>(f: (a: A) => Result.Result<B, E2>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R, I>;
+  <A, E, R, I extends Input, B, E2>(self: Parser<A, E, R, I>, f: (a: A) => Result.Result<B, E2>): Parser<B, E | E2, R, I>;
 };
 /**
  * Like {@link tryMap}, but the function may throw. Thrown values become the
@@ -435,8 +403,8 @@ export declare const tryMap: {
  * @category mapping
  */
 export declare const tryMapUnknown: {
-    <A, B>(f: (a: A) => B): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | unknown, R, I>;
-    <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, f: (a: A) => B): Parser<B, E | unknown, R, I>;
+  <A, B>(f: (a: A) => B): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | unknown, R, I>;
+  <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, f: (a: A) => B): Parser<B, E | unknown, R, I>;
 };
 /**
  * Transforms the output of a parser with a function returning an `Option`;
@@ -447,8 +415,8 @@ export declare const tryMapUnknown: {
  * @category filtering
  */
 export declare const filterMap: {
-    <A, B>(f: (a: A) => Option.Option<B>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
-    <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, f: (a: A) => Option.Option<B>): Parser<B, E, R, I>;
+  <A, B>(f: (a: A) => Option.Option<B>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
+  <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, f: (a: A) => Option.Option<B>): Parser<B, E, R, I>;
 };
 /**
  * Keeps the output of a parser only if it satisfies a predicate, otherwise
@@ -458,10 +426,10 @@ export declare const filterMap: {
  * @category filtering
  */
 export declare const filter: {
-    <A, B extends A>(refinement: (a: NoInfer<A>) => a is B): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
-    <A>(predicate: (a: NoInfer<A>) => boolean): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
-    <A, E, R, I extends Input, B extends A>(self: Parser<A, E, R, I>, refinement: (a: A) => a is B): Parser<B, E, R, I>;
-    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, predicate: (a: A) => boolean): Parser<A, E, R, I>;
+  <A, B extends A>(refinement: (a: NoInfer<A>) => a is B): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
+  <A>(predicate: (a: NoInfer<A>) => boolean): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+  <A, E, R, I extends Input, B extends A>(self: Parser<A, E, R, I>, refinement: (a: A) => a is B): Parser<B, E, R, I>;
+  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, predicate: (a: A) => boolean): Parser<A, E, R, I>;
 };
 /**
  * Keeps the output of a parser only if it satisfies a predicate, otherwise
@@ -471,10 +439,10 @@ export declare const filter: {
  * @category filtering
  */
 export declare const filterOrFail: {
-    <A, B extends A, E2>(refinement: (a: NoInfer<A>) => a is B, orFailWith: (a: NoInfer<A>) => E2): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R, I>;
-    <A, E2>(predicate: (a: NoInfer<A>) => boolean, orFailWith: (a: NoInfer<A>) => E2): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E | E2, R, I>;
-    <A, E, R, I extends Input, B extends A, E2>(self: Parser<A, E, R, I>, refinement: (a: A) => a is B, orFailWith: (a: A) => E2): Parser<B, E | E2, R, I>;
-    <A, E, R, I extends Input, E2>(self: Parser<A, E, R, I>, predicate: (a: A) => boolean, orFailWith: (a: A) => E2): Parser<A, E | E2, R, I>;
+  <A, B extends A, E2>(refinement: (a: NoInfer<A>) => a is B, orFailWith: (a: NoInfer<A>) => E2): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R, I>;
+  <A, E2>(predicate: (a: NoInfer<A>) => boolean, orFailWith: (a: NoInfer<A>) => E2): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E | E2, R, I>;
+  <A, E, R, I extends Input, B extends A, E2>(self: Parser<A, E, R, I>, refinement: (a: A) => a is B, orFailWith: (a: A) => E2): Parser<B, E | E2, R, I>;
+  <A, E, R, I extends Input, E2>(self: Parser<A, E, R, I>, predicate: (a: A) => boolean, orFailWith: (a: A) => E2): Parser<A, E | E2, R, I>;
 };
 /**
  * Returns the slice of input consumed by a parser instead of its output
@@ -550,8 +518,8 @@ export declare const complete: <A, E, R, I extends Input>(self: Parser<A, E, R,
  * @category error management
  */
 export declare const context: {
-    (label: string): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
-    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, label: string): Parser<A, E, R, I>;
+  (label: string): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, label: string): Parser<A, E, R, I>;
 };
 /**
  * Names what a parser expects. When the parser fails without consuming any
@@ -563,8 +531,8 @@ export declare const context: {
  * @category error management
  */
 export declare const expected: {
-    (description: string): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
-    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, description: string): Parser<A, E, R, I>;
+  (description: string): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, description: string): Parser<A, E, R, I>;
 };
 /**
  * Transforms the user error (cause) of a parser's failures.
@@ -573,8 +541,8 @@ export declare const expected: {
  * @category error management
  */
 export declare const mapError: {
-    <E, E2>(f: (e: E) => E2): <A, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E2, R, I>;
-    <A, E, R, I extends Input, E2>(self: Parser<A, E, R, I>, f: (e: E) => E2): Parser<A, E2, R, I>;
+  <E, E2>(f: (e: E) => E2): <A, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E2, R, I>;
+  <A, E, R, I extends Input, E2>(self: Parser<A, E, R, I>, f: (e: E) => E2): Parser<A, E2, R, I>;
 };
 /**
  * Replaces any failure of a parser with the given user error, keeping the
@@ -584,8 +552,8 @@ export declare const mapError: {
  * @category error management
  */
 export declare const orFail: {
-    <E2>(error: () => E2): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E2, R, I>;
-    <A, E, R, I extends Input, E2>(self: Parser<A, E, R, I>, error: () => E2): Parser<A, E2, R, I>;
+  <E2>(error: () => E2): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E2, R, I>;
+  <A, E, R, I extends Input, E2>(self: Parser<A, E, R, I>, error: () => E2): Parser<A, E2, R, I>;
 };
 /**
  * If the parser fails recoverably, tries `that` from the same position.
@@ -595,8 +563,8 @@ export declare const orFail: {
  * @category error management
  */
 export declare const orElse: {
-    <B, E2, R2, I2 extends Input>(that: () => Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A | B, E | E2, R | R2, I & I2>;
-    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, that: () => Parser<B, E2, R2, I2>): Parser<A | B, E | E2, R | R2, I & I2>;
+  <B, E2, R2, I2 extends Input>(that: () => Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A | B, E | E2, R | R2, I & I2>;
+  <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, that: () => Parser<B, E2, R2, I2>): Parser<A | B, E | E2, R | R2, I & I2>;
 };
 /**
  * If the parser fails recoverably, succeeds with the given value without
@@ -606,8 +574,8 @@ export declare const orElse: {
  * @category error management
  */
 export declare const orElseSucceed: {
-    <B>(value: () => B): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A | B, E, R, I>;
-    <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, value: () => B): Parser<A | B, E, R, I>;
+  <B>(value: () => B): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A | B, E, R, I>;
+  <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, value: () => B): Parser<A | B, E, R, I>;
 };
 /**
  * Makes a parser optional: returns `Option.none()` without consuming input if
@@ -678,8 +646,8 @@ export declare const struct: <const Fields extends Readonly<Record<string, Parse
  * @category sequencing
  */
 export declare const zip: {
-    <B, E2, R2, I2 extends Input>(that: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<[A, B], E | E2, R | R2, I & I2>;
-    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, that: Parser<B, E2, R2, I2>): Parser<[A, B], E | E2, R | R2, I & I2>;
+  <B, E2, R2, I2 extends Input>(that: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<[A, B], E | E2, R | R2, I & I2>;
+  <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, that: Parser<B, E2, R2, I2>): Parser<[A, B], E | E2, R | R2, I & I2>;
 };
 /**
  * Runs two parsers in sequence and combines their outputs.
@@ -688,8 +656,8 @@ export declare const zip: {
  * @category sequencing
  */
 export declare const zipWith: {
-    <B, E2, R2, I2 extends Input, A, C>(that: Parser<B, E2, R2, I2>, f: (a: A, b: B) => C): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<C, E | E2, R | R2, I & I2>;
-    <A, E, R, I extends Input, B, E2, R2, I2 extends Input, C>(self: Parser<A, E, R, I>, that: Parser<B, E2, R2, I2>, f: (a: A, b: B) => C): Parser<C, E | E2, R | R2, I & I2>;
+  <B, E2, R2, I2 extends Input, A, C>(that: Parser<B, E2, R2, I2>, f: (a: A, b: B) => C): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<C, E | E2, R | R2, I & I2>;
+  <A, E, R, I extends Input, B, E2, R2, I2 extends Input, C>(self: Parser<A, E, R, I>, that: Parser<B, E2, R2, I2>, f: (a: A, b: B) => C): Parser<C, E | E2, R | R2, I & I2>;
 };
 /**
  * Runs two parsers in sequence, keeping the output of the first.
@@ -698,8 +666,8 @@ export declare const zipWith: {
  * @category sequencing
  */
 export declare const zipLeft: {
-    <B, E2, R2, I2 extends Input>(that: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E | E2, R | R2, I & I2>;
-    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, that: Parser<B, E2, R2, I2>): Parser<A, E | E2, R | R2, I & I2>;
+  <B, E2, R2, I2 extends Input>(that: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E | E2, R | R2, I & I2>;
+  <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, that: Parser<B, E2, R2, I2>): Parser<A, E | E2, R | R2, I & I2>;
 };
 /**
  * Runs two parsers in sequence, keeping the output of the second.
@@ -708,8 +676,8 @@ export declare const zipLeft: {
  * @category sequencing
  */
 export declare const zipRight: {
-    <B, E2, R2, I2 extends Input>(that: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R | R2, I & I2>;
-    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, that: Parser<B, E2, R2, I2>): Parser<B, E | E2, R | R2, I & I2>;
+  <B, E2, R2, I2 extends Input>(that: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E | E2, R | R2, I & I2>;
+  <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, that: Parser<B, E2, R2, I2>): Parser<B, E | E2, R | R2, I & I2>;
 };
 /**
  * Runs `prefix` then `parser`, keeping the output of `parser` (winnow's and
@@ -759,6 +727,23 @@ export declare const separatedPair: <A1, E1, R1, I1 extends Input, A2, E2, R2, I
  * })
  * ```
  *
+ * The body runs on every parse, so parsers created inside it, like
+ * `Token.literal("=")` above, are rebuilt on every run. On hot paths, build
+ * them once outside the body:
+ *
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const equals = Token.literal("=")
+ *
+ * const keyValue = Parser.gen(function*() {
+ *   const key = yield* Ascii.alpha1
+ *   yield* equals
+ *   const value = yield* Ascii.decInt
+ *   return [key, value] as const
+ * })
+ * ```
+ *
  * @since 0.1.0
  * @category sequencing
  */
@@ -780,7 +765,7 @@ export declare const gen: <Eff extends Parser.Any, AEff>(f: () => Generator<Eff,
  * @since 0.1.0
  * @category do notation
  */
-export declare const Do: Parser<{}, never, never, Input>;
+export declare const Do: Parser<Record<never, never>, never, never, Input>;
 /**
  * Binds the output of a parser to a field of the Do record.
  *
@@ -788,12 +773,8 @@ export declare const Do: Parser<{}, never, never, Input>;
  * @category do notation
  */
 export declare const bind: {
-    <N extends string, A extends object, B, E2, R2, I2 extends Input>(name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => Parser<B, E2, R2, I2>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Simplify<Omit<A, N> & {
-        [K in N]: B;
-    }>, E | E2, R | R2, I & I2>;
-    <A extends object, E, R, I extends Input, N extends string, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => Parser<B, E2, R2, I2>): Parser<Simplify<Omit<A, N> & {
-        [K in N]: B;
-    }>, E | E2, R | R2, I & I2>;
+  <N extends string, A extends object, B, E2, R2, I2 extends Input>(name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => Parser<B, E2, R2, I2>): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Simplify<Omit<A, N> & { [K in N]: B; }>, E | E2, R | R2, I & I2>;
+  <A extends object, E, R, I extends Input, N extends string, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => Parser<B, E2, R2, I2>): Parser<Simplify<Omit<A, N> & { [K in N]: B; }>, E | E2, R | R2, I & I2>;
 };
 /**
  * Wraps the output of a parser in a record with a single field.
@@ -802,29 +783,13 @@ export declare const bind: {
  * @category do notation
  */
 export declare const bindTo: {
-    <N extends string>(name: N): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<{
-        [K in N]: A;
-    }, E, R, I>;
-    <A, E, R, I extends Input, N extends string>(self: Parser<A, E, R, I>, name: N): Parser<{
-        [K in N]: A;
-    }, E, R, I>;
+  <N extends string>(name: N): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<{ [K in N]: A; }, E, R, I>;
+  <A, E, R, I extends Input, N extends string>(self: Parser<A, E, R, I>, name: N): Parser<{ [K in N]: A; }, E, R, I>;
 };
 declare const let_: {
-    <N extends string, A extends object, B>(name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => B): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Simplify<Omit<A, N> & {
-        [K in N]: B;
-    }>, E, R, I>;
-    <A extends object, E, R, I extends Input, N extends string, B>(self: Parser<A, E, R, I>, name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => B): Parser<Simplify<Omit<A, N> & {
-        [K in N]: B;
-    }>, E, R, I>;
+  <N extends string, A extends object, B>(name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => B): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Simplify<Omit<A, N> & { [K in N]: B; }>, E, R, I>;
+  <A extends object, E, R, I extends Input, N extends string, B>(self: Parser<A, E, R, I>, name: Exclude<N, keyof A>, f: (a: NoInfer<A>) => B): Parser<Simplify<Omit<A, N> & { [K in N]: B; }>, E, R, I>;
 };
-export { 
-/**
- * Adds a computed field to the Do record.
- *
- * @since 0.1.0
- * @category do notation
- */
-let_ as let };
 /**
  * Tries each parser in turn and returns the output of the first that
  * succeeds (winnow's and nom's `alt`).
@@ -847,6 +812,11 @@ export declare const alt: <const Ps extends ReadonlyArray<Parser.Any>>(...parser
  * an optional `otherwise` parser for unlisted keys, like winnow's `_ =>`
  * arm), or as a function returning a parser (or `undefined` for no match).
  *
+ * Prefer a record where the keys are known. Compiled code (see the
+ * `Compiler` module) switches on the key and runs every case compiled; the
+ * parser a function returns always runs interpreted, and one the function
+ * builds (`(c) => Parser.cut(p)`) is rebuilt on every run.
+ *
  * @example
  * ```ts
  * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
@@ -868,10 +838,8 @@ export declare const alt: <const Ps extends ReadonlyArray<Parser.Any>>(...parser
  * @category choice
  */
 export declare const dispatch: {
-    <K, E, R, I extends Input, P extends Parser.Any>(selector: Parser<K, E, R, I>, cases: (key: K) => P | undefined): Parser<Parser.Success<P>, E | Parser.Error<P>, R | Parser.Services<P>, I & Parser.InputOf<P>>;
-    <K extends PropertyKey, E, R, I extends Input, const Cases extends {
-        readonly [key in K]?: Parser.Any;
-    }, Otherwise extends Parser.Any = never>(selector: Parser<K, E, R, I>, cases: Cases, otherwise?: Otherwise): Parser<Parser.Success<NonNullable<Cases[keyof Cases]> | Otherwise>, E | Parser.Error<NonNullable<Cases[keyof Cases]> | Otherwise>, R | Parser.Services<NonNullable<Cases[keyof Cases]> | Otherwise>, I & Parser.InputOf<NonNullable<Cases[keyof Cases]> | Otherwise>>;
+  <K, E, R, I extends Input, P extends Parser.Any>(selector: Parser<K, E, R, I>, cases: (key: K) => P | undefined): Parser<Parser.Success<P>, E | Parser.Error<P>, R | Parser.Services<P>, I & Parser.InputOf<P>>;
+  <K extends PropertyKey, E, R, I extends Input, const Cases extends { readonly [key in K]?: Parser.Any; }, Otherwise extends Parser.Any = never>(selector: Parser<K, E, R, I>, cases: Cases, otherwise?: Otherwise): Parser<Parser.Success<NonNullable<Cases[keyof Cases]> | Otherwise>, E | Parser.Error<NonNullable<Cases[keyof Cases]> | Otherwise>, R | Parser.Services<NonNullable<Cases[keyof Cases]> | Otherwise>, I & Parser.InputOf<NonNullable<Cases[keyof Cases]> | Otherwise>>;
 };
 /**
  * Applies every parser exactly once, in whatever order they match, and
@@ -906,32 +874,52 @@ export declare const permutation: <const Ps extends ReadonlyArray<Parser.Any>>(.
  * @category repetition
  */
 export declare const repeat: {
-    <const Rg extends Range = {
-        readonly min: 0;
-    }>(range?: Rg): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Repeated<A, Rg>, E, R, I>;
-    <A, E, R, I extends Input, const Rg extends Range = {
-        readonly min: 0;
-    }>(self: Parser<A, E, R, I>, range?: Rg): Parser<Repeated<A, Rg>, E, R, I>;
+  <const Rg extends Range = {
+    readonly min: 0;
+  }>(range?: Rg): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Repeated<A, Rg>, E, R, I>;
+  <A, E, R, I extends Input, const Rg extends Range = {
+    readonly min: 0;
+  }>(self: Parser<A, E, R, I>, range?: Rg): Parser<Repeated<A, Rg>, E, R, I>;
 };
 /**
  * Applies a parser repeatedly, folding the outputs into an accumulator
  * (winnow's `repeat(..).fold(..)`, nom's `fold_many0`/`fold_many1`/
  * `fold_many_m_n`).
  *
+ * With `while`, the repetition also stops, successfully and without
+ * consuming more input, as soon as the predicate is false of the
+ * accumulator. It is checked before each element once `range.min` elements
+ * have been folded, so `min` still holds.
+ *
+ * @example
+ * ```ts
+ * import { Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * // Keeps the first two digits, leaving the rest unparsed
+ * const two = Parser.fold(Token.oneOf("0123456789"), {
+ *   init: () => "",
+ *   f: (acc, d) => acc + d,
+ *   while: (acc) => acc.length < 2
+ * })
+ * Parser.parsePeek(two, "1234") // Result.succeed(["34", "12"])
+ * ```
+ *
  * @since 0.1.0
  * @category repetition
  */
 export declare const fold: {
-    <A, B>(options: {
-        readonly init: () => B;
-        readonly f: (acc: B, a: A) => B;
-        readonly range?: Range | undefined;
-    }): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
-    <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, options: {
-        readonly init: () => B;
-        readonly f: (acc: B, a: A) => B;
-        readonly range?: Range | undefined;
-    }): Parser<B, E, R, I>;
+  <A, B>(options: {
+    readonly init: () => B;
+    readonly f: (acc: B, a: A) => B;
+    readonly range?: Range | undefined;
+    readonly while?: ((acc: B) => boolean) | undefined;
+  }): <E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<B, E, R, I>;
+  <A, E, R, I extends Input, B>(self: Parser<A, E, R, I>, options: {
+    readonly init: () => B;
+    readonly f: (acc: B, a: A) => B;
+    readonly range?: Range | undefined;
+    readonly while?: ((acc: B) => boolean) | undefined;
+  }): Parser<B, E, R, I>;
 };
 /**
  * Applies `self` repeatedly until `end` succeeds, returning the collected
@@ -942,20 +930,36 @@ export declare const fold: {
  * @category repetition
  */
 export declare const repeatTill: {
-    <B, E2, R2, I2 extends Input, const Rg extends Range = {
-        readonly min: 0;
-    }>(end: Parser<B, E2, R2, I2>, range?: Rg): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<[Repeated<A, Rg>, B], E | E2, R | R2, I & I2>;
-    <A, E, R, I extends Input, B, E2, R2, I2 extends Input, const Rg extends Range = {
-        readonly min: 0;
-    }>(self: Parser<A, E, R, I>, end: Parser<B, E2, R2, I2>, range?: Rg): Parser<[Repeated<A, Rg>, B], E | E2, R | R2, I & I2>;
+  <B, E2, R2, I2 extends Input, const Rg extends Range = {
+    readonly min: 0;
+  }>(end: Parser<B, E2, R2, I2>, range?: Rg): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<[Repeated<A, Rg>, B], E | E2, R | R2, I & I2>;
+  <A, E, R, I extends Input, B, E2, R2, I2 extends Input, const Rg extends Range = {
+    readonly min: 0;
+  }>(self: Parser<A, E, R, I>, end: Parser<B, E2, R2, I2>, range?: Rg): Parser<[Repeated<A, Rg>, B], E | E2, R | R2, I & I2>;
 };
+/**
+ * Applies `self` repeatedly, separated by `separator`, collecting the
+ * outputs of `self` (winnow's `separated`, nom's `separated_list0` and
+ * `separated_list1`). A trailing separator is not consumed.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const csv = Parser.separated(Ascii.decInt, Token.literal(","))
+ * Parser.parse(csv, "1,2,3") // Result.succeed([1, 2, 3])
+ * ```
+ *
+ * @since 0.1.0
+ * @category repetition
+ */
 export declare const separated: {
-    <S, E2, R2, I2 extends Input, const Rg extends Range = {
-        readonly min: 0;
-    }>(separator: Parser<S, E2, R2, I2>, range?: Rg): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Repeated<A, Rg>, E | E2, R | R2, I & I2>;
-    <A, E, R, I extends Input, S, E2, R2, I2 extends Input, const Rg extends Range = {
-        readonly min: 0;
-    }>(self: Parser<A, E, R, I>, separator: Parser<S, E2, R2, I2>, range?: Rg): Parser<Repeated<A, Rg>, E | E2, R | R2, I & I2>;
+  <S, E2, R2, I2 extends Input, const Rg extends Range = {
+    readonly min: 0;
+  }>(separator: Parser<S, E2, R2, I2>, range?: Rg): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Repeated<A, Rg>, E | E2, R | R2, I & I2>;
+  <A, E, R, I extends Input, S, E2, R2, I2 extends Input, const Rg extends Range = {
+    readonly min: 0;
+  }>(self: Parser<A, E, R, I>, separator: Parser<S, E2, R2, I2>, range?: Rg): Parser<Repeated<A, Rg>, E | E2, R | R2, I & I2>;
 };
 /**
  * Parses one or more `self` separated by `separator`, folding them from the
@@ -1028,8 +1032,8 @@ export declare const service: <Id, S>(key: Context.Key<Id, S>) => Parser<S, neve
  * @category services
  */
 export declare const provideService: {
-    <Id, S>(key: Context.Key<Id, S>, service: NoInfer<S>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, Exclude<R, Id>, I>;
-    <A, E, R, I extends Input, Id, S>(self: Parser<A, E, R, I>, key: Context.Key<Id, S>, service: NoInfer<S>): Parser<A, E, Exclude<R, Id>, I>;
+  <Id, S>(key: Context.Key<Id, S>, service: NoInfer<S>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, Exclude<R, Id>, I>;
+  <A, E, R, I extends Input, Id, S>(self: Parser<A, E, R, I>, key: Context.Key<Id, S>, service: NoInfer<S>): Parser<A, E, Exclude<R, Id>, I>;
 };
 /**
  * Provides a context of services to a parser.
@@ -1038,8 +1042,8 @@ export declare const provideService: {
  * @category services
  */
 export declare const provide: {
-    <R2>(context: Context.Context<R2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, Exclude<R, R2>, I>;
-    <A, E, R, I extends Input, R2>(self: Parser<A, E, R, I>, context: Context.Context<R2>): Parser<A, E, Exclude<R, R2>, I>;
+  <R2>(context: Context.Context<R2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, Exclude<R, R2>, I>;
+  <A, E, R, I extends Input, R2>(self: Parser<A, E, R, I>, context: Context.Context<R2>): Parser<A, E, Exclude<R, R2>, I>;
 };
 /**
  * Error recovery: if the parser fails, record the failure, skip input with
@@ -1052,8 +1056,8 @@ export declare const provide: {
  * @category error recovery
  */
 export declare const resumeAfter: {
-    <B, E2, R2, I2 extends Input>(recover: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Option.Option<A>, E | E2, R | R2, I & I2>;
-    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, recover: Parser<B, E2, R2, I2>): Parser<Option.Option<A>, E | E2, R | R2, I & I2>;
+  <B, E2, R2, I2 extends Input>(recover: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<Option.Option<A>, E | E2, R | R2, I & I2>;
+  <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, recover: Parser<B, E2, R2, I2>): Parser<Option.Option<A>, E | E2, R | R2, I & I2>;
 };
 /**
  * Error recovery: if the parser fails, record the failure, skip input with
@@ -1066,8 +1070,8 @@ export declare const resumeAfter: {
  * @category error recovery
  */
 export declare const retryAfter: {
-    <B, E2, R2, I2 extends Input>(recover: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E | E2, R | R2, I & I2>;
-    <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, recover: Parser<B, E2, R2, I2>): Parser<A, E | E2, R | R2, I & I2>;
+  <B, E2, R2, I2 extends Input>(recover: Parser<B, E2, R2, I2>): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E | E2, R | R2, I & I2>;
+  <A, E, R, I extends Input, B, E2, R2, I2 extends Input>(self: Parser<A, E, R, I>, recover: Parser<B, E2, R2, I2>): Parser<A, E | E2, R | R2, I & I2>;
 };
 /**
  * Traces the execution of a parser (winnow's `trace`). When a tracer is
@@ -1079,8 +1083,8 @@ export declare const retryAfter: {
  * @category debugging
  */
 export declare const trace: {
-    (name: string): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
-    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, name: string): Parser<A, E, R, I>;
+  (name: string): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
+  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, name: string): Parser<A, E, R, I>;
 };
 /**
  * A tracer that writes an indented trace to `console.log`, similar to
@@ -1090,67 +1094,6 @@ export declare const trace: {
  * @category debugging
  */
 export declare const consoleTracer: (event: TraceEvent) => void;
-/**
- * Options for {@link compile}.
- *
- * @since 0.1.0
- * @category compilation
- */
-export interface CompileOptions {
-    /**
-     * Which compiler to use:
-     *
-     * - `"auto"` (the default): generated code (a JIT) where `new Function`
-     *   is allowed, otherwise specialized closures
-     * - `"closure"`: specialized closures only. It never generates code, so
-     *   it is the choice under a Content Security Policy, where even probing
-     *   for `new Function` is reported as a violation.
-     */
-    readonly backend?: "auto" | "closure" | undefined;
-}
-/**
- * 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 declare const compile: {
-    (options?: CompileOptions): <A, E, R, I extends Input>(self: Parser<A, E, R, I>) => Parser<A, E, R, I>;
-    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, options?: CompileOptions): Parser<A, E, R, I>;
-};
 /**
  * Options accepted by the runners.
  *
@@ -1158,11 +1101,24 @@ export declare const compile: {
  * @category running
  */
 export interface ParseOptions {
-    /**
-     * Install a tracer for {@link trace}d parsers: `true` uses
-     * {@link consoleTracer}.
-     */
-    readonly trace?: boolean | ((event: TraceEvent) => void) | undefined;
+  /**
+   * Install a tracer for {@link trace}d parsers: `true` uses
+   * {@link consoleTracer}.
+   */
+  readonly trace?: boolean | ((event: TraceEvent) => void) | undefined;
+  /**
+   * Where to start parsing (default `0`): in code units for strings, bytes
+   * for byte input and elements for arrays. The result is that of parsing
+   * `input.slice(offset)`, but without copying the input, and every offset
+   * (`parsePartial`'s `Done`, `location`, spans, `ParseError.offset` and its
+   * line and column) is a position in the whole input. This is what an
+   * incremental driver, such as a lexer reading one token at a time from a
+   * buffer, needs: compiled parsers run compiled from any offset.
+   *
+   * Throws a `RangeError` unless it is an integer from `0` to the input's
+   * length.
+   */
+  readonly offset?: number | undefined;
 }
 /**
  * Options accepted by the runners for parsers that require services.
@@ -1171,7 +1127,7 @@ export interface ParseOptions {
  * @category running
  */
 export interface ParseOptionsWithContext<R> extends ParseOptions {
-    readonly context: Context.Context<R>;
+  readonly context: Context.Context<R>;
 }
 /**
  * Runs a parser against a complete input, requiring the whole input to be
@@ -1190,8 +1146,8 @@ export interface ParseOptionsWithContext<R> extends ParseOptions {
  * @category running
  */
 export declare const parse: {
-    <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): Result.Result<A, ParseError.ParseError<E>>;
-    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): Result.Result<A, ParseError.ParseError<E>>;
+  <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): Result.Result<A, ParseError.ParseError<E>>;
+  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): Result.Result<A, ParseError.ParseError<E>>;
 };
 /**
  * Like {@link parse}, but throws the `ParseError` on failure.
@@ -1200,20 +1156,24 @@ export declare const parse: {
  * @category running
  */
 export declare const parseSync: {
-    <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): A;
-    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): A;
+  <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): A;
+  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): A;
 };
 /**
  * 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`).
  *
+ * The parser ended at offset `input.length - remaining.length`, which is
+ * how a caller running from an `offset` (see {@link ParseOptions}) finds
+ * where to continue.
+ *
  * @since 0.1.0
  * @category running
  */
 export declare const parsePeek: {
-    <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): Result.Result<[remaining: Slice<I>, output: A], ParseError.ParseError<E>>;
-    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): Result.Result<[remaining: Slice<I>, output: A], ParseError.ParseError<E>>;
+  <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): Result.Result<[remaining: Slice<I>, output: A], ParseError.ParseError<E>>;
+  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): Result.Result<[remaining: Slice<I>, output: A], ParseError.ParseError<E>>;
 };
 /**
  * The outcome of parsing a partial (streaming) input.
@@ -1225,12 +1185,12 @@ export declare const parsePeek: {
  * @category running
  */
 export type PartialResult<A> = {
-    readonly _tag: "Done";
-    readonly value: A;
-    readonly offset: number;
+  readonly _tag: "Done";
+  readonly value: A;
+  readonly offset: number;
 } | {
-    readonly _tag: "Incomplete";
-    readonly needed: Option.Option<number>;
+  readonly _tag: "Incomplete";
+  readonly needed: Option.Option<number>;
 };
 /**
  * Runs a parser against a *partial* input, i.e. a chunk of a stream that may
@@ -1239,7 +1199,14 @@ export type PartialResult<A> = {
  * of failing or succeeding early.
  *
  * The parser does not have to consume the whole input; the returned
- * `offset` says how much was consumed.
+ * `offset` says where it stopped. It is a position in the whole input, so
+ * with the `offset` option (see {@link ParseOptions}) it is where the next
+ * parse starts.
+ *
+ * A parser compiled with the `Compiler` module runs compiled, with a build
+ * that handles partial input. When it fails or needs more input, it runs again
+ * interpreted, so `Incomplete`'s `needed` and every `ParseError` are the
+ * interpreter's.
  *
  * @example
  * ```ts
@@ -1255,8 +1222,8 @@ export type PartialResult<A> = {
  * @category running
  */
 export declare const parsePartial: {
-    <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): Result.Result<PartialResult<A>, ParseError.ParseError<E>>;
-    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): Result.Result<PartialResult<A>, ParseError.ParseError<E>>;
+  <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): Result.Result<PartialResult<A>, ParseError.ParseError<E>>;
+  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): Result.Result<PartialResult<A>, ParseError.ParseError<E>>;
 };
 /**
  * Runs a parser against a complete input as an `Effect`. Services required
@@ -1277,6 +1244,77 @@ export declare const parsePartial: {
  * @category running
  */
 export declare const parseEffect: <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options?: ParseOptions) => Effect.Effect<A, ParseError.ParseError<E>, R>;
+/**
+ * Runs a parser on a state you own, from `state.pos`, and returns its output
+ * or {@link Fail}: like calling `self.step(state)`, but using the parser's
+ * compiled form when it has one (see the `Compiler` module). This is the
+ * runner for drivers that make many small runs over one buffer, such as a
+ * lexer reading one token at a time: keep one `Input.State` and
+ * `reset` it (`Input.State.reset`) before each run, and no run allocates a
+ * state, a `Result` or a slice.
+ *
+ * On success the cursor is where the parser stopped. On failure the state
+ * holds the interpreter's failure (`mode`, `failure`, and what
+ * `reportedFailure()` returns): a compiled run that fails is thrown away and
+ * the parser's step runs again from the same position. A partial state
+ * (`partial: true`) runs the compiled build that handles partial input, so
+ * `Incomplete` is reported as the step would report it. Under a tracer,
+ * with recovery on or inside a `Syntax` parse, the step runs interpreted.
+ *
+ * A driver that only needs to know *that* a parser failed (it tries
+ * another, or skips a character) can pass `{ diagnostics: false }` to skip
+ * the interpreted re-run; see {@link RunOptions}.
+ *
+ * Compiled code records no hints or furthest failure when it succeeds, so
+ * a later failure on the same state can list fewer expectations than one
+ * after interpreted runs would: reset the state between runs (as above) and
+ * its errors are the ones {@link parse} reports. Deep nesting fails with an
+ * unrecoverable `TooDeep` failure instead of throwing, as in the other
+ * runners.
+ *
+ * @example
+ * ```ts
+ * import { Ascii, Compiler, Input, Parser, Token } from "@thomasfosterau/effect-parse"
+ *
+ * const token = Compiler.jit(Parser.preceded(Ascii.space0, Parser.alt(Ascii.alpha1, Token.oneOf("+-"))))
+ *
+ * const tokens = (text: string): Array<string> => {
+ *   const state = new Input.State(text)
+ *   const out: Array<string> = []
+ *   while (state.pos < state.end) {
+ *     const t = Parser.run(token, state.reset(state.pos))
+ *     if (t === Input.Fail) break
+ *     out.push(t)
+ *   }
+ *   return out
+ * }
+ *
+ * tokens("a + b") // ["a", "+", "b"]
+ * ```
+ *
+ * @since 0.2.0
+ * @category running
+ */
+export declare const run: <A, E, R, I extends Input>(self: Parser<A, E, R, I>, state: State<I>, options?: RunOptions) => A | Fail;
+/**
+ * Options for {@link run}.
+ *
+ * @since 0.2.0
+ * @category running
+ */
+export interface RunOptions {
+  /**
+   * Whether a failure records the interpreter's diagnostics (default
+   * `true`). With `false`, a compiled run that fails is not run again
+   * interpreted: the state's `mode` (`Backtrack`, `Cut` or `Incomplete`)
+   * is set and the cursor is back where the run started, but `failure`,
+   * hints and the furthest failure are left as they were. For drivers that
+   * try a parser and move on when it fails, without reporting why, this
+   * halves the cost of each failure. Parsers that run interpreted record
+   * their diagnostics either way.
+   */
+  readonly diagnostics?: boolean | undefined;
+}
 /**
  * The outcome of {@link parseRecoverable}.
  *
@@ -1284,10 +1322,10 @@ export declare const parseEffect: <A, E, R, I extends Input>(self: Parser<A, E,
  * @category running
  */
 export interface RecoverableResult<A, E> {
-    /** The output, if parsing ultimately succeeded. */
-    readonly value: Option.Option<A>;
-    /** Every error encountered: recovered ones, then the fatal one (if any). */
-    readonly errors: ReadonlyArray<ParseError.ParseError<E>>;
+  /** The output, if parsing ultimately succeeded. */
+  readonly value: Option.Option<A>;
+  /** Every error encountered: recovered ones, then the fatal one (if any). */
+  readonly errors: ReadonlyArray<ParseError.ParseError<E>>;
 }
 /**
  * Runs a parser with error recovery enabled (winnow's `Recoverable`
@@ -1298,15 +1336,9 @@ export interface RecoverableResult<A, E> {
  * @category running
  */
 export declare const parseRecoverable: {
-    <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): RecoverableResult<A, E>;
-    <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): RecoverableResult<A, E>;
+  <A, E, I extends Input>(self: Parser<A, E, never, I>, input: NoInfer<Source<I>>, options?: ParseOptions): RecoverableResult<A, E>;
+  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, input: NoInfer<Source<I>>, options: ParseOptionsWithContext<R>): RecoverableResult<A, E>;
 };
-/**
- * Records a failure kind for use in custom parsers; re-exported for
- * convenience.
- *
- * @since 0.1.0
- * @category models
- */
-export type { ErrorKind };
+//#endregion
+export { type ErrorKind, let_ as let, void_ as void };
 //# sourceMappingURL=Parser.d.ts.map