@ultimat3/realtime 20.2.1 → 21.0.0

package/src/use-connection.ts

@@ -0,0 +1,59 @@
+// The page socket, as four getters: whether it is up, when it redials, and whether a newer build
+// is live. Getters, never a snapshot, so a read inside a tracking scope stays live. Asking opens
+// the socket — this hook IS a question about it.
+
+import { pageSocket } from './page-socket';
+import { isServerRender, signalFor } from './reactivity';
+
+export interface Connection extends Disposable {
+  /** Stop listening to the socket (Solid: `onCleanup`). The socket itself stays up. */
+  release(): void;
+  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;
+}
+
+/**
+ * A server render is ONLINE: the banner is about this visitor's connectivity, and the request
+ * being served is the proof it is up. Answering offline would render "you are offline" into every
+ * document and remove it on hydrate.
+ */
+const SERVER_RENDER: Connection = Object.freeze({
+  release: (): void => undefined,
+  [Symbol.dispose]: (): void => undefined,
+  offline: false,
+  online: true,
+  reconnectAt: null,
+  updateAvailable: null,
+});
+
+export function useConnection(): Connection {
+  const signal = signalFor('useConnection');
+  if (isServerRender()) return SERVER_RENDER;
+  const client = pageSocket('useConnection');
+  const [version, setVersion] = signal(0);
+  const release = client.onStatus(() => setVersion(version() + 1));
+  return {
+    release,
+    [Symbol.dispose]: release,
+    get offline() {
+      version();
+      return !client.connected;
+    },
+    get online() {
+      version();
+      return client.connected;
+    },
+    get reconnectAt() {
+      version();
+      return client.reconnectAt();
+    },
+    get updateAvailable() {
+      version();
+      return client.appUpdateAvailable();
+    },
+  };
+}

package/src/use-mutation.ts

