@ultimat3/realtime 20.2.0 → 21.0.0

package/src/query-hook.ts

@@ -1,56 +0,0 @@
-// The typed projection of a query into the hook a component calls: `liveHookFor(liveFeed)` is
-// `useLiveFeed`, and `useLiveFeed({ orgId })` carries that query's own input and row types. It
-// binds `useLive` rather than re-implementing it — one subscribe path, given the query's name.
-
-import { QueryNotSubscribableError } from './errors';
-import { type LiveInput, type LiveRows, useLive } from './hooks';
-
-/**
- * What the hook needs from a `@ultimat3/query` `Query`: the name it subscribes under, the declared
- * `live:` flag, and the call signature both types are read off. Named structurally rather than
- * imported, the way `hooks.ts` names a mutator — a hook is browser code, and a value import of
- * `@ultimat3/query` would carry the server's read path into the bundle.
- *
- * `options` is `never` because this side never passes one; a `Query`, whose second parameter is
- * optional and wider, still assigns.
- */
-export interface LiveQuerySource<TInput, TRow extends object> {
-  (input: TInput, options?: never): Promise<readonly TRow[]>;
-  readonly name: string;
-  readonly isLive: boolean;
-}
-
-/**
- * The bound hook. Input is the query's own — a wrong key is a compile error in the component, not
- * a subscription that returns nothing. A thunk is read **once**, at subscribe time, exactly as
- * `useLive`'s is: there is no reactive runtime here to re-run it, so new input means a new
- * subscription.
- */
-export type LiveQueryHook<TInput, TRow extends object> = (
-  input: TInput | (() => TInput),
-) => LiveRows<TRow>;
-
-/**
- * Bind one live query to one hook: `export const useLiveFeed = liveHookFor(liveFeed)`, then
- * `useLiveFeed({ orgId })` in a component. Nothing is generated and nothing is fetched by hand —
- * the types come off the query declaration and the rows off its subscription.
- *
- * Binding a query that is not `live: true` throws here, at module load, rather than handing back a
- * hook that could only ever return an empty set.
- */
-export function liveHookFor<TInput, TRow extends object>(
-  query: LiveQuerySource<TInput, TRow>,
-): LiveQueryHook<TInput, TRow> {
-  if (!query.isLive) throw new QueryNotSubscribableError({ name: query.name });
-  // The query object is handed through, never its `name` read now: `registerQueries()` stamps that
-  // at boot, and this binding runs at import — earlier. `useLive` reads it per subscription.
-  return (input) => {
-    // Both assertions are the one wire seam: the input is about to be serialised into a subscribe
-    // frame, and the rows come back off that subscription. `unknown` in between rather than a
-    // direct cast, exactly as `query.client()` hops through it at the same seam.
-    const rows: unknown = useLive(query, input as LiveInput);
-    // Erased at the wire seam, the way `query.client()` erases its own: the rows arriving on this
-    // subscription are this query's by construction, because the server built them from its `sql`.
-    return rows as LiveRows<TRow>;
-  };
-}

package/src/rebase.ts

