@ultimat3/realtime 1.2.0 → 2.0.0

package/src/live-rows.ts

@@ -0,0 +1,143 @@
+// One live subscription's window, projected out of the identity map. The registration owns the
+// ORDER (its ids) and the map owns the VALUES — which is what makes post #7 one object however
+// many queries returned it, and what makes a write through any of them reach all of them.
+
+import { orderAfterPatches } from './apply-patches';
+import type { LiveCursor } from './cursor';
+import { type IdentityMap, type RowKey, type RowScope, rowKey } from './identity-map';
+import type { JsonValue, Row, RowPatch } from './json';
+
+export type LiveState = 'loading' | 'live' | 'stale' | 'offline';
+
+/** One live query this client holds. Mutable: the ids and cursor a frame advances live here. */
+export interface Registration {
+  readonly sid: string;
+  readonly name: string;
+  readonly input: JsonValue;
+  readonly setRows: (rows: readonly Row[]) => void;
+  readonly setState: (state: LiveState) => void;
+  readonly setCursor: (cursor: LiveCursor | null) => void;
+  /** Where this window's rows live in the map: the entity the server named, or a private scope. */
+  scope: RowScope;
+  /** Membership and order. The values are the map's — never a second copy of them. */
+  ids: readonly string[];
+  cursor: LiveCursor | null;
+}
+
+/**
+ * Every open window over one identity map. It is the only writer of `Registration.ids`, so the
+ * retain/release pairs that keep the map from growing without end cannot be forgotten by a caller.
+ */
+export class RowWindows {
+  readonly #identity: IdentityMap;
+  /** The window a write is running for, so its own listener does not emit the same rows twice. */
+  #writing: Registration | null = null;
+
+  constructor(identity: IdentityMap) {
+    this.#identity = identity;
+  }
+
+  /**
+   * Start rendering this registration out of the map. The returned close releases its rows and
+   * drops its listener — an unsubscribed component must stop holding rows and stop hearing about
+   * them in the same call, or one of the two outlives the other.
+   */
+  open(registration: Registration): () => void {
+    const unsubscribe = this.#identity.subscribe((changed) => {
+      if (this.#writing === registration) return;
+      if (!holds(registration, changed)) return;
+      this.#emit(registration);
+    });
+    return () => {
+      unsubscribe();
+      this.#identity.batch(() => {
+        for (const id of registration.ids) this.#identity.release(registration.scope, id);
+        registration.ids = [];
+      });
+    };
+  }
+
+  /**
+   * A snapshot: server truth for the whole window. `entity` is the scope the server named for this
+   * subscription — the first one that arrives upgrades a private scope to the shared one, which is
+   * what lets two different queries over one entity meet on the same row.
+   */
+  snapshot(registration: Registration, entity: string | null, rows: readonly Row[]): void {
+    const scope = entity ?? registration.scope;
+    this.#reseat(
+      registration,
+      scope,
+      rows.map((row) => row.id),
+      (held) => {
+        for (const row of rows) {
+          if (held.has(row.id)) this.#identity.merge(scope, row.id, row);
+        }
+      },
+    );
+  }
+
+  /** A patch list: values merged into the map, membership and order folded over the ids. */
+  patch(registration: Registration, patches: readonly RowPatch[]): void {
+    const scope = registration.scope;
+    // A `delete` is this window losing the row, never the map losing it: another window holding
+    // the same row keeps it until its own delete arrives.
+    this.#reseat(registration, scope, orderAfterPatches(registration.ids, patches), (held) => {
+      for (const patch of patches) {
+        if (patch.op === 'delete' || patch.row === null) continue;
+        if (held.has(patch.id)) this.#identity.merge(scope, patch.id, patch.row);
+      }
+    });
+  }
+
+  /** The window's rows, in its order. Absent ids are skipped — a released row renders as gone. */
+  rows(registration: Registration): readonly Row[] {
+    const out: Row[] = [];
+    for (const id of registration.ids) {
+      const row = this.#identity.peek(registration.scope, id);
+      if (row !== undefined) out.push(row);
+    }
+    return out;
+  }
+
+  /**
+   * Move the window to `nextIds` under `scope`, writing values in between. One batch per frame,
+   * and one emit for the window that caused it.
+   *
+   * The retain comes before the write and the release after it, so a row this window keeps across
+   * the move never reaches zero holds and gets dropped out from under the value it is about to be
+   * given. `write` only touches ids the window ends up holding — a value nobody holds is a value
+   * no release will ever reclaim.
+   */
+  #reseat(
+    registration: Registration,
+    scope: RowScope,
+    nextIds: readonly string[],
+    write: (held: ReadonlySet<string>) => void,
+  ): void {
+    const previous = this.#writing;
+    this.#writing = registration;
+    try {
+      this.#identity.batch(() => {
+        for (const id of nextIds) this.#identity.retain(scope, id);
+        write(new Set(nextIds));
+        for (const id of registration.ids) this.#identity.release(registration.scope, id);
+        registration.scope = scope;
+        registration.ids = nextIds;
+      });
+    } finally {
+      this.#writing = previous;
+    }
+    this.#emit(registration);
+  }
+
+  #emit(registration: Registration): void {
+    registration.setRows(this.rows(registration));
+  }
+}
+
+function holds(registration: Registration, changed: ReadonlySet<RowKey>): boolean {
+  for (const id of registration.ids) {
+    if (changed.has(rowKey(registration.scope, id))) return true;
+  }
+  return false;
+}