@@ -0,0 +1,214 @@
+// A client write, the one way: the mutator's optimistic twin into the store's OVERLAY (visible to
+// every island before this returns), then its action over HTTP through core's one transport with
+// an idempotency key. The answer's records are adopted before the overlay goes — no flicker — and
+// a refusal takes the overlay back. The socket carries no writes.
+
+import type { ConflictPolicy } from '@ultimat3/core/page';
+import {
+  actionPath,
+  clientTransport,
+  isSuperseded,
+  isUltimateError,
+  uuid,
+} from '@ultimat3/core/page';
+import type { JsonValue } from './json';
+import { type OutboxHandle, peekOutbox } from './outbox-slot';
+import { ServerRenderLiveError } from './page-errors';
+import { type PageWrites, pageRealtime } from './page-store';
+import { isServerRender, signalFor } from './reactivity';
+import { carriedBy } from './record-store';
+
+/**
+ * What a hook needs from a mutator, and nothing a server holds: the name its action is routed
+ * under, the optimistic twin, and the conflict policy. An island declares this beside its
+ * component — the `mutator()` VALUE drags its server half into the bundle.
+ *
+ * `local` is declared with **method syntax** on purpose: TypeScript relates method parameters
+ * bivariantly, so a twin typed over its own `tx` and parsed input assigns here with no cast.
+ */
+export interface MutatorLike {
+  readonly name: string;
+  /** Pure: no I/O, no clock, no randomness — it is REPLAYED over every server update. */
+  local?(tx: unknown, input: unknown): void;
+  /** `@ultimat3/core`'s one row-shaped vocabulary. Default `server-wins`. */
+  readonly conflict?: ConflictPolicy;
+}
+
+/**
+ * A callable mutator with its own in-flight count attached. Resolves with the action's output — or
+ * with `undefined` when the network took nothing and the write went to the outbox, overlay kept.
+ */
+export type Mutate = ((input: JsonValue) => Promise<unknown>) & {
+  /** Calls of this mutator the server has not answered yet. */
+  readonly pending: number;
+  /** Stop counting for this hook (Solid: `onCleanup`). A call already made still settles. */
+  release(): void;
+  [Symbol.dispose](): void;
+};
+
+export interface MutationQueue extends Disposable {
+  /** Optimistic writes the server has not answered yet, across every mutator on the page. */
+  readonly pending: number;
+  /** Writes the server refused since the page loaded. */
+  readonly failed: number;
+  /** Stop listening (Solid: `onCleanup`) — a page-wide listener outlives any one component. */
+  release(): void;
+}
+
+/** How a transport failure failed (`meta.failure`), or `undefined` for any other error. */
+function transportFailure(error: unknown): unknown {
+  if (!isUltimateError(error) || error.code !== 'X_CLIENT_TRANSPORT_FAILED') return undefined;
+  return error.meta?.['failure'];
+}
+
+function notify(writes: PageWrites): void {
+  for (const listener of writes.listeners) listener();
+}
+
+function count(writes: PageWrites, name: string, delta: number): void {
+  const next = (writes.pending.get(name) ?? 0) + delta;
+  if (next > 0) writes.pending.set(name, next);
+  else writes.pending.delete(name);
+  notify(writes);
+}
+
+/**
+ * One version signal over the page's write counts, per hook: that bundle's reactive handle, plus
+ * the release that takes its listener off the page — the counts outlive every component.
+ */
+function watch(hook: string, writes: PageWrites | undefined): [() => number, () => void] {
+  const [version, setVersion] = signalFor(hook)(0);
+  const listener = (): void => setVersion(version() + 1);
+  writes?.listeners.add(listener);
+  return [version, () => writes?.listeners.delete(listener)];
+}
+
+/**
+ * After a reload the outbox still holds the writes the network refused, but the store holds only
+ * synced truth — the persister never writes an overlay. So the first `useMutation` of a mutator on
+ * the page re-applies its twin for each of those writes, in queue order, as the overlay keyed to
+ * that write's idempotency key: a replay then settles or rolls it back exactly as a live write.
+ */
+function restoreOverlays(mutator: MutatorLike): void {
+  const local = mutator.local;
+  if (local === undefined) return;
+  const page = pageRealtime();
+  // The boot opens the outbox; after it, so a queue the previous load left is on disk to read.
+  void page.booted.then(async () => {
+    const outbox = peekOutbox();
+    if (outbox === undefined) return;
+    await outbox.ready;
+    const store = page.store;
+    const shown = new Set(store.pending());
+    for (const entry of outbox.pending()) {
+      if (entry.name !== mutator.name || shown.has(entry.key)) continue;
+      store.push(
+        entry.key,
+        (tx) => mutator.local?.(tx, entry.input),
+        mutator.conflict ?? 'server-wins',
+      );
+    }
+  });
+}
+
+/** The page's outbox once the boot has finished opening it; `undefined` on a page with no boot. */
+async function bootedOutbox(page: {
+  readonly booted: Promise<void>;
+}): Promise<OutboxHandle | undefined> {
+  await page.booted;
+  return peekOutbox();
+}
+
+export function useMutation(mutator: MutatorLike): Mutate {
+  const server = isServerRender();
+  const writes = server ? undefined : pageRealtime().writes;
+  if (!server) restoreOverlays(mutator);
+  const [version, release] = watch('useMutation', writes);
+  const call = async (input: JsonValue): Promise<unknown> => {
+    if (writes === undefined) throw new ServerRenderLiveError({ operation: 'useMutation()' });
+    const page = pageRealtime();
+    const key = `${mutator.name}:${uuid()}`;
+    const local = mutator.local;
+    // Called back through the mutator: `local` may be a method, and an unbound one loses `this`.
+    if (local !== undefined) {
+      page.store.push(key, (tx) => mutator.local?.(tx, input), mutator.conflict ?? 'server-wins');
+    }
+    count(writes, mutator.name, 1);
+    let output: unknown;
+    /** The records the answer carried, `type:key` — what the overlay may be settled against. */
+    const carried = new Set<string>();
+    try {
+      output = await clientTransport({
+        method: 'POST',
+        url: actionPath(mutator.name),
+        body: input,
+        idempotencyKey: key,
+        onEnvelope: (envelope) => carriedBy(envelope, carried),
+      });
+    } catch (error) {
+      const failure = transportFailure(error);
+      // No response at all: the write is the outbox's now, under the SAME idempotency key, and its
+      // overlay stays on screen until the replay settles or refuses it. Only a page the boot opened
+      // an outbox on can promise that; with none (no boot, so nothing on this page persists) the
+      // write is refused like any other, never held in a memory queue a reload would silently lose.
+      const outbox = failure === 'network' ? await bootedOutbox(page) : undefined;
+      if (outbox !== undefined) {
+        await outbox.enqueue({ key, name: mutator.name, input });
+        return undefined;
+      }
+      if (failure === 'body') {
+        // A 2xx whose body was not JSON: the write may well have landed, so it is neither queued
+        // (a replay would be a second attempt) nor taken back — its overlay waits for the next
+        // server row it touched. The caller is still told: nothing here can confirm it.
+        page.store.awaitServer(key);
+        writes.failed += 1;
+        throw error;
+      }
+      page.store.drop(key);
+      // A write superseded by a principal change DID land; it is the previous principal's, and
+      // nothing about it is this page's failure to report.
+      if (!isSuperseded(error)) writes.failed += 1;
+      throw error;
+    } finally {
+      count(writes, mutator.name, -1);
+    }
+    try {
+      // A row the answer did not carry keeps its overlay until the server's row reaches it.
+      page.store.settle(key, carried);
+    } catch (error) {
+      // A custom merge that answered no row: the server's truth stands, and the caller is told.
+      page.store.drop(key);
+      throw error;
+    }
+    return output;
+  };
+  Object.defineProperty(call, 'pending', {
+    get: (): number => {
+      version();
+      return writes?.pending.get(mutator.name) ?? 0;
+    },
+  });
+  Object.assign(call, { release, [Symbol.dispose]: release });
+  // `defineProperty` cannot widen a function type, so the assembled shape is asserted once, here.
+  return call as Mutate;
+}
+
+/** Every write on the page, as two counts. Zero on a server render, where nothing is written. */
+export function useMutationQueue(): MutationQueue {
+  const writes = isServerRender() ? undefined : pageRealtime().writes;
+  const [version, release] = watch('useMutationQueue', writes);
+  return {
+    release,
+    [Symbol.dispose]: release,
+    get pending() {
+      version();
+      let total = 0;
+      for (const n of writes?.pending.values() ?? []) total += n;
+      return total;
+    },
+    get failed() {
+      version();
+      return writes?.failed ?? 0;
+    },
+  };
+}