@@ -1,263 +0,0 @@
-// Tier 3: the reconcile loop. The server rebases; the client rolls back and reapplies.
-//
-// Truth is always the server — a client is never the merge authority. So reconciliation is exactly:
-// undo the optimistic writes from the acknowledged mutation onward (newest first), land server
-// truth, then replay the still-pending mutators in sequence order. Because `local` is a pure
-// function of `(tx, input)`, that replay is deterministic; that purity rule is the whole reason
-// tier 3 is affordable.
-
-import { RebaseConflictError } from './errors';
-import type { Row } from './json';
-import type { LocalStore, LocalTx, TableMap } from './local-store';
-import { type ConflictStrategyName, PROTOCOL_VERSION, type RebaseFrame } from './sync-protocol';
-
-export interface MergeArgs {
-  /** Local row as the user last saw it, before any rollback. */
-  readonly local: Row | undefined;
-  /** Local row after the optimistic writes were undone — the shared base. */
-  readonly base: Row | undefined;
-  /** Server truth. `null` means the server deleted the row. */
-  readonly server: Row | null;
-}
-
-export interface CustomMerge {
-  readonly kind: 'custom';
-  merge(args: MergeArgs): Row | null | undefined;
-}
-
-/** `conflict: custom(merge)` — exactly the name the mutator contract uses. */
-export function custom(merge: (args: MergeArgs) => Row | null | undefined): CustomMerge {
-  return { kind: 'custom', merge };
-}
-
-export type ConflictStrategy = 'server-wins' | 'last-write-wins' | CustomMerge;
-
-export function strategyName(strategy: ConflictStrategy): ConflictStrategyName {
-  return typeof strategy === 'string' ? strategy : 'custom';
-}
-
-export interface RebaseEntry<T extends TableMap = TableMap> {
-  /** Idempotency key — the same key the offline queue uses. */
-  readonly key: string;
-  readonly seq: number;
-  readonly entity: string;
-  readonly strategy: ConflictStrategy;
-  /** The mutator's `local` half, curried with its input. Pure, therefore replayable. */
-  apply(tx: LocalTx<T>): void;
-}
-
-/** Optimistic writes awaiting server truth, ordered by client sequence. */
-export class RebaseLog<T extends TableMap = TableMap> {
-  readonly #entries = new Map<string, RebaseEntry<T>>();
-
-  record(entry: RebaseEntry<T>): void {
-    this.#entries.set(entry.key, entry);
-  }
-
-  get(key: string): RebaseEntry<T> | undefined {
-    return this.#entries.get(key);
-  }
-
-  drop(key: string): void {
-    this.#entries.delete(key);
-  }
-
-  pending(): readonly RebaseEntry<T>[] {
-    return [...this.#entries.values()].sort((a, b) => a.seq - b.seq);
-  }
-
-  get size(): number {
-    return this.#entries.size;
-  }
-}
-
-export interface ServerAck {
-  readonly key: string;
-  readonly entity: string;
-  readonly id: string;
-  readonly row: Row | null;
-}
-
-export interface ReconcileOptions {
-  /** Field compared by `last-write-wins`. Must be a number (epoch ms) written by the server. */
-  readonly clockField?: string;
-}
-
-export interface ReconcileResult {
-  readonly strategy: ConflictStrategyName;
-  readonly rolledBack: readonly string[];
-  readonly reapplied: readonly string[];
-  readonly winner: 'server' | 'local' | 'merge';
-}
-
-/**
- * One acknowledgement, one rebase. Rolls back the acked mutation and every later optimistic write,
- * lands server truth under the mutator's conflict strategy, then replays the rest in sequence order.
- */
-export function reconcile<T extends TableMap = TableMap>(
-  args: {
-    store: LocalStore<T>;
-    log: RebaseLog<T>;
-    ack: ServerAck;
-  },
-  options: ReconcileOptions = {},
-): ReconcileResult {
-  const { store, log, ack } = args;
-  const entry = log.get(ack.key);
-  const strategy = entry?.strategy ?? 'server-wins';
-  const table = store.table(ack.entity);
-  const local = table.get(ack.id);
-
-  const { affected, rolledBack } = undoFrom(store, log, entry?.seq ?? 0);
-
-  const base = store.table(ack.entity).get(ack.id);
-  const winner = land(store, ack, strategy, { local, base }, options);
-  log.drop(ack.key);
-
-  return {
-    strategy: strategyName(strategy),
-    rolledBack,
-    reapplied: replayExcept(store, affected, ack.key),
-    winner,
-  };
-}
-
-/**
- * Everything at or after `from` is optimistic, so it is undone newest-first — and `reconcile` and
- * `rollbackMutation` are one rule with different middles, not two. Spelled twice, the next change
- * to the replay order has to be made twice, and the half that is missed diverges silently.
- */
-function undoFrom<T extends TableMap>(
-  store: LocalStore<T>,
-  log: RebaseLog<T>,
-  from: number,
-): { affected: readonly RebaseEntry<T>[]; rolledBack: string[] } {
-  const affected = log.pending().filter((candidate) => candidate.seq >= from);
-  const rolledBack: string[] = [];
-  for (const candidate of [...affected].reverse()) {
-    store.rollback(candidate.key);
-    rolledBack.push(candidate.key);
-  }
-  return { affected, rolledBack };
-}
-
-/**
- * The other half: replay in sequence order, skipping the one the server has now settled. `local` is
- * pure, which is what makes replaying it deterministic and therefore safe to do at all.
- */
-function replayExcept<T extends TableMap>(
-  store: LocalStore<T>,
-  affected: readonly RebaseEntry<T>[],
-  settled: string,
-): string[] {
-  const reapplied: string[] = [];
-  for (const candidate of affected) {
-    if (candidate.key === settled) continue;
-    store.apply(candidate.key, (tx) => candidate.apply(tx));
-    reapplied.push(candidate.key);
-  }
-  return reapplied;
-}
-
-export interface RollbackResult {
-  readonly rolledBack: readonly string[];
-  readonly reapplied: readonly string[];
-}
-
-/**
- * The other half of `reconcile`: the server **refused** a mutation, so there is no server truth to
- * land — only an optimistic write to take back. Same shape as a reconcile, and for the same reason:
- * the writes made after it may depend on it, so everything from its sequence onward is undone
- * newest-first and then replayed without it. Replay is deterministic because `local` is pure.
- *
- * Idempotent for a key the log does not hold: a denial can arrive twice, and tier 2 records nothing
- * to undo in the first place.
- */
-export function rollbackMutation<T extends TableMap = TableMap>(args: {
-  store: LocalStore<T>;
-  log: RebaseLog<T>;
-  key: string;
-}): RollbackResult {
-  const { store, log, key } = args;
-  const entry = log.get(key);
-  if (!entry) return { rolledBack: [], reapplied: [] };
-
-  const { affected, rolledBack } = undoFrom(store, log, entry.seq);
-  // The one thing that differs from `reconcile`'s middle: there is no server truth to land. Dropped
-  // and never retried — a denial is a decision about this intent, so replaying it on the next
-  // reconcile would put the write the server refused back on the screen.
-  log.drop(key);
-  return { rolledBack, reapplied: replayExcept(store, affected, key) };
-}
-
-function land<T extends TableMap>(
-  store: LocalStore<T>,
-  ack: ServerAck,
-  strategy: ConflictStrategy,
-  rows: { local: Row | undefined; base: Row | undefined },
-  options: ReconcileOptions,
-): 'server' | 'local' | 'merge' {
-  const table = store.table(ack.entity);
-
-  if (strategy === 'server-wins') {
-    write(store, ack.entity, ack.id, ack.row);
-    return 'server';
-  }
-
-  if (strategy === 'last-write-wins') {
-    const field = options.clockField ?? 'updatedAt';
-    const localAt = numberAt(rows.local, field);
-    const serverAt = numberAt(ack.row, field);
-    if (localAt !== null && serverAt !== null && localAt > serverAt) {
-      // The local write is newer by the server's own clock field: keep it, do not clobber.
-      if (rows.local) table.upsert(rows.local);
-      return 'local';
-    }
-    write(store, ack.entity, ack.id, ack.row);
-    return 'server';
-  }
-
-  const merged = strategy.merge({ local: rows.local, base: rows.base, server: ack.row });
-  if (merged === undefined) {
-    throw new RebaseConflictError({
-      key: ack.key,
-      entity: ack.entity,
-      reason: 'custom(merge) returned undefined; return a row, or null to accept the delete',
-    });
-  }
-  write(store, ack.entity, ack.id, merged);
-  return 'merge';
-}
-
-function write<T extends TableMap>(
-  store: LocalStore<T>,
-  entity: string,
-  id: string,
-  row: Row | null,
-): void {
-  const table = store.table(entity);
-  if (row === null) table.delete(id);
-  else table.upsert(row);
-}
-
-function numberAt(row: Row | null | undefined, field: string): number | null {
-  if (!row) return null;
-  const value = row[field];
-  return typeof value === 'number' ? value : null;
-}
-
-/**
- * `RebaseFrame`, not `Frame`: this builds exactly one member of the union and declaring the whole
- * union threw that away, so every caller had to re-narrow a frame it had just constructed before it
- * could read `strategy` or `row` back off it.
- */
-export function rebaseFrame(ack: ServerAck, strategy: ConflictStrategy): RebaseFrame {
-  return {
-    type: 'rebase',
-    v: PROTOCOL_VERSION,
-    key: ack.key,
-    entity: ack.entity,
-    strategy: strategyName(strategy),
-    row: ack.row,
-  };
-}

package/src/server-render-client.ts

@@ -1,96 +0,0 @@
-// What a live client IS on the server: one that serves the first render and opens no socket.
-//
-// The rule it exists for is `@ultimat3/ui`'s, one package over — no runtime and no DOM is a SERVER
-// RENDER, and a server render gets an honest account of itself rather than a throw. A page whose
-// whole body reads a live query could not server-render at all before this: `useConnection()` threw
-// `X_LIVE_CLIENT_MISSING` and the route answered 500 (issue #271).
-//
-// It implements `LiveClientLike` and imports NO connection lifecycle — no `LiveClient`, no
-// heartbeat, no wire protocol. Measured: reaching the class from here costs every island that
-// calls `useLive` 18 kB it can never run.
-
-import type { LiveClientLike, LiveHandle, LiveQueryRef, SignalFactory } from './client-contract';
-import { ServerRenderLiveError } from './errors';
-import type { JsonValue, Row } from './json';
-import type { LiveState } from './live-rows';
-
-/**
- * A signal that never changes, because nothing on the server can change it: one render, one pass,
- * no reactive runtime. The setter is kept rather than dropped so a caller that writes through it
- * reads its own write back — a signal that swallowed writes would be a different lie.
- */
-const inertSignal: SignalFactory = <T>(initial: T): [() => T, (next: T) => void] => {
-  let held = initial;
-  return [
-    (): T => held,
-    (next: T): void => {
-      held = next;
-    },
-  ];
-};
-
-/** Frozen, so a handle a page holds cannot be turned into a result set by writing to it. */
-const NO_ROWS: readonly Row[] = Object.freeze([]);
-
-/** Nothing was subscribed, so nothing is released — and a teardown never fails a render. */
-const releaseNothing = (): void => undefined;
-
-/**
- * The handle a server render gets for a live query: `loading`, never `offline` and never `live`.
- *
- * That is the one honest state — the rows arrive over a socket this render does not have, so the
- * page's own loading fallback is what the document carries until hydration replaces it. `offline`
- * would be read as a SETTLED answer (`state() !== 'loading'` is the gate `examples/dummy`'s feed
- * uses), so an empty result set would render "you have no posts" for a feed that has some.
- */
-function serverRenderHandle<R extends Row>(): LiveHandle<R> {
-  return {
-    rows: () => NO_ROWS as readonly R[],
-    state: (): LiveState => 'loading',
-    cursor: () => null,
-    unsubscribe: releaseNothing,
-    [Symbol.dispose]: releaseNothing,
-  };
-}
-
-/**
- * Every member that can only mean "talk to the socket" refuses; every member a render READS
- * answers what a server render actually is.
- *
- * `connected: true` is not a lie about the socket — `useConnection().offline` is a banner about
- * THIS visitor's connectivity, and the request being served is the proof it is up. Answering
- * `false` would server-render "you are offline" into every document, for a reader who is not, and
- * then remove it on hydrate.
- *
- * It registers nothing, which is what makes ONE instance per process safe under concurrent
- * renders: a client that kept a registration per `useLive` would grow by one entry per request,
- * forever, and hold a row window with each.
- */
-function build(): LiveClientLike {
-  return {
-    signal: inertSignal,
-    queue: undefined,
-    connected: true,
-    reconnectAt: () => null,
-    appUpdateAvailable: () => null,
-    useLive: <R extends Row>(_query: LiveQueryRef, _input: JsonValue): LiveHandle<R> =>
-      serverRenderHandle<R>(),
-    mutate: (): Promise<void> => {
-      throw new ServerRenderLiveError({ operation: 'mutate()' });
-    },
-    drain: (): Promise<void> => {
-      throw new ServerRenderLiveError({ operation: 'drain()' });
-    },
-    // A listener is accepted and never called: nothing on the server can change a queue that does
-    // not exist. Refusing here would break `setLiveClient`, which registers one unconditionally.
-    onQueueChange: () => releaseNothing,
-  };
-}
-
-let held: LiveClientLike | null = null;
-
-/** ONE per process, built on first use. It holds nothing per request — see `build` above. */
-export function serverRenderLiveClient(): LiveClientLike {
-  held ??= build();
-  return held;
-}