@toclocoinc/lattice-grid 1.63.2 → 1.64.0

package/modules/data-router.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Lattice Grid 1.63.2, data-router module type declarations
+ * Lattice Grid 1.64.0, data-router module type declarations
  * Copyright (c) 2026 TOCLOCO Inc. All rights reserved.
  * https://latticegrid.dev
  */
@@ -9,25 +9,89 @@
  */
 type RouterRecord = Record<string, unknown>;
 
+/** A property name, or a function reading the value off a row. */
+type RouterKey = string | ((row: RouterRecord) => unknown);
+
 /** A per-route diff summary returned by `load`. */
 interface RouteDiff { added: number; updated: number; removed: number }
 
-/** A predicate: a property value (`row[key] === value`) or a `fn(row)`. */
-type RoutePredicate = unknown | ((row: RouterRecord) => boolean);
+/**
+ * What a route matches: a partition VALUE (the record is routed when
+ * `row[key] === value`), or a `fn(row)` predicate for a composite route.
+ * Declared as `unknown` because any value can be a partition key; the
+ * function form is the only one TypeScript can check.
+ */
+type RoutePredicate = unknown;
+
+/** A route's `sort`: a comparator, or a key and direction (`'asc'` unless `'desc'`). */
+type RouteSort = ((a: RouterRecord, b: RouterRecord) => number) | { key: string; dir?: 'asc' | 'desc' };
+
+/**
+ * One incremental change: `upsert` adds or updates the row by `rowKey`,
+ * `delete` removes it. `seq` versions the delta when the row itself carries
+ * no version field (the router's `seq` option names one that does).
+ */
+interface RouterDelta { op: 'upsert' | 'delete'; row: RouterRecord; seq?: number }
+
+/** The change a `subscribe` handler receives: the same keyed diff a grid gets. */
+interface RouterChange { add: RouterRecord[]; update: RouterRecord[]; remove: string[] }
+
+/**
+ * A filter-wire condition for a route's `where` (v7): `{ col, op, value }`,
+ * or an `and` / `or` / `not` group of them.
+ */
+type RouteWhere = Record<string, unknown>;
+
+/**
+ * A rollup route's summary spec (v3): one summary row per `groupBy` group,
+ * each `aggregate` a named reducer over the group's rows or a `{ op, field }`
+ * shorthand (`sum`, `avg`, `min`, `max`, `count`).
+ */
+interface RouteRollup {
+  groupBy: RouterKey | RouterKey[];
+  aggregate?: Record<string, ((rows: RouterRecord[]) => unknown) | { op: string; field?: string }>;
+}
+
+/**
+ * A route's backpressure policy (v13): how its viewer is refreshed under load.
+ * `maxHz` or `minInterval` caps the refresh rate; `sample` repaints only once
+ * N changes have accrued; `maxLag` is the backlog depth at or below which
+ * changes pass straight through and the limits stay off. All optional.
+ */
+interface RouteBackpressure { maxHz?: number; minInterval?: number; sample?: number; maxLag?: number }
+
+/** A write captured off a writable route's grid, handed to `onWrite`. */
+type RouterWrite = Record<string, unknown>;
 
 /**
- * Per-route reshaping options (v3, BACKLOG-0000887): `transform` maps/renames/
- * derives each row before the grid sees it; `filter` gives the grid only the
- * rows it admits; `sort` (a comparator or `{ key, dir }`) orders what the grid
- * receives. `rowKey` overrides the router default. All optional.
+ * Per-route options, shared by `attach`, `attachDefault` and `subscribe`.
+ * `rowKey` overrides the router default for this route. `transform` reshapes
+ * each row before the viewer sees it; `filter` admits a subset; `sort`
+ * orders what the viewer receives; `rollup` summarises the slice (v3). A
+ * `transform` or `rollup` route is derived and cannot be `writable`. `where`
+ * is read only by `query()` (v7). `writable` routes the grid's committed
+ * edits to `onWrite`, reverting on reject, with `onConflict` for a last-
+ * write-wins conflict (v8); both default to the router's own. `label` names
+ * the route in metrics and the devtools panel; `backpressure` throttles its
+ * refresh under load (v13).
  */
 interface RouteOptions {
-  rowKey?: (string | ((row: RouterRecord) => unknown));
+  rowKey?: RouterKey;
   transform?: (row: RouterRecord) => RouterRecord;
   filter?: (row: RouterRecord) => boolean;
-  sort?: (((a: RouterRecord, b: RouterRecord) => number) | { key: string; dir?: 'asc' | 'desc' });
+  sort?: RouteSort;
+  rollup?: RouteRollup;
+  where?: RouteWhere;
+  writable?: boolean;
+  onWrite?: (change: RouterWrite, ctx: { route: unknown; source: unknown }) => unknown;
+  onConflict?: (change: RouterWrite, ctx: { serverRow: RouterRecord }) => void;
+  label?: string;
+  backpressure?: RouteBackpressure;
 }
 
