@thomasfosterau/effect-parse 0.4.1 → 0.6.0

package/src/internal/compiler/wasmAsm.ts

@@ -0,0 +1,484 @@
+/**
+ * A small WebAssembly assembler for the WASM compiler: function bodies with
+ * structured labels, and the binary module around them. It writes only the
+ * instructions and sections that compiler uses.
+ */
+
+/** Value types. */
+export const I32 = 0x7f
+export const I64 = 0x7e
+export const F64 = 0x7c
+export const V128 = 0x7b
+const Void = 0x40
+
+/** Opcodes used by the compiler. */
+export const Op = {
+  unreachable: 0x00,
+  block: 0x02,
+  loop: 0x03,
+  if: 0x04,
+  else: 0x05,
+  end: 0x0b,
+  br: 0x0c,
+  brIf: 0x0d,
+  brTable: 0x0e,
+  return: 0x0f,
+  call: 0x10,
+  drop: 0x1a,
+  select: 0x1b,
+  localGet: 0x20,
+  localSet: 0x21,
+  localTee: 0x22,
+  globalGet: 0x23,
+  globalSet: 0x24,
+  i32Load: 0x28,
+  i64Load: 0x29,
+  f64Load: 0x2b,
+  i32Load8U: 0x2d,
+  i32Load16U: 0x2f,
+  i32Store: 0x36,
+  i64Store: 0x37,
+  i32Store8: 0x3a,
+  i32Store16: 0x3b,
+  f64Store: 0x39,
+  i32Const: 0x41,
+  i64Const: 0x42,
+  f64Const: 0x44,
+  i32Eqz: 0x45,
+  i32Eq: 0x46,
+  i32Ne: 0x47,
+  i32LtS: 0x48,
+  i32LtU: 0x49,
+  i32GtS: 0x4a,
+  i32GtU: 0x4b,
+  i32LeS: 0x4c,
+  i32LeU: 0x4d,
+  i32GeS: 0x4e,
+  i32GeU: 0x4f,
+  i64Eqz: 0x50,
+  i64Ne: 0x52,
+  f64Eq: 0x61,
+  f64Ne: 0x62,
+  i32Add: 0x6a,
+  i32Sub: 0x6b,
+  i32Mul: 0x6c,
+  i32And: 0x71,
+  i32Or: 0x72,
+  i32Xor: 0x73,
+  i32Shl: 0x74,
+  i32ShrU: 0x76,
+  i32Ctz: 0x68,
+  i64And: 0x83,
+  i64Or: 0x84,
+  i64Shl: 0x86,
+  i64ShrU: 0x88,
+  f64Abs: 0x99,
+  f64Neg: 0x9a,
+  f64Add: 0xa0,
+  f64Sub: 0xa1,
+  f64Mul: 0xa2,
+  f64Div: 0xa3,
+  f64ConvertI32U: 0xb8
+} as const
+
+/** Unsigned LEB128. */
+export const uleb = (n: number, out: Array<number> = []): Array<number> => {
+  let v = n >>> 0
+  do {
+    let b = v & 0x7f
+    v >>>= 7
+    if (v !== 0) b |= 0x80
+    out.push(b)
+  } while (v !== 0)
+  return out
+}
+
+/** Signed LEB128 of a 32-bit integer. */
+export const sleb = (n: number, out: Array<number> = []): Array<number> => {
+  let v = n | 0
+  for (;;) {
+    const b = v & 0x7f
+    v >>= 7
+    if ((v === 0 && (b & 0x40) === 0) || (v === -1 && (b & 0x40) !== 0)) {
+      out.push(b)
+      return out
+    }
+    out.push(b | 0x80)
+  }
+}
+
+/** SIMD opcodes, after the `0xfd` prefix. */
+export const Simd = {
+  v128Load: 0x00,
+  v128Store: 0x0b,
+  v128Const: 0x0c,
+  i8x16Swizzle: 0x0e,
+  i8x16Splat: 0x0f,
+  i8x16Eq: 0x23,
+  i8x16Ne: 0x24,
+  v128Not: 0x4d,
+  v128And: 0x4e,
+  v128Or: 0x50,
+  v128AnyTrue: 0x53,
+  i8x16AllTrue: 0x63,
+  i8x16Bitmask: 0x64,
+  i8x16ShrU: 0x6d,
+  i8x16RelaxedSwizzle: 0x100,
+  i16x8ExtendLowI8x16U: 0x89,
+  i16x8ExtendHighI8x16U: 0x8a
+} as const
+
+/** Signed LEB128 of a 64-bit integer. */
+const sleb64 = (n: bigint, out: Array<number>): Array<number> => {
+  let v = BigInt.asIntN(64, n)
+  for (;;) {
+    const b = Number(v & 0x7fn)
+    v >>= 7n
+    if ((v === 0n && (b & 0x40) === 0) || (v === -1n && (b & 0x40) !== 0)) {
+      out.push(b)
+      return out
+    }
+    out.push(b | 0x80)
+  }
+}
+
+/** A branch target: a block, a loop or an `if`. */
+export class Label {
+  readonly _label = true
+}
+
+/**
+ * The body of a function being written: its code, its locals (after the
+ * parameters) and the stack of labels that branches refer to.
+ */
+export class Body {
+  readonly code: Array<number> = []
+  /** The types of the locals after the parameters. */
+  private readonly types: Array<number> = []
+  private readonly labels: Array<Label> = []
+  private next: number
+  /** Trace writes since the last check that dominates the code that follows (see the compiler). */
+  writes = 0
+  /** The local holding the trace pointer, in the compiler's rule functions. */
+  tp = -1
+  /** The local holding the end of the input, in the compiler's rule functions (-1: read the global). */
+  endLocal = -1
+
+  constructor(readonly params: number) {
+    this.next = params
+  }
+
+  /** A new local of type `i32`. */
+  local(): number {
+    this.types.push(I32)
+    return this.next++
+  }
+
+  /** A new local of type `i64`. */
+  localI64(): number {
+    this.types.push(I64)
+    return this.next++
+  }
+
+  /** A new local of type `v128`. */
+  localV128(): number {
+    this.types.push(V128)
+    return this.next++
+  }
+
+  /** A new local of type `f64`. */
+  localF64(): number {
+    this.types.push(F64)
+    return this.next++
+  }
+
+  /** The locals declaration, in index order (runs of one type each). */
+  locals(): Array<number> {
+    const groups: Array<[number, number]> = []
+    for (const type of this.types) {
+      const last = groups[groups.length - 1]
+      if (last !== undefined && last[1] === type) last[0]++
+      else groups.push([1, type])
+    }
+    const out = uleb(groups.length)
+    for (const [n, type] of groups) {
+      uleb(n, out)
+      out.push(type)
+    }
+    return out
+  }
+
+  op(...bytes: ReadonlyArray<number>): this {
+    for (const b of bytes) this.code.push(b)
+    return this
+  }
+
+  i32(n: number): this {
+    this.code.push(Op.i32Const)
+    sleb(n, this.code)
+    return this
+  }
+
+  i64(n: bigint): this {
+    this.code.push(Op.i64Const)
+    sleb64(n, this.code)
+    return this
+  }
+
+  f64(x: number): this {
+    this.code.push(Op.f64Const)
+    const bytes = new Uint8Array(new Float64Array([x]).buffer)
+    for (const b of bytes) this.code.push(b)
+    return this
+  }
+
+  get(l: number): this {
+    this.code.push(Op.localGet)
+    uleb(l, this.code)
+    return this
+  }
+
+  set(l: number): this {
+    this.code.push(Op.localSet)
+    uleb(l, this.code)
+    return this
+  }
+
+  tee(l: number): this {
+    this.code.push(Op.localTee)
+    uleb(l, this.code)
+    return this
+  }
+
+  gget(g: number): this {
+    this.code.push(Op.globalGet)
+    uleb(g, this.code)
+    return this
+  }
+
+  gset(g: number): this {
+    this.code.push(Op.globalSet)
+    uleb(g, this.code)
+    return this
+  }
+
+  call(f: number): this {
+    this.code.push(Op.call)
+    uleb(f, this.code)
+    return this
+  }
+
+  /** `v128.const` of sixteen bytes. */
+  v128(bytes: ArrayLike<number>): this {
+    this.code.push(0xfd)
+    uleb(Simd.v128Const, this.code)
+    for (let i = 0; i < 16; i++) this.code.push((bytes[i] ?? 0) & 0xff)
+    return this
+  }
+
+  /** A SIMD instruction, with a memory access's alignment and offset for loads and stores. */
+  simd(op: number, align = -1, offset = 0): this {
+    this.code.push(0xfd)
+    uleb(op, this.code)
+    if (align >= 0) {
+      uleb(align, this.code)
+      uleb(offset, this.code)
+    }
+    return this
+  }
+
+  /** A memory access with an alignment exponent and a constant offset. */
+  mem(op: number, align: number, offset: number): this {
+    this.code.push(op)
+    uleb(align, this.code)
+    uleb(offset, this.code)
+    return this
+  }
+
+  /** `block ... end`: a branch to its label exits the block. */
+  block(body: (exit: Label) => void): this {
+    return this.structured(Op.block, body)
+  }
+
+  /** `loop ... end`: a branch to its label restarts the loop. */
+  loop(body: (again: Label) => void): this {
+    return this.structured(Op.loop, body)
+  }
+
+  /** `if ... (else ...) end` on the `i32` at the top of the stack. */
+  if(then: () => void, otherwise?: () => void): this {
+    this.code.push(Op.if, Void)
+    this.labels.push(new Label())
+    then()
+    if (otherwise !== undefined) {
+      this.code.push(Op.else)
+      otherwise()
+    }
+    this.labels.pop()
+    this.code.push(Op.end)
+    return this
+  }
+
+  /** `if (result i32) ... else ... end`. */
+  ifI32(then: () => void, otherwise: () => void): this {
+    this.code.push(Op.if, I32)
+    this.labels.push(new Label())
+    then()
+    this.code.push(Op.else)
+    otherwise()
+    this.labels.pop()
+    this.code.push(Op.end)
+    return this
+  }
+
+  private structured(op: number, body: (label: Label) => void): this {
+    const label = new Label()
+    this.code.push(op, Void)
+    this.labels.push(label)
+    body(label)
+    this.labels.pop()
+    this.code.push(Op.end)
+    return this
+  }
+
+  /**
+   * Whether a branch went to a label out of scope: a bug in the compiler,
+   * which then refuses the function (see the WebAssembly compiler).
+   */
+  invalid = false
+
+  private depth(label: Label): number {
+    const i = this.labels.lastIndexOf(label)
+    if (i < 0) this.invalid = true
+    return this.labels.length - 1 - i
+  }
+
+  br(label: Label): this {
+    this.code.push(Op.br)
+    uleb(this.depth(label), this.code)
+    return this
+  }
+
+  brIf(label: Label): this {
+    this.code.push(Op.brIf)
+    uleb(this.depth(label), this.code)
+    return this
+  }
+
+  /** `br_table`: `targets[i]` for the index at the top of the stack, `otherwise` out of range. */
+  brTable(targets: ReadonlyArray<Label>, otherwise: Label): this {
+    this.code.push(Op.brTable)
+    uleb(targets.length, this.code)
+    for (const t of targets) uleb(this.depth(t), this.code)
+    uleb(this.depth(otherwise), this.code)
+    return this
+  }
+}
+
+/** A function type: parameter and result types. */
+export interface FuncType {
+  readonly params: ReadonlyArray<number>
+  readonly results: ReadonlyArray<number>
+}
+
+/** A global: its type, whether it is mutable, and its initial value. */
+export interface Global {
+  readonly type: number
+  readonly init: number
+}
+
+/** What a module is made of. */
+export interface ModuleSpec {
+  readonly types: ReadonlyArray<FuncType>
+  /** Imported functions: module, name, type index. */
+  readonly imports: ReadonlyArray<readonly [string, string, number]>
+  /** The imported memory (module "env", name "mem"). */
+  readonly memoryPages: number
+  /** Defined functions: type index and body. */
+  readonly functions: ReadonlyArray<readonly [number, Body]>
+  readonly globals: ReadonlyArray<Global>
+  /** Exported functions and globals: name, kind (0 function, 3 global), index. */
+  readonly exports: ReadonlyArray<readonly [string, 0 | 3, number]>
+  /** Active data segments: offset and bytes. */
+  readonly data: ReadonlyArray<readonly [number, Uint8Array]>
+}
+
+const utf8Encoder = /*#__PURE__*/ new TextEncoder()
+
+/** Appends `bytes` to `out`. */
+const append = (out: Array<number>, bytes: ArrayLike<number>): void => {
+  for (let i = 0; i < bytes.length; i++) out.push(bytes[i])
+}
+
+/** Appends a name: its length and its UTF-8 bytes. */
+const name = (out: Array<number>, s: string): void => {
+  const bytes = utf8Encoder.encode(s)
+  uleb(bytes.length, out)
+  append(out, bytes)
+}
+
+/** Appends a section: its id, its size, the number of its items and the items `write` appends. */
+const section = <A>(
+  out: Array<number>,
+  id: number,
+  items: ReadonlyArray<A>,
+  write: (body: Array<number>, item: A) => void
+) => {
+  const body = uleb(items.length)
+  for (const item of items) write(body, item)
+  out.push(id)
+  uleb(body.length, out)
+  append(out, body)
+}
+
+const f64Bytes = (x: number): Uint8Array => new Uint8Array(new Float64Array([x]).buffer)
+
+/** The binary module. */
+export const encodeModule = (spec: ModuleSpec): Uint8Array<ArrayBuffer> => {
+  const out = [0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]
+  section(out, 1, spec.types, (body, t) => {
+    body.push(0x60)
+    uleb(t.params.length, body)
+    append(body, t.params)
+    uleb(t.results.length, body)
+    append(body, t.results)
+  })
+  const memory: readonly [string, string, number] = ["env", "mem", -1]
+  section(out, 2, [...spec.imports, memory], (body, [m, n, t]) => {
+    name(body, m)
+    name(body, n)
+    if (t < 0) body.push(0x02, 0x00, ...uleb(spec.memoryPages))
+    else body.push(0x00, ...uleb(t))
+  })
+  section(out, 3, spec.functions, (body, [t]) => uleb(t, body))
+  section(out, 6, spec.globals, (body, g) => {
+    if (g.type === F64) {
+      body.push(F64, 0x01, Op.f64Const)
+      append(body, f64Bytes(g.init))
+    } else {
+      body.push(I32, 0x01, Op.i32Const)
+      sleb(g.init, body)
+    }
+    body.push(Op.end)
+  })
+  section(out, 7, spec.exports, (body, [n, kind, i]) => {
+    name(body, n)
+    body.push(kind)
+    uleb(i, body)
+  })
+  section(out, 10, spec.functions, (body, [, fn]) => {
+    const locals = fn.locals()
+    uleb(locals.length + fn.code.length + 1, body)
+    append(body, locals)
+    append(body, fn.code)
+    body.push(Op.end)
+  })
+  section(out, 11, spec.data, (body, [offset, bytes]) => {
+    body.push(0x00, Op.i32Const)
+    sleb(offset, body)
+    body.push(Op.end)
+    uleb(bytes.length, body)
+    append(body, bytes)
+  })
+  return new Uint8Array(out)
+}

