@ultimat3/realtime 1.0.0

package/src/local-store.ts

@@ -0,0 +1,188 @@
+// Tier 3: the durable local store a `mutator`'s `local(tx, input)` half writes to.
+//
+// `local` must be replayable — no I/O, no Date.now(), no Math.random() — because rebase replays it.
+// That is why every write goes through a journal keyed by the mutation's idempotency key: rollback
+// is "undo this key's journal in reverse", not "re-fetch and hope".
+
+import { NotImplementedError } from './errors';
+import type { JsonObject, Row } from './json';
+
+export interface LocalTable<R extends Row = Row> {
+  get(id: string): R | undefined;
+  all(): readonly R[];
+  insert(row: R): void;
+  upsert(row: R): void;
+  /** `patch` returns changed fields only, mirroring the canonical mutator example. */
+  update(id: string, patch: (row: R) => Partial<R>): void;
+  delete(id: string): void;
+}
+
+export type TableMap = Record<string, Row>;
+
+/**
+ * The transaction handle passed to `local`. In a generated app the table map comes from the app's
+ * entities, so `tx.posts` is a real property with a real row type — never an index signature.
+ */
+export type LocalTx<T extends TableMap = TableMap> = { readonly [K in keyof T]: LocalTable<T[K]> };
+
+interface JournalEntry {
+  readonly table: string;
+  readonly id: string;
+  /** Row state before the write; `undefined` means "did not exist" (so undo = delete). */
+  readonly before: Row | undefined;
+}
+
+export interface LocalStore<T extends TableMap = TableMap> {
+  readonly tx: LocalTx<T>;
+  table(name: string): LocalTable;
+  /** Runs `fn` while journalling every write under `key`, so it can be rolled back verbatim. */
+  apply(key: string, fn: (tx: LocalTx<T>) => void): void;
+  /** Undo one key's writes, newest first. Used by rebase before reapplying pending mutations. */
+  rollback(key: string): void;
+  /** Server confirmed: drop the journal. After this the write is no longer optimistic. */
+  commit(key: string): void;
+  pendingKeys(): readonly string[];
+  snapshot(name: string): readonly Row[];
+  reset(tables: Readonly<Record<string, readonly Row[]>>): void;
+}
+
+/**
+ * The reference implementation. Every rule in the tier-3 contract (journalling, ordered undo, key
+ * scoping) is implemented here; OPFS SQLite swaps the storage, not the semantics.
+ */
+export class MemoryLocalStore<T extends TableMap = TableMap> implements LocalStore<T> {
+  readonly #tables = new Map<string, Map<string, Row>>();
+  readonly #journals = new Map<string, JournalEntry[]>();
+  #recordingKey: string | null = null;
+
+  readonly tx: LocalTx<T>;
+
+  constructor(tables: Readonly<Record<string, readonly Row[]>> = {}) {
+    this.reset(tables);
+    const handler: ProxyHandler<Record<string, LocalTable>> = {
+      // Symbols (`Symbol.iterator`, `then`) must not resolve to a table, or awaiting a tx would
+      // silently create one.
+      get: (_target, property) => (typeof property === 'symbol' ? undefined : this.table(property)),
+    };
+    this.tx = new Proxy({} as Record<string, LocalTable>, handler) as LocalTx<T>;
+  }
+
+  table(name: string): LocalTable {
+    const rows = this.#rows(name);
+    return {
+      get: (id) => rows.get(id),
+      all: () => [...rows.values()],
+      insert: (row) => {
+        this.#journal(name, row.id, rows.get(row.id));
+        rows.set(row.id, row);
+      },
+      upsert: (row) => {
+        const current = rows.get(row.id);
+        this.#journal(name, row.id, current);
+        rows.set(row.id, { ...(current ?? {}), ...row });
+      },
+      update: (id, patch) => {
+        const current = rows.get(id);
+        if (!current) return;
+        this.#journal(name, id, current);
+        rows.set(id, merge(current, patch(current)));
+      },
+      delete: (id) => {
+        const current = rows.get(id);
+        if (!current) return;
+        this.#journal(name, id, current);
+        rows.delete(id);
+      },
+    };
+  }
+
+  apply(key: string, fn: (tx: LocalTx<T>) => void): void {
+    const previous = this.#recordingKey;
+    this.#recordingKey = key;
+    if (!this.#journals.has(key)) this.#journals.set(key, []);
+    try {
+      fn(this.tx);
+    } finally {
+      this.#recordingKey = previous;
+    }
+  }
+
+  rollback(key: string): void {
+    const journal = this.#journals.get(key);
+    if (!journal) return;
+    for (let i = journal.length - 1; i >= 0; i -= 1) {
+      const entry = journal[i];
+      if (!entry) continue;
+      const rows = this.#rows(entry.table);
+      if (entry.before === undefined) rows.delete(entry.id);
+      else rows.set(entry.id, entry.before);
+    }
+    this.#journals.delete(key);
+  }
+
+  commit(key: string): void {
+    this.#journals.delete(key);
+  }
+
+  pendingKeys(): readonly string[] {
+    return [...this.#journals.keys()];
+  }
+
+  snapshot(name: string): readonly Row[] {
+    return [...this.#rows(name).values()];
+  }
+
+  reset(tables: Readonly<Record<string, readonly Row[]>>): void {
+    this.#tables.clear();
+    this.#journals.clear();
+    for (const [name, rows] of Object.entries(tables)) {
+      this.#tables.set(name, new Map(rows.map((row) => [row.id, row])));
+    }
+  }
+
+  #rows(name: string): Map<string, Row> {
+    const existing = this.#tables.get(name);
+    if (existing) return existing;
+    const created = new Map<string, Row>();
+    this.#tables.set(name, created);
+    return created;
+  }
+
+  /** Only the *first* write to a row within one key is journalled — undo must reach the base state. */
+  #journal(table: string, id: string, before: Row | undefined): void {
+    const key = this.#recordingKey;
+    if (key === null) return;
+    const journal = this.#journals.get(key);
+    if (!journal) return;
+    if (journal.some((entry) => entry.table === table && entry.id === id)) return;
+    journal.push(before === undefined ? { table, id, before: undefined } : { table, id, before });
+  }
+}
+
+/** `undefined` in a patch means "leave it alone" — a row column is never set to undefined. */
+function merge(row: Row, patch: Partial<Row>): Row {
+  const next: JsonObject = { ...row };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value !== undefined) next[key] = value;
+  }
+  return { ...next, id: row.id };
+}
+
+export interface OpfsLocalStoreOptions {
+  /** OPFS file name, versioned so a client-side migration can run before first read. */
+  readonly file: string;
+  readonly schemaVersion: number;
+}
+
+/**
+ * The production tier-3 store: SQLite over the Origin Private File System, opened in a worker so a
+ * long write never blocks the main thread. Browser-only, so it must not be reachable from a server
+ * bundle — which is why it is a factory that throws rather than a class you can accidentally new
+ * on the server.
+ */
+export function createOpfsLocalStore(options: OpfsLocalStoreOptions): LocalStore {
+  throw new NotImplementedError({
+    what: `OPFS SQLite local store (${options.file} v${options.schemaVersion})`,
+    fix: "import { createOpfsLocalStore } from '@ultimat3/realtime/browser' (tier 3, v2); today use MemoryLocalStore or set persist: false on the query",
+  });
+}

