@tabnas/transduce 0.1.0 → 0.1.2

package/src/matcher.ts

@@ -0,0 +1,287 @@
+/* Copyright (c) 2026 tabnas, MIT License */
+
+// Shared-prefix matching of many selectors in one pass.
+//
+// The router has to recognize every capture's selector over one event
+// stream, and a document can be hundreds of megabytes, so the matcher
+// never spells out a path per event: the selectors are compiled into one
+// trie of steps, and the matcher walks the document with a stack of open
+// containers (a level per container: its kind, how many values it has
+// started, the current member's key) and, per level, the trie nodes that
+// named that container, kept on one flat stack.
+//
+// The matcher also validates the protocol as it goes, because it holds the
+// state that makes a malformed stream visible (a key outside an object, an
+// array ending an object, a value after the root). Every stage downstream
+// of it can therefore trust the sequence. A concrete `Path` is built only
+// on request, for a delivered match or a failure.
+
+import { Fail } from './error'
+import { JsonEvent } from './event'
+import { Path, Segment, Selector } from './selector'
+
+// Which selector matched: its position in the list given to the matcher.
+export type CaptureId = number
+
+const ROOT = 0
+
+// One trie node: the selectors' next steps below one position.
+type Node = {
+  properties: Map<string, number>
+  indexes: Map<number, number>
+  eachIndex: number
+  eachMember: number
+  // The selectors that end here, in id order.
+  terminals: CaptureId[]
+}
+
+function newNode(): Node {
+  return {
+    properties: new Map(),
+    indexes: new Map(),
+    eachIndex: -1,
+    eachMember: -1,
+    terminals: [],
+  }
+}
+
+// One open container.
+type Level = {
+  array: boolean
+  // Values started in this container so far; the current or last one is
+  // at index `started - 1`.
+  started: number
+  // The current member's key, for objects.
+  key: string
+  // Between a key and its value.
+  inValue: boolean
+  // The trie nodes that named this container: `nodeStack[start..end]`.
+  start: number
+  end: number
+}
+
+// What one event did to the document's structure: a member name (`key`),
+// a container began (`start`), a whole scalar (`scalar`), a container
+// completed (`close`), the document completed (`end`).
+export type HitKind = 'key' | 'start' | 'scalar' | 'close' | 'end'
+
+// The matcher's answer for one event.
+export type Hit = {
+  kind: HitKind
+  // How many captures begin with this event: their ids are
+  // `Matcher.begins()`, valid until the next event.
+  begins: number
+  // For `start` and `scalar`, the number of containers enclosing the
+  // value; for `close`, the number enclosing the container that closed.
+  depth: number
+}
+
+// Recognizes every selector of a set over one event stream.
+export class Matcher {
+  private nodes: Node[] = [newNode()]
+  private levels: Level[] = []
+  private open = 0
+  private nodeStack: number[] = []
+  private begun: CaptureId[] = []
+  private rootDone = false
+  private isEnded = false
+
+  // Compile the selectors; their positions are the capture ids.
+  constructor(selectors: readonly Selector[]) {
+    selectors.forEach((selector, id) => {
+      let at = ROOT
+      for (const step of selector.steps) {
+        const node = this.nodes[at]
+        let next: number | undefined
+        switch (step.type) {
+          case 'property':
+            next = node.properties.get(step.name)
+            break
+          case 'index':
+            next = node.indexes.get(step.index)
+            break
+          case 'each_index':
+            next = node.eachIndex < 0 ? undefined : node.eachIndex
+            break
+          case 'each_member':
+            next = node.eachMember < 0 ? undefined : node.eachMember
+            break
+        }
+        if (undefined === next) {
+          next = this.nodes.length
+          this.nodes.push(newNode())
+          switch (step.type) {
+            case 'property':
+              node.properties.set(step.name, next)
+              break
+            case 'index':
+              node.indexes.set(step.index, next)
+              break
+            case 'each_index':
+              node.eachIndex = next
+              break
+            case 'each_member':
+              node.eachMember = next
+              break
+          }
+        }
+        at = next
+      }
+      this.nodes[at].terminals.push(id)
+    })
+  }
+
+  // Open containers right now.
+  depth(): number {
+    return this.open
+  }
+
+  // Whether `end` has been seen.
+  ended(): boolean {
+    return this.isEnded
+  }
+
+  // The concrete path of the value at `depth` enclosing containers. Asked
+  // at a `start` or `scalar` hit it names the value; asked at a `close`
+  // hit it names the container that closed.
+  path(depth: number): Path {
+    const segments: Segment[] = []
+    const n = Math.min(depth, this.open)
+    for (let i = 0; i < n; i++) {
+      const level = this.levels[i]
+      segments.push(level.array ? Math.max(0, level.started - 1) : level.key)
+    }
+    return new Path(segments)
+  }
+
+  // The captures that began with the last event, in id order.
+  begins(): readonly CaptureId[] {
+    return this.begun
+  }
+
+  // One event. A malformed sequence is a `PROTOCOL_ORDER_ERROR`.
+  event(ev: JsonEvent): Hit {
+    if (this.isEnded) {
+      throw Fail.protocol('an event arrived after the document ended')
+    }
+    switch (ev.type) {
+      case 'key': {
+        const level = 0 < this.open ? this.levels[this.open - 1] : undefined
+        if (undefined === level || level.array) {
+          throw Fail.protocol('a key arrived outside an object')
+        }
+        if (level.inValue) {
+          throw Fail.protocol('a key arrived where a value was expected')
+        }
+        level.key = ev.key
+        level.inValue = true
+        this.begun.length = 0
+        return { kind: 'key', begins: 0, depth: this.open }
+      }
+      case 'object_start':
+      case 'array_start': {
+        const depth = this.open
+        const start = this.beginValue()
+        const end = this.nodeStack.length
+        const array = 'array_start' === ev.type
+        const level: Level = {
+          array,
+          started: 0,
+          key: '',
+          inValue: false,
+          start,
+          end,
+        }
+        if (depth === this.levels.length) this.levels.push(level)
+        else this.levels[depth] = level
+        this.open++
+        return { kind: 'start', begins: this.begun.length, depth }
+      }
+      case 'object_end':
+      case 'array_end': {
+        const wantArray = 'array_end' === ev.type
+        const level = 0 < this.open ? this.levels[this.open - 1] : undefined
+        if (undefined === level) {
+          throw Fail.protocol('a container ended that had not started')
+        }
+        if (level.array !== wantArray) {
+          throw Fail.protocol(
+            wantArray ? 'an array ended inside an object' : 'an object ended inside an array',
+          )
+        }
+        if (level.inValue) {
+          throw Fail.protocol('an object ended after a key without its value')
+        }
+        this.open--
+        this.nodeStack.length = level.start
+        this.completeValue()
+        this.begun.length = 0
+        return { kind: 'close', begins: 0, depth: this.open }
+      }
+      case 'end':
+        if (0 < this.open) {
+          throw Fail.protocol('the document ended inside a container')
+        }
+        if (!this.rootDone) {
+          throw Fail.protocol('the document ended before its root value')
+        }
+        this.isEnded = true
+        this.begun.length = 0
+        return { kind: 'end', begins: 0, depth: 0 }
+      default: {
+        const depth = this.open
+        const start = this.beginValue()
+        this.nodeStack.length = start
+        this.completeValue()
+        return { kind: 'scalar', begins: this.begun.length, depth }
+      }
+    }
+  }
+
+  // A value begins at the current position: check that one is allowed
+  // here, push the trie nodes naming it onto the node stack, and fill
+  // `begun`. Returns where on the node stack the value's nodes start.
+  private beginValue(): number {
+    let base: number
+    if (0 === this.open) {
+      if (this.rootDone) throw Fail.protocol('a second root value arrived')
+      this.nodeStack.length = 0
+      this.nodeStack.push(ROOT)
+      base = 0
+    } else {
+      const level = this.levels[this.open - 1]
+      if (!level.array && !level.inValue) {
+        throw Fail.protocol('a value arrived inside an object without a key')
+      }
+      const index = level.started
+      level.started++
+      this.nodeStack.length = level.end
+      for (let at = level.start; at < level.end; at++) {
+        const node = this.nodes[this.nodeStack[at]]
+        if (level.array) {
+          if (0 <= node.eachIndex) this.nodeStack.push(node.eachIndex)
+          const c = node.indexes.get(index)
+          if (undefined !== c) this.nodeStack.push(c)
+        } else {
+          if (0 <= node.eachMember) this.nodeStack.push(node.eachMember)
+          const c = node.properties.get(level.key)
+          if (undefined !== c) this.nodeStack.push(c)
+        }
+      }
+      base = level.end
+    }
+    this.begun.length = 0
+    for (let i = base; i < this.nodeStack.length; i++) {
+      const terminals = this.nodes[this.nodeStack[i]].terminals
+      for (const t of terminals) this.begun.push(t)
+    }
+    if (this.begun.length > 1) this.begun.sort((a, b) => a - b)
+    return base
+  }
+
+  // The value at the current position is complete.
+  private completeValue(): void {
+    if (0 === this.open) this.rootDone = true
+    else this.levels[this.open - 1].inValue = false
+  }
+}