package/src/internal/entries.ts

@@ -6,9 +6,12 @@
 
 import * as Predicate from "effect/Predicate"
 
+type FromEntries = <K extends PropertyKey, V>(entries: Iterable<readonly [K, V]>) => { [P in K]: V }
+
 /** The built-in `Object.fromEntries`, which compiled parsers recognize. */
-export const fromEntries: <K extends PropertyKey, V>(entries: Iterable<readonly [K, V]>) => { [P in K]: V } =
-  Object.fromEntries as any
+// SAFETY: `Object.fromEntries` gives each `[key, value]` entry an own
+// property `key` holding `value`, so entries keyed by `K` build `{ [P in K]: V }`
+export const fromEntries: FromEntries = Object.fromEntries as FromEntries
 
 const objectPrototype = Object.prototype
 
@@ -22,6 +25,9 @@ export const isPlainKey = (key: unknown): key is string =>
   Predicate.isString(key) && !Object.hasOwn(objectPrototype, key)
 
 const define = (o: object, key: unknown, value: unknown): void => {
+  // SAFETY: `Object.defineProperty` converts any key to a property key
+  // (ToPropertyKey), as `Object.fromEntries` does; its `PropertyKey`
+  // parameter type is narrower than what it accepts
   Object.defineProperty(o, key as PropertyKey, { value, writable: true, enumerable: true, configurable: true })
 }
 

