@ultimat3/realtime 30.8.0 → 31.0.0

package/src/live-replicator.ts

@@ -6,8 +6,8 @@
 //
 // WHAT IS REAL HERE, and it is everything downstream of the decoder: the matcher, the shared window,
 // the per-subscriber `visible` gate, the cursor, the frames. This substitutes for the WAL DECODER
-// and for nothing else — `@ultimat3/entity`'s `setRowObserver` reports what a repository wrote, in
-// this process, and the events are shaped exactly as `PostgresChangeFeed` shapes them.
+// and for nothing else — `@ultimat3/entity`'s `entity.row` / `entity.bulk` events on core's
+// instrumentation bus report what a repository wrote, in this process, and the events are shaped exactly as `PostgresChangeFeed` shapes them.
 //
 // WHAT IS NOT: a write another process made is invisible, because nothing here reads a log. That is
 // the honest bound, and it is why `selectChangeFeed` never picks it — the boot that installs it
@@ -23,9 +23,10 @@
 // runs in that one process, so the bound above holds by construction — and a real `DATABASE_URL`
 // gets the decoder instead, never both.
 
-import type { RowBulkChange, RowChange, RowObserver } from '@ultimat3/entity';
+import type { EntityBulkEvent, EntityRowEvent } from '@ultimat3/core';
+import { subscribe } from '@ultimat3/core';
 import type { ChangeEvent, ChangeOp } from './changefeed';
-import type { Row } from './json';
+import type { LiveRow } from './json';
 import type { LiveQueryRegistry } from './live-query';
 import { isPublishedTable } from './record-publisher';
 
@@ -57,13 +58,13 @@ export interface LiveReplicator {
 }
 
 /**
- * A `ChangeEvent` row is `Row` — a JSON object carrying an `id`. Every row a repository stores has
- * one; the cast is what says so to a compiler that only sees `Record<string, unknown>`, and a row
+ * A `ChangeEvent` row is `LiveRow` — a JSON object carrying an `id`. Every row a repository
+ * stores has one; the cast is what says so to a compiler that only sees `Record<string, unknown>`, and a row
  * that genuinely has none fails downstream in `idOf`, with the entity named, exactly as a row off
  * the wire would.
  */
-const asRow = (value: Readonly<Record<string, unknown>> | null): Row | null =>
-  value === null ? null : (value as unknown as Row);
+const asRow = (value: Readonly<Record<string, unknown>> | null): LiveRow | null =>
+  value === null ? null : (value as unknown as LiveRow);
 
 /**
  * Lexicographically comparable, which is the whole contract of an lsn — `formatLsn` in
@@ -73,13 +74,13 @@ const asRow = (value: Readonly<Record<string, unknown>> | null): Row | null =>
 const lsnOf = (position: number): string => position.toString(16).padStart(16, '0');
 
 /**
- * Install the replicator for the length of one test. It takes over the process row observer and
- * hands back whatever was installed before, because `bun test` shares one process across files and
- * an unconditional clear would take an outer harness's observer with it.
+ * Install the replicator for the length of one test. It SUBSCRIBES to the bus, so an outer
+ * harness's subscriber — or a second replicator — keeps hearing every write beside it; `stop()`
+ * releases this subscription and nobody else's.
  */
 export async function startLiveReplicator(options: LiveReplicatorOptions): Promise<LiveReplicator> {
-  // Awaited BEFORE the observer exists, so installation is the last thing this function does and
-  // no write between the call and the install can slip past unobserved.
+  // Awaited BEFORE the subscription exists, so subscribing is the last thing this function does and
+  // no write between the call and the subscribe can slip past unobserved.
   const entity = await import('@ultimat3/entity');
   const { registry } = options;
   const tenant = options.tenantColumn ?? 'orgId';
@@ -93,7 +94,7 @@ export async function startLiveReplicator(options: LiveReplicatorOptions): Promi
   /**
    * The RELATION an entity's rows live in — what `ChangeEvent.table` carries on every producer:
    * the WAL decoder reads it off the Relation message, a channel matches `projection.table`, and a
-   * live shape is `from('<table>', …)`. The row observer reports the entity's declared NAME, which
+   * live shape is `from('<table>', …)`. The `entity.row` event reports the entity's declared NAME, which
    * is the table only until an entity adopts one (`entity('ledger', { table: 'gl_entries' })`);
    * passed through, such an entity reached no channel, no window and no bulk re-read here.
    */
@@ -107,8 +108,8 @@ export async function startLiveReplicator(options: LiveReplicatorOptions): Promi
     });
   };
 
