@thomasfosterau/effect-parse 0.4.0 → 0.5.0

package/src/ParserSchema.ts

@@ -431,7 +431,7 @@ const isAnnotated = (ast: SchemaAST.AST): boolean => lookup(ast, annotationKey)
 
 const withStop = <T>(ctx: Context<T>, text: string | undefined): Context<T> => {
   if (text === undefined || text === "" || ctx.stop.includes(text[0])) return ctx
-  return { ...ctx, stop: Arr.sort([...ctx.stop, text[0]], Order.String).join("") }
+  return { ...ctx, stop: Arr.sort([...ctx.stop.split(""), text[0]], Order.String).join("") }
 }
 
 const at = <T>(ctx: Context<T>, key: PropertyKey): Context<T> => ({

package/src/ParserStream.ts

@@ -47,19 +47,31 @@ import type { Parser } from "./Parser.js"
  */
 export type Chunkable = string | Uint8Array | ReadonlyArray<unknown>
 
-const concat = <I extends Chunkable>(a: I, b: I): I => {
-  if (Predicate.isString(a)) return (a + (b as string)) as I
+const concat = <I extends Chunkable>(first: I, b: I): I => {
+  // Widened so the checks below narrow it (a type parameter does not narrow).
+  const a: Chunkable = first
+  if (Predicate.isString(a)) {
+    // SAFETY: both are chunks of one stream of `I`, so `b` is a string when `a` is, and so is their concatenation
+    return (a + (b as string)) as I
+  }
   if (a instanceof Uint8Array) {
     if (a.byteLength === 0) return b
+    // SAFETY: both are chunks of one stream of `I`, so `b` is a `Uint8Array` when `a` is
     const out = new Uint8Array(a.length + (b as Uint8Array).length)
     out.set(a)
+    // SAFETY: both are chunks of one stream of `I`, so `b` is a `Uint8Array` when `a` is
     out.set(b as Uint8Array, a.length)
+    // SAFETY: `I` is `a`'s type, a `Uint8Array` here, and `out` is a new `Uint8Array`
     return out as I
   }
-  return [...a, ...(b as ReadonlyArray<unknown>)] as unknown as I
+  // SAFETY: both are chunks of one stream of `I`, so `b` is an array when `a` is
+  const joined: Chunkable = [...a, ...(b as ReadonlyArray<unknown>)]
+  // SAFETY: `I` is `a`'s type, an array here, and `joined` is a new array of both chunks' elements
+  return joined as I
 }
 
 const sliceFrom = <I extends Chunkable>(input: I, offset: number): I =>
+  // SAFETY: slicing a string, `Uint8Array` or array returns a value of the same kind
   (Predicate.isString(input) ? input.slice(offset) : input.slice(offset)) as I
 
 const noProgress = (input: Input, offset: number) =>
@@ -90,8 +102,9 @@ export interface ParseManyOptions<I> {
  *
  * A parser compiled with the `Compiler` module runs compiled, with the
  * build that handles partial input (see `Parser.run`); a value that fails
- * or needs more input is parsed again interpreted, so errors and
- * `Incomplete` are the interpreter's.
+ * is parsed again interpreted, so errors are the interpreter's. A value
+ * cut short by its chunk is not: compiled code reports `Incomplete` where
+ * the interpreter does.
  *
  * @since 0.1.0
  * @category combinators
@@ -126,9 +139,12 @@ export const parseMany: {
         let offset = 0
         while (offset < input.length) {
           state.reset(offset, { partial, context })
-          const a = Run.runOn(parser, step, state)
+          // A compiled `Incomplete` is the interpreter's: only an error needs the interpreted run
+          const a = Run.runOn(parser, step, state, false)
           if (a === Fail) {
             if (partial && state.mode === "Incomplete") break
+            state.reset(offset, { partial, context })
+            Run.runOn(parser, step, state)
             return Effect.fail(ParseError.fromFailure<E>(input, state.reportedFailure(), state.mode, state.encoding))
           }
           if (state.pos === offset) return Effect.fail(noProgress(input, offset))
@@ -211,15 +227,19 @@ class Incremental<A, E, I extends Chunkable> {
   }
 
   private input(): I {
-    switch (this.kind) {
-      case 1:
-        return this.bytes.subarray(0, this.length) as I
-      case 2:
-        // Items are only appended between attempts, after each state has read its `end`
-        return this.items as unknown as I
-      default:
-        return this.text as I
+    if (this.kind === 1) {
+      // SAFETY: `kind` 1 is set by the first chunk being a `Uint8Array`, so `I` is `Uint8Array`
+      return this.bytes.subarray(0, this.length) as I
+    }
+    if (this.kind === 2) {
+      // Items are only appended between attempts, after each state has read its `end`
+      const items: Chunkable = this.items
+      // SAFETY: `kind` 2 is set by the first chunk being an array, so `I` is an array of the items' type
+      return items as I
     }
+    // SAFETY: `kind` 0 means the first chunk was a string, so `I` is `string`; while `kind` is unset (no
+    // chunk arrived) `I` is unknown and the empty string stands for the empty input
+    return this.text as I
   }
 
   push(chunk: I): void {
@@ -245,8 +265,9 @@ class Incremental<A, E, I extends Chunkable> {
    * The step attempts run: the parser's compiled code if it was compiled
    * (the resumable build, unless `resumable` is false), else the interpreter.
    */
-  private step(state: State<I>, resumable = true): unknown {
-    return Stack.run(Registry.stepFor(this.parser, state, resumable) ?? this.parser.step, state)
+  private step(state: State<I>, resumable = true): A | Fail {
+    // SAFETY: a compiled step (typed `any` by the compilers) returns what the parser's own step returns
+    return Stack.run(Registry.stepFor(this.parser, state, resumable) ?? this.parser.step, state) as A | Fail
   }
 
   private attempt(): void {
@@ -255,7 +276,7 @@ class Incremental<A, E, I extends Chunkable> {
     const a = this.step(state)
     this.attempted = this.length
     if (a !== Fail) {
-      this.settled = { value: a as A, pos: state.pos }
+      this.settled = { value: a, pos: state.pos }
     } else if (state.mode === "Incomplete") {
       this.restart = state.failure.offset
     } else {
@@ -274,7 +295,7 @@ class Incremental<A, E, I extends Chunkable> {
       const resumable = this.attempted > 0
       if (resumable) state.resume = this.resume
       const a = this.step(state, resumable)
-      if (a !== Fail && state.pos === state.end) return Effect.succeed(a as A)
+      if (a !== Fail && state.pos === state.end) return Effect.succeed(a)
     }
     // The error comes from an ordinary parse of the whole input, so it is the
     // same as if the input had been parsed in one go
@@ -329,7 +350,7 @@ export const parseAll: {
     Effect.flatMap(Effect.context<R>(), (context) =>
       Effect.suspend(() => {
         const empty = options?.empty === undefined ? undefined : fromSource<I>(options.empty)
-        const incremental = new Incremental(parser, context as Context.Context<never>, empty)
+        const incremental = new Incremental(parser, context, empty)
         return Effect.flatMap(
           Stream.runForEach(self, (chunk) => Effect.sync(() => incremental.push(fromSource<I>(chunk)))),
           () => Effect.suspend(() => incremental.finish())

package/src/Syntax.ts

@@ -66,11 +66,15 @@ import { described, isParser } from "./Parser.js"
 // Grammar annotations
 // -----------------------------------------------------------------------------
 
-const syntaxNode = (self: Parser.Any, kind: string, named: boolean): Parser.Any => {
+const syntaxNode = <A, E, R, I extends Input>(
+  self: Parser<A, E, R, I>,
+  kind: string,
+  named: boolean
+): Parser<A, E, R, I> => {
   const step = self.step
   // Identifies the nodes this parser builds, so a reparse can reuse them
   const key = new Key()
-  return described<unknown, unknown, unknown, Input>(
+  return described<A, E, R, I>(
     (state) => {
       const builder = state.syntax
       return builder === undefined ? step(state) : builder.node(state, step, key, kind, named)
@@ -101,10 +105,8 @@ const syntaxNode = (self: Parser.Any, kind: string, named: boolean): Parser.Any
 export const node: {
   (kind: 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>, kind: string): Parser<A, E, R, I>
-} = /*#__PURE__*/ dual(
-  2,
-  <A, E, R, I extends Input>(self: Parser<A, E, R, I>, kind: string): Parser<A, E, R, I> =>
-    syntaxNode(self, kind, true) as Parser<A, E, R, I>
+} = /*#__PURE__*/ dual(2, <A, E, R, I extends Input>(self: Parser<A, E, R, I>, kind: string): Parser<A, E, R, I> =>
+  syntaxNode(self, kind, true)
 )
 
 /**
@@ -130,7 +132,7 @@ export const token: {
 } = /*#__PURE__*/ dual(
   (args) => isParser(args[0]),
   <A, E, R, I extends Input>(self: Parser<A, E, R, I>, kind?: string): Parser<A, E, R, I> =>
-    syntaxNode(self, kind ?? defaultTokenKind(self), false) as Parser<A, E, R, I>
+    syntaxNode(self, kind ?? defaultTokenKind(self), false)
 )
 
 const defaultTokenKind = (self: Parser.Any): string => {
@@ -168,7 +170,7 @@ export const field: {
   return described<A, E, R, I>(
     (state) => {
       const builder = state.syntax
-      return (builder === undefined ? step(state) : builder.field(state, step, name)) as A | typeof Fail
+      return builder === undefined ? step(state) : builder.field(state, step, name)
     },
     self.name,
     { _tag: "Syntax", self, kind: undefined, named: false }
@@ -346,6 +348,18 @@ export class Tree<out A, out E = never, I extends Input = string> {
   }
 }
 
+/**
+ * What `JSON.stringify` writes for a {@link SyntaxNode}: its kind and span.
+ *
+ * @since 0.5.0
+ * @category models
+ */
+export interface SyntaxNodeJson {
+  readonly kind: string
+  readonly start: number
+  readonly end: number
+}
+
 /**
  * A node of a syntax tree: its kind, span and value, and its place in the
  * tree. Nodes are views built on demand; two views of the same node are
@@ -403,10 +417,11 @@ export class SyntaxNode<I extends Input = string> {
 
   /** The input the node spans. */
   get text(): Slice<I> {
-    const input = this.tree.input as any
-    return input instanceof Uint8Array
-      ? (input.subarray(this.start, this.end) as any)
-      : input.slice(this.start, this.end)
+    const input: Input = this.tree.input
+    // SAFETY: a `subarray` of a `Uint8Array`, or a `slice` of a string or array, has the input's own kind, `Slice<I>`
+    return (
+      input instanceof Uint8Array ? input.subarray(this.start, this.end) : input.slice(this.start, this.end)
+    ) as Slice<I>
   }
 
   /** Whether this is an `ERROR` node. */
@@ -592,7 +607,7 @@ export class SyntaxNode<I extends Input = string> {
     return out
   }
 
-  toJSON(): unknown {
+  toJSON(): SyntaxNodeJson {
     return { kind: this.kind, start: this.start, end: this.end }
   }
 
@@ -723,6 +738,8 @@ const run = <A, E, I extends Input>(config: Config, input: I, previous: Previous
     state.backtrack("Eof", expectedEof)
     fatal = { failure: state.reportedFailure(), mode: "Backtrack" }
   } else {
+    // SAFETY: `config.inner` is the `Parser<A, ...>` given to `parse` or the parser its root `node` wraps, which returns
+    // the same `A` (a `reparse` reuses the tree's config)
     value = Option.some(a as A)
   }
   const green = builder.finish(config.kind, Option.getOrUndefined(value), fatal, state.pos)
@@ -730,19 +747,12 @@ const run = <A, E, I extends Input>(config: Config, input: I, previous: Previous
 }
 
 /**
- * Parses an input into a syntax {@link Tree}. The grammar's output is the
- * tree's `value`, and its {@link node}s are the tree's nodes. When the
- * grammar is itself a {@link node}, that node is the root; otherwise the
- * root is a node of kind `options.kind` (by default `"document"`).
- *
- * The parse never fails: recovered failures (see `Parser.resumeAfter`), a
- * fatal failure and unparsed input at the end all become `ERROR` nodes, and
- * are listed in `tree.errors`. The parse is interpreted, never compiled.
+ * The overloads of {@link parse}.
  *
- * @since 0.2.0
+ * @since 0.5.0
  * @category parsing
  */
-export const parse: {
+export interface ParseFn {
   <A, E, I extends Input>(
     grammar: Parser<A, E, never, I>,
     input: NoInfer<Source<I>>,
@@ -753,7 +763,22 @@ export const parse: {
     input: NoInfer<Source<I>>,
     options: ParseOptionsWithContext<R>
   ): Tree<A, E, I>
-} = <A, E, R, I extends Input>(
+}
+
+/**
+ * Parses an input into a syntax {@link Tree}. The grammar's output is the
+ * tree's `value`, and its {@link node}s are the tree's nodes. When the
+ * grammar is itself a {@link node}, that node is the root; otherwise the
+ * root is a node of kind `options.kind` (by default `"document"`).
+ *
+ * The parse never fails: recovered failures (see `Parser.resumeAfter`), a
+ * fatal failure and unparsed input at the end all become `ERROR` nodes, and
+ * are listed in `tree.errors`. The parse is interpreted, never compiled.
+ *
+ * @since 0.2.0
+ * @category parsing
+ */
+export const parse: ParseFn = <A, E, R, I extends Input>(
   grammar: Parser<A, E, R, I>,
   input: I | Source<I>,
   options?: ParseOptions & { readonly context?: Context.Context<R> }
@@ -762,11 +787,12 @@ export const parse: {
   const isRoot = Predicate.isTagged(n, "Syntax") && n.kind !== undefined && n.named
   const config: Config = {
     kind: isRoot ? n.kind : (options?.kind ?? "document"),
+    // SAFETY: a `Syntax` node's `self` is the parser that `node` wrapped, a parser built by this library
     inner: isRoot ? (n.self as Parser.Any) : grammar,
     lookahead: options?.lookahead ?? 0,
-    context: options?.context as Context.Context<never> | undefined
+    context: options?.context
   }
-  return run(config, fromSource(input as Input) as I, undefined)
+  return run(config, fromSource<I>(input), undefined)
 }
 
 /**
@@ -803,13 +829,8 @@ export const reparse = <A, E, I extends Input>(
   input: NoInfer<Source<I>>,
   edits?: Edit | ReadonlyArray<Edit>
 ): Tree<A, E, I> => {
-  const next = fromSource(input as Input) as I
-  const list =
-    edits === undefined
-      ? diffList(tree.input, next)
-      : "start" in edits
-        ? [edits as Edit]
-        : (edits as ReadonlyArray<Edit>)
+  const next = fromSource<I>(input)
+  const list = edits === undefined ? diffList(tree.input, next) : "start" in edits ? [edits] : edits
   const previous: Previous = {
     root: tree.green,
     oldLength: tree.input.length,
@@ -854,9 +875,12 @@ export const replace = <A, E>(
  * @category parsing
  */
 export const diff = <I extends Input>(before: I, after: I): Edit | undefined => {
-  const a = before as any
-  const b = after as any
-  const at = Predicate.isString(a) ? (s: string, i: number) => s.charCodeAt(i) : (s: any, i: number) => s[i]
+  const a: Input = before
+  const b: Input = after
+  // SAFETY: the string reader is chosen only when `a` is a string, and `b` has the same type `I`
+  const at = Predicate.isString(a)
+    ? (s: Input, i: number) => (s as string).charCodeAt(i)
+    : (s: Input, i: number) => s[i]
   const max = Math.min(a.length, b.length)
   let prefix = 0
   while (prefix < max && at(a, prefix) === at(b, prefix)) prefix++

package/src/Text.ts

@@ -39,7 +39,7 @@
 import * as Predicate from "effect/Predicate"
 import type { Encoding } from "./Encoding.js"
 import * as Encodings from "./Encoding.js"
-import type { Input, State } from "./Input.js"
+import type { State } from "./Input.js"
 import { Fail } from "./Input.js"
 import { escapedImpl, overflow, takeEscapedImpl, toFloat } from "./Ascii.js"
 import { codePointPredicate, compile, indexOf, matchLiteral } from "./internal/tokens.js"
@@ -392,7 +392,7 @@ const expectedIdentifier = ["identifier"]
  * @category constructors
  */
 export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): TextParsers<I> => {
-  const enc = encoding as Encoding<any>
+  const enc = encoding
   const fast = internal.fastLimit(enc)
 
   // Each parser records its encoding on byte input (`state.encoding`), so
@@ -410,7 +410,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
   ): string | Fail => {
     const count = internal.validate(enc, state, start, end)
     if (count < 0) return backtrack(state, kind, expected, -1 - count)
-    return enc.text(state.input, start, end)
+    return internal.textIn(enc, state, start, end)
   }
 
   const takeWhileText = (
@@ -438,7 +438,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
         // More matching characters would have been accepted where we stopped
         if (hint && count < max) state.setHint(offset, expected)
         state.pos = offset
-        return enc.text(state.input, start, offset)
+        return internal.textIn(enc, state, start, offset)
       },
       name,
       { _tag: "TakeWhile", set, negate, min, max, encoding: enc }
@@ -471,6 +471,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
           if (state.inputKind === 1) state.encoding = enc
           if (pos >= state.end) return state.eoi("Literal", expected, 1)
           const input = state.input
+          // SAFETY: a `Text` parser runs on strings or `Uint8Array`s, and `inputKind` 0 is set only for a string
           if ((state.inputKind === 0 ? (input as string).charCodeAt(pos) : (input as Uint8Array)[pos]) !== unit) {
             return backtrack(state, "Literal", expected)
           }
@@ -518,7 +519,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
           pos += internal.width
         }
         state.pos = pos
-        return enc.text(state.input, start, pos)
+        return internal.textIn(enc, state, start, pos)
       },
       expected[0],
       { _tag: "Literal", literal: lit, caseless: true, encoding: enc }
@@ -559,7 +560,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
           pos += internal.width
         }
         state.pos = pos
-        return enc.text(state.input, start, pos)
+        return internal.textIn(enc, state, start, pos)
       },
       "take",
       { _tag: "Take", count, encoding: enc }
@@ -575,9 +576,9 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
       (state: State<any>) => {
         if (state.inputKind === 1) state.encoding = enc
         const start = state.pos
-        let idx = indexOf(state, needle as Input, start)
+        let idx = indexOf(state, needle, start)
         // Multi-unit encodings: only accept matches on a character boundary
-        while (unit > 1 && idx >= 0 && (idx - start) % unit !== 0) idx = indexOf(state, needle as Input, idx + 1)
+        while (unit > 1 && idx >= 0 && (idx - start) % unit !== 0) idx = indexOf(state, needle, idx + 1)
         if (idx < 0) {
           if (state.partial) return state.incomplete(0, expected)
           return backtrack(state, "TakeUntil", expected, state.end)
@@ -590,7 +591,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
         if (count < min) return backtrack(state, "TakeUntil", expected, idx)
         if (count > max) return backtrack(state, "TakeUntil", expected)
         state.pos = idx
-        return enc.text(state.input, start, idx)
+        return internal.textIn(enc, state, start, idx)
       },
       "takeUntil",
       { _tag: "TakeUntil", literal: lit, min, max, encoding: enc }
@@ -607,7 +608,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
       if (internal.scanStop === internal.Truncated) return state.incomplete(1, expectedAny)
       if (internal.scanStop === internal.Invalid) return backtrack(state, "Token", expectedAny, offset)
       state.pos = offset
-      return enc.text(state.input, start, offset)
+      return internal.textIn(enc, state, start, offset)
     },
     "rest",
     { _tag: "Rest", encoding: enc }
@@ -628,7 +629,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
   }
 
   const cls = (test: CharPredicate, min: 0 | 1, description: string, kind: ErrorKind, hint = true) =>
-    takeWhileText(test as any, { min }, false, `${kind.toLowerCase()}${min}`, [description], kind, hint)
+    takeWhileText(test, { min }, false, `${kind.toLowerCase()}${min}`, [description], kind, hint)
 
   const identifierStart = (cp: number) => cp === 95 || isIdStart(cp)
   const identifier: Parser<string, never, never, I> = P.described<string, never, never, I>(
@@ -638,13 +639,13 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
       const cp = internal.next(enc, state)
       if (cp < 0) return internal.failAt(state, cp, "TakeWhile", expectedIdentifier)
       if (!identifierStart(cp)) return state.backtrack("TakeWhile", expectedIdentifier)
-      internal.scan(enc, state, isIdContinue as any, false, Infinity, start + internal.width, fast)
+      internal.scan(enc, state, isIdContinue, false, Infinity, start + internal.width, fast)
       const stop = internal.scanStop
       if (state.partial && (stop === internal.End || stop === internal.Truncated)) {
         return state.incomplete(1, expectedIdentifier)
       }
       state.pos = internal.scanOffset
-      return enc.text(state.input, start, state.pos)
+      return internal.textIn(enc, state, start, state.pos)
     },
     "identifier",
     { _tag: "Identifier", encoding: enc }
@@ -691,7 +692,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
         if (after !== 10) return backtrack(state, "LineEnding", expectedLineEnding, offset)
       }
       state.pos = offset
-      return enc.text(state.input, start, offset)
+      return internal.textIn(enc, state, start, offset)
     },
     "tillLineEnding",
     { _tag: "TillLineEnding", encoding: enc }
@@ -783,7 +784,7 @@ export const make = <I extends string | Uint8Array>(encoding: Encoding<I>): Text
         normal,
         matchControl(control),
         escapable,
-        (state, start) => enc.text(state.input, start, state.pos),
+        (state, start) => internal.textIn(enc, state, start, state.pos),
         internal.firstCodePoint(control),
         enc
       ),