package/src/internal/node.ts

@@ -34,6 +34,13 @@ interface Bounds {
  */
 type Enc = Encoding<any> | undefined
 
+/**
+ * A user callback building a value from parser outputs: `map`, `mapOrFail`
+ * (one output), `mapSpan` (an output and its span), `zipWith` and `seqWith`
+ * (one argument per parser).
+ */
+type Mapper = (...values: Array<any>) => unknown
+
 export type Node =
   // Constants
   | { readonly _tag: "Opaque"; readonly step: Step }
@@ -50,7 +57,14 @@ export type Node =
   | { readonly _tag: "Take"; readonly count: number; readonly encoding: Enc }
   | ({ readonly _tag: "TakeWhile"; readonly set: unknown; readonly negate: boolean; readonly encoding: Enc } & Bounds)
   | ({ readonly _tag: "TakeUntil"; readonly literal: Input; readonly encoding: Enc } & Bounds)
+  | ({ readonly _tag: "TakeUntilAny"; readonly literals: ReadonlyArray<Input>; readonly encoding: Enc } & Bounds)
   | { readonly _tag: "Rest"; readonly encoding: Enc }
+  // `Binary`'s fixed-size numbers: `read` reads `size` bytes at an offset of the state's bytes
+  | {
+      readonly _tag: "Fixed"
+      readonly size: number
+      readonly read: (bytes: Uint8Array, offset: number, state: State<Uint8Array>) => unknown
+    }
   | { readonly _tag: "RestLen" }
   | { readonly _tag: "TillLineEnding"; readonly encoding: Enc }
   | { readonly _tag: "Identifier"; readonly encoding: Enc }
@@ -66,11 +80,13 @@ export type Node =
       readonly encoding: Enc
     }
   // Mapping
