@tabnas/transduce 0.1.1 → 0.2.0

package/src/parser-source.ts

@@ -30,13 +30,11 @@
 // event the adapter could turn into a value (YAML's empty document is
 // `null`) has its value walked instead.
 
+import { AbortFlag, Ev, Fail, Flow, Limits, Metrics, Sink } from '@tabnas/alchemy/shared'
+
 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.

package/src/route.ts

@@ -15,76 +15,24 @@
 // stream the check could not foresee still fails rather than mixing two
 // values.
 
-import { Datum, DatumBuilder, Duplicates } from './datum'
-import { Fail } from './error'
-import { JsonEvent } from './event'
-import { Limits, Metrics } from './limits'
-import { CaptureId, Matcher } from './matcher'
-import { Path, Selector } from './selector'
-import { Flow, Sink } from './sink'
-
-// What a capture keeps of its match: build the value and deliver it whole
-// (`materialize`), or deliver only that the value occurred, and where,
-// when it ends (`observe`).
-export type CaptureMode = 'materialize' | 'observe'
-
-// The byte budget one materialized capture may not exceed, named after the
-// `Limits` field the failure reports.
-export type Budget = { bytes: number; name: string }
-
-// One capture: a tag for the consumer, the selector to match, the mode,
-// and for a `materialize` capture an optional budget (else the router's
-// `max_capture_bytes`).
-export class CaptureSpec {
-  readonly tag: string
-  readonly selector: Selector
-  readonly mode: CaptureMode
-  budget: Budget | null = null
-
-  constructor(tag: string, selector: Selector, mode: CaptureMode) {
-    this.tag = tag
-    this.selector = selector
-    this.mode = mode
-  }
-
-  static materialize(tag: string, selector: Selector): CaptureSpec {
-    return new CaptureSpec(tag, selector, 'materialize')
-  }
-
-  static observe(tag: string, selector: Selector): CaptureSpec {
-    return new CaptureSpec(tag, selector, 'observe')
-  }
-
-  // This spec with its own budget, whose failure names `name`.
-  withBudget(bytes: number, name: string): CaptureSpec {
-    this.budget = { bytes, name }
-    return this
-  }
-}
-
-// One completed match: the spec's position in the router's list, its tag,
-// the concrete path, and the value for a `materialize` capture (`null`
-// for `observe`).
-export type Selected = {
-  id: CaptureId
-  tag: string
-  path: Path
-  value: Datum | null
-}
-
-// The consumer of a router's matches.
-export interface RouteSink {
-  // A capture's value is beginning. Nothing has been retained for it yet,
-  // so a consumer that knows the value is out of order can refuse it here
-  // at no cost (throw a `Fail`); the router adds the path to a failure
-  // that has none.
-  began?(id: CaptureId, tag: string): void
-
-  selected(selected: Selected): Flow
-
-  // The document ended, validated. Exactly once, after the last match.
-  end(): Flow
-}
+import {
+  CaptureId,
+  CaptureSpec,
+  Datum,
+  DatumBuilder,
+  Duplicates,
+  Fail,
+  Flow,
+  JsonEvent,
+  Limits,
+  Metrics,
+  Path,
+  RouteSink,
+  Selected,
+  Sink,
+} from '@tabnas/alchemy/shared'
+
+import { Matcher } from './matcher'
 
 // A route sink that records every match.
 export class SelectedRecorder implements RouteSink {

package/src/routers.ts

@@ -0,0 +1,64 @@
+/* Copyright (c) 2026 tabnas, MIT License */
+
+// This package's stages as alchemy's `Routers`: what an alchemy program's
+// runtime builds its routes, tables, scans and guards from. Alchemy
+// declares the interface (`@tabnas/alchemy/shared`) and imports no
+// transducer; a host passes `routers` to its `compile`, with render's
+// `renderers`: `compile(src, file, { routers, renderers })`.
+
+import {
+  AbortFlag,
+  CaptureSpec,
+  Duplicates,
+  Flow,
+  Limits,
+  Metrics,
+  RouteSink,
+  Routers,
+  Scan,
+  Sink,
+  TableBinding,
+  TableSink,
+  Transition,
+} from '@tabnas/alchemy/shared'
+
+import { Guarded } from './guard'
+import { Router } from './route'
+import { ScanEmit } from './scan'
+import { TableFromJson } from './table-from-json'
+
+// Each method constructs the stage it names with the same parameters.
+export const routers: Routers = Object.freeze({
+  router(
+    specs: readonly CaptureSpec[],
+    limits: Limits,
+    duplicates: Duplicates,
+    metrics: Metrics,
+    downstream: RouteSink,
+  ): Sink {
+    return new Router(specs, limits, duplicates, metrics, downstream)
+  },
+
+  tableFromJson(
+    binding: TableBinding,
+    limits: Limits,
+    duplicates: Duplicates,
+    metrics: Metrics,
+    sink: TableSink,
+  ): Sink {
+    return new TableFromJson(binding, limits, duplicates, metrics, sink)
+  },
+
+  scanEmit<S, I, O>(
+    initial: S,
+    step: (state: S, item: I) => Transition<S, O>,
+    finish: (state: S) => O[],
+    out: (output: O) => Flow,
+  ): Scan<I> {
+    return new ScanEmit<S, I, O>(initial, step, finish, out)
+  },
+
+  guarded(inner: Sink, limits: Limits, abort: AbortFlag, metrics: Metrics): Sink {
+    return new Guarded(inner, limits, abort, metrics)
+  },
+})

package/src/rule-events.ts

@@ -50,16 +50,26 @@
 // the engine returns, which is why only the incremental source, which
 // discards that value, ever asks for it.
 
-import { Fail } from './error'
-import { Ev, JsonEvent } from './event'
+import {
+  AbortFlag,
+  Ev,
+  Fail,
+  Flow,
+  JsonEvent,
+  Limits,
+  Metrics,
+  Selector,
+  Sink,
+  engineKeys,
+  engineScalar,
+  isEngineContainer,
+  isEngineMap,
+  isJsonNumber,
+} from '@tabnas/alchemy/shared'
+
 import { Guarded } from './guard'
-import { isJsonNumber } from './json'
-import { AbortFlag, Limits, Metrics } from './limits'
 import { Matcher } from './matcher'
-import { Selector } from './selector'
-import { Flow, Sink } from './sink'
 import { Prune, walkValue } from './source'
-import { engineKeys, engineScalar, isEngineContainer, isEngineMap } from './value'
 
 // One open container.
 type Frame = {

package/src/scan.ts

@@ -8,25 +8,7 @@
 // the functions own nothing. This is what the DSL's `scan-emit` lowers to,
 // and the table transducer is one instance of it.
 
-import { Fail } from './error'
-import { Flow } from './sink'
-
-// The result of one step: the next state and what to emit for it.
-export type Transition<S, O> = { state: S; outputs: O[] }
-
-export const Transition = Object.freeze({
-  of<S, O>(state: S, outputs: O[]): Transition<S, O> {
-    return { state, outputs }
-  },
-  // A step that emits nothing.
-  stay<S, O>(state: S): Transition<S, O> {
-    return { state, outputs: [] }
-  },
-  // A step that emits one item.
-  emit<S, O>(state: S, output: O): Transition<S, O> {
-    return { state, outputs: [output] }
-  },
-})
+import { Fail, Flow, Transition } from '@tabnas/alchemy/shared'
 
 // The operator. Feed items with `item`, then call `finish` exactly once
 // when the input completed successfully; never call it after a failure or

package/src/source.ts

@@ -14,12 +14,18 @@
 // Every source emits through `Guarded`, which enforces the source limits,
 // polls the abort flag and counts the source metrics.
 
-import { Fail, engineCode, engineDetail } from './error'
-import { Ev } from './event'
-import { AbortFlag } from './limits'
-import { Selector } from './selector'
-import { Flow, Sink } from './sink'
-import { engineKeys, engineScalar } from './value'
+import {
+  AbortFlag,
+  Ev,
+  Fail,
+  Flow,
+  Selector,
+  Sink,
+  engineCode,
+  engineDetail,
+  engineKeys,
+  engineScalar,
+} from '@tabnas/alchemy/shared'
 
 // Which arrays the incremental source empties as it streams them: none
 // (`never`), the array whose elements the selector names (`under`: a

package/src/table-from-json.ts

@@ -15,23 +15,34 @@
 // of members inside a row never matters, and a number keeps the lexeme the
 // source events carried.
 
-import { Datum, Duplicates, getPath } from './datum'
-import { Fail } from './error'
-import { JsonEvent } from './event'
-import { Limits, Metrics, NODE_BYTES, utf8Bytes } from './limits'
-import { CaptureId } from './matcher'
-import { CaptureSpec, RouteSink, Router, Selected } from './route'
-import { Path, Selector } from './selector'
-import { Flow, Sink } from './sink'
 import {
   BoundColumn,
+  CaptureId,
+  CaptureSpec,
   Cell,
   ColumnMapper,
+  Datum,
+  Duplicates,
+  Fail,
+  Flow,
+  JsonEvent,
+  Limits,
+  Metrics,
+  NODE_BYTES,
+  Path,
   PublicColumn,
+  RouteSink,
+  Selected,
+  Selector,
+  Sink,
   TableBinding,
   TableSink,
   boundColumn,
-} from './table'
+  getPath,
+  utf8Bytes,
+} from '@tabnas/alchemy/shared'
+
+import { Router } from './route'
 
 // Where the columns are, once known.
 type Columns =

package/src/transduce.ts

@@ -20,9 +20,15 @@
 // Everything is synchronous and push-based: the parser calls the first
 // sink from inside its own callback, and a slow writer at the end of the
 // chain slows the parse at the start. That is the backpressure.
+//
+// The protocols, `Fail` and its codes, `Limits`, `Metrics`, `Selector`,
+// `Datum` and the captures' types are alchemy's shared types
+// (`@tabnas/alchemy/shared`), which this package imports and re-exports
+// under the names it always exported them by. `routers` is this package's
+// stages as alchemy's `Routers`, for a host to pass to alchemy's `compile`.
 
 // This package's version, as package.json declares it.
-export const VERSION = '0.1.1'
+export const VERSION = '0.2.0'
 
 export {
   Datum,
@@ -35,23 +41,33 @@ export {
   toJSON,
   toText,
   walkDatum,
-} from './datum'
-export type { Duplicates } from './datum'
-export { Code, Fail, isFail } from './error'
-export type { Limit } from './error'
-export { Ev, eventEquals, eventText, isEnd, isScalar, isStart } from './event'
-export type { JsonEvent, JsonEventType } from './event'
-export { isJsonNumber, jsonNumber, jsonString, numberText } from './json'
-export { AbortFlag, LIMIT_NAMES, Limits, Metrics, NODE_BYTES, utf8Bytes } from './limits'
+} from '@tabnas/alchemy/shared'
+export type { Duplicates } from '@tabnas/alchemy/shared'
+export { Code, Fail, isFail } from '@tabnas/alchemy/shared'
+export type { Limit } from '@tabnas/alchemy/shared'
+export { Ev, eventEquals, eventText, isEnd, isScalar, isStart } from '@tabnas/alchemy/shared'
+export type { JsonEvent, JsonEventType } from '@tabnas/alchemy/shared'
+export { isJsonNumber, jsonNumber, jsonString, numberText } from '@tabnas/alchemy/shared'
+export {
+  AbortFlag,
+  LIMIT_NAMES,
+  Limits,
+  Metrics,
+  NODE_BYTES,
+  utf8Bytes,
+} from '@tabnas/alchemy/shared'
 export { Matcher } from './matcher'
-export type { CaptureId, Hit, HitKind } from './matcher'
-export { CaptureSpec, FnRoute, Router, SelectedRecorder } from './route'
-export type { Budget, CaptureMode, RouteSink, Selected } from './route'
-export { ScanEmit, Transition } from './scan'
-export { Path, Selector, keyText, pathText } from './selector'
-export type { Segment, Step } from './selector'
-export { CountSink, EventRecorder, FnSink, TreeContract, replay } from './sink'
-export type { Flow, Sink } from './sink'
+export type { Hit, HitKind } from './matcher'
+export type { CaptureId } from '@tabnas/alchemy/shared'
+export { FnRoute, Router, SelectedRecorder } from './route'
+export { CaptureSpec } from '@tabnas/alchemy/shared'
+export type { Budget, CaptureMode, RouteSink, Selected } from '@tabnas/alchemy/shared'
+export { ScanEmit } from './scan'
+export { Transition } from '@tabnas/alchemy/shared'
+export { Path, Selector, keyText, pathText } from '@tabnas/alchemy/shared'
+export type { Segment, Step } from '@tabnas/alchemy/shared'
+export { CountSink, EventRecorder, FnSink, TreeContract, replay } from '@tabnas/alchemy/shared'
+export type { Flow, Sink } from '@tabnas/alchemy/shared'
 export { Prune, SourceMode, ValueSource, engineFailure, walkValue } from './source'
 export type { Source } from './source'
 export { Guarded } from './guard'
@@ -59,7 +75,7 @@ export { ParserSource } from './parser-source'
 export { DEFAULT_CHUNK_BYTES, LineFormat, LinesSource } from './lines'
 export type { LinesChunk, LinesInput, LinesWriter } from './lines'
 export { INCREMENTAL, capability, isIncremental } from './capability'
-export { Cell, Schema, Table, boundColumn, columnFromMeta } from './table'
+export { Cell, Schema, Table, boundColumn, columnFromMeta } from '@tabnas/alchemy/shared'
 export type {
   BoundColumn,
   ColumnMapper,
@@ -68,5 +84,6 @@ export type {
   TableBinding,
   TableEvent,
   TableSink,
-} from './table'
+} from '@tabnas/alchemy/shared'
 export { TableFromJson } from './table-from-json'
+export { routers } from './routers'

package/dist/datum.d.ts

@@ -1,64 +0,0 @@
-import { JsonEvent } from './event';
-import { Segment } from './selector';
-import { Flow, Sink } from './sink';
-export type Datum = {
-    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: 'array';
-    readonly items: Datum[];
-} | {
-    readonly type: 'object';
-    readonly members: Map<string, Datum>;
-};
-export declare const Datum: Readonly<{
-    null: {
-        readonly type: 'null';
-    };
-    bool(value: boolean): Datum;
-    number(value: number, lexeme?: string | null): Datum;
-    string(value: string): Datum;
-    array(items?: Datum[]): Datum;
-    object(members?: Map<string, Datum> | Iterable<[string, Datum]>): Datum;
-    byteSize: typeof byteSize;
-    getPath: typeof getPath;
-    takePath: typeof takePath;
-    isContainer(d: Datum): boolean;
-    fromTabnas: typeof fromTabnas;
-    toJSON: typeof toJSON;
-    fromJSON: typeof fromJSON;
-    toText: typeof toText;
-}>;
-export declare function byteSize(d: Datum): number;
-export declare function getPath(d: Datum, path: readonly Segment[]): Datum | undefined;
-export declare function takePath(d: Datum, path: readonly Segment[]): Datum | undefined;
-export declare function fromTabnas(value: unknown): Datum;
-export declare function toJSON(d: Datum): unknown;
-export declare function fromJSON(value: unknown): Datum;
-export declare function toText(d: Datum): string;
-export declare function walkDatum(d: Datum, sink: Sink): Flow;
-export type Duplicates = 'reject' | 'last_wins' | 'first_wins';
-export declare class DatumBuilder {
-    private stack;
-    private done;
-    private held;
-    private readonly limit;
-    private readonly limitName;
-    private readonly duplicates;
-    constructor(limit: number, limitName: string, duplicates: Duplicates);
-    bytes(): number;
-    finished(): boolean;
-    take(): Datum | undefined;
-    private charge;
-    private place;
-    event(ev: JsonEvent): void;
-}