@tabnas/transduce 0.1.1 → 0.2.0

package/src/event.ts

@@ -1,134 +0,0 @@
-/* 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/json.ts

@@ -1,82 +0,0 @@
-/* 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

@@ -1,165 +0,0 @@
-/* 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
-  }
-}

package/src/selector.ts

@@ -1,191 +0,0 @@
-/* Copyright (c) 2026 tabnas, MIT License */
-
-// Selectors: reusable descriptions of where in a document to look.
-//
-// A selector is data, never code: it is built from constructors or from
-// validated path segments (`Selector.fromSegments`), and a matcher
-// interprets it. A concrete `Path` names one location; a `Selector` may
-// name many (`each_index`, `each_member`). Both print in jq syntax, which
-// is what the rest of the fleet prints and accepts.
-
-import { jsonString } from './json'
-
-// One step of a concrete path: a string is a member's key, a non-negative
-// integer an element's index.
-export type Segment = string | number
-
-// One key as jq writes it: bare when it is an ASCII identifier, a JSON
-// string otherwise.
-export function keyText(key: string): string {
-  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) ? '.' + key : '.' + jsonString(key)
-}
-
-// A concrete location in a document.
-export class Path {
-  readonly segments: Segment[]
-
-  constructor(segments: Segment[] = []) {
-    this.segments = segments
-  }
-
-  static root(): Path {
-    return new Path([])
-  }
-
-  push(seg: Segment): void {
-    this.segments.push(seg)
-  }
-
-  pop(): Segment | undefined {
-    return this.segments.pop()
-  }
-
-  depth(): number {
-    return this.segments.length
-  }
-
-  clone(): Path {
-    return new Path(this.segments.slice())
-  }
-
-  // jq syntax: `.a[0]."b-c"`, and `.` for the root.
-  toString(): string {
-    return pathText(this.segments)
-  }
-}
-
-// Segments in jq syntax.
-export function pathText(segments: readonly Segment[]): string {
-  if (0 === segments.length) return '.'
-  let out = ''
-  for (const seg of segments) {
-    out += 'number' === typeof seg ? `[${seg}]` : keyText(seg)
-  }
-  return out
-}
-
-// One step of a selector.
-export type Step =
-  // The member with this name, inside an object.
-  | { readonly type: 'property'; readonly name: string }
-  // The element at this position, inside an array.
-  | { readonly type: 'index'; readonly index: number }
-  // Every element of an array.
-  | { readonly type: 'each_index' }
-  // Every member value of an object.
-  | { readonly type: 'each_member' }
-
-const EACH_INDEX: Step = Object.freeze({ type: 'each_index' })
-const EACH_MEMBER: Step = Object.freeze({ type: 'each_member' })
-
-// A description of locations: the root, narrowed step by step. Immutable:
-// every builder returns a new selector.
-export class Selector {
-  readonly steps: readonly Step[]
-
-  constructor(steps: readonly Step[] = []) {
-    this.steps = Object.freeze(steps.slice())
-  }
-
-  // The document itself.
-  static root(): Selector {
-    return new Selector([])
-  }
-
-  property(name: string): Selector {
-    return new Selector([...this.steps, { type: 'property', name }])
-  }
-
-  index(index: number): Selector {
-    if (!Number.isInteger(index) || index < 0) {
-      throw new TypeError('an index step is a non-negative integer: ' + index)
-    }
-    return new Selector([...this.steps, { type: 'index', index }])
-  }
-
-  eachIndex(): Selector {
-    return new Selector([...this.steps, EACH_INDEX])
-  }
-
-  eachMember(): Selector {
-    return new Selector([...this.steps, EACH_MEMBER])
-  }
-
-  // `this`, then `other` below every location `this` names.
-  compose(other: Selector): Selector {
-    return new Selector([...this.steps, ...other.steps])
-  }
-
-  // A selector naming exactly one location: `as-path` over data.
-  static fromSegments(segments: readonly Segment[]): Selector {
-    let s = Selector.root()
-    for (const seg of segments) {
-      s = 'number' === typeof seg ? s.index(seg) : s.property(seg)
-    }
-    return s
-  }
-
-  isRoot(): boolean {
-    return 0 === this.steps.length
-  }
-
-  // Whether the selector can name more than one location.
-  isMulti(): boolean {
-    return this.steps.some((s) => 'each_index' === s.type || 'each_member' === s.type)
-  }
-
-  // Whether this selector names a location strictly inside a location
-  // `other` names, or the same one: the test a router uses to refuse
-  // overlapping captures.
-  mayOverlap(other: Selector): boolean {
-    const [short, long] =
-      this.steps.length <= other.steps.length ? [this, other] : [other, this]
-    for (let i = 0; i < short.steps.length; i++) {
-      if (!stepMayMatchSame(short.steps[i], long.steps[i])) return false
-    }
-    return true
-  }
-
-  equals(other: Selector): boolean {
-    return this.toString() === other.toString()
-  }
-
-  // jq syntax: `.response.records[*]`, `."odd key"`, `[3]`, `[]` for
-  // every member, `.` for the root.
-  toString(): string {
-    if (0 === this.steps.length) return '.'
-    let out = ''
-    for (const step of this.steps) {
-      switch (step.type) {
-        case 'property':
-          out += keyText(step.name)
-          break
-        case 'index':
-          out += `[${step.index}]`
-          break
-        case 'each_index':
-          out += '[*]'
-          break
-        case 'each_member':
-          out += '[]'
-          break
-      }
-    }
-    return out
-  }
-}
-
-function stepMayMatchSame(a: Step, b: Step): boolean {
-  switch (a.type) {
-    case 'property':
-      return (
-        ('property' === b.type && a.name === b.name) || 'each_member' === b.type
-      )
-    case 'each_member':
-      return 'property' === b.type || 'each_member' === b.type
-    case 'index':
-      return ('index' === b.type && a.index === b.index) || 'each_index' === b.type
-    case 'each_index':
-      return 'index' === b.type || 'each_index' === b.type
-  }
-}