-  | { readonly _tag: "Map"; readonly self: P; readonly f: (a: any) => unknown }
+  | { readonly _tag: "Map"; readonly self: P; readonly f: Mapper }
   | { readonly _tag: "As"; readonly self: P; readonly value: unknown }
   | { readonly _tag: "Tap"; readonly self: P; readonly f: (a: any) => void }
   | { readonly _tag: "TryMap"; readonly self: P; readonly f: (a: any) => Result.Result<unknown, unknown> }
   | { readonly _tag: "FilterMap"; readonly self: P; readonly f: (a: any) => Option.Option<unknown> }
+  /** `mapOrFail`: `f` returns `Fail` to reject the value. */
+  | { readonly _tag: "MapOrFail"; readonly self: P; readonly f: Mapper }
   | { readonly _tag: "Filter"; readonly self: P; readonly predicate: (a: any) => boolean }
   | { readonly _tag: "FlatMap"; readonly self: P; readonly f: (a: any) => P }
   // Consumed input
@@ -78,10 +94,15 @@ export type Node =
   | { readonly _tag: "WithTaken"; readonly self: P }
   | { readonly _tag: "Span"; readonly self: P }
   | { readonly _tag: "WithSpan"; readonly self: P }
+  /** `mapSpan`: `f(output, start, end)`. */
+  | { readonly _tag: "MapSpan"; readonly self: P; readonly f: Mapper }
+  /** `withFastPath`: `fast` runs first in compiled code; `Defer` runs `self`. */
+  | { readonly _tag: "FastPath"; readonly self: P; readonly fast: Step }
   // Errors
   | { readonly _tag: "Mode"; readonly self: P; readonly from: ErrMode; readonly to: ErrMode }
   | { readonly _tag: "Context"; readonly self: P; readonly label: string }
   | { readonly _tag: "Expected"; readonly self: P; readonly description: string }
