@tabnas/transduce 0.1.1 → 0.2.0

package/src/sink.ts

@@ -1,199 +0,0 @@
-/* Copyright (c) 2026 tabnas, MIT License */
-
-// The push boundary between stages.
-//
-// A pipeline is a chain of sinks. The source calls the first sink once per
-// event, synchronously, inside the parse; each stage does its work and
-// calls the next. Nothing is queued between stages, so a slow writer at the
-// end slows the parser at the start: that is the backpressure, and it
-// costs no buffer. A stage that must stop early (a `take`) answers
-// `'stop'`, which the source turns into a cancelled parse. A stage that
-// fails throws a `Fail`; the source stops the parse and the failure
-// reaches the caller unchanged.
-
-import { Fail } from './error'
-import { JsonEvent } from './event'
-import { Path, Segment } from './selector'
-
-// What a stage wants next: `'continue'`, or `'stop'` (the stage has all it
-// needs; the source stops the parse, releases what it holds and reports
-// nothing further; not an error).
-export type Flow = 'continue' | 'stop'
-
-// A consumer of `JsonEvents/1`. `event` throws a `Fail` to fail the run.
-export interface Sink {
-  event(ev: JsonEvent): Flow
-}
-
-// A sink that records every event, for tests and small results.
-export class EventRecorder implements Sink {
-  readonly events: JsonEvent[] = []
-
-  event(ev: JsonEvent): Flow {
-    this.events.push(ev)
-    return 'continue'
-  }
-}
-
-// A sink made of a function. A function that returns nothing continues.
-export class FnSink implements Sink {
-  private fn: (ev: JsonEvent) => Flow | void
-
-  constructor(fn: (ev: JsonEvent) => Flow | void) {
-    this.fn = fn
-  }
-
-  event(ev: JsonEvent): Flow {
-    return this.fn(ev) || 'continue'
-  }
-}
-
-// A sink that counts events and drops them: the cheapest consumer, for
-// measuring a source on its own.
-export class CountSink implements Sink {
-  events = 0
-
-  event(_ev: JsonEvent): Flow {
-    this.events++
-    return 'continue'
-  }
-}
-
-// Replay a recording into a sink, stopping where the sink stops.
-export function replay(events: Iterable<JsonEvent>, sink: Sink): Flow {
-  for (const ev of events) {
-    if ('stop' === sink.event(ev)) return 'stop'
-  }
-  return 'continue'
-}
-
-// A container `TreeContract` has open: an object with the keys it has had
-// (the last of them the member whose value is due unless `keyDue`), or an
-// array with the index of the element due next.
-type Open =
-  | { array: false; keys: Set<string>; last: string | null; keyDue: boolean }
-  | { array: true; next: number }
-
-// A tree's events, held to their contract in front of a sink that takes
-// them as one (a render that writes a document from them): one root value,
-// and in each object a key and then its value, each key once. A value
-// walked from a parsed tree keeps it by construction. A parse streamed as
-// it proceeds may not: it hands on a member its grammar reads twice
-// (JSON's `{"a":1,"a":2}`, whose value keeps the last) where a tree has
-// one, and the rule-event adapter refuses most shapes it cannot follow but
-// not every one a grammar can produce. A repeated key in one object is
-// refused with `DUPLICATE_MEMBER`, and events no tree has (a value where a
-// key is due, a key outside an object, a close with nothing open, a second
-// root) with `STREAMABILITY_UNKNOWN`, each at the path of the object
-// concerned; the event is not passed on. Each open object keeps the keys
-// it has had, dropped when it closes.
-export class TreeContract<S extends Sink> implements Sink {
-  readonly inner: S
-  private open: Open[] = []
-  private rootDone = false
-
-  constructor(inner: S) {
-    this.inner = inner
-  }
-
-  // The path of the value due next: the open containers, each by the member
-  // or element open in it, and in the innermost object its last key when
-  // that member's value is due.
-  private path(): Path {
-    const segments: Segment[] = []
-    const last = this.open.length - 1
-    this.open.forEach((open, i) => {
-      if (open.array) {
-        segments.push(open.next)
-      } else if ((i !== last || !open.keyDue) && null != open.last) {
-        // A container open inside this object is its last key's value,
-        // whatever `keyDue` says: the member was counted as taken when its
-        // value opened.
-        segments.push(open.last)
-      }
-    })
-    return new Path(segments)
-  }
-
-  private notATree(what: string): Fail {
-    return new Fail(
-      'STREAMABILITY_UNKNOWN',
-      `the stream holds ${what}, which a tree's events never do, so it is not a tree's`,
-    ).atPath(this.path().toString())
-  }
-
-  // A value is complete: the next in its array is due, or the root is.
-  private closed(): void {
-    const top = this.open[this.open.length - 1]
-    if (undefined === top) this.rootDone = true
-    else if (top.array) top.next++
-  }
-
-  event(ev: JsonEvent): Flow {
-    const top = this.open[this.open.length - 1]
-    switch (ev.type) {
-      case 'key': {
-        if (undefined !== top && !top.array && top.keyDue) {
-          if (top.keys.has(ev.key)) {
-            const path = this.path()
-            path.push(ev.key)
-            throw new Fail(
-              'DUPLICATE_MEMBER',
-              `member ${JSON.stringify(ev.key)} appears twice in one object, and a tree's ` +
-                `events hold each key once`,
-            ).atPath(path.toString())
-          }
-          top.keys.add(ev.key)
-          top.last = ev.key
-          top.keyDue = false
-        } else if (undefined !== top && !top.array) {
-          throw this.notATree('a key where a value is due')
-        } else {
-          throw this.notATree('a key outside an object')
-        }
-        break
-      }
-      case 'object_end':
-        if (undefined !== top && !top.array && top.keyDue) {
-          this.open.pop()
-          this.closed()
-        } else if (undefined !== top && !top.array) {
-          throw this.notATree("an object's end where a value is due")
-        } else {
-          throw this.notATree("an object's end where none is due")
-        }
-        break
-      case 'array_end':
-        if (undefined !== top && top.array) {
-          this.open.pop()
-          this.closed()
-        } else {
-          throw this.notATree("an array's end where none is due")
-        }
-        break
-      case 'end':
-        if (0 < this.open.length) {
-          throw this.notATree('its end inside an open container')
-        }
-        break
-      default: {
-        // A value: in an object, only once its key is in; at the root,
-        // only once.
-        if (undefined === top) {
-          if (this.rootDone) throw this.notATree('a second root value')
-        } else if (!top.array) {
-          if (top.keyDue) throw this.notATree('a value where a key is due')
-          top.keyDue = true
-        }
-        if ('object_start' === ev.type) {
-          this.open.push({ array: false, keys: new Set(), last: null, keyDue: true })
-        } else if ('array_start' === ev.type) {
-          this.open.push({ array: true, next: 0 })
-        } else {
-          this.closed()
-        }
-      }
-    }
-    return this.inner.event(ev)
-  }
-}