package/src/local-store.ts

@@ -3,9 +3,13 @@
 // `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".
+//
+// A table owns MEMBERSHIP (which ids it holds); the shared `IdentityMap` owns the VALUES, so an
+// optimistic write and the live query rendering that row are one row, not two copies.
 
 import { NotImplementedError } from './errors';
-import type { JsonObject, Row } from './json';
+import { IdentityMap } from './identity-map';
+import type { Row } from './json';
 
 export interface LocalTable<R extends Row = Row> {
   get(id: string): R | undefined;
@@ -28,11 +32,17 @@ export type LocalTx<T extends TableMap = TableMap> = { readonly [K in keyof T]:
 interface JournalEntry {
   readonly table: string;
   readonly id: string;
-  /** Row state before the write; `undefined` means "did not exist" (so undo = delete). */
+  /** Row state before the write; `undefined` means "did not exist" (so undo = drop membership). */
   readonly before: Row | undefined;
 }
 
 export interface LocalStore<T extends TableMap = TableMap> {
+  /**
+   * The one map every row value lives in, shared with the live-query windows on the same client.
+   * A `LiveClient` reads it off the store rather than building its own — two identity maps in one
+   * client is the bug an identity map exists to prevent, one level up.
+   */
+  readonly identity: IdentityMap;
   readonly tx: LocalTx<T>;
   table(name: string): LocalTable;
   /** Runs `fn` while journalling every write under `key`, so it can be rolled back verbatim. */
@@ -51,13 +61,16 @@ export interface LocalStore<T extends TableMap = TableMap> {
  * 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>>();
+  /** Membership and nothing else: `#members.get('posts')` is which ids this table holds. */
+  readonly #members = new Map<string, Set<string>>();
   readonly #journals = new Map<string, JournalEntry[]>();
   #recordingKey: string | null = null;
 
+  readonly identity: IdentityMap;
   readonly tx: LocalTx<T>;
 
-  constructor(tables: Readonly<Record<string, readonly Row[]>> = {}) {
+  constructor(tables: Readonly<Record<string, readonly Row[]>> = {}, identity = new IdentityMap()) {
+    this.identity = identity;
     this.reset(tables);
     const handler: ProxyHandler<Record<string, LocalTable>> = {
       // Symbols (`Symbol.iterator`, `then`) must not resolve to a table, or awaiting a tx would
@@ -68,30 +81,40 @@ export class MemoryLocalStore<T extends TableMap = TableMap> implements LocalSto
   }
 
   table(name: string): LocalTable {
-    const rows = this.#rows(name);
+    const ids = this.#ids(name);
+    const read = (id: string): Row | undefined =>
+      ids.has(id) ? this.identity.peek(name, id) : undefined;
     return {
-      get: (id) => rows.get(id),
-      all: () => [...rows.values()],
+      get: read,
+      all: () => {
+        const rows: Row[] = [];
+        for (const id of ids) {
+          const row = this.identity.peek(name, id);
+          if (row !== undefined) rows.push(row);
+        }
+        return rows;
+      },
       insert: (row) => {
-        this.#journal(name, row.id, rows.get(row.id));
-        rows.set(row.id, row);
+        this.#journal(name, row.id, read(row.id));
+        this.#join(name, row.id, ids);
+        this.identity.set(name, row);
       },
       upsert: (row) => {
-        const current = rows.get(row.id);
-        this.#journal(name, row.id, current);
-        rows.set(row.id, { ...(current ?? {}), ...row });
+        this.#journal(name, row.id, read(row.id));
+        this.#join(name, row.id, ids);
+        this.identity.merge(name, row.id, row);
       },
       update: (id, patch) => {
-        const current = rows.get(id);
+        const current = read(id);
         if (!current) return;
         this.#journal(name, id, current);
-        rows.set(id, merge(current, patch(current)));
+        this.identity.merge(name, id, patch(current));
       },
       delete: (id) => {
-        const current = rows.get(id);
+        const current = read(id);
         if (!current) return;
         this.#journal(name, id, current);
-        rows.delete(id);
+        this.#leave(name, id, ids);
       },
     };
   }
@@ -101,7 +124,8 @@ export class MemoryLocalStore<T extends TableMap = TableMap> implements LocalSto
     this.#recordingKey = key;
     if (!this.#journals.has(key)) this.#journals.set(key, []);
     try {
-      fn(this.tx);
+      // One notification for the whole twin: a mutator touching twenty rows is one render.
+      this.identity.batch(() => fn(this.tx));
     } finally {
       this.#recordingKey = previous;
     }
@@ -110,13 +134,19 @@ export class MemoryLocalStore<T extends TableMap = TableMap> implements LocalSto
   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.identity.batch(() => {
+      for (let i = journal.length - 1; i >= 0; i -= 1) {
+        const entry = journal[i];
+        if (!entry) continue;
+        const ids = this.#ids(entry.table);
+        if (entry.before === undefined) {
+          this.#leave(entry.table, entry.id, ids);
+          continue;
+        }
+        this.#join(entry.table, entry.id, ids);
+        this.identity.set(entry.table, entry.before);
+      }
+    });
     this.#journals.delete(key);
   }
 
@@ -129,25 +159,47 @@ export class MemoryLocalStore<T extends TableMap = TableMap> implements LocalSto
   }
 
   snapshot(name: string): readonly Row[] {
-    return [...this.#rows(name).values()];
+    return this.table(name).all();
   }
 
   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])));
-    }
+    this.identity.batch(() => {
+      for (const [name, ids] of this.#members) {
+        for (const id of ids) this.identity.release(name, id);
+      }
+      this.#members.clear();
+      this.#journals.clear();
+      for (const [name, rows] of Object.entries(tables)) {
+        const ids = this.#ids(name);
+        for (const row of rows) {
+          this.#join(name, row.id, ids);
+          this.identity.set(name, row);
+        }
+      }
+    });
   }
 