package/src/matcher-bridge.ts

@@ -0,0 +1,169 @@
+// One `ChangeEvent` -> the minimal patches for one subscription, via `@ultimat3/query`'s matcher.
+//
+// The pre-filter is the load-bearing part. Fanout is affordable only because a change that cannot
+// touch a subscription costs three comparisons (entity, tenant, column set) and never reaches the
+// matcher. A change touching no registered query costs one predicate check in total.
+
+import { type LiveQuery, match, type Patch } from '@ultimat3/query';
+import type { ChangeEvent } from './changefeed';
+import { changedColumns, isJsonObject, type JsonObject, type Row, type RowPatch } from './json';
+
+export interface SubscriptionShape {
+  readonly qid: string;
+  /** Dependency set: the entities and tags this query reads (`LiveQuery.reads`). */
+  readonly entities: readonly string[];
+  /** Tenant scope. A change in another tenant is dropped before any predicate runs. */
+  readonly orgId: string | null;
+  /** Read set. An update touching none of these columns cannot change the result. */
+  readonly columns?: readonly string[];
+}
+
+export interface BridgeResult {
+  readonly patches: readonly RowPatch[];
+  /**
+   * The window lost a row and the tail is unknown: the subscriber must re-read rather than guess.
+   * Handled as a re-snapshot, which is exactly the fallback the reconnect budget already pays for.
+   */
+  readonly refill: boolean;
+}
+
+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;
+}
+
+/** The cheap pre-filter. Pure, and the only thing that runs for a change nobody subscribed to. */
+export function canAffect(shape: SubscriptionShape, change: ChangeEvent): boolean {
+  if (!shape.entities.includes(change.entity)) return false;
+  if (shape.orgId !== null && change.orgId !== null && shape.orgId !== change.orgId) return false;
+  if (shape.columns && change.op === 'update' && change.after !== null) {
+    const touched = Object.keys(changedColumns(change.before, change.after));
+    if (touched.length > 0 && !touched.some((column) => shape.columns?.includes(column)))
+      return false;
+  }
+  return true;
+}
+
+/** Pre-filter, then match. Returns `null` for "skip this subscription" — the common case. */
+export function bridgeChange(
+  shape: SubscriptionShape,
+  incremental: IncrementalMatcher,
+  change: ChangeEvent,
+  rows: readonly Row[],
+): BridgeResult | null {
+  if (!canAffect(shape, change)) return null;
+  const result = incremental.match(change, rows);
+  return result.patches.length === 0 && !result.refill ? null : result;
+}
+
+/** Default derivation, used by matchers that only answer "affected" without describing the delta. */
+export function patchFromChange(change: ChangeEvent): RowPatch | null {
+  if (change.op === 'delete') {
+    const id = change.before?.id;
+    return id === undefined ? null : { op: 'delete', id, row: null, lsn: change.lsn };
+  }
+  const after = change.after;
+  if (after === null) return null;
+  const row: JsonObject =
+    change.op === 'insert' ? after : { id: after.id, ...changedColumns(change.before, after) };
+  return { op: change.op === 'insert' ? 'insert' : 'update', id: after.id, row, lsn: change.lsn };
+}
+
+/**
+ * The seam to `@ultimat3/query`. Everything else in this package talks to `IncrementalMatcher`, so
+ * swapping the matcher — or adopting an external protocol's, per the risk register — touches this
+ * function only.
+ */
+export function matcherFor(live: LiveQuery): IncrementalMatcher {
+  return {
+    entities: live.reads,
+    match: (change, rows) => {
+      const row = change.after ?? change.before;
+      if (!row) return NO_CHANGE;
+      const patches = match<Row>(live.name, live.shape, rows, {
+        entity: change.entity,
+        op: change.op,
+        row,
+        ...(change.before === null ? {} : { before: change.before }),
+      });
+      return toBridgeResult(patches, change);
+    },
+  };
+}
+
+/** `Patch<Row>` (add/update/remove/refill, positional) -> the wire's `RowPatch`. */
+export function toBridgeResult(patches: readonly Patch<Row>[], change: ChangeEvent): BridgeResult {
+  const out: RowPatch[] = [];
+  let refill = false;
+  for (const patch of patches) {
+    switch (patch.kind) {
+      case 'add':
+        out.push({
+          op: 'insert',
+          id: patch.row.id,
+          row: patch.row,
+          lsn: change.lsn,
+          index: patch.position,
+        });
+        break;
+      case 'update':
+        out.push({
+          op: 'update',
+          id: patch.row.id,
+          row: { id: patch.row.id, ...changedColumns(change.before, patch.row) },
+          lsn: change.lsn,
+          index: patch.position,
+        });
+        break;
+      case 'remove':
+        out.push({ op: 'delete', id: patch.id, row: null, lsn: change.lsn, index: patch.position });
+        break;
+      case 'refill':
+        refill = true;
+        break;
+    }
+  }
+  return { patches: out, refill };
+}
+
+/** 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[] {
+  const next = [...rows];
+  for (const patch of patches) {
+    const index = next.findIndex((row) => row.id === patch.id);
+    if (patch.op === 'delete') {
+      if (index >= 0) next.splice(index, 1);
+      continue;
+    }
+    if (patch.row === null) continue;
+    const current = index >= 0 ? next[index] : undefined;
+    const merged: Row = { ...(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);
+  }
+  return next;
+}
+
+/** Accepts a foreign matcher's patch shape and lands it on the wire shape. Defensive by design. */
+export function normalizePatch(candidate: unknown, change: ChangeEvent): RowPatch | null {
+  if (candidate === null || candidate === undefined || candidate === false) return null;
+  if (candidate === true) return patchFromChange(change);
+  if (!isJsonObject(candidate)) return null;
+  const op = candidate['op'];
+  if (op !== 'insert' && op !== 'update' && op !== 'delete') return patchFromChange(change);
+  const id = candidate['id'];
+  const rowValue = candidate['row'];
+  const index = candidate['index'];
+  const base: RowPatch = {
+    op,
+    id: typeof id === 'string' ? id : (change.after?.id ?? change.before?.id ?? ''),
+    row: op === 'delete' ? null : isJsonObject(rowValue) ? rowValue : (change.after ?? null),
+    lsn: typeof candidate['lsn'] === 'string' ? candidate['lsn'] : change.lsn,
+  };
+  if (base.id === '') return null;
+  return typeof index === 'number' ? { ...base, index } : base;
+}

