@tabnas/transduce 0.1.0 → 0.1.2

package/src/error.ts

@@ -0,0 +1,198 @@
+/* Copyright (c) 2026 tabnas, MIT License */
+
+// Failures, with stable codes.
+//
+// The code is the contract: scripts and agents branch on it, and every
+// renderer, transducer and host uses the same set. The message, path and
+// limit are informative. A code is never renamed, removed or repurposed;
+// one may be added.
+
+const CODES = [
+  'DSL_PARSE_ERROR',
+  'DSL_TYPE_ERROR',
+  'STREAM_REUSED',
+  'STREAMABILITY_UNKNOWN',
+  'INPUT_ORDER_VIOLATION',
+  'CAPTURE_OVERLAP_UNSUPPORTED',
+  'MISSING_VALUE',
+  'DUPLICATE_MEMBER',
+  'INVALID_NUMBER',
+  'PROTOCOL_ORDER_ERROR',
+  'TARGET_VALUE_UNREPRESENTABLE',
+  'RESOURCE_LIMIT_EXCEEDED',
+  'INPUT_INVALID',
+  'OUTPUT_FAILED',
+  'ABORTED',
+] as const
+
+// One of the stable failure codes, written in `SCREAMING_SNAKE_CASE`.
+export type Code = (typeof CODES)[number]
+
+type CodeTable = { readonly [K in Code]: K } & {
+  // Every code, in declaration order (the Rust `Code::ALL`).
+  readonly ALL: readonly Code[]
+  // A code by its written form, or `undefined`.
+  parse(text: string): Code | undefined
+}
+
+const table: any = {}
+for (const c of CODES) table[c] = c
+table.ALL = Object.freeze([...CODES])
+table.parse = (text: string): Code | undefined =>
+  (CODES as readonly string[]).includes(text) ? (text as Code) : undefined
+
+// The codes as constants: `Code.INPUT_INVALID`, and `Code.ALL`.
+export const Code: CodeTable = Object.freeze(table)
+
+// The limit a `RESOURCE_LIMIT_EXCEEDED` failure names.
+export type Limit = {
+  // The `Limits` field, as written there (`max_record_bytes`).
+  name: string
+  value: number
+}
+
+// A failure: a code, and what is known about where and why.
+//
+// `committedOutput` says whether bytes had already been written when the
+// failure was found: an incremental export cannot take them back, and the
+// caller must be told the output may be partial.
+export class Fail extends Error {
+  code: Code
+  // The input path the failure concerns, in jq syntax, when one applies.
+  path?: string
+  limit?: Limit
+  // 1-based source row and column, when the failure has a position.
+  row?: number
+  col?: number
+  // The source file the position is in, when the program the failure came
+  // from was compiled from several.
+  file?: string
+  committedOutput: boolean
+
+  constructor(code: Code, message: string) {
+    super(message)
+    this.name = 'Fail'
+    this.code = code
+    this.committedOutput = false
+  }
+
+  // The failure with the source file its position is in.
+  inFile(file: string): this {
+    this.file = file
+    return this
+  }
+
+  atPath(path: string): this {
+    this.path = path
+    return this
+  }
+
+  at(row: number, col: number): this {
+    this.row = row
+    this.col = col
+    return this
+  }
+
+  committed(): this {
+    this.committedOutput = true
+    return this
+  }
+
+  // A limit failure, named after the `Limits` field that was passed.
+  static limit(name: string, value: number, message: string): Fail {
+    const f = new Fail('RESOURCE_LIMIT_EXCEEDED', message)
+    f.limit = { name, value }
+    return f
+  }
+
+  static protocol(message: string): Fail {
+    return new Fail('PROTOCOL_ORDER_ERROR', message)
+  }
+
+  static input(message: string): Fail {
+    return new Fail('INPUT_INVALID', message)
+  }
+
+  static output(message: string): Fail {
+    return new Fail('OUTPUT_FAILED', message)
+  }
+
+  static aborted(): Fail {
+    return new Fail('ABORTED', 'the run was cancelled')
+  }
+
+  // The engine's own error, as an input failure carrying its code,
+  // position and report.
+  static fromTabnas(e: any): Fail {
+    const f = new Fail('INPUT_INVALID', `${engineCode(e)}: ${engineDetail(e)}`)
+    const pos = enginePosition(e)
+    if (pos) {
+      f.row = pos.row
+      f.col = pos.col
+    }
+    return f
+  }
+
+  // The failure as a plain object: `code`, `message`, and `path`, `limit`
+  // (`{name, value}`), `row`, `col`, `file`, `output` ("partial" or
+  // "none") when they apply. This is the shape hosts print.
+  toJSON(): Record<string, unknown> {
+    const out: Record<string, unknown> = {
+      code: this.code,
+      message: this.message,
+    }
+    if (null != this.path) out.path = this.path
+    if (null != this.limit) out.limit = { name: this.limit.name, value: this.limit.value }
+    if (null != this.row) out.row = this.row
+    if (null != this.col) out.col = this.col
+    if (null != this.file) out.file = this.file
+    out.output = this.committedOutput ? 'partial' : 'none'
+    return out
+  }
+
+  toString(): string {
+    let s = `${this.code}: ${this.message}`
+    if (null != this.path) s += ` at ${this.path}`
+    if (null != this.file && null != this.row && null != this.col) {
+      s += ` (${this.file}:${this.row}:${this.col})`
+    } else if (null != this.row && null != this.col) {
+      s += ` (${this.row}:${this.col})`
+    } else if (null != this.file) {
+      s += ` (in ${this.file})`
+    }
+    if (null != this.limit) s += ` [${this.limit.name} = ${this.limit.value}]`
+    return s
+  }
+}
+
+// Whether a thrown value is a `Fail`.
+export function isFail(e: unknown): e is Fail {
+  return e instanceof Fail
+}
+
+// The engine error's code (`unexpected`, `cancel`, ...).
+export function engineCode(e: any): string {
+  return 'string' === typeof e?.code ? e.code : 'unknown'
+}
+
+// The engine error's one-line description, without the code.
+export function engineDetail(e: any): string {
+  let detail = ''
+  try {
+    if ('function' === typeof e?.toJSON) detail = e.toJSON()?.message ?? ''
+  } catch (_err) {
+    detail = ''
+  }
+  if ('' === detail) detail = String(e?.message ?? e)
+  return detail.trimEnd()
+}
+
+// The engine error's 1-based position, when it has one.
+export function enginePosition(e: any): { row: number; col: number } | undefined {
+  const row = e?.lineNumber
+  const col = e?.columnNumber
+  if ('number' === typeof row && 0 < row) {
+    return { row, col: 'number' === typeof col ? col : 0 }
+  }
+  return undefined
+}