package/src/parser-source.ts

@@ -0,0 +1,225 @@
+/* Copyright (c) 2026 tabnas, MIT License */
+
+// `ParserSource`: `JsonEvents/1` from a tabnas parse of one text.
+//
+// Two modes. `materialize` parses, then walks the value: always sound, and
+// retains the whole value. `incremental` installs the rule-event adapter
+// so events leave the parse as containers open and entries land, and
+// optionally prunes streamed array elements from the engine's tree. It is
+// sound for the grammars `capability.incremental` lists, which the
+// differential suite verifies in this runtime, and for no other: an
+// imperative grammar's rule events give a well-formed stream of the wrong
+// shape or a malformed one, and the run would still return. So the
+// incremental path is gated on the list, by the grammar's name, which the
+// source cannot learn from the `Tabnas` and so must be told (`grammar`);
+// without a listed name it fails with `STREAMABILITY_UNKNOWN` before the
+// parse, having emitted nothing. `unverified()` lifts the gate for the
+// differential suite that maintains the list.
+//
+// The parser is the source's: the source subscribes to its rule events and
+// sets its parse budget (the engine has no way to take either back), so a
+// parser is given to one source and not reused afterwards, and a source
+// runs once (a second run is `STREAM_REUSED`).
+//
+// Failure mapping, in this order: a sink failure is thrown as it was; a
+// sink that stopped is `'stop'`; a parse cancelled through the caller's
+// `AbortFlag` is `ABORTED`; any other engine error is `INPUT_INVALID`
+// with the engine's code and position; a grammar's own guard cancelling
+// the parse is `INPUT_INVALID` too, with a message that names the
+// grammar's guard. An incremental parse that returned without one rule
+// event the adapter could turn into a value (YAML's empty document is
+// `null`) has its value walked instead.
+
+import { isIncremental } from './capability'
+import { Fail } from './error'
+import { Ev } from './event'
+import { Guarded } from './guard'
+import { AbortFlag, Limits, Metrics } from './limits'
+import { Adapter, notStreamable, prepare } from './rule-events'
+import { Flow, Sink } from './sink'
+import { Prune, Source, SourceMode, engineFailure, walkValue } from './source'
+
+// A tabnas parser applied to one text, as a source.
+export class ParserSource implements Source {
+  private parser: any
+  private text: string
+  private sourceMode: SourceMode = SourceMode.materialize()
+  private sourceLimits: Limits = Limits.default()
+  private abortFlag: AbortFlag = new AbortFlag()
+  private sourceMetrics: Metrics = new Metrics()
+  private grammarName: string | null = null
+  private isUnverified = false
+  private used = false
+
+  // A source in materialize mode with default limits, its own abort flag
+  // and fresh metrics; the builder methods change each.
+  constructor(parser: any, text: string) {
+    this.parser = parser
+    this.text = text
+  }
+
+  mode(mode: SourceMode): this {
+    this.sourceMode = mode
+    return this
+  }
+
+  // The grammar the parser implements, by its package's name (`json` for
+  // `@tabnas/json`). Incremental mode runs only for a name
+  // `capability.incremental` lists.
+  grammar(name: string): this {
+    this.grammarName = name
+    return this
+  }
+
+  // Run incremental mode whatever the verified list says. This exists for
+  // the differential suite that maintains the list and for nothing else.
+  unverified(): this {
+    this.isUnverified = true
+    return this
+  }
+
+  limits(limits: Limits): this {
+    this.sourceLimits = limits
+    return this
+  }
+
+  abort(abort: AbortFlag): this {
+    this.abortFlag = abort
+    return this
+  }
+
+  metrics(metrics: Metrics): this {
+    this.sourceMetrics = metrics
+    return this
+  }
+
+  // Why the incremental path may not run, when it may not.
+  private gate(): Fail | null {
+    if (this.isUnverified) return null
+    const name = this.grammarName
+    if (null !== name && isIncremental(name)) return null
+    if (null !== name) {
+      return new Fail(
+        'STREAMABILITY_UNKNOWN',
+        `grammar ${JSON.stringify(name)} is not in capability.incremental: the differential ` +
+          'suite has not verified that its rule events stream as the walk does; run it with ' +
+          'SourceMode.materialize',
+      )
+    }
+    return new Fail(
+      'STREAMABILITY_UNKNOWN',
+      "SourceMode.incremental needs the grammar's name (ParserSource.grammar) to check " +
+        'capability.incremental; without one, run SourceMode.materialize',
+    )
+  }
+
+  // Run in the configured mode.
+  run(sink: Sink): Flow {
+    return this.runWithValue(sink).flow
+  }
+
+  // `run`, also handing back the value the engine returned. In materialize
+  // mode that is the grammar's value. In incremental mode it is the
+  // engine's tree AFTER pruning, which is neither the grammar's value nor
+  // the run's result (the events are): it exists so a test can measure
+  // what pruning left in the tree, and nothing else should read it.
+  runWithValue(sink: Sink): { flow: Flow; value: unknown } {
+    if (this.used) {
+      throw new Fail(
+        'STREAM_REUSED',
+        'a ParserSource runs once: its parser carries the run\'s subscriber and budget; ' +
+          'make a new source, with a new parser, for another run',
+      )
+    }
+    this.used = true
+    const mode = this.sourceMode
+    if ('materialize' === mode.type) {
+      const guarded = new Guarded(sink, this.sourceLimits, this.abortFlag, this.sourceMetrics)
+      try {
+        return materialize(this.parser, this.text, this.abortFlag, guarded)
+      } finally {
+        guarded.flush()
+      }
+    }
+    const refused = this.gate()
+    if (null !== refused) throw refused
+    return incremental(
+      this.parser,
+      this.text,
+      this.sourceLimits,
+      this.abortFlag,
+      this.sourceMetrics,
+      mode.prune,
+      sink,
+    )
+  }
+}
+
+// Parse, then walk; the grammar's value comes back beside the outcome.
+function materialize<S extends Sink>(
+  parser: any,
+  text: string,
+  abort: AbortFlag,
+  guarded: Guarded<S>,
+): { flow: Flow; value: unknown } {
+  prepare(parser, () => !abort.isAborted())
+  let value: unknown
+  try {
+    value = parser.parse(text)
+  } catch (err) {
+    throw engineFailure(err, abort)
+  }
+  let flow = walkValue(value, guarded)
+  if ('continue' === flow) flow = guarded.event(Ev.end)
+  return { flow, value }
+}
+
+function incremental<S extends Sink>(
+  parser: any,
+  text: string,
+  limits: Limits,
+  abort: AbortFlag,
+  metrics: Metrics,
+  prune: Prune,
+  sink: S,
+): { flow: Flow; value: unknown } {
+  const stop = new AbortFlag()
+  const adapter = new Adapter(sink, limits, abort, metrics, prune, stop)
+  prepare(
+    parser,
+    () => !abort.isAborted() && !stop.isAborted(),
+    (rule, done) => adapter.onDone(rule, done),
+  )
+  let parsed: { ok: true; value: unknown } | { ok: false; error: unknown }
+  try {
+    parsed = { ok: true, value: parser.parse(text) }
+  } catch (error) {
+    parsed = { ok: false, error }
+  }
+  let outcome: { flow: Flow } | { error: unknown } = { flow: 'continue' }
+  try {
+    if ('running' === adapter.status.type) {
+      if (parsed.ok && adapter.complete()) {
+        outcome = { flow: adapter.send(Ev.end) }
+      } else if (parsed.ok && adapter.idle()) {
+        let flow = adapter.walkWhole(parsed.value)
+        if ('continue' === flow) flow = adapter.send(Ev.end)
+        outcome = { flow }
+      } else if (parsed.ok) {
+        outcome = { error: notStreamable() }
+      } else {
+        outcome = { error: engineFailure(parsed.error, abort) }
+      }
+    }
+  } catch (error) {
+    outcome = { error }
+  } finally {
+    adapter.sink.flush()
+  }
+  const value = parsed.ok ? parsed.value : undefined
+  const status = adapter.status
+  if ('failed' === status.type) throw status.error
+  if ('stopped' === status.type) return { flow: 'stop', value }
+  if ('error' in outcome) throw outcome.error
+  return { flow: outcome.flow, value }
+}