package/src/nats-commands.ts

@@ -0,0 +1,97 @@
+// Single responsibility: the client half of the NATS protocol — the commands a client writes.
+// Split from the parser on purpose: encoding is pure string building with no state at all, while
+// decoding has to carry a buffer across chunk boundaries, and mixing the two hides both.
+
+import { TransportProtocolError } from './errors';
+import { concatBytes, type NatsHeaders } from './nats-protocol';
+
+const encoder = new TextEncoder();
+const CRLF = '\r\n';
+
+export interface NatsConnectOptions {
+  readonly verbose?: boolean; // default false
+  readonly pedantic?: boolean; // default false
+  readonly name?: string; // client name, default 'ultimate'
+  readonly user?: string | undefined;
+  readonly pass?: string | undefined;
+  readonly authToken?: string | undefined;
+  readonly tlsRequired?: boolean; // default false
+}
+const CLIENT_VERSION = '0.0.1';
+
+/** `CONNECT {json}\r\n` — the first frame a client sends, before subscribing or publishing. */
+export function connectMessage(options: NatsConnectOptions = {}): Uint8Array {
+  const payload: Record<string, unknown> = {
+    verbose: options.verbose ?? false,
+    pedantic: options.pedantic ?? false,
+    tls_required: options.tlsRequired ?? false,
+    name: options.name ?? 'ultimate',
+    lang: 'bun',
+    version: CLIENT_VERSION,
+    protocol: 1,
+    headers: true,
+    no_responders: true,
+  };
+  if (options.user !== undefined && options.pass !== undefined) {
+    payload['user'] = options.user;
+    payload['pass'] = options.pass;
+  }
+  if (options.authToken !== undefined) payload['auth_token'] = options.authToken;
+  return encoder.encode(`CONNECT ${JSON.stringify(payload)}${CRLF}`);
+}
+
+/**
+ * A header line ends at the first CRLF, so a break inside a key or value closes the line early and
+ * everything after it is read as a fresh command. A security boundary, not a style rule.
+ */
+const HEADER_BREAK = /[\r\n]/;
+
+const encodeHeaderBlock = (headers: NatsHeaders): Uint8Array => {
+  let block = `NATS/1.0${CRLF}`;
+  for (const [key, value] of headers) {
+    if (HEADER_BREAK.test(key) || HEADER_BREAK.test(value)) {
+      throw new TransportProtocolError({
+        transport: 'nats',
+        stage: 'headers',
+        // Quoted through JSON so the break that caused this cannot break the message reporting it.
+        detail: `header ${JSON.stringify(key)} carries a CR or LF, which would inject a command`,
+        fix: "strip the breaks first: headers.set(name, value.replace(/[\\r\\n]+/g, ' '))",
+      });
+    }
+    block += `${key}: ${value}${CRLF}`;
+  }
+  return encoder.encode(`${block}${CRLF}`);
+};
+
+/** `PUB` when there are no headers, `HPUB` when there are — never both shapes for one call. */
+export function pubMessage(args: {
+  readonly subject: string;
+  readonly payload?: Uint8Array | undefined;
+  readonly replyTo?: string | undefined;
+  readonly headers?: NatsHeaders | undefined;
+}): Uint8Array {
+  const payload = args.payload ?? new Uint8Array(0);
+  const replyPart = args.replyTo !== undefined ? ` ${args.replyTo}` : '';
+  const crlfBytes = encoder.encode(CRLF);
+  if (args.headers === undefined || args.headers.size === 0) {
+    const control = `PUB ${args.subject}${replyPart} ${payload.length}${CRLF}`;
+    return concatBytes(encoder.encode(control), payload, crlfBytes);
+  }
+  const headerBlock = encodeHeaderBlock(args.headers);
+  const total = headerBlock.length + payload.length;
+  const control = `HPUB ${args.subject}${replyPart} ${headerBlock.length} ${total}${CRLF}`;
+  return concatBytes(encoder.encode(control), headerBlock, payload, crlfBytes);
+}
+
+export function subMessage(subject: string, sid: string, queue?: string): Uint8Array {
+  const queuePart = queue !== undefined ? ` ${queue}` : '';
+  return encoder.encode(`SUB ${subject}${queuePart} ${sid}${CRLF}`);
+}
+
+export function unsubMessage(sid: string, max?: number): Uint8Array {
+  const maxPart = max !== undefined ? ` ${max}` : '';
+  return encoder.encode(`UNSUB ${sid}${maxPart}${CRLF}`);
+}
+
+export const PING_MESSAGE: Uint8Array = encoder.encode(`PING${CRLF}`);
+export const PONG_MESSAGE: Uint8Array = encoder.encode(`PONG${CRLF}`);

