@ultimat3/realtime 20.2.1 → 22.0.0

package/src/client-mutations.ts

@@ -1,114 +0,0 @@
-// The outbound mutation path: the optimistic twin, the durable queue entry, and the sender the
-// drain hands each frame to. One file because those are the three places a single intent is
-// recorded, and an intent that reaches two of them is the divergence tier 3 exists to prevent.
-
-import { uuid } from '@ultimat3/core';
-import type { ClientSocket, MutatorRef } from './client-contract';
-import { TransportUnavailableError } from './errors';
-import type { JsonValue } from './json';
-import type { LocalStore, TableMap } from './local-store';
-import { type MutationSender, mutateFrame, type OfflineQueue } from './offline-queue';
-import type { RebaseLog } from './rebase';
-import { encode, type Frame } from './sync-protocol';
-
-/**
- * Queued bytes past which the drain stops rather than adds. The same number the node uses at its
- * end of the socket (`DEFAULT_MAX_BUFFERED_BYTES`), and deliberately NOT imported from it: this is
- * browser code, and `socket.ts` is the node's socket registry, its metrics and its close codes —
- * one import pulls the whole server half into the tab's bundle to read an integer. The node's two
- * spellings were merged because they configure one buffer on one side; these are two sides.
- */
-export const MAX_BUFFERED_BYTES = 1024 * 1024;
-
-/** Everything the mutation path touches. Narrow on purpose, exactly like `ClientFrameTarget`. */
-export interface MutationDeps<T extends TableMap = TableMap> {
-  readonly store: LocalStore<T> | undefined;
-  readonly queue: OfflineQueue | undefined;
-  readonly log: RebaseLog<T> | undefined;
-  readonly now: () => number;
-  /** Read per send, never captured: the socket a drain started on may already be gone. */
-  socket(): ClientSocket | null;
-  send(frame: Frame): void;
-}
-
-/**
- * Record one intent everywhere it has to be recorded: the local store (so the UI moves now), the
- * rebase log (so it can be taken back) and the durable queue (so it survives the tab). Nothing is
- * sent here — `drain` is the only thing that puts a mutation on a socket, and with no queue at all
- * (tier 2) the frame goes straight out because there is nothing to drain it from later.
- */
-export async function recordMutation<T extends TableMap>(
-  deps: MutationDeps<T>,
-  mutator: MutatorRef<T>,
-  input: JsonValue,
-  key?: string,
-): Promise<void> {
-  const idempotencyKey = key ?? `${mutator.name}:${uuid()}`;
-  const { store, queue } = deps;
-  const local = mutator.local;
-  const existing = queue?.find(idempotencyKey);
-  const queued = await queue?.enqueue({
-    key: idempotencyKey,
-    name: mutator.name,
-    input,
-    at: deps.now(),
-  });
-  // Identity, not a second copy of the queue's collapse rule: `enqueue` hands back the SAME entry
-  // when it collapses and a new one when it does not. A repeated key is ONE intent whose twin is
-  // already applied — applying it again double-counts the write (a like becomes two) and replaces
-  // the log entry a rollback would have undone to the pre-mutation row.
-  const collapsed = existing !== undefined && queued === existing;
-  if (store && local && !collapsed) {
-    store.apply(idempotencyKey, (tx) => local(tx, input));
-    deps.log?.record({
-      key: idempotencyKey,
-      seq: queued?.seq ?? 0,
-      entity: mutator.entity ?? mutator.name,
-      strategy: mutator.conflict ?? 'server-wins',
-      apply: (tx) => local(tx, input),
-    });
-  }
-  if (queue) return;
-  deps.send(
-    mutateFrame({
-      key: idempotencyKey,
-      seq: 0,
-      name: mutator.name,
-      input,
-      enqueuedAt: deps.now(),
-      attempts: 0,
-      status: 'pending',
-      error: null,
-    }),
-  );
-}
-
-/**
- * The queue's sender. Throwing is how a sender declines: the queue keeps that mutation pending,
- * stops the pass rather than reordering the ones behind it, and the next drain resumes there.
- *
- * Backpressure is a decline and not a failure — the frames already queued in the tab are ones the
- * socket has not managed to write, so adding to them is how a client sends a burst it will never
- * see acknowledged. A socket that does not report `bufferedAmount` is treated as never backed up.
- */
-export function mutationSender<T extends TableMap>(deps: MutationDeps<T>): MutationSender {
-  return async (mutation) => {
-    const socket = deps.socket();
-    if (!socket) {
-      throw new TransportUnavailableError({
-        transport: 'websocket',
-        reason: 'the socket went away before this mutation reached it',
-        fix: 'it stays queued: await useMutationQueue().drain() once useConnection().online',
-      });
-    }
-    const buffered = socket.bufferedAmount ?? 0;
-    if (buffered > MAX_BUFFERED_BYTES) {
-      throw new TransportUnavailableError({
-        transport: 'websocket',
-        reason: `${buffered} bytes are already queued on this socket, over the ${MAX_BUFFERED_BYTES} ceiling`,
-        fix: 'it stays queued: await useMutationQueue().drain() once the socket has caught up',
-      });
-    }
-    socket.send(encode(mutateFrame(mutation)));
-  };
-}