package/src/event.ts

@@ -0,0 +1,134 @@
+/* Copyright (c) 2026 tabnas, MIT License */
+
+// `JsonEvents/1`: the source protocol every transducer consumes.
+//
+// A source (a tabnas parse, a parsed value, a line-delimited reader) emits
+// the events of one document in order: container boundaries, keys, whole
+// scalars, and one `end` after the root value. Events are plain frozen
+// objects, so a recorder keeps them as they are and a stage that keeps
+// anything keeps the event itself.
+//
+// Scalars arrive whole because the tabnas lexer produces whole tokens. A
+// later `JsonEvents/2` may chunk strings; it will be a separately named
+// protocol, never a change to this one.
+
+// One event of `JsonEvents/1`, a tagged union on `type`.
+//
+// `number` carries the machine value and, when the source could hand it
+// over, its `lexeme` (the source text), else `null`; a renderer falls back
+// to the value. Keeping both is how `50.25` stays `50.25` and how a number
+// beyond a double's exact range keeps its digits.
+export type JsonEvent =
+  | { readonly type: 'object_start' }
+  | { readonly type: 'object_end' }
+  | { readonly type: 'array_start' }
+  | { readonly type: 'array_end' }
+  | { readonly type: 'key'; readonly key: string }
+  | { 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: 'end' }
+
+export type JsonEventType = JsonEvent['type']
+
+// The events without a payload are shared, so emitting one allocates
+// nothing.
+const OBJECT_START: JsonEvent = Object.freeze({ type: 'object_start' })
+const OBJECT_END: JsonEvent = Object.freeze({ type: 'object_end' })
+const ARRAY_START: JsonEvent = Object.freeze({ type: 'array_start' })
+const ARRAY_END: JsonEvent = Object.freeze({ type: 'array_end' })
+const NULL: JsonEvent = Object.freeze({ type: 'null' })
+const TRUE: JsonEvent = Object.freeze({ type: 'bool', value: true })
+const FALSE: JsonEvent = Object.freeze({ type: 'bool', value: false })
+const END: JsonEvent = Object.freeze({ type: 'end' })
+
+// Constructors for every event.
+export const Ev = Object.freeze({
+  objectStart: OBJECT_START,
+  objectEnd: OBJECT_END,
+  arrayStart: ARRAY_START,
+  arrayEnd: ARRAY_END,
+  null: NULL,
+  end: END,
+  key(key: string): JsonEvent {
+    return { type: 'key', key }
+  },
+  bool(value: boolean): JsonEvent {
+    return value ? TRUE : FALSE
+  },
+  number(value: number, lexeme?: string | null): JsonEvent {
+    return { type: 'number', value, lexeme: lexeme ?? null }
+  },
+  string(value: string): JsonEvent {
+    return { type: 'string', value }
+  },
+})
+
+// Whether the event opens a container.
+export function isStart(ev: JsonEvent): boolean {
+  return 'object_start' === ev.type || 'array_start' === ev.type
+}
+
+// Whether the event closes a container.
+export function isEnd(ev: JsonEvent): boolean {
+  return 'object_end' === ev.type || 'array_end' === ev.type
+}
+
+// Whether the event is a whole scalar value.
+export function isScalar(ev: JsonEvent): boolean {
+  return (
+    'null' === ev.type ||
+    'bool' === ev.type ||
+    'number' === ev.type ||
+    'string' === ev.type
+  )
+}
+
+// Two events are equal: same type and payload. Numbers compare by
+// `Object.is` (so `-0` is not `0`) and lexeme.
+export function eventEquals(a: JsonEvent, b: JsonEvent): boolean {
+  if (a.type !== b.type) return false
+  switch (a.type) {
+    case 'key':
+      return a.key === (b as any).key
+    case 'bool':
+    case 'string':
+      return a.value === (b as any).value
+    case 'number':
+      return (
+        (Object.is(a.value, (b as any).value) ||
+          (Number.isNaN(a.value) && Number.isNaN((b as any).value))) &&
+        a.lexeme === (b as any).lexeme
+      )
+    default:
+      return true
+  }
+}
+
+// The event as short text, for messages: `{`, `}`, `[`, `]`, `key "a"`,
+// a scalar as JSON, `end`.
+export function eventText(ev: JsonEvent): string {
+  switch (ev.type) {
+    case 'object_start':
+      return '{'
+    case 'object_end':
+      return '}'
+    case 'array_start':
+      return '['
+    case 'array_end':
+      return ']'
+    case 'key':
+      return 'key ' + JSON.stringify(ev.key)
+    case 'null':
+      return 'null'
+    case 'bool':
+      return String(ev.value)
+    case 'number':
+      return null != ev.lexeme ? ev.lexeme : String(ev.value)
+    case 'string':
+      return JSON.stringify(ev.value)
+    case 'end':
+      return 'end'
+  }
+}