+  | { readonly _tag: "Quiet"; readonly self: P }
   | { readonly _tag: "MapError"; readonly self: P }
   | { readonly _tag: "OrFail"; readonly self: P }
   // Control
@@ -97,7 +118,9 @@ export type Node =
       readonly output: "tuple" | number | readonly [number, number]
     }
   | { readonly _tag: "Struct"; readonly keys: ReadonlyArray<string>; readonly parsers: ReadonlyArray<P> }
-  | { readonly _tag: "ZipWith"; readonly self: P; readonly that: P; readonly f: (a: any, b: any) => unknown }
+  | { readonly _tag: "ZipWith"; readonly self: P; readonly that: P; readonly f: Mapper }
+  /** `seqWith`: `f` receives one output per parser. */
+  | { readonly _tag: "SeqWith"; readonly parsers: ReadonlyArray<P>; readonly f: Mapper }
   // Choice
   | { readonly _tag: "Alt"; readonly parsers: ReadonlyArray<P> }
   | {
@@ -128,6 +151,17 @@ export type Node =
       readonly op: (l: any, s: any, r: any) => unknown
       readonly right: boolean
     }
+  /**
+   * A combinator whose algorithm the compilers don't know (`Expression.make`,
+   * `permutation`): `build` makes its step from the steps of `parsers`. The
+   * interpreter passes their own steps; the closure compiler (and the JIT,
+   * through it) passes their compiled steps, so the parsers inside compile.
+   */
+  | {
+      readonly _tag: "Combinator"
+      readonly parsers: ReadonlyArray<P>
+      readonly build: (steps: ReadonlyArray<Step>) => Step
+    }
   // Services, recovery, debugging
   | { readonly _tag: "Service" }
   | { readonly _tag: "Provide"; readonly self: P }