-  const observer: RowObserver = {
-    onChange(change: RowChange): void {
+  const handlers = {
+    onChange(change: EntityRowEvent): void {
       if (stopped) return;
       position += 1;
       const at = position;
@@ -147,7 +148,7 @@ export async function startLiveReplicator(options: LiveReplicatorOptions): Promi
      * something", used here for the one write that genuinely does. Silence would be the
      * alternative, and a subscriber told nothing happened diverges with nobody ever asking again.
      */
-    onBulk(change: RowBulkChange): void {
+    onBulk(change: EntityBulkEvent): void {
       if (stopped) return;
       const table = tableOf(change.entity);
       registry.invalidate(table);
@@ -159,7 +160,9 @@ export async function startLiveReplicator(options: LiveReplicatorOptions): Promi
     },
   };
 
-  const previous = entity.setRowObserver(observer);
+  // Handlers never throw: a strict subscriber's throw would reach the repository write.
+  const offRow = subscribe('entity.row', (event) => handlers.onChange(event.payload));
+  const offBulk = subscribe('entity.bulk', (event) => handlers.onBulk(event.payload));
 
   return {
     get delivered() {
@@ -175,9 +178,9 @@ export async function startLiveReplicator(options: LiveReplicatorOptions): Promi
     },
     stop: () => {
       stopped = true;
-      // Restored, never cleared: one process runs every test file, and an outer harness's observer
-      // must survive an inner fixture finishing.
-      entity.setRowObserver(previous);
+      // This replicator's subscriptions only: an outer harness's survive an inner fixture finishing.
+      offRow();
+      offBulk();
     },
   };
 }

package/src/local-store-idb.ts

@@ -6,7 +6,12 @@
  */
 
 import type { ClientScope, RecordRows, Row } from '@ultimat3/core/page';
-import { isJsonObject, renderThrowable, type UltimateError } from '@ultimat3/core/page';
+import {
+  finiteOption,
+  isJsonObject,
+  renderThrowable,
+  type UltimateError,
+} from '@ultimat3/core/page';
 import type { IdbDatabaseLike, IdbFactoryLike, IdbRequestLike } from './idb-types';
 import type { QueueChange, QueuedMutation, QueueState } from './offline-queue';
 import { LocalStoreUnavailableError } from './page-errors';
@@ -239,8 +244,19 @@ export interface OpenLocalStoreOptions {
   /** Where the one fallback warning goes. Default `console.warn`. */
   readonly warn?: ((error: UltimateError) => void) | undefined;
   readonly name?: string | undefined;
+  /**
+   * How long an open `blocked` by another tab's connection waits for that tab to close it before
+   * falling back to memory. Default `DEFAULT_BLOCKED_TIMEOUT_MS`.
+   */
+  readonly blockedTimeoutMs?: number | undefined;
 }
 
+/**
+ * Every tab running this module closes its connection on `versionchange` at once, so a block that
+ * outlives this is a tab on code that does not — one the user has to close.
+ */
+const DEFAULT_BLOCKED_TIMEOUT_MS = 5_000;
+
 /** IndexedDB when the page has it and it opens; memory, warned once, when it does not. */
 export async function openLocalStore(options: OpenLocalStoreOptions = {}): Promise<LocalStore> {
   // The browser's `IDBFactory` IS this shape at runtime; its DOM typings (event-typed handlers)
@@ -248,12 +264,18 @@ export async function openLocalStore(options: OpenLocalStoreOptions = {}): Promi
   const ambient: unknown = Reflect.get(globalThis, 'indexedDB');
   const factory = options.indexedDB ?? (ambient as IdbFactoryLike | undefined);
   const warn = options.warn ?? ((error: UltimateError) => console.warn(error));
+  const blockedMs = finiteOption(
+    'openLocalStore',
+    'blockedTimeoutMs',
+    options.blockedTimeoutMs ?? DEFAULT_BLOCKED_TIMEOUT_MS,
+  );
   if (factory === undefined) {
     warn(new LocalStoreUnavailableError({ reason: 'this runtime has no indexedDB' }));
     return new MemoryLocalStore();
   }
   try {
-    return new IdbLocalStore(await openDatabase(factory, options.name ?? 'ultimate-client'));
+    const name = options.name ?? 'ultimate-client';
+    return new IdbLocalStore(await openDatabase(factory, name, blockedMs));
   } catch (error) {
     warn(
       new LocalStoreUnavailableError({
@@ -264,17 +286,55 @@ export async function openLocalStore(options: OpenLocalStoreOptions = {}): Promi
   }
 }
 
-function openDatabase(factory: IdbFactoryLike, name: string): Promise<IdbDatabaseLike> {
+/**
+ * `blocked` is not a failure: it means another tab still holds an older connection, and the open
+ * goes on to `upgradeneeded` and `success` the moment that tab closes it. Refusing there sent every
+ * new tab to memory on any schema bump, and its offline writes died with it. So the open WAITS,
+ * bounded; and the connection it yields closes itself when a later tab asks for a newer version.
+ */
+function openDatabase(
+  factory: IdbFactoryLike,
+  name: string,
+  blockedMs: number,
+): Promise<IdbDatabaseLike> {
   return new Promise((resolve, reject) => {
     const request = factory.open(name, 1);
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const settle = (): boolean => {
+      if (settled) return false;
+      settled = true;
+      if (timer !== undefined) clearTimeout(timer);
+      return true;
+    };
     request.onupgradeneeded = (): void => {
       const db = request.result;
       if (!db.objectStoreNames.contains(RECORDS)) db.createObjectStore(RECORDS);
       if (!db.objectStoreNames.contains(OUTBOX)) db.createObjectStore(OUTBOX);
     };
-    request.onsuccess = (): void => resolve(request.result);
-    request.onerror = (): void => reject(request.error);
-    request.onblocked = (): void => reject(request.error ?? 'blocked by another open tab');
+    request.onsuccess = (): void => {
+      const db = request.result;
+      // Past the bound this page already runs on memory: a connection nobody uses, held open,
+      // would block the next tab's upgrade exactly as this one was blocked.
+      if (!settle()) {
+        db.close();
+        return;
+      }
+      // Holding on would block that tab; this tab's later writes fail and reject instead.
+      db.onversionchange = (): void => db.close();
+      resolve(db);
+    };
+    request.onerror = (): void => {
+      if (settle()) reject(request.error);
+    };
+    request.onblocked = (): void => {
+      if (settled || timer !== undefined) return;
+      timer = setTimeout(() => {
+        if (!settle()) return;
+        const reason = `blocked by another open tab for ${blockedMs} ms — close the other tabs of this site`;
+        reject(new DOMException(reason, 'TimeoutError'));
+      }, blockedMs);
+    };
   });
 }
 

package/src/matcher-bridge.ts

@@ -10,7 +10,7 @@ import {
   changedColumns,
   isParsedJsonObject,
   type JsonObject,
-  type Row,
+  type LiveRow,
   type RowPatch,
 } from './json';
 
@@ -38,7 +38,7 @@ export const NO_CHANGE: BridgeResult = { patches: [], refill: false };
 export interface IncrementalMatcher {
   readonly entities: readonly string[];
   /** `rows` is the query's current *pre-policy* window, shared by every subscriber of the qid. */
-  match(change: ChangeEvent, rows: readonly Row[]): BridgeResult;
+  match(change: ChangeEvent, rows: readonly LiveRow[]): BridgeResult;
 }
 
 /** The cheap pre-filter. Pure, and the only thing that runs for a change nobody subscribed to. */
@@ -58,7 +58,7 @@ export function bridgeChange(
   shape: SubscriptionShape,
   incremental: IncrementalMatcher,
   change: ChangeEvent,
-  rows: readonly Row[],
+  rows: readonly LiveRow[],
 ): BridgeResult | null {
   if (!canAffect(shape, change)) return null;
   const result = incremental.match(change, rows);
@@ -94,7 +94,7 @@ export function matcherFor(live: LiveQuery, projection?: () => Projection): Incr
       if (change.op === 'truncate') return { patches: [], refill: true };
       const row = change.after ?? change.before;
       if (!row) return NO_CHANGE;
-      const patches = match<Row>(live.name, live.shape, rows, {
+      const patches = match<LiveRow>(live.name, live.shape, rows, {
         entity: change.table,
         op: change.op,
         row,
@@ -116,18 +116,18 @@ export function matcherFor(live: LiveQuery, projection?: () => Projection): Incr
 export type Projection = ReadonlySet<string> | undefined;
 
 /** The projection a window's own rows describe. Empty window, no answer. */
-export const projectionOf = (rows: readonly Row[]): Projection =>
+export const projectionOf = (rows: readonly LiveRow[]): Projection =>
   rows[0] === undefined ? undefined : new Set(Object.keys(rows[0]));
 
 /**
  * One row, restricted to the columns the result set carries.
  *
- * A `ChangeEvent` carries the whole TABLE row — that is what logical replication emits and what
- * `setRowObserver` emits — while a live query's result set is whatever its `sql` returned. Sending
- * the change row through unnarrowed put every column of the table on the socket, including the ones
- * a projection exists to withhold: `examples/dummy`'s feed projects ten columns and a single publish
- * delivered `body` to every subscriber. The per-subscriber gate cannot help — it decides whether a
- * ROW is delivered, never which of its columns.
+ * A `ChangeEvent` carries the whole TABLE row — that is what logical replication emits and what an
+ * `entity.row` event carries — while a live query's result set is whatever its `sql` returned.
+ * Sending the change row through unnarrowed put every column of the table on the socket, including
+ * the ones a projection exists to withhold: `examples/dummy`'s feed projects ten columns and a
+ * single publish delivered `body` to every subscriber. The per-subscriber gate cannot help — it
+ * decides whether a ROW is delivered, never which of its columns.
  *
  * `id` always survives: it is the row's identity on the wire, and `applyToWindow` and every client
  * store key by it.
@@ -141,9 +141,9 @@ export function narrowRow(row: JsonObject, projection: Projection): JsonObject {
   return out;
 }
 
-/** `Patch<Row>` (add/update/remove/refill, positional) -> the wire's `RowPatch`. */
+/** `Patch<LiveRow>` (add/update/remove/refill, positional) -> the wire's `RowPatch`. */
 export function toBridgeResult(
-  patches: readonly Patch<Row>[],
+  patches: readonly Patch<LiveRow>[],
   change: ChangeEvent,
   projection?: Projection,
 ): BridgeResult {
@@ -184,7 +184,7 @@ export function toBridgeResult(
 }
 
 /** Applies patches to the shared pre-policy window so the matcher sees the current result set. */
-export function applyToWindow(rows: readonly Row[], patches: readonly RowPatch[]): Row[] {
+export function applyToWindow(rows: readonly LiveRow[], patches: readonly RowPatch[]): LiveRow[] {
   const next = [...rows];
   for (const patch of patches) {
     const index = next.findIndex((row) => row.id === patch.id);
@@ -194,7 +194,7 @@ export function applyToWindow(rows: readonly Row[], patches: readonly RowPatch[]
     }
     if (patch.row === null) continue;
     const current = index >= 0 ? next[index] : undefined;
-    const merged: Row = { ...(current ?? {}), ...patch.row, id: patch.id };
+    const merged: LiveRow = { ...(current ?? {}), ...patch.row, id: patch.id };
     if (index >= 0) next[index] = merged;
     else if (patch.index !== undefined) next.splice(patch.index, 0, merged);
     else next.push(merged);

package/src/nats-transport.ts

@@ -26,7 +26,7 @@ import { NatsKvSet } from './nats-kv';
 import { openNatsClient } from './nats-open';
 import { NatsReports } from './nats-reports';
 import { NatsSubscriptions } from './nats-subscriptions';
-import { type BackoffPolicy, defaultBackoff, policyDelay, type Rng } from './thundering-herd';
+import { defaultBackoff, policyDelay, type ReconnectBackoff, type Rng } from './thundering-herd';
 
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
@@ -36,7 +36,7 @@ export interface NatsTransportOptions {
   /** KV bucket backing `shared`. Created on first connect when the cluster has none. */
   readonly bucket: string;
   readonly maxReconnectAttempts?: number;
-  readonly backoff?: BackoffPolicy;
+  readonly backoff?: ReconnectBackoff;
   readonly clock?: Clock;
   /** Presence TTL, only as the floor for the bucket's whole-stream age limit. */
   readonly presenceTtlMs?: number;
@@ -70,7 +70,7 @@ export class NatsTransport implements Transport {
   readonly shared: TransportSet;
   readonly #options: NatsTransportOptions;
   readonly #connect: NatsConnect;
-  readonly #backoff: BackoffPolicy;
+  readonly #backoff: ReconnectBackoff;
   readonly #attempts: number;
   readonly #rng: Rng;
   #client: NatsClient | undefined;
@@ -355,7 +355,7 @@ export class NatsTransport implements Transport {
   /**
    * Dial until a client is up or the transport is closed — the first dial of a process that does
    * not wait for the bus, and the replacement of a client the library gave up on. One loop however
-   * many callers ask. Bounded by our backoff between attempts (capped at the policy's `maxMs`), so
+   * many callers ask. Bounded by our backoff between attempts (capped at the policy's `max`), so
    * a long outage costs one dial per interval rather than a spin. A dial that lands re-binds every
    * kept subscription and is announced: changes published in the gap are gone.
    */
@@ -398,7 +398,7 @@ export class NatsTransport implements Transport {
     }
   }
 
-  /** A wait `close()` can cut short, so a closed transport never holds a timer for `maxMs`. */
+  /** A wait `close()` can cut short, so a closed transport never holds a timer for `max`. */
   #pause(ms: number): Promise<void> {
     return new Promise((resolve) => {
       const done = (): void => {

package/src/offline-queue-store.ts

@@ -0,0 +1,69 @@
+// Single responsibility: what the durable mutation queue IS on disk — an entry, a queue's state,
+// one keyed change to it — and the in-memory store tests and SSR run it on. The queue's rules
+// (order, dedupe, only the server removes) are `offline-queue.ts`'s, which re-exports these.
+
+import type { ActionPin } from '@ultimat3/core/page';
+import type { JsonValue } from './json';
+import type { WireError } from './sync-protocol';
+
+export type MutationStatus = 'pending' | 'inflight' | 'acked' | 'failed';
+
+export interface QueuedMutation {
+  /** Idempotency key. Supplied by the mutator, stable across retries and reloads. */
+  readonly key: string;
+  /** Monotonic per client. Never renumbered — rebase replays in this order. */
+  readonly seq: number;
+  readonly name: string;
+  readonly input: JsonValue;
+  /** The action's `http` pin, when the write was made against one (`pinned-wire.ts`). */
+  readonly http?: ActionPin | undefined;
+  readonly enqueuedAt: number;
+  attempts: number;
+  status: MutationStatus;
+  error: WireError | null;
+}
+
+export interface QueueState {
+  readonly mutations: readonly QueuedMutation[];
+  readonly nextSeq: number;
+}
+
+/**
+ * One change to the durable queue: these entries written BY KEY, these keys deleted, and the
+ * sequence floor. Never the whole queue — two tabs of one user share the store, and a whole-queue
+ * save let the last tab to save erase the other's queued write.
+ */
+export interface QueueChange {
+  readonly puts: readonly QueuedMutation[];
+  readonly deletes: readonly string[];
+  readonly nextSeq: number;
+}
+
+/** Durability seam: IndexedDB in the browser (`page-outbox.ts`), memory in tests. */
+export interface QueueStore {
+  load(): Promise<QueueState>;
+  write(change: QueueChange): Promise<void>;
+}
+
+export class MemoryQueueStore implements QueueStore {
+  readonly #mutations = new Map<string, QueuedMutation>();
+  #nextSeq = 1;
+
+  async load(): Promise<QueueState> {
+    return {
+      mutations: [...this.#mutations.values()].map((m) => ({ ...m })),
+      nextSeq: this.#nextSeq,
+    };
+  }
+
+  async write(change: QueueChange): Promise<void> {
+    for (const key of change.deletes) this.#mutations.delete(key);
+    for (const mutation of change.puts) this.#mutations.set(mutation.key, { ...mutation });
+    this.#nextSeq = Math.max(this.#nextSeq, change.nextSeq);
+  }
+}
+
+/** The one way to build the in-process queue store; the class is a type in the barrel only (`X_FACTORY_NAME_SPELLING`). */
+export function memoryQueueStore(): MemoryQueueStore {
+  return new MemoryQueueStore();
+}