package/src/guard.ts

@@ -0,0 +1,112 @@
+/* Copyright (c) 2026 tabnas, MIT License */
+
+// The source-side limits, applied to events as they are produced.
+//
+// Every source emits through a `Guarded` sink, so the three limits a source
+// owns (`max_depth`, `max_key_bytes`, `max_scalar_bytes`) are checked once,
+// in one place, whether the events come from a live parse or from a walk
+// over a parsed value; the abort flag is polled per event so a walk stops
+// as promptly as a parse does; and the source metrics (events, keys,
+// scalars) are counted locally and flushed in one step.
+
+import { Fail } from './error'
+import { JsonEvent } from './event'
+import { AbortFlag, Limits, Metrics, utf8Bytes } from './limits'
+import { Flow, Sink } from './sink'
+
+// A sink wrapper that enforces the source limits and counts.
+export class Guarded<S extends Sink> implements Sink {
+  readonly inner: S
+  private maxDepth: number
+  private maxKeyBytes: number
+  private maxScalarBytes: number
+  private abort: AbortFlag
+  private metrics: Metrics
+  private open = 0
+  private events = 0
+  private keys = 0
+  private scalars = 0
+
+  constructor(inner: S, limits: Limits, abort: AbortFlag, metrics: Metrics) {
+    this.inner = inner
+    this.maxDepth = limits.max_depth
+    this.maxKeyBytes = limits.max_key_bytes
+    this.maxScalarBytes = limits.max_scalar_bytes
+    this.abort = abort
+    this.metrics = metrics
+  }
+
+  // Add the counts so far to the shared metrics and start again.
+  flush(): void {
+    this.metrics.events += this.events
+    this.metrics.keys += this.keys
+    this.metrics.scalars += this.scalars
+    this.events = 0
+    this.keys = 0
+    this.scalars = 0
+  }
+
+  // Open containers right now.
+  depth(): number {
+    return this.open
+  }
+
+  private scalar(bytes: number): void {
+    this.scalars++
+    if (bytes > this.maxScalarBytes) {
+      throw Fail.limit(
+        'max_scalar_bytes',
+        this.maxScalarBytes,
+        `a scalar of ${bytes} bytes is larger than ${this.maxScalarBytes}`,
+      )
+    }
+  }
+
+  event(ev: JsonEvent): Flow {
+    if (this.abort.isAborted()) throw Fail.aborted()
+    this.events++
+    switch (ev.type) {
+      case 'object_start':
+      case 'array_start':
+        this.open++
+        if (this.open > this.maxDepth) {
+          throw Fail.limit(
+            'max_depth',
+            this.maxDepth,
+            `a container is nested deeper than ${this.maxDepth}`,
+          )
+        }
+        break
+      case 'object_end':
+      case 'array_end':
+        this.open = Math.max(0, this.open - 1)
+        break
+      case 'key': {
+        this.keys++
+        const n = utf8Bytes(ev.key)
+        if (n > this.maxKeyBytes) {
+          throw Fail.limit(
+            'max_key_bytes',
+            this.maxKeyBytes,
+            `a key of ${n} bytes is longer than ${this.maxKeyBytes}`,
+          )
+        }
+        break
+      }
+      case 'string':
+        this.scalar(utf8Bytes(ev.value))
+        break
+      case 'number':
+        this.scalar(null != ev.lexeme ? utf8Bytes(ev.lexeme) : 0)
+        break
+      case 'null':
+      case 'bool':
+        this.scalar(0)
+        break
+      case 'end':
+        this.flush()
+        break
+    }
+    return this.inner.event(ev)
+  }
+}