@@ -147,19 +181,75 @@ export type Tag = Node["_tag"]
 
 export type NodeOf<T extends Tag> = Extract<Node, { readonly _tag: T }>
 
+/** What a fast path returns to leave the input to its grammar (`Parser.Defer`). */
+export const Defer: unique symbol = /*#__PURE__*/ Symbol.for("effect-parse/Parser/Defer")
+
 /** Where a parser's description is stored. */
 export const NodeId: unique symbol = /*#__PURE__*/ Symbol.for("effect-parse/Parser/node")
 
+/** The description recorded for a parser, if it has one. */
+export const describedNode = (p: ParserLike): Node | undefined =>
+  // SAFETY: `Parser.described` stores a parser's `Node` under `NodeId`;
+  // reading it from any other parser (or one built by `Parser.make`, which
+  // stores `undefined`) yields `undefined`
+  (p as ParserLike & { readonly [NodeId]?: Node })[NodeId]
+
 /** The description of a parser: `Opaque` when it has none. */
-export const nodeOf = (p: ParserLike): Node => (p as any)[NodeId] ?? { _tag: "Opaque", step: p.step }
+export const nodeOf = (p: ParserLike): Node => describedNode(p) ?? { _tag: "Opaque", step: p.step }
+
+/** How a rejected argument reads in an error: never the argument's own text. */
+const describeArgument = (u: unknown): string =>
+  Predicate.isNumber(u) || Predicate.isBigInt(u) || u === undefined || u === null
+    ? String(u)
+    : Predicate.isString(u)
+      ? "a string"
+      : "a value that is not a number"
 