package/src/client-topics.ts

@@ -1,54 +0,0 @@
-// The client's channel book: which handlers hold which topic, and the one frame that announces a
-// membership. Split out of `client.ts` because the announcement has two callers that must never
-// disagree — `subscribe()` and the reconnect replay — and one of them was missing.
-
-import type { Topic } from './channel';
-import type { JsonObject } from './json';
-import { PROTOCOL_VERSION, type SubscribeFrame } from './sync-protocol';
-
-export type TopicHandler = (message: JsonObject) => void;
-
-/**
- * The membership frame. `sid` is the topic itself: a channel subscription is identified by what it
- * is subscribed to, so re-sending it after a reconnect re-establishes the same membership rather
- * than a second one — and on the node, sending it again IS the presence heartbeat.
- */
-export function topicSubscribeFrame(name: string, op: 'add' | 'drop'): SubscribeFrame {
-  return {
-    type: 'subscribe',
-    v: PROTOCOL_VERSION,
-    op,
-    sid: name,
-    target: { kind: 'topic', topic: name },
-  };
-}
-
-/** Topic -> the handlers holding it. One entry per topic, however many components subscribed. */
-export class TopicBook {
-  readonly #topics = new Map<string, Set<TopicHandler>>();
-
-  add(name: Topic, handler: TopicHandler): void {
-    const handlers = this.#topics.get(name) ?? new Set<TopicHandler>();
-    handlers.add(handler);
-    this.#topics.set(name, handlers);
-  }
-
-  /** True when that was the last holder, so the caller is the one that sends the drop frame. */
-  remove(name: Topic, handler: TopicHandler): boolean {
-    const handlers = this.#topics.get(name);
-    if (!handlers) return false;
-    handlers.delete(handler);
-    if (handlers.size > 0) return false;
-    this.#topics.delete(name);
-    return true;
-  }
-
-  handlers(name: string): ReadonlySet<TopicHandler> | undefined {
-    return this.#topics.get(name);
-  }
-
-  /** Every membership this client still holds — what a reconnect has to re-announce. */
-  names(): readonly string[] {
-    return [...this.#topics.keys()];
-  }
-}

package/src/hooks.ts

@@ -1,277 +0,0 @@
-// The four calls a component makes: one live query, one connection view, one mutator call, one
-// queue view. Nothing here is a reactive runtime — realtime never imports solid-js, so every
-// accessor is a closure over the `SignalFactory` the registered `LiveClient` was built with, and
-// every hook resolves that client through one ambient seam rather than a context per surface.
-
-import type { LiveClientLike, LiveHandle, LiveQueryRef, MutatorRef } from './client';
-import { LiveClientMissingError } from './errors';
-import type { JsonValue, Row } from './json';
-import type { LocalTx } from './local-store';
-import type { ConflictStrategy } from './rebase';
-import { serverRenderLiveClient } from './server-render-client';
-
-/** What `setLiveClient` holds. The version signal is the queue's only reactive handle — see below. */
-interface Registered {
-  readonly client: LiveClientLike;
-  /** Read to subscribe, bumped to invalidate: `OfflineQueue` stores plain arrays, not signals. */
-  readonly version: () => number;
-  readonly bump: () => void;
-  /** Drops this registration's queue listener. The client outlives the registration. */
-  readonly release: () => void;
-}
-
-let registered: Registered | null = null;
-
-/** Register once, in the app entry, before the first render. One app, one socket, one client. */
-export function setLiveClient(client: LiveClientLike): void {
-  // The previous registration's listener goes with it. The client outlives `setLiveClient` — a hot
-  // reload, a test's next case, an app that re-registers after signing in — so a discarded
-  // unsubscribe is a listener nothing can reach, bumping a signal nothing renders, once per
-  // registration this process ever made.
-  registered?.release();
-  const [version, setVersion] = client.signal<number>(0);
-  const bump = (): void => {
-    setVersion(version() + 1);
-  };
-  // Closes the gap a direct call can't: a reconnect drains automatically inside `connect()`, and
-  // an ack/fail frame arrives asynchronously inside `#onFrame` — neither is awaited by any hook, so
-  // this is the only path that reaches them. The direct `bump()` calls below stay too: they fire at
-  // the earliest possible moment for the call that made them, and a redundant bump is harmless.
-  const release = client.onQueueChange(bump);
-  registered = { client, version, bump, release };
-}
-
-/** For tests: drop the registration so cases stay independent. */
-export function clearLiveClient(): void {
-  registered?.release();
-  registered = null;
-}
-
-export function hasLiveClient(): boolean {
-  return registered !== null;
-}
-
-/**
- * A DOM is the whole of the question — the same probe and the same rule `@ultimat3/ui`'s `solid()`
- * follows, and deliberately the same words. With a DOM, a hook reaching for a client nobody
- * registered is a real bug: the app entry forgot `setLiveClient`, and every live query on the page
- * is dead. Without one there is no socket a client could have been registered FOR — that is a
- * server render, and `serverRenderLiveClient()` is an honest account of it rather than a
- * degradation of a working path. Never widen this to "no client, never throw": that is the silent
- * feed-that-never-loads the split exists to prevent.
- */
-function hasDom(): boolean {
-  return typeof document !== 'undefined' && typeof window !== 'undefined';
-}
-
-/**
- * The server render's registration, built once. Deliberately NOT written to `registered`:
- * `hasLiveClient()` must keep answering `false` on the server, because that is the guard a
- * component with a static fallback already uses to decide it is being server-rendered
- * (`examples/dummy`'s `update-banner.tsx`).
- */
-let serverSide: Registered | null = null;
-
-function serverRegistration(): Registered {
-  if (serverSide !== null) return serverSide;
-  const client = serverRenderLiveClient();
-  // The version signal never moves, and nothing on the server can move it: one pass, no queue,
-  // no ack — so `bump` and `release` are the no-ops that fact makes them.
-  const [version] = client.signal<number>(0);
-  serverSide = { client, version, bump: () => undefined, release: () => undefined };
-  return serverSide;
-}
-
-function live(hook: string): Registered {
-  if (registered !== null) return registered;
-  if (hasDom()) throw new LiveClientMissingError({ hook });
-  return serverRegistration();
-}
-
-// ---- useLive ------------------------------------------------------------------------------------
-
-/** The query's input, or a thunk returning it. The thunk is read once — see `useLive`. */
-export type LiveInput = JsonValue | (() => JsonValue);
-
-/**
- * A callable result set: `feed()` are the rows, `feed.state()` / `feed.cursor()` /
- * `feed.unsubscribe()` are the rest of the `LiveHandle` hanging off it. It is also `Disposable`
- * (inherited from `LiveHandle`), so `using feed = useLive(...)` unsubscribes on scope exit.
- *
- * `R` is only constrained to `object`: on the wire every row is a `Row`, but a hook bound to a
- * declared query (`query-hook.ts`) answers in that query's own row type, which is whatever its
- * `sql` returns. The three members hanging off the accessor are the same for every `R`.
- */
-export type LiveRows<R extends object = Row> = (() => readonly R[]) & Omit<LiveHandle, 'rows'>;
-
-/**
- * Subscribe to a live query. `query` is anything carrying a `name`, which a `@ultimat3/query`
- * `Query` satisfies structurally — realtime is tier 3, so it names the shape rather than importing
- * the package sideways.
- *
- * A thunk `input` is read **once**, at subscribe time: tier 3 has no reactive runtime of its own,
- * so nothing re-runs it when its dependencies change. Changing input means a new subscription.
- * The caller owns `unsubscribe` — nothing here disposes on unmount, because nothing here knows
- * what a mount is. `using` works too, when the caller does have a scope to hang it on.
- */
-export function useLive<R extends Row = Row>(query: LiveQueryRef, input: LiveInput): LiveRows<R> {
-  const handle = live('useLive').client.useLive<R>(
-    query,
-    typeof input === 'function' ? input() : input,
-  );
-  return Object.assign((): readonly R[] => handle.rows(), {
-    state: handle.state,
-    cursor: handle.cursor,
-    unsubscribe: handle.unsubscribe,
-    [Symbol.dispose]: handle[Symbol.dispose],
-  });
-}
-
-// ---- useConnection ------------------------------------------------------------------------------
-
-export interface Connection {
-  readonly offline: boolean;
-  readonly online: boolean;
-  /** Epoch ms of the next reconnect attempt; `null` while the socket is up. */
-  readonly reconnectAt: number | null;
-  /** The buildId the server announced, or `null` while this build is current. */
-  readonly updateAvailable: string | null;
-}
-
-/**
- * The socket, as four booleans and two values. Every member is a **getter**, so a read inside a
- * tracking scope reaches the underlying signal; a snapshot object would freeze the answer at the
- * moment the component rendered and never say "offline" again.
- */
-export function useConnection(): Connection {
-  const client = live('useConnection').client;
-  return {
-    get offline() {
-      return !client.connected;
-    },
-    get online() {
-      return client.connected;
-    },
-    get reconnectAt() {
-      return client.reconnectAt();
-    },
-    get updateAvailable() {
-      return client.appUpdateAvailable();
-    },
-  };
-}
-
-// ---- useMutation --------------------------------------------------------------------------------
-
-/**
- * Both spellings of a conflict strategy: realtime's `custom()` (`{ kind: 'custom' }`, merging rows)
- * and `@ultimat3/action`'s (`{ strategy: 'custom' }`, merging parsed outputs).
- */
-export type ConflictLike = ConflictStrategy | { readonly strategy: 'custom' };
-
-/**
- * What a hook needs from a mutator: the name it queues under, and the optimistic twin. A
- * `@ultimat3/action` `Mutator` satisfies it structurally.
- *
- * `local` is declared with **method syntax** on purpose. TypeScript relates method parameters
- * bivariantly, so a `Mutator` whose `local` takes its own parsed input and its own `tx` assigns
- * here with no cast at the call site; written as a function-typed property, `strictFunctionTypes`
- * would reject exactly that mutator. The parameters are `unknown` because this layer never reads
- * them — it binds them and hands the closure to the client.
- */
-export interface MutatorLike {
-  readonly name: string;
-  local?(tx: unknown, input: unknown): void;
-  readonly entity?: string;
-  readonly conflict?: ConflictLike;
-}
-
-/** A callable mutator with its own queue depth attached. */
-export type Mutate = ((input: JsonValue) => Promise<void>) & {
-  /** Queued mutations of this mutator. Always `0` at tier 2, where nothing is queued. */
-  readonly pending: number;
-};
-
-/**
- * Call a mutator: optimistic twin, rebase entry, durable queue, drain — all of it inside
- * `LiveClient.mutate`. `pending` is a getter, so it stays reactive for as long as the component
- * reads it; it refreshes on every call routed through this hook and on `useMutationQueue().drain`.
- */
-export function useMutation(mutator: MutatorLike): Mutate {
-  const state = live('useMutation');
-  const ref = mutatorRef(mutator);
-  const call = async (input: JsonValue): Promise<void> => {
-    await state.client.mutate(ref, input);
-    state.bump();
-  };
-  Object.defineProperty(call, 'pending', {
-    get: (): number => {
-      state.version();
-      const queue = state.client.queue;
-      return queue === undefined
-        ? 0
-        : queue.pending().filter((mutation) => mutation.name === mutator.name).length;
-    },
-  });
-  // `defineProperty` cannot widen a function type, so the assembled shape is asserted once, here.
-  return call as Mutate;
-}
-
-// ---- useMutationQueue ---------------------------------------------------------------------------
-
-export interface MutationQueue {
-  /** Queued and not yet acknowledged, across every mutator. */
-  readonly pending: number;
-  /** Terminally failed — a policy denial or a validation error, kept for the UI, never retried. */
-  readonly failed: number;
-  drain(): Promise<void>;
-}
-
-/** The whole durable queue, as two counts and the one command that empties it. */
-export function useMutationQueue(): MutationQueue {
-  const state = live('useMutationQueue');
-  return {
-    get pending() {
-      state.version();
-      return state.client.queue?.pending().length ?? 0;
-    },
-    get failed() {
-      state.version();
-      const all = state.client.queue?.all() ?? [];
-      return all.filter((mutation) => mutation.status === 'failed').length;
-    },
-    drain: async () => {
-      await state.client.drain();
-      state.bump();
-    },
-  };
-}
-
-/** The hook's mutator, as the client's. Only the twin needs binding; the rest is carried through. */
-function mutatorRef(mutator: MutatorLike): MutatorRef {
-  const conflict = replayable(mutator.conflict);
-  return {
-    name: mutator.name,
-    // Called back through the mutator rather than through a hoisted reference: `local` may be
-    // written as a method, and an unbound method loses the receiver its body could read.
-    ...(mutator.local === undefined
-      ? {}
-      : {
-          local: (tx: LocalTx, input: JsonValue) => {
-            mutator.local?.(tx, input);
-          },
-        }),
-    ...(mutator.entity === undefined ? {} : { entity: mutator.entity }),
-    ...(conflict === undefined ? {} : { conflict }),
-  };
-}
-
-/**
- * `@ultimat3/action`'s `custom(merge)` merges parsed *outputs*; realtime's merges *rows*. Only the
- * second is a `CustomMerge` `reconcile` can replay, so the other spelling is dropped rather than
- * handed to a rebase that would call it with the wrong argument — the log then takes its default.
- */
-function replayable(conflict: ConflictLike | undefined): ConflictStrategy | undefined {
-  if (conflict === undefined || typeof conflict === 'string') return conflict;
-  return 'kind' in conflict ? conflict : undefined;
-}

package/src/identity-map.ts

@@ -1,141 +0,0 @@
-// One row VALUE per `(scope, id)` for the whole client — the identity map the thesis takes from
-// Ember Data. Two components holding two copies of one row is the bug it makes unrepresentable:
-// a live query's window and the tier-3 local store are both projections over this one map, so a
-// write through either is the same row for both. Membership and order live in the projections.
-
-import type { JsonObject, JsonValue, Row } from './json';
-
-/**
- * The entity's table — the same name `ChangeEvent.entity`, `tx.<table>` and a mutator's `entity`
- * already use, which is what makes the live path and the local store address one row identically.
- * A subscription whose entity the server did not name gets a private `?query:<name>` scope: no
- * sharing is worse than sharing two different entities that happen to spell one id the same way.
- */
-export type RowScope = string;
-
-/** `scope`+NUL+`id`. NUL cannot occur in an entity name, so the join is unambiguous. */
-export type RowKey = string;
-
-export function rowKey(scope: RowScope, id: string): RowKey {
-  return `${scope}\u0000${id}`;
-}
-
-/** The scope a subscription uses until the server names its entity. `?` starts no entity name. */
-export function privateScope(queryName: string): RowScope {
-  return `?query:${queryName}`;
-}
-
-export type IdentityListener = (changed: ReadonlySet<RowKey>) => void;
-
-/**
- * The map. Values are immutable: every write produces a NEW row object, because a projection over
- * this map hands its rows to a signal and a mutated-in-place row is a render that never happens.
- * "One row per id" therefore means one *current value* per id, referenced by every holder at once.
- */
-export class IdentityMap {
-  readonly #values = new Map<RowKey, Row>();
-  /** How many projections hold each key. A row nobody holds is dropped — a window is not a leak. */
-  readonly #holds = new Map<RowKey, number>();
-  readonly #listeners = new Set<IdentityListener>();
-  /** Non-null while a batch is open; every write inside one notifies exactly once, at the end. */
-  #changed: Set<RowKey> | null = null;
-
-  peek(scope: RowScope, id: string): Row | undefined {
-    return this.#values.get(rowKey(scope, id));
-  }
-
-  /** Whole-row write: the value becomes exactly this row. `insert` and a rollback's undo use it. */
-  set(scope: RowScope, row: Row): Row {
-    const key = rowKey(scope, row.id);
-    const current = this.#values.get(key);
-    if (current === row) return row;
-    this.#values.set(key, row);
-    this.#touch(key);
-    return row;
-  }
-
-  /**
-   * Merge changed columns onto the current value. This is the write every server patch, every
-   * snapshot row and every `upsert` takes: a projection that selected fewer columns must not blank
-   * the columns another projection is rendering, so a write never removes a key. `undefined` in a
-   * patch means "leave it alone", exactly as the local store's contract already says.
-   */
-  merge(
-    scope: RowScope,
-    id: string,
-    columns: Readonly<Record<string, JsonValue | undefined>>,
-  ): Row {
-    const key = rowKey(scope, id);
-    const current = this.#values.get(key);
-    const next: JsonObject = { ...current };
-    let changed = current === undefined;
-    for (const [column, value] of Object.entries(columns)) {
-      if (value === undefined || column === 'id') continue;
-      if (current === undefined || current[column] !== value) changed = true;
-      next[column] = value;
-    }
-    const row: Row = { ...next, id };
-    // A patch that changed nothing must not re-emit: a no-op write re-rendering every holder is
-    // how a live query becomes the most expensive thing on the page.
-    if (!changed && current !== undefined) return current;
-    this.#values.set(key, row);
-    this.#touch(key);
-    return row;
-  }
-
-  retain(scope: RowScope, id: string): void {
-    const key = rowKey(scope, id);
-    this.#holds.set(key, (this.#holds.get(key) ?? 0) + 1);
-  }
-
-  /** The last holder leaving drops the value: an infinite scroll must not retain every row it saw. */
-  release(scope: RowScope, id: string): void {
-    const key = rowKey(scope, id);
-    const holds = this.#holds.get(key);
-    if (holds === undefined) return;
-    if (holds > 1) {
-      this.#holds.set(key, holds - 1);
-      return;
-    }
-    this.#holds.delete(key);
-    if (this.#values.delete(key)) this.#touch(key);
-  }
-
-  /** Every write inside `fn` collapses into one notification — one patch frame, one render. */
-  batch<T>(fn: () => T): T {
-    if (this.#changed !== null) return fn();
-    const collected = new Set<RowKey>();
-    this.#changed = collected;
-    try {
-      return fn();
-    } finally {
-      this.#changed = null;
-      if (collected.size > 0) this.#notify(collected);
-    }
-  }
-
-  subscribe(listener: IdentityListener): () => void {
-    this.#listeners.add(listener);
-    return () => {
-      this.#listeners.delete(listener);
-    };
-  }
-
-  /** Held keys. Tests assert on it; nothing in the client branches on a count. */
-  get size(): number {
-    return this.#values.size;
-  }
-
-  #touch(key: RowKey): void {
-    const batch = this.#changed;
-    if (batch !== null) {
-      batch.add(key);
-      return;
-    }
-    this.#notify(new Set([key]));
-  }
-
-  #notify(changed: ReadonlySet<RowKey>): void {
-    for (const listener of this.#listeners) listener(changed);
-  }
-}