package/src/json.ts

@@ -0,0 +1,82 @@
+/* Copyright (c) 2026 tabnas, MIT License */
+
+// JSON text: the escaping and number spelling every runtime shares.
+
+// `s` as a JSON string literal, escaped as RFC 8259 requires: `"` and `\`
+// escaped, the short forms `\b \f \n \r \t`, other control characters as
+// `\u00XX` with lowercase hex, and everything else as itself.
+export function jsonString(s: string): string {
+  let out = '"'
+  let from = 0
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    if (c >= 0x20 && c !== 0x22 && c !== 0x5c) continue
+    if (i > from) out += s.slice(from, i)
+    from = i + 1
+    switch (c) {
+      case 0x22:
+        out += '\\"'
+        break
+      case 0x5c:
+        out += '\\\\'
+        break
+      case 0x08:
+        out += '\\b'
+        break
+      case 0x0c:
+        out += '\\f'
+        break
+      case 0x0a:
+        out += '\\n'
+        break
+      case 0x0d:
+        out += '\\r'
+        break
+      case 0x09:
+        out += '\\t'
+        break
+      default:
+        out += '\\u' + c.toString(16).padStart(4, '0')
+    }
+  }
+  if (from < s.length) out += s.slice(from)
+  return out + '"'
+}
+
+// A number with no lexeme, as text: the shortest digits that read back as
+// the same double, written positionally, never with an exponent (`1e21` is
+// `1000000000000000000000`, `1e-7` is `0.0000001`, `-0` is `-0`). This is
+// the spelling the Rust runtime's `f64` `Display` gives, so a container
+// cell holding such a number reads the same in every runtime;
+// `DIVERGENCE.md` keeps the decision open. A non-finite value has no JSON
+// form and is `null`.
+export function numberText(value: number): string {
+  if (!Number.isFinite(value)) return 'null'
+  if (Object.is(value, -0)) return '-0'
+  if (0 === value) return '0'
+  const neg = value < 0
+  const exp = Math.abs(value).toExponential()
+  const at = exp.indexOf('e')
+  const digits = exp.slice(0, at).replace('.', '')
+  const e = parseInt(exp.slice(at + 1), 10)
+  let text: string
+  if (e >= digits.length - 1) {
+    text = digits + '0'.repeat(e - (digits.length - 1))
+  } else if (e >= 0) {
+    text = digits.slice(0, e + 1) + '.' + digits.slice(e + 1)
+  } else {
+    text = '0.' + '0'.repeat(-e - 1) + digits
+  }
+  return neg ? '-' + text : text
+}
+
+// A number as JSON text: its lexeme when known, else `numberText`.
+export function jsonNumber(value: number, lexeme: string | null | undefined): string {
+  return null != lexeme ? lexeme : numberText(value)
+}
+
+// RFC 8259's number grammar: `-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?`.
+// Only such a lexeme is kept, so a renderer can write it as it stands.
+export function isJsonNumber(s: string): boolean {
+  return /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$/.test(s)
+}