package/src/table.ts

@@ -1,213 +0,0 @@
-/* Copyright (c) 2026 tabnas, MIT License */
-
-// `TableRows/1`: one schema, ordered finite rows, completion.
-//
-// The protocol is flat and budgeted: a row is a finite vector of cells,
-// already projected into schema order by the transducer, and a renderer
-// never sees a source path. Public columns carry a label; the source
-// binding (`BoundColumn`) stays on the transducer's side of the boundary.
-
-import { Datum, toText } from './datum'
-import { Fail } from './error'
-import { jsonNumber, jsonString } from './json'
-import { NODE_BYTES, utf8Bytes } from './limits'
-import { Segment, Selector } from './selector'
-import { Flow } from './sink'
-
-// One projected value. `missing`: the source had no value at the column's
-// path; not null, not the empty string, not zero: a policy maps or rejects
-// it later.
-export type Cell =
-  | { readonly type: 'null' }
-  | { readonly type: 'bool'; readonly value: boolean }
-  | { readonly type: 'number'; readonly value: number; readonly lexeme: string | null }
-  | { readonly type: 'string'; readonly value: string }
-  | { readonly type: 'missing' }
-
-const NULL: Cell = Object.freeze({ type: 'null' })
-const MISSING: Cell = Object.freeze({ type: 'missing' })
-
-export const Cell = Object.freeze({
-  null: NULL,
-  missing: MISSING,
-  bool(value: boolean): Cell {
-    return { type: 'bool', value }
-  },
-  number(value: number, lexeme?: string | null): Cell {
-    return { type: 'number', value, lexeme: lexeme ?? null }
-  },
-  string(value: string): Cell {
-    return { type: 'string', value }
-  },
-
-  // From a retained value. A container is not a cell; it is serialized as
-  // compact JSON text, the lossy but unambiguous choice the standard
-  // binding makes and documents.
-  fromDatum(d: Datum): Cell {
-    switch (d.type) {
-      case 'null':
-        return NULL
-      case 'bool':
-        return { type: 'bool', value: d.value }
-      case 'number':
-        return { type: 'number', value: d.value, lexeme: d.lexeme }
-      case 'string':
-        return { type: 'string', value: d.value }
-      default:
-        return { type: 'string', value: toText(d) }
-    }
-  },
-
-  // The bytes this cell retains, on the same basis as a datum's size.
-  byteSize(c: Cell): number {
-    switch (c.type) {
-      case 'number':
-        return NODE_BYTES + (null != c.lexeme ? utf8Bytes(c.lexeme) : 8)
-      case 'string':
-        return NODE_BYTES + utf8Bytes(c.value)
-      default:
-        return NODE_BYTES
-    }
-  },
-
-  // The cell as JSON text; `missing` prints as `missing`.
-  toText(c: Cell): string {
-    switch (c.type) {
-      case 'null':
-        return 'null'
-      case 'bool':
-        return String(c.value)
-      case 'number':
-        return jsonNumber(c.value, c.lexeme)
-      case 'string':
-        return jsonString(c.value)
-      case 'missing':
-        return 'missing'
-    }
-  },
-})
-
-// What a renderer knows about a column.
-export type PublicColumn = { label: string }
-
-// One event of `TableRows/1`: the `schema` exactly once and first, a `row`
-// per row (each exactly as wide as the schema), the `end` exactly once and
-// last, and only after the source validated to its end.
-export type TableEvent =
-  | { readonly type: 'schema'; readonly columns: readonly PublicColumn[] }
-  | { readonly type: 'row'; readonly cells: readonly Cell[] }
-  | { readonly type: 'end' }
-
-// A consumer of `TableRows/1`. Throws a `Fail` to fail the run.
-export interface TableSink {
-  tableEvent(ev: TableEvent): Flow
-}
-
-// An owned recording of a table, for tests and small results.
-export class Table implements TableSink {
-  columns: PublicColumn[] = []
-  rows: Cell[][] = []
-  ended = false
-
-  tableEvent(ev: TableEvent): Flow {
-    switch (ev.type) {
-      case 'schema':
-        this.columns = ev.columns.slice()
-        break
-      case 'row':
-        this.rows.push(ev.cells.slice())
-        break
-      case 'end':
-        this.ended = true
-        break
-    }
-    return 'continue'
-  }
-}
-
-// What to do when a row has no value at a column's path: deliver a
-// `missing` cell (the default; the renderer's policy decides), deliver
-// `null`, or fail the run with `MISSING_VALUE`.
-export type MissingPolicy = 'missing' | 'null' | 'error'
-
-// A column as the transducer binds it: the public label, and the source
-// path projected from each row. Never crosses into a renderer.
-export type BoundColumn = {
-  label: string
-  source: Segment[]
-  missing: MissingPolicy
-}
-
-export function boundColumn(
-  label: string,
-  source: Segment[],
-  missing: MissingPolicy = 'missing',
-): BoundColumn {
-  return { label, source, missing }
-}
-
-// Maps one metadata descriptor to a bound column; throws a `Fail` for a
-// descriptor it cannot read.
-export type ColumnMapper = (meta: Datum) => BoundColumn
-
-// Where a table's columns come from: declared by the caller (`static`),
-// selected from the source and mapped one descriptor at a time
-// (`metadata`; the metadata must complete before the first row begins),
-// or the first row's member names in its order (`infer`; data-dependent: a
-// later row's extra members are dropped, its absent ones are `missing`).
-export type Schema =
-  | { type: 'static'; columns: BoundColumn[] }
-  | { type: 'metadata'; columns: Selector; column: ColumnMapper }
-  | { type: 'infer' }
-
-export const Schema = Object.freeze({
-  static(columns: BoundColumn[]): Schema {
-    return { type: 'static', columns }
-  },
-  fromMetadata(columns: Selector, column: ColumnMapper = columnFromMeta): Schema {
-    return { type: 'metadata', columns, column }
-  },
-  infer(): Schema {
-    return { type: 'infer' }
-  },
-})
-
-// A table transducer's source binding: the schema, and the rows (each
-// location `rows` names is one row).
-export type TableBinding = {
-  schema: Schema
-  rows: Selector
-}
-
-// The standard mapping from a metadata descriptor to a column: the spec's
-// `column-from-meta`, reading `title` and a `path` of segments.
-export function columnFromMeta(meta: Datum): BoundColumn {
-  if ('object' !== meta.type) {
-    throw Fail.input('a column descriptor is not an object')
-  }
-  const title = meta.members.get('title')
-  if (undefined === title || 'string' !== title.type) {
-    throw Fail.input('a column descriptor has no string "title"')
-  }
-  const label = title.value
-  const path = meta.members.get('path')
-  if (undefined === path || 'array' !== path.type) {
-    throw Fail.input(`column ${JSON.stringify(label)} has no "path" array`)
-  }
-  const source: Segment[] = path.items.map((seg) => {
-    if ('string' === seg.type) return seg.value
-    if (
-      'number' === seg.type &&
-      seg.value >= 0 &&
-      Number.isInteger(seg.value) &&
-      seg.value <= 0xffffffff
-    ) {
-      return seg.value
-    }
-    throw Fail.input(
-      `column ${JSON.stringify(label)} has a path segment that is neither a string nor a ` +
-        `non-negative integer: ${toText(seg)}`,
-    )
-  })
-  return boundColumn(label, source)
-}