package/src/nats-connection-fixture.ts

@@ -0,0 +1,105 @@
+// Single responsibility: the scripted stream and the two `open()` shorthands this package's NATS
+// session tests share. Split out of `nats-connection.test.ts` so neither file outgrows its
+// ceiling. Not part of the public API — `index.ts` deliberately does not re-export it.
+
+import { isUltimateError } from '@ultimat3/core';
+import { TransportUnavailableError } from './errors';
+import { NatsConnection } from './nats-connection';
+import type { FakeNatsServer } from './nats-fake';
+import type { NatsStream, NatsTarget } from './nats-socket';
+
+export const encoder = new TextEncoder();
+export const decoder = new TextDecoder();
+
+export const TARGET: NatsTarget = {
+  host: 'bus.test',
+  port: 4222,
+  tls: false,
+  user: undefined,
+  pass: undefined,
+  token: undefined,
+};
+
+export const codeOf = (value: unknown): string =>
+  isUltimateError(value) ? value.code : `not an UltimateError: ${String(value)}`;
+
+export const caught = (promise: Promise<unknown>): Promise<unknown> =>
+  promise.then(
+    () => undefined,
+    (error: unknown) => error,
+  );
+
+/** A stream whose server side is a script: the test pushes bytes and reads what the client wrote. */
+export class ScriptedStream implements NatsStream {
+  readonly writes: string[] = [];
+  /**
+   * A socket that rejects a frame — the fault the session has to survive without keeping state
+   * that claims the frame arrived. A refused frame still lands in `writes`: the client did hand
+   * it over, and counting attempts is how a test sees a retry.
+   */
+  refuse: (frame: string) => boolean = () => false;
+  upgrades = 0;
+  closed = false;
+  readonly #queue: (Uint8Array | undefined)[] = [];
+  #waiting: ((chunk: Uint8Array | undefined) => void) | undefined;
+
+  constructor(...script: string[]) {
+    for (const text of script) this.push(text);
+  }
+
+  push(text: string): void {
+    const chunk = encoder.encode(text);
+    const waiter = this.#waiting;
+    this.#waiting = undefined;
+    if (waiter) waiter(chunk);
+    else this.#queue.push(chunk);
+  }
+
+  eof(): void {
+    const waiter = this.#waiting;
+    this.#waiting = undefined;
+    if (waiter) waiter(undefined);
+    else this.#queue.push(undefined);
+  }
+
+  read(): Promise<Uint8Array | undefined> {
+    if (this.#queue.length > 0) return Promise.resolve(this.#queue.shift());
+    return new Promise((resolve) => {
+      this.#waiting = resolve;
+    });
+  }
+
+  async write(bytes: Uint8Array): Promise<void> {
+    const frame = decoder.decode(bytes);
+    this.writes.push(frame);
+    if (this.refuse(frame)) {
+      throw new TransportUnavailableError({ transport: 'nats', reason: `refused: ${frame}` });
+    }
+  }
+
+  upgradeTls(): void {
+    this.upgrades += 1;
+  }
+
+  close(): void {
+    this.closed = true;
+    this.eof();
+  }
+}
+
+export const INFO =
+  'INFO {"server_id":"S","version":"2.11.0","max_payload":1048576,"headers":true}\r\n';
+
+export const openScripted = async (
+  stream: ScriptedStream,
+  target: NatsTarget = TARGET,
+): Promise<NatsConnection> =>
+  await NatsConnection.open({ stream, target, rng: () => 0.5, requestTimeoutMs: 50 });
+
+export const openFake = async (server: FakeNatsServer): Promise<NatsConnection> =>
+  await NatsConnection.open({
+    stream: server.connect(),
+    target: TARGET,
+    rng: () => 0.5,
+    requestTimeoutMs: 200,
+  });