-/** Normalizes a range, as `repeat`, `takeWhile`, ... do. */
+/**
+ * `count` as given, which must be a non-negative safe integer, else a
+ * `RangeError`. A count is a `number` only in the types, and each backend
+ * read a negative, fractional, `NaN` or non-number count its own way: the
+ * interpreter moved the cursor backwards, and the JIT wrote the value into
+ * the source it compiles.
+ */
+export const checkCount = (count: number, what: string = "count"): number => {
+  if (!Number.isSafeInteger(count) || count < 0)
+    throw new RangeError(`invalid ${what}: expected a non-negative integer, got ${describeArgument(count)}`)
+  return count
+}
+
+/**
+ * Normalizes a range, as `repeat`, `takeWhile`, ... do. Throws a
+ * `RangeError` unless both bounds are non-negative integers (`max` may be
+ * `Infinity`) with `min <= max` (see {@link checkCount}).
+ */
 export const bounds = (
   range: number | { readonly min?: number | undefined; readonly max?: number | undefined } | undefined
 ): Bounds => {
   if (range === undefined) return { min: 0, max: Infinity }
-  if (Predicate.isNumber(range)) return { min: range, max: range }
-  return { min: range.min ?? 0, max: range.max ?? Infinity }
+  if (!Predicate.isObject(range)) {
+    const count = checkCount(range)
+    return { min: count, max: count }
+  }
+  const min = checkCount(range.min ?? 0, "range: min")
+  const max = range.max ?? Infinity
+  if (max !== Infinity) checkCount(max, "range: max")
+  if (min > max) throw new RangeError(`invalid range: min (${min}) > max (${max})`)
+  return { min, max }
+}
+
+/**
+ * The code of a control character given as a one-character string or a
+ * code: a non-negative integer, else a `RangeError` (it is compared with
+ * input units, and the JIT writes it into the source it compiles).
+ */
+export const controlCode = (control: string | number, read: (s: string) => number): number => {
+  const code = Predicate.isString(control) ? read(control) : control
+  if (!Number.isSafeInteger(code) || code < 0)
+    throw new RangeError(
+      `invalid control character: expected a character or its code, got ${describeArgument(control)}`
+    )
+  return code
 }
 
 /**
@@ -187,15 +277,19 @@ export const children = (node: Node): ReadonlyArray<P> => {
     case "Tap":
     case "TryMap":
     case "FilterMap":
+    case "MapOrFail":
     case "Filter":
     case "FlatMap":
     case "Taken":
     case "WithTaken":
     case "Span":
     case "WithSpan":
+    case "MapSpan":
     case "Mode":
     case "Context":
     case "Expected":
+    case "Quiet":
+    case "FastPath":
     case "MapError":
     case "OrFail":
     case "Opt":
@@ -213,14 +307,16 @@ export const children = (node: Node): ReadonlyArray<P> => {
       return [node.self, node.recover]
     case "Seq":
     case "Struct":
+    case "SeqWith":
     case "Alt":
+    case "Combinator":
       return node.parsers
     case "ZipWith":
       return [node.self, node.that]
     case "Dispatch": {
       const out: Array<P> = [node.selector]
       if (node.cases !== undefined) {
-        for (const key of Reflect.ownKeys(node.cases)) out.push(node.cases[key as any])
+        for (const key of Reflect.ownKeys(node.cases)) out.push(node.cases[key])
       }
       if (node.otherwise !== undefined) out.push(node.otherwise)
       return out