package/src/limits.ts

@@ -0,0 +1,165 @@
+/* Copyright (c) 2026 tabnas, MIT License */
+
+// Limits, metrics and cancellation.
+//
+// Limits are part of a plan, not advice: a stage that would exceed one
+// fails with `RESOURCE_LIMIT_EXCEEDED` naming the field, rather than
+// switching to a slower or larger algorithm. Values are payload bytes
+// (UTF-8 lengths of keys and scalars, and the sum of them for a retained
+// value plus a fixed per-node allowance), which is a stable and portable
+// measure, the same in every runtime; they are not a heap measurement. A
+// JavaScript string is UTF-16, so every count here goes through
+// `utf8Bytes`, never `length`.
+
+// Per-run limits. Every field is named in a failure as written here, which
+// is why the fields keep the snake_case names every runtime shares.
+export type Limits = {
+  // Container nesting the source may reach.
+  max_depth: number
+  // Bytes in one object key.
+  max_key_bytes: number
+  // Bytes in one scalar (a string's text, a number's lexeme).
+  max_scalar_bytes: number
+  // Bytes retained for metadata (the column descriptors).
+  max_metadata_bytes: number
+  // Columns a schema may declare.
+  max_columns: number
+  // Bytes retained for one row before projection.
+  max_record_bytes: number
+  // Bytes retained for any one materialized capture.
+  max_capture_bytes: number
+  // Bytes the run may write; `null` for no limit.
+  max_output_bytes: number | null
+}
+
+// The names of the `Limits` fields, in declaration order.
+export const LIMIT_NAMES: readonly (keyof Limits)[] = Object.freeze([
+  'max_depth',
+  'max_key_bytes',
+  'max_scalar_bytes',
+  'max_metadata_bytes',
+  'max_columns',
+  'max_record_bytes',
+  'max_capture_bytes',
+  'max_output_bytes',
+])
+
+export const Limits = Object.freeze({
+  // The defaults: 256, 64 KiB, 16 MiB, 16 MiB, 10 000, 64 MiB, 64 MiB, none.
+  default(): Limits {
+    return {
+      max_depth: 256,
+      max_key_bytes: 64 * 1024,
+      max_scalar_bytes: 16 * 1024 * 1024,
+      max_metadata_bytes: 16 * 1024 * 1024,
+      max_columns: 10_000,
+      max_record_bytes: 64 * 1024 * 1024,
+      max_capture_bytes: 64 * 1024 * 1024,
+      max_output_bytes: null,
+    }
+  },
+
+  // No limit on anything that can be unlimited, and the largest values
+  // otherwise. For tests and trusted, measured inputs only.
+  unlimited(): Limits {
+    const max = Number.MAX_SAFE_INTEGER
+    return {
+      max_depth: max,
+      max_key_bytes: max,
+      max_scalar_bytes: max,
+      max_metadata_bytes: max,
+      max_columns: max,
+      max_record_bytes: max,
+      max_capture_bytes: max,
+      max_output_bytes: null,
+    }
+  },
+
+  // The defaults with `fields` applied over them.
+  with(fields: Partial<Limits>): Limits {
+    return { ...Limits.default(), ...fields }
+  },
+})
+
+// The fixed allowance counted for every retained node (a container, a
+// member, an element) on top of its payload bytes.
+export const NODE_BYTES = 16
+
+// The UTF-8 length of a string: `é` is 2, `日` 3, `😀` 4. A lone
+// surrogate counts 3, as its replacement character would.
+export function utf8Bytes(s: string): number {
+  const n = s.length
+  // ASCII fast path: most keys and scalars never leave it.
+  let i = 0
+  for (; i < n; i++) {
+    if (s.charCodeAt(i) >= 0x80) break
+  }
+  if (i === n) return n
+  return Buffer.byteLength(s, 'utf8')
+}
+
+// Counters and high-water marks a run reports, shared between stages.
+export class Metrics {
+  // Source events seen.
+  events = 0
+  // Object keys seen.
+  keys = 0
+  // Scalars seen.
+  scalars = 0
+  // Rows delivered to the table protocol.
+  rows = 0
+  // Bytes currently held by materialized captures.
+  captured_bytes = 0
+  // The most bytes ever held by captures at once.
+  captured_bytes_high = 0
+  // The most bytes ever retained at once across every retaining stage.
+  retained_bytes_high = 0
+  // Bytes written to the output.
+  output_bytes = 0
+
+  // Account `bytes` as captured now, and raise the high-water marks.
+  capture(bytes: number): void {
+    this.captured_bytes += bytes
+    if (this.captured_bytes > this.captured_bytes_high) {
+      this.captured_bytes_high = this.captured_bytes
+    }
+    if (this.captured_bytes > this.retained_bytes_high) {
+      this.retained_bytes_high = this.captured_bytes
+    }
+  }
+
+  // Release `bytes` captured earlier.
+  release(bytes: number): void {
+    this.captured_bytes -= bytes
+  }
+
+  // The metrics as a plain object, one field per counter.
+  toJSON(): Record<string, number> {
+    return {
+      events: this.events,
+      keys: this.keys,
+      scalars: this.scalars,
+      rows: this.rows,
+      captured_bytes: this.captured_bytes,
+      captured_bytes_high: this.captured_bytes_high,
+      retained_bytes_high: this.retained_bytes_high,
+      output_bytes: this.output_bytes,
+    }
+  }
+}
+
+// A cancellation flag shared by the caller, the source and the stages.
+//
+// The source polls it between parse steps through the engine's parse
+// budget and stops with `ABORTED`; long loops in stages poll it too.
+export class AbortFlag {
+  private aborted = false
+
+  abort(): void {
+    this.aborted = true
+  }
+
+  isAborted(): boolean {
+    return this.aborted
+  }
+}