+/** Per-alert options (v5): `filter` narrows the slice; `debounce` (ms) coalesces a burst into one emit. */
+interface AlertOptions { rowKey?: RouterKey; filter?: (row: RouterRecord) => boolean; debounce?: number }
+
 /**
  * A cross-grid selection relation (v2, BACKLOG-0000880): a key map (target
  * rows whose `to` value is among the selected source rows' `from` values — an
@@ -38,6 +102,137 @@ type SelectionRelation =
   | { from: string; to: string }
   | ((selected: RouterRecord[]) => ((row: RouterRecord) => boolean));
 
+/**
+ * One edge of a relationship graph (v3): the source grid whose selection
+ * filters the target. `on` (or `relation`) is the relation; `mutual` makes
+ * the edge work in both directions.
+ */
+interface RouterEdge { from: unknown; to: unknown; on?: SelectionRelation; relation?: SelectionRelation; mutual?: boolean }
+
+/**
+ * A declarative routing graph (v5, BACKLOG-0000910): the same routes, links,
+ * relationship edges and buffer the imperative calls would make, as one data
+ * spec. Desugars to those calls and composes with them.
+ */
+interface RouterConfig {
+  routes?: Record<string, unknown>[];
+  links?: { from: unknown; to: unknown; on?: SelectionRelation; relation?: SelectionRelation }[];
+  relate?: RouterEdge[];
+  buffer?: { window?: number; max?: number };
+}
+
+/**
+ * A fan-in source's lookup join (v11): `from` is the lookup source's id;
+ * `localKey` (alias `on`) reads the joining value off this source's row;
+ * `foreignKey` (alias `fromKey`) reads it off the lookup row, defaulting to a
+ * string `localKey`; `fields` (alias `select`) picks the lookup fields to
+ * carry — a list, a rename map, or a function of both rows; `missing` says
+ * what to do while the lookup row has not arrived: `hold` the row back,
+ * `passthrough` it unjoined, or fill the fields with `null`.
+ */
+interface RouterJoin {
+  from: string;
+  localKey?: RouterKey;
+  on?: RouterKey;
+  foreignKey?: RouterKey;
+  fromKey?: RouterKey;
+  fields?: string[] | Record<string, string> | ((lookupRow: RouterRecord | null, leftRow: RouterRecord) => RouterRecord);
+  select?: string[] | Record<string, string> | ((lookupRow: RouterRecord | null, leftRow: RouterRecord) => RouterRecord);
+  missing?: 'hold' | 'passthrough' | 'null';
+}
+
+/**
+ * Options for a fan-in source (v9): `map` normalises each of the feed's rows
+ * before routing; `key` namespaces the feed's identities (`true` prefixes
+ * the source id) so feeds with colliding ids do not clobber one another;
+ * `join` enriches rows from another registered source (v11).
+ */
+interface RouterSourceOptions { id?: string; map?: (row: RouterRecord) => RouterRecord; key?: unknown; join?: RouterJoin }
+
+/**
+ * The handle `addSource` returns for one feed (v9). Its `load` is a
+ * per-source snapshot — a keyed diff over this feed's rows only, other feeds
+ * untouched; `apply` and `push` take this feed's deltas through the router's
+ * ordinary and batched paths; `remove` deletes exactly the rows it holds and
+ * unregisters it, returning the router.
+ */
+interface RouterSourceHandle {
+  /** The source id. */
+  readonly id: string;
+  /** How many rows this source currently holds live. */
+  readonly size: number;
+  /** Apply a per-source snapshot: upsert its current rows, delete the ones it no longer has. */
+  load(rows: RouterRecord[]): RouterSourceHandle;
+  /** Apply per-source deltas through the router's ordinary apply path. */
+  apply(deltas: RouterDelta[]): RouterSourceHandle;
+  /** Enqueue per-source deltas through the router's stream path (batching honoured). */
+  push(delta: RouterDelta | RouterDelta[]): RouterSourceHandle;
+  /** Remove this source: delete exactly the rows it holds from every route, then unregister it. */
+  remove(): DataRouter;
+}
+
+/** One route's figures in a `metrics()` snapshot (v10). */
+interface RouterRouteMetrics {
+  label: string | null;
+  rows: number;
+  shown: number;
+  throughput: number;
+  [key: string]: unknown;
+}
+
+/** One source's figures in a `metrics()` snapshot (v10). */
+interface RouterSourceMetrics { id: string; rows: number; throughput: number; [key: string]: unknown }
+
+/**
+ * A `metrics()` snapshot (v10): per-route and per-source counts and
+ * throughput (rows/sec since the previous read), and the global unrouted,
+ * dropped (duplicate), buffered and lag figures.
+ */
+interface RouterMetrics {
+  routes: RouterRouteMetrics[];
+  sources: RouterSourceMetrics[];
+  unrouted: number;
+  dropped: number;
+  buffered: number;
+  lag: number;
+  throughput: number;
+}
+
+/**
+ * One entry of `lastQueryPlan()` (v7): a `where` route's fetch, or the single
+ * `base` fetch that fed every route without a `where`. `pushedFilter` says
+ * whether the filter reached the engine; `residual` is what was finished
+ * client-side.
+ */
+interface RouterQueryPlanEntry { route?: unknown; base?: boolean; pushedFilter: boolean; residual: unknown }
+
+/** The controller `mountDevtools` returns: `refresh` re-renders now, `destroy` unsubscribes and removes the panel. */
+interface RouterDevtoolsPanel { refresh(): void; destroy(): void }
+
+/**
+ * A pushdown adapter `query()` can source the router from (v7): anything
+ * with an `execute(query, request)` returning rows, and optional
+ * `capabilities` the planner consults to decide what it may push down.
+ */
+interface RouterQueryAdapter {
+  capabilities?: Record<string, unknown>;
+  execute: (query: Record<string, unknown>, request?: Record<string, unknown>) => Promise<{ rows: RouterRecord[]; total?: number }>;
+}
+
+/**
+ * Durable persistence options (v12): `key` names the snapshot, `debounce`
+ * (ms) coalesces writes, `storage` is a `{ get, set }` pair of your own, or
+ * `indexedDB` / `dbName` / `storeName` select the browser store.
+ */
+interface RouterPersistOptions {
+  key?: string;
+  debounce?: number;
+  storage?: { get: (key: string) => Promise<unknown>; set: (key: string, value: unknown) => Promise<void> };
+  indexedDB?: unknown;
+  dbName?: string;
+  storeName?: string;
+}
+
 /**
  * A data router: one arriving stream, partitioned by a property (or composite
  * predicate), fanned out to a grid per partition (BACKLOG-0000879). Each grid
@@ -47,16 +242,16 @@ type SelectionRelation =
  * update or remove in place by `rowKey`, preserving selection and scroll.
  */
 interface DataRouter {
-  /** Attach a grid behind a predicate; `opts` may reshape/filter/sort the route (v3). */
+  /** Attach a grid behind a predicate; `opts` may reshape, filter, sort, summarise or throttle the route. */
   attach(grid: unknown, predicate: RoutePredicate, opts?: RouteOptions): DataRouter;
-  /** Attach the "rest" sink for records no explicit route matched. */
+  /** Attach the "rest" sink for records no explicit route matched. A second call replaces the first. */
   attachDefault(grid: unknown, opts?: RouteOptions): DataRouter;
-  /** Detach a grid; the host still owns and destroys it. */
-  detach(grid: unknown): DataRouter;
-  /** Apply a full snapshot as a keyed diff per grid; returns per-route counts. */
-  load(snapshot: RouterRecord[]): RouteDiff[];
-  /** Apply incremental deltas, routed and applied in place by `rowKey`. */
-  apply(deltas: { op: 'upsert' | 'delete'; row: RouterRecord }[]): void;
+  /** Route a partition slice to any non-grid view (v5): the handler receives the same keyed diff a grid would. */
+  subscribe(predicate: RoutePredicate, handler: (change: RouterChange) => void, opts?: RouteOptions): DataRouter;
+  /** Watch a slice and emit on a rising edge of `condition` rather than render (v5). Removed only by `destroy`. */
+  alert(predicate: RoutePredicate, condition: (rows: RouterRecord[]) => unknown, handler: (signal: unknown, rows: RouterRecord[]) => void, opts?: AlertOptions): DataRouter;
+  /** Take the whole routing graph as one declarative spec (v5); desugars to the calls above and composes with them. */
+  configure(spec?: RouterConfig): DataRouter;
   /**
    * Link a source grid's selection to what a target grid receives (v2,
    * BACKLOG-0000880): the target shows the subset of its partition the
@@ -64,28 +259,116 @@ interface DataRouter {
    * shows the full partition; changes are debounced.
    */
   link(source: unknown, target: unknown, relation: SelectionRelation): DataRouter;
+  /** Declare a relationship graph (v3): multi-hop, several-into-one and mutual edges — the scalable form of `link`. */
+  relate(edges: RouterEdge[]): DataRouter;
   /** Apply any debounced selection refilter synchronously (for tests/determinism). */
   flush(): DataRouter;
-  /** How many records matched no route. */
+  /** Detach a grid — or a `subscribe` handler — and drop any link it is part of; the host still owns and destroys it. */
+  detach(grid: unknown): DataRouter;
+  /** Apply a full snapshot as a keyed diff per grid; returns per-route counts. Resets `unrouted`. */
+  load(snapshot: RouterRecord[]): RouteDiff[];
+  /** Apply incremental deltas, routed and applied in place by `rowKey`; ordered and de-duplicated when `seq` is on. */
+  apply(deltas: RouterDelta[]): void;
+  /** Enqueue deltas for batched or coalesced application (v3); applies at once when no batching mode is on. */
+  push(delta: RouterDelta | RouterDelta[]): DataRouter;
+  /** Apply the buffered deltas now as a single `apply` (v3) — a deterministic point, and for tests. */
+  flushStream(): DataRouter;
+  /** Refresh every backpressured route to the latest state now (v13); a no-op with nothing pending. */
+  flushBackpressure(): DataRouter;
+  /** Register a source feed for fan-in (v9): its rows are normalised and namespaced into the one keyed store. */
+  addSource(feed: string | RouterSourceOptions, opts?: RouterSourceOptions): RouterSourceHandle;
+  /** Remove a source feed by id or handle (v9): delete exactly its rows from every route, then unregister it. */
+  removeSource(ref: string | RouterSourceHandle): DataRouter;
+  /** The registered source ids (v9). */
+  sources(): string[];
+  /** A cheap point-in-time snapshot of the router's runtime (v10); throughput is measured since the previous read. */
+  metrics(): RouterMetrics;
+  /** Subscribe to the periodic `metrics` emit (v10) — the only event; the timer runs only while a listener is registered. Returns the unsubscribe. */
+  on(event: 'metrics', handler: (snapshot: RouterMetrics) => void): () => void;
+  /** Mount the live devtools panel into `el` (v10); it re-renders on each `metrics` emit. */
+  mountDevtools(el: unknown): RouterDevtoolsPanel;
+  /** How many records matched no route since the last `load` or `query`, running for deltas. */
   readonly unrouted: number;
+  /** How many stale or duplicate deltas the dedupe gate dropped since creation (v3). */
+  readonly dropped: number;
+  /** The highest seq applied — the resume point to request the feed from after a dropped socket (v3). */
+  lastSeq(): number | undefined;
+  /** A copy of the per-record resume checkpoint: record identity → last applied seq (v3). */
+  checkpoint(): Map<string, number>;
+  /** Prime the resume checkpoint from a persisted one, so replayed deltas at or below those seqs are dropped (v3). */
+  seenThrough(mark: Map<string, number> | Record<string, number>): DataRouter;
+  /** Turn on durable persistence of the router's state (v12). */
+  persist(opts?: RouterPersistOptions): DataRouter;
+  /** Resume from the durable snapshot (v12); resolves true when one was found and applied. */
+  restore(): Promise<boolean>;
+  /** Flush any pending durable write now (v12); resolves once it has settled. */
+  flushPersist(): Promise<DataRouter>;
+  /** Whether durable persistence is on and not degraded to in-memory (v12). */
+  readonly persisting: boolean;
+  /** Record the stream into a bounded ring for time travel (v4): a time `window` in ms and/or a `max` delta count. */
+  buffer(opts?: { window?: number; max?: number }): DataRouter;
+  /** Scrub the attached grids to a past seq or timestamp (v4). */
+  scrubTo(target: number, opts?: { by?: 'seq' | 'time' }): DataRouter;
+  /** Replay a buffered range step by step (v4); resolves when it completes or is superseded. */
+  replay(from: number, to: number, opts?: { speed?: number; by?: 'seq' | 'time' }): Promise<void>;
+  /** Pause an in-flight replay at the current step (v4); a no-op when nothing is replaying. */
+  pause(): DataRouter;
+  /** Resume a paused replay from where it stopped (v4); a no-op when not paused. */
+  resume(): DataRouter;
+  /** Return to live (v4): rebuild the head from the base plus every buffered delta. */
+  live(): DataRouter;
+  /** Whether the grids are currently showing a reconstructed past (v4). */
+  readonly traveling: boolean;
+  /** How many deltas the bounded buffer currently holds (v4). */
+  readonly buffered: number;
+  /** Mirror the ordered, de-duplicated deltas to other tabs over a BroadcastChannel (v6), with no echo loop. */
+  broadcast(opts: { channel: string }): DataRouter;
+  /** Whether the router is mirroring to a BroadcastChannel (v6). */
+  readonly broadcasting: boolean;
+  /** Source the router from a pushdown adapter (v7): each `where` route is planned against the adapter's capabilities. */
+  query(adapter: RouterQueryAdapter, request?: Record<string, unknown>): Promise<DataRouter>;
+  /** The pushed/residual split of the last `query()` (v7), per fetch, or null before any. */
+  lastQueryPlan(): RouterQueryPlanEntry[] | null;
   /** Detach every grid and drop every link (the host destroys the grids themselves). */
   destroy(): void;
 }
 
 /**
- * Create a data router that partitions one stream to many grids.
- *
- * `key` is the partition property or `fn(row)`; `rowKey` is the identity within
- * a grid; `overlap` fans a record to every matching route (default: first match
- * wins); `onUnrouted` receives records that match none; `selectionDebounce` is
- * the debounce in ms for cross-grid selection refilters (default 16; `0` is
- * synchronous).
+ * Options for `createDataRouter`. `key` is the partition property or
+ * `fn(row)`; optional, since a router whose routes all use `fn(row)`
+ * predicates never reads it. `rowKey` is the identity within a grid;
+ * `overlap` fans a record to every matching route (default: first match
+ * wins); `onUnrouted` receives what matched no route — the row on `load` and
+ * `query`, the whole delta on `apply`; `selectionDebounce` is the ms
+ * debounce for cross-grid selection refilters (default 16; `0` is
+ * synchronous). `seq` names the per-record version that orders and
+ * de-duplicates a feed (v3), `dedupe` (default on with `seq`) drops stale
+ * and duplicate deltas; `batch` (ms, or `{ intervalMs }`) and `coalesce`
+ * buffer a high-frequency feed for `push`; `time` reads a row's timestamp
+ * for time-domain scrubbing and `now` overrides the clock (v4); `config` is
+ * a declarative routing graph applied at construction (v5); `onWrite` and
+ * `onConflict` are the defaults for every writable route (v8);
+ * `metricsInterval` is the ms between `metrics` emits (default 1000; `0`
+ * disables the timer) (v10).
  */
-export function createDataRouter(opts: {
-  key: (string | ((row: RouterRecord) => unknown));
-  rowKey?: (string | ((row: RouterRecord) => unknown));
+interface DataRouterOptions {
+  key?: RouterKey;
+  rowKey?: RouterKey;
   overlap?: boolean;
-  onUnrouted?: (item: unknown) => void;
+  onUnrouted?: (item: RouterRecord | RouterDelta) => void;
   selectionDebounce?: number;
-}): DataRouter;
+  seq?: RouterKey;
+  dedupe?: boolean;
+  batch?: number | { intervalMs: number };
+  coalesce?: boolean;
+  time?: RouterKey;
+  now?: () => number;
+  config?: RouterConfig;
+  onWrite?: (change: RouterWrite, ctx: { route: unknown; source: unknown }) => unknown;
+  onConflict?: (change: RouterWrite, ctx: { serverRow: RouterRecord }) => void;
+  metricsInterval?: number;
+}
+
+/** Create a data router that partitions one stream to many grids. */
+export function createDataRouter(opts?: DataRouterOptions): DataRouter;
 export default createDataRouter;