-  #rows(name: string): Map<string, Row> {
-    const existing = this.#tables.get(name);
+  #ids(name: string): Set<string> {
+    const existing = this.#members.get(name);
     if (existing) return existing;
-    const created = new Map<string, Row>();
-    this.#tables.set(name, created);
+    const created = new Set<string>();
+    this.#members.set(name, created);
     return created;
   }
 
+  /** Membership is what holds a value in the map, so joining and retaining are one step. */
+  #join(name: string, id: string, ids: Set<string>): void {
+    if (ids.has(id)) return;
+    ids.add(id);
+    this.identity.retain(name, id);
+  }
+
+  /** Leaving releases: the value survives only while a live window still holds the same row. */
+  #leave(name: string, id: string, ids: Set<string>): void {
+    if (!ids.delete(id)) return;
+    this.identity.release(name, id);
+  }
+
   /** 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;
@@ -159,15 +211,6 @@ export class MemoryLocalStore<T extends TableMap = TableMap> implements LocalSto
   }
 }
 
-/** `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;

package/src/nats-client.ts

@@ -0,0 +1,132 @@
+// Single responsibility: the bus port — the narrow NATS surface this package uses, and the URL that
+// names a server. Everything above this file is written against the port, so framing, the parser,
+// PING/PONG, the TLS upgrade and the reconnect belong to whoever implements it: `nats` in
+// production (`nats-lib-client.ts`), an in-memory bus in a test (`nats-fake.ts`).
+
+import { TransportUnavailableError } from './errors';
+
+export type NatsHeaders = ReadonlyMap<string, string>;
+
+export interface NatsMessage {
+  readonly subject: string;
+  readonly payload: Uint8Array;
+  /** `0` unless the reply carried a status: a direct read answers `404`, a batch ends on `204`. */
+  readonly status: number;
+  /** Case-insensitive — the server spells `Nats-Subject` and the caller asks however it likes. */
+  header(name: string): string | undefined;
+}
+
+export interface NatsSubscription {
+  unsubscribe(): void;
+}
+
+export type NatsMessageHandler = (message: NatsMessage) => void;
+
+export interface NatsRequestOptions {
+  readonly headers?: NatsHeaders | undefined;
+}
+
+export interface NatsRequestManyOptions {
+  /** Collection stops at the first message this accepts, and that message is not collected. */
+  readonly until: (message: NatsMessage) => boolean;
+}
+
+/**
+ * What the bus needs from a NATS connection, and nothing more. A subscription outlives a reconnect —
+ * the client re-establishes it underneath the caller — which is why nothing above this port keeps
+ * subscription bookkeeping of its own.
+ */
+export interface NatsClient {
+  /** The connected server's version, as `assertServerVersion` reads it. */
+  readonly version: string;
+  /** False while a reconnect is in flight, and forever once `close()` has run. */
+  readonly connected: boolean;
+  publish(subject: string, payload: Uint8Array): void;
+  subscribe(subject: string, handler: NatsMessageHandler): NatsSubscription;
+  request(subject: string, payload: Uint8Array, options?: NatsRequestOptions): Promise<NatsMessage>;
+  requestMany(
+    subject: string,
+    payload: Uint8Array,
+    options: NatsRequestManyOptions,
+  ): Promise<readonly NatsMessage[]>;
+  close(): Promise<void>;
+}
+
+export interface NatsTarget {
+  readonly host: string;
+  readonly port: number; // default 4222
+  /** `tls://` demands TLS; `nats://` still upgrades when the server's INFO says it is required. */
+  readonly tls: boolean;
+  readonly user: string | undefined;
+  readonly pass: string | undefined;
+  /** `nats://token@host` — NATS' single-credential form, mutually exclusive with user/pass. */
+  readonly token: string | undefined;
+}
+
+export interface NatsClientOptions {
+  readonly url: string;
+  /** Shows up in `nats server report connections`, so an operator can name the process. */
+  readonly name?: string | undefined;
+  readonly maxReconnectAttempts?: number | undefined;
+  /** Our jitter policy, asked once per attempt — the herd is ours to spread, not the library's. */
+  readonly reconnectDelay?: (() => number) | undefined;
+  readonly requestTimeoutMs?: number | undefined;
+  /** A background failure: a dropped connection, a server error, an exhausted reconnect. */
+  readonly onError?: ((error: unknown) => void) | undefined;
+  /** The library re-established the connection. The cluster behind it may be a different one. */
+  readonly onReconnect?: (() => void) | undefined;
+}
+
+/** The one seam a test replaces: a client that never touches a socket. */
+export type NatsConnect = (options: NatsClientOptions) => Promise<NatsClient>;
+
+export const DEFAULT_NATS_PORT = 4222;
+export const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
+
+/**
+ * `nats://user:pass@host:4222`. The one place a bus URL is read — the library takes a bare
+ * `host:port` plus credentials as options, and never looks at a URL's userinfo.
+ */
+export function parseNatsUrl(url: string): NatsTarget {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new TransportUnavailableError({
+      transport: 'nats',
+      reason: `"${url}" is not a connection URL`,
+    });
+  }
+  if (parsed.protocol !== 'nats:' && parsed.protocol !== 'tls:') {
+    throw new TransportUnavailableError({
+      transport: 'nats',
+      reason: `the connection URL uses "${parsed.protocol}" rather than nats: or tls:`,
+    });
+  }
+  if (parsed.hostname === '') {
+    throw new TransportUnavailableError({ transport: 'nats', reason: `"${url}" has no host` });
+  }
+  const hasUser = parsed.username !== '';
+  const hasPass = parsed.password !== '';
+  // A password with no user matches neither credential form, and dropping it silently connects
+  // anonymously — the failure then surfaces as the server's own 'Authorization Violation', which
+  // names nothing about the URL. The URL itself is never echoed back: it holds the secret.
+  if (!hasUser && hasPass) {
+    throw new TransportUnavailableError({
+      transport: 'nats',
+      reason: `the connection URL for ${parsed.hostname} carries a password with no user`,
+      fix: 'set the URL to nats://<user>:<pass>@host:4222, or the bare-token form nats://<token>@host:4222',
+    });
+  }
+  const user = hasUser ? decodeURIComponent(parsed.username) : undefined;
+  const pass = hasPass ? decodeURIComponent(parsed.password) : undefined;
+  return {
+    host: parsed.hostname,
+    port: parsed.port === '' ? DEFAULT_NATS_PORT : Number.parseInt(parsed.port, 10),
+    tls: parsed.protocol === 'tls:',
+    // A username with no password is NATS' bare-token form; a password makes it user/pass instead.
+    user: hasUser && hasPass ? user : undefined,
+    pass: hasUser && hasPass ? pass : undefined,
+    token: hasUser && !hasPass ? user : undefined,
+  };
+}