package/src/use-query.ts

@@ -0,0 +1,255 @@
+// The ONE read hook. Live-ness is the query's, not the hook's: a live ref subscribes over the
+// page socket, any other is one HTTP read through `@ultimat3/query`'s client (and so through
+// core's one transport). Either way a list is an ORDER of keys and the rows are the page store's,
+// so a record updated anywhere re-renders every list showing it without refetching the list.
+
+import { type AsyncState, isSuperseded, type RecordEnvelope, type Row } from '@ultimat3/core/page';
+import { queryClientMethodFor } from '@ultimat3/query/client';
+import type { LiveHandle } from './client-contract';
+import type { JsonValue } from './json';
+import { pageSocket } from './page-socket';
+import { pageStore } from './page-store';
+import { isServerRender, signalFor } from './reactivity';
+import { type RecordStore, recordKey } from './record-store';
+
+/**
+ * What a browser may name a query by: its registered name and two facts the server declaration
+ * holds. Never the query VALUE — importing one drags its whole read path into the island
+ * (measured 698,801 B for the dummy feed). The type has no server field, which is the rule.
+ */
+export interface QueryRef {
+  readonly name: string;
+  /** `live: true` on the declaration: rows arrive and move over the page socket. */
+  readonly live?: boolean;
+  /**
+   * The record type (entity name) a NON-live read's rows are. Named, the list is the keys of the
+   * answer's `records[type]` — store records any write moves; omitted, or answered with no records
+   * envelope, the list holds its rows itself and only a refetch moves them. A live read needs none.
+   */
+  readonly entity?: string;
+}
+
+/** A callable `AsyncState` over the list, plus the two things a caller does to it. */
+export type QueryAccessor<R extends object = Row> = (() => AsyncState<readonly R[]>) & {
+  /** Read again from the first page, keeping the current rows on screen (`refreshing`). */
+  refetch(): void;
+  /**
+   * The next page, appended — from the cursor the server's last page answered with. A no-op on a
+   * live read, on a read with no `first`, and once the server said there is no next page.
+   */
+  more(): void;
+  /** Whether the server's last page said another follows. Reactive, like the accessor itself. */
+  hasMore(): boolean;
+  release(): void;
+  [Symbol.dispose](): void;
+};
+
+const PENDING: AsyncState<never> = Object.freeze({ status: 'pending' });
+const nothing = (): void => undefined;
+
+/**
+ * `input` is read ONCE, at call time: there is no reactive runtime here to re-run it, and a
+ * silently stale subscription is worse than a new call. A changed input is a new `useQuery`.
+ */
+export interface QueryOptions {
+  /** Read in pages of this many rows (`query.page`); `more()` appends the next. Non-live only. */
+  readonly first?: number;
+}
+
+export function useQuery<R extends object = Row>(
+  ref: QueryRef,
+  input: JsonValue,
+  options: QueryOptions = {},
+): QueryAccessor<R> {
+  const signal = signalFor('useQuery');
+  if (isServerRender()) {
+    return Object.assign((): AsyncState<readonly R[]> => PENDING, {
+      refetch: nothing,
+      more: nothing,
+      hasMore: () => false,
+      release: nothing,
+      [Symbol.dispose]: nothing,
+    });
+  }
+  const [version, setVersion] = signal(0);
+  const bump = (): void => setVersion(version() + 1);
+  return ref.live === true
+    ? liveAccessor<R>(pageSocket('useQuery').subscribeLive<R>(ref, input), version, bump)
+    : readAccessor<R>(pageStore(), ref, input, options, version, bump);
+}
+
+function liveAccessor<R extends object>(
+  handle: LiveHandle<R>,
+  version: () => number,
+  bump: () => void,
+): QueryAccessor<R> {
+  // Seen once a snapshot landed — read or not — so a drop after it keeps the rows on screen.
+  let seen = handle.state() === 'live';
+  const off = handle.onChange(() => {
+    if (handle.state() === 'live') seen = true;
+    bump();
+  });
+  const read = (): AsyncState<readonly R[]> => {
+    version();
+    const state = handle.state();
+    if (state === 'failed') return { status: 'failed', error: handle.error() };
+    if (state === 'live') {
+      seen = true;
+      return { status: 'ready', data: handle.rows() };
+    }
+    // Loading, stale or offline: what was shown stays shown, marked busy — never torn down.
+    return seen ? { status: 'refreshing', data: handle.rows() } : PENDING;
+  };
+  const release = (): void => {
+    off();
+    handle.unsubscribe();
+  };
+  return Object.assign(read, {
+    refetch: nothing,
+    more: nothing,
+    hasMore: () => false,
+    release,
+    [Symbol.dispose]: release,
+  });
+}
+
+function readAccessor<R extends object>(
+  store: RecordStore,
+  ref: QueryRef,
+  input: JsonValue,
+  options: QueryOptions,
+  version: () => number,
+  bump: () => void,
+): QueryAccessor<R> {
+  const type = ref.entity;
+  const method = queryClientMethodFor(ref.name, { baseUrl: '' });
+  let state: AsyncState<readonly Row[]> = PENDING;
+  /** Record keys in answer order when the rows are records; the rows themselves when not. */
+  let keys: readonly string[] = [];
+  let own: readonly Row[] = [];
+  let released = false;
+  let generation = 0;
+  /** The cursor the server's last page answered with; `null` = no next page (or not paged). */
+  let after: string | null = null;
+  const off =
+    type === undefined
+      ? nothing
+      : store.subscribe((changed) => {
+          if (keys.some((key) => changed.has(recordKey(type, key)))) bump();
+        });
+
+  const rows = (): readonly Row[] => {
+    if (type === undefined || keys.length === 0) return own;
+    const out: Row[] = [];
+    for (const key of keys) {
+      const row = store.peek(type, key);
+      if (row !== undefined) out.push(row);
+    }
+    return out;
+  };
+
+  const hold = (next: readonly string[]): void => {
+    if (type === undefined) return;
+    store.batch(() => {
+      for (const key of next) store.retain(type, key);
+      for (const key of keys) store.release(type, key);
+    });
+  };
+
+  /**
+   * One answer: its rows, and — when the server sent the records envelope — the KEYS of this
+   * read's records in answer order (`records[type]`, which `rowsOf` fills first-seen = data order).
+   * The browser never derives a key: an answer with no records envelope holds its rows itself.
+   */
+  const fetch = (append: boolean): Promise<{ rows: readonly Row[]; keys: string[] | null }> => {
+    let keysOf: string[] | null = null;
+    const onEnvelope = (envelope: RecordEnvelope): void => {
+      const records = type === undefined ? undefined : envelope.records?.[type];
+      keysOf = records === undefined ? null : Object.keys(records);
+    };
+    const answered = (rows: readonly Row[]) => ({ rows, keys: keysOf });
+    if (options.first === undefined) {
+      return (method(input, { onEnvelope }) as Promise<readonly Row[]>).then(answered);
+    }
+    const controls =
+      append && after !== null ? { first: options.first, after } : { first: options.first };
+    return method.page(input, controls, { onEnvelope }).then((page) => {
+      after = page.hasNextPage ? page.endCursor : null;
+      return answered(page.rows as readonly Row[]);
+    });
+  };
+
+  const load = (append = false): void => {
+    const mine = ++generation;
+    if (state.status === 'ready') state = { status: 'refreshing', data: rows() };
+    bump();
+    fetch(append).then(
+      (answer) => {
+        if (released || mine !== generation) return;
+        if (type === undefined || answer.keys === null) {
+          // Not records — no type named, or no envelope: the list holds its own rows.
+          own = append ? [...own, ...answer.rows] : answer.rows;
+          if (!append) {
+            hold([]);
+            keys = [];
+          }
+        } else {
+          // The transport adopted the envelope's records before this ran; the window is their keys.
+          const answered = answer.keys;
+          const next = append
+            ? [...keys, ...answered.filter((key) => !keys.includes(key))]
+            : answered;
+          hold(next);
+          keys = next;
+          if (!append) own = [];
+        }
+        state = { status: 'ready', data: [] };
+        bump();
+      },
+      (error: unknown) => {
+        if (released || mine !== generation) return;
+        // The page changed principal under this read: its answer was the previous one's, and the
+        // store it would have landed in is already empty. Read again, as the new principal.
+        if (isSuperseded(error)) {
+          load();
+          return;
+        }
+        state = { status: 'failed', error };
+        bump();
+      },
+    );
+  };
+
+  load();
+  const read = (): AsyncState<readonly R[]> => {
+    version();
+    if (state.status === 'pending' || state.status === 'failed') return state;
+    // Rows are typed by the caller's query; the store holds them as JSON rows.
+    const data = rows() as readonly R[];
+    return state.status === 'refreshing'
+      ? { status: 'refreshing', data }
+      : { status: 'ready', data };
+  };
+  const release = (): void => {
+    if (released) return;
+    released = true;
+    off();
+    hold([]);
+    keys = [];
+  };
+  return Object.assign(read, {
+    refetch: () => {
+      after = null;
+      load();
+    },
+    more: () => {
+      if (after !== null && state.status === 'ready') load(true);
+    },
+    hasMore: () => {
+      version();
+      return after !== null;
+    },
+    release,
+    [Symbol.dispose]: release,
+  });
+}