package/src/value.ts

@@ -1,93 +0,0 @@
-/* Copyright (c) 2026 tabnas, MIT License */
-
-// Reading the engine's values: what a tabnas parse returns in TypeScript.
-//
-// The engine builds plain JavaScript values: `null` and `undefined`,
-// booleans, numbers, strings, arrays and objects. A few grammars hand over
-// host types, which read as the scalars they stand for: a boxed `String`
-// (the engine's text annotation), a `BigInt`, and a TOML `Date`, which
-// reads as the source text it carries (`__toml__.src`), as the Rust
-// runtime's date does.
-//
-// An object's member order is its insertion order. A plain object
-// enumerates integer-like keys first whatever order they were written in,
-// so the engine records the order on the node under `map.ordered` (read
-// with `KEY_ORDER`); the sources switch that on, and `engineKeys` reads
-// it, falling back to `Object.keys`.
-
-// The engine's key-order side channel (`keyOrder` in @tabnas/parser).
-const KEY_ORDER = Symbol.for('tabnas.keyOrder')
-
-export type EngineScalar =
-  | { type: 'null' }
-  | { type: 'bool'; value: boolean }
-  | { type: 'number'; value: number }
-  | { type: 'string'; value: string }
-
-const NULL: EngineScalar = { type: 'null' }
-
-// The value as a scalar, or `undefined` when it is a container.
-export function engineScalar(v: unknown): EngineScalar | undefined {
-  switch (typeof v) {
-    case 'undefined':
-      return NULL
-    case 'boolean':
-      return { type: 'bool', value: v }
-    case 'number':
-      return { type: 'number', value: v }
-    case 'bigint':
-      return { type: 'number', value: Number(v) }
-    case 'string':
-      return { type: 'string', value: v }
-    case 'object':
-      if (null === v) return NULL
-      if (Array.isArray(v)) return undefined
-      if (v instanceof String) return { type: 'string', value: v.valueOf() }
-      if (v instanceof Number) return { type: 'number', value: v.valueOf() }
-      if (v instanceof Boolean) return { type: 'bool', value: v.valueOf() }
-      if (v instanceof Date) {
-        const src = (v as any).__toml__?.src
-        return { type: 'string', value: 'string' === typeof src ? src : v.toJSON() ?? 'null' }
-      }
-      return undefined
-    default:
-      // A function or a symbol has no JSON form.
-      return NULL
-  }
-}
-
-// Whether the value is a container: an array, or an object that is no
-// scalar's host type.
-export function isEngineContainer(v: unknown): boolean {
-  return null !== v && 'object' === typeof v && undefined === engineScalar(v)
-}
-
-// Whether the value is a map (a container that is not an array).
-export function isEngineMap(v: unknown): v is Record<string, unknown> {
-  return isEngineContainer(v) && !Array.isArray(v)
-}
-
-// A map's member names, in insertion order: the engine's recorded order
-// where it kept one, each name once and only while the map still holds it,
-// then any member the record missed.
-export function engineKeys(v: unknown): string[] {
-  if (null === v || 'object' !== typeof v) return []
-  const own = Object.keys(v as object)
-  const order: unknown = (v as any)[KEY_ORDER]
-  if (!Array.isArray(order) || 0 === order.length) return own
-  const has = Object.prototype.hasOwnProperty
-  const seen = new Set<string>()
-  const out: string[] = []
-  for (const k of order) {
-    const key = String(k)
-    if (seen.has(key) || !has.call(v, key)) continue
-    seen.add(key)
-    out.push(key)
-  }
-  if (out.length !== own.length) {
-    for (const k of own) {
-      if (!seen.has(k)) out.push(k)
-    }
-  }
-  return out
-}