package/src/use-record.ts

@@ -0,0 +1,121 @@
+// One record, by type and key, out of the page's store — the same object every island showing it
+// holds, moved once by whichever write lands first (an HTTP answer, a socket frame, an optimistic
+// twin). Imports no socket: an island that only reads records ships none of the lifecycle.
+
+import type { AsyncState, Row } from '@ultimat3/core/page';
+import { pageStore } from './page-store';
+import { isServerRender, signalFor } from './reactivity';
+import { recordKey } from './record-store';
+
+/**
+ * A callable `AsyncState`: `pending` until the record first arrives, `ready` from then on —
+ * `ready` with `undefined` once the server removed it, so a deleted record is a settled answer
+ * and never a skeleton forever. `release()` lets go; the caller owns it (Solid: `onCleanup`).
+ */
+export type RecordAccessor<R extends object = Row> = (() => AsyncState<R | undefined>) & {
+  release(): void;
+  [Symbol.dispose](): void;
+};
+
+const PENDING: AsyncState<never> = Object.freeze({ status: 'pending' });
+
+/** Nothing was held, so nothing is released — and a teardown never fails a render. */
+const releaseNothing = (): void => undefined;
+
+export function useRecord<R extends object = Row>(type: string, key: string): RecordAccessor<R> {
+  const signal = signalFor('useRecord');
+  if (isServerRender()) {
+    // The record arrives in a browser this render does not have: the page's own loading branch.
+    return Object.assign((): AsyncState<R | undefined> => PENDING, {
+      release: releaseNothing,
+      [Symbol.dispose]: releaseNothing,
+    });
+  }
+  const store = pageStore();
+  const [version, setVersion] = signal(0);
+  const target = recordKey(type, key);
+  store.retain(type, key);
+  // Seen once it has ever been there — read or not — so a removal after it is a settled answer.
+  let seen = store.peek(type, key) !== undefined;
+  const unsubscribe = store.subscribe((changed) => {
+    if (!changed.has(target)) return;
+    if (store.peek(type, key) !== undefined) seen = true;
+    setVersion(version() + 1);
+  });
+  const read = (): AsyncState<R | undefined> => {
+    version();
+    // The store holds JSON rows; the caller names the entity row type it reads them as.
+    const row = store.peek(type, key) as R | undefined;
+    if (row !== undefined) seen = true;
+    return row === undefined && !seen ? PENDING : { status: 'ready', data: row };
+  };
+  let held = true;
+  const release = (): void => {
+    if (!held) return;
+    held = false;
+    unsubscribe();
+    store.release(type, key);
+  };
+  return Object.assign(read, { release, [Symbol.dispose]: release });
+}
+
+/** A callable `AsyncState` over several records, in the order their keys were given. */
+export type RecordsAccessor<R extends object = Row> = (() => AsyncState<readonly R[]>) & {
+  release(): void;
+  [Symbol.dispose](): void;
+};
+
+/**
+ * Several records of one type, by key — the same store objects `useRecord` hands out. `pending`
+ * until the first of them arrives; then `ready` with those present, in key order: a record the
+ * server removed simply drops out, and a list is never shown as its skeleton again.
+ */
+export function useRecords<R extends object = Row>(
+  type: string,
+  keys: readonly string[],
+): RecordsAccessor<R> {
+  const signal = signalFor('useRecords');
+  if (isServerRender()) {
+    return Object.assign((): AsyncState<readonly R[]> => PENDING, {
+      release: releaseNothing,
+      [Symbol.dispose]: releaseNothing,
+    });
+  }
+  const store = pageStore();
+  const [version, setVersion] = signal(0);
+  const targets = new Set(keys.map((key) => recordKey(type, key)));
+  const present = (): R[] => {
+    const out: R[] = [];
+    // The store holds JSON rows; the caller names the entity row type it reads them as.
+    for (const key of keys) {
+      const row = store.peek(type, key) as R | undefined;
+      if (row !== undefined) out.push(row);
+    }
+    return out;
+  };
+  store.batch(() => {
+    for (const key of keys) store.retain(type, key);
+  });
+  let seen = present().length > 0;
+  const unsubscribe = store.subscribe((changed) => {
+    if (![...changed].some((key) => targets.has(key))) return;
+    if (present().length > 0) seen = true;
+    setVersion(version() + 1);
+  });
+  const read = (): AsyncState<readonly R[]> => {
+    version();
+    const rows = present();
+    if (rows.length > 0) seen = true;
+    return !seen ? PENDING : { status: 'ready', data: rows };
+  };
+  let held = true;
+  const release = (): void => {
+    if (!held) return;
+    held = false;
+    unsubscribe();
+    store.batch(() => {
+      for (const key of keys) store.release(type, key);
+    });
+  };
+  return Object.assign(read, { release, [Symbol.dispose]: release });
+}