@ultimat3/realtime 24.0.0 → 25.1.0

package/src/use-channel.ts

@@ -1,9 +1,10 @@
 // A declared channel, held by a component. Every holder of one topic on the page shares ONE
-// membership on the page socket; its `records` land in the store (read them with `useRecord` /
-// `useQuery`), and only `events` and presence reach the handlers given here.
+// membership on the page socket — the page runtime's, reached off the page, never bundled here;
+// its `records` land in the store (read them with `useRecord` / `useQuery`), and only `events`
+// and presence reach the handlers given here.
 
 import type { ChannelHandlers, ChannelRef, ChannelState } from './client-channels';
-import { pageSocket } from './page-socket';
+import { installedPage } from './page-store';
 import { isServerRender, signalFor } from './reactivity';
 import type { PresenceMember } from './sync-protocol';
 
@@ -32,7 +33,9 @@ export function useChannel<K extends string>(
       [Symbol.dispose]: nothing,
     });
   }
-  const membership = pageSocket('useChannel').holdChannel(declared, params, handlers);
+  const membership = installedPage('useChannel')
+    .services.socket('useChannel')
+    .holdChannel(declared, params, handlers);
   const [version, setVersion] = signal(0);
   const off = membership.onChange(() => setVersion(version() + 1));
   const read = (): ChannelState => {
@@ -70,16 +73,18 @@ export function usePresence<K extends string>(
   }
   const [version, setVersion] = signal(0);
   let members = new Map<string, PresenceMember>();
-  const membership = pageSocket('usePresence').holdChannel(declared, params, {
-    onPresence: (event) => {
-      if (event.presence === 'sync') members = new Map();
-      for (const member of event.members) {
-        if (event.presence === 'leave') members.delete(member.id);
-        else members.set(member.id, member);
-      }
-      setVersion(version() + 1);
-    },
-  });
+  const membership = installedPage('usePresence')
+    .services.socket('usePresence')
+    .holdChannel(declared, params, {
+      onPresence: (event) => {
+        if (event.presence === 'sync') members = new Map();
+        for (const member of event.members) {
+          if (event.presence === 'leave') members.delete(member.id);
+          else members.set(member.id, member);
+        }
+        setVersion(version() + 1);
+      },
+    });
   const read = (): readonly PresenceMember[] => {
     version();
     return [...members.values()];

package/src/use-connection.ts

@@ -1,8 +1,8 @@
 // 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.
+// the socket — this hook IS a question about it — and the socket is the page runtime's.
 
-import { pageSocket } from './page-socket';
+import { installedPage } from './page-store';
 import { isServerRender, signalFor } from './reactivity';
 
 export interface Connection extends Disposable {
@@ -33,7 +33,7 @@ const SERVER_RENDER: Connection = Object.freeze({
 export function useConnection(): Connection {
   const signal = signalFor('useConnection');
   if (isServerRender()) return SERVER_RENDER;
-  const client = pageSocket('useConnection');
+  const client = installedPage('useConnection').services.socket('useConnection');
   const [version, setVersion] = signal(0);
   const release = client.onStatus(() => setVersion(version() + 1));
   return {

package/src/use-mutation.ts

@@ -1,21 +1,14 @@
 // 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.
+// every island before this returns), then its action over HTTP through core's one transport — the
+// page runtime's, called off the page — with an idempotency key. The answer's records are adopted
+// before the overlay goes — no flicker — and a refusal takes the overlay back. No socket writes.
 
 import type { ConflictPolicy } from '@ultimat3/core/page';
-import {
-  actionPath,
-  clientTransport,
-  isSuperseded,
-  isUltimateError,
-  pageClient,
-  uuid,
-} from '@ultimat3/core/page';
+import { actionPath, isSuperseded, isUltimateError, pageClient, uuidV7 } from '@ultimat3/core/page';
 import type { JsonValue } from './json';
 import { type OutboxHandle, peekOutbox } from './outbox-slot';
 import { OfflineQueueAbandonedError, ServerRenderLiveError } from './page-errors';
-import { type PageWrites, pageRealtime } from './page-store';
+import { installedPage, type PageWrites, pageRealtime } from './page-store';
 import { isServerRender, signalFor } from './reactivity';
 import { carriedBy } from './record-store';
 
@@ -93,7 +86,7 @@ function watch(hook: string, writes: PageWrites | undefined): [() => number, ()
 function restoreOverlays(mutator: MutatorLike): void {
   const local = mutator.local;
   if (local === undefined) return;
-  const page = pageRealtime();
+  const page = installedPage('useMutation');
   // 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();
@@ -127,9 +120,9 @@ export function useMutation(mutator: MutatorLike): Mutate {
   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 page = installedPage('useMutation');
     const issued = pageClient().scope.epoch;
-    const key = `${mutator.name}:${uuid()}`;
+    const key = `${mutator.name}:${uuidV7()}`;
     const local = mutator.local;
     // Called back through the mutator: `local` may be a method, and an unbound one loses `this`.
     if (local !== undefined) {
@@ -175,7 +168,7 @@ export function useMutation(mutator: MutatorLike): Mutate {
     /** The records the answer carried, `type:key` — what the overlay may be settled against. */
     const carried = new Set<string>();
     try {
-      output = await clientTransport({
+      output = await page.services.send({
         method: 'POST',
         url: actionPath(mutator.name),
         body: input,

package/src/use-query.ts

@@ -1,14 +1,12 @@
-// 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.
+// The ONE read hook. Live-ness is the query's: a live ref subscribes over the page socket, any other
+// is one HTTP read through `@ultimat3/query`'s client — both the page runtime's, never bundled here.
+// 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 { installedPage, type PageServices } from './page-store';
 import { isServerRender, signalFor } from './reactivity';
 import { type RecordStore, recordKey } from './record-store';
 
@@ -71,11 +69,12 @@ export function useQuery<R extends object = Row>(
       [Symbol.dispose]: nothing,
     });
   }
+  const page = installedPage('useQuery');
   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);
+    ? liveAccessor<R>(page.services.socket('useQuery').subscribeLive<R>(ref, input), version, bump)
+    : readAccessor<R>(page.store, page.services.read(ref.name), ref, input, options, version, bump);
 }
 
 function liveAccessor<R extends object>(
@@ -115,6 +114,7 @@ function liveAccessor<R extends object>(
 
 function readAccessor<R extends object>(
   store: RecordStore,
+  method: ReturnType<PageServices['read']>,
   ref: QueryRef,
   input: JsonValue,
   options: QueryOptions,
@@ -122,7 +122,6 @@ function readAccessor<R extends object>(
   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[] = [];
@@ -177,9 +176,10 @@ function readAccessor<R extends object>(
       append && after !== null ? { first: options.first, after } : { first: options.first };
     // The page's cursor travels WITH its rows and is taken only where the rows are: a `more()`
     // a refetch superseded wrote its cursor here, before the generation check discarded its rows.
+    // `nextCursor` is `null` exactly when `hasMore` is false (core's `Page`), so it IS the answer.
     return method.page(input, controls, { onEnvelope }).then((page) => ({
       ...answered(page.rows as readonly Row[]),
-      next: page.hasNextPage ? page.endCursor : null,
+      next: page.nextCursor,
     }));
   };
 

package/src/use-record.ts

@@ -1,11 +1,12 @@
 // 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.
+// twin). A reader of the page runtime's store: an island that only reads records ships the hook and
+// none of the store, the socket or its lifecycle.
 
 import type { AsyncState, Row } from '@ultimat3/core/page';
 import { pageStore } from './page-store';
 import { isServerRender, signalFor } from './reactivity';
-import { recordKey } from './record-store';
+import { type RecordStore, recordKey } from './record-store';
 
 /**
  * A callable `AsyncState`: `pending` until the record first arrives, `ready` from then on —
@@ -31,7 +32,7 @@ export function useRecord<R extends object = Row>(type: string, key: string): Re
       [Symbol.dispose]: releaseNothing,
     });
   }
-  const store = pageStore();
+  const store = pageStore('useRecord');
   const [version, setVersion] = signal(0);
   const target = recordKey(type, key);
   store.retain(type, key);
@@ -59,20 +60,37 @@ export function useRecord<R extends object = Row>(type: string, key: string): Re
   return Object.assign(read, { release, [Symbol.dispose]: release });
 }
 
-/** A callable `AsyncState` over several records, in the order their keys were given. */
+/** A callable `AsyncState` over several records of one type. */
 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.
+ * Which records of a type a whole-type `useRecords` shows, and in what order. Both run on every
+ * change to that type, in the browser, over rows already on the page: pure, and cheap.
+ */
+export interface RecordSelection<R extends object = Row> {
+  /** Keep a record only when this answers `true`. Absent: every record of the type. */
+  readonly where?: (record: R) => boolean;
+  /** Absent: by record key, ascending — creation order for a uuid v7 key. */
+  readonly order?: (a: R, b: R) => number;
+}
+
+/**
+ * Records of one type out of the page store — the same objects `useRecord` hands out.
+ *
+ * - **By key** (`useRecords('posts', keys)`): `pending` until the first of them arrives, then
+ *   `ready` with those present, in key order; a record the server removed drops out.
+ * - **The whole type** (`useRecords('runs', {})`, `useRecords('runs', { where, order })`): every record
+ *   of it the store holds — HTTP answers, live patches, a channel's `records` frames and pending
+ *   optimistic writes alike — `ready` from the first read (an empty store is an empty list; whether
+ *   the page has caught up is the channel's or the query's to say). A record a frame adopts joins
+ *   the list; none is evicted while it is held. The channel-records counterpart of a live window.
  */
 export function useRecords<R extends object = Row>(
   type: string,
-  keys: readonly string[],
+  select: readonly string[] | RecordSelection<R>,
 ): RecordsAccessor<R> {
   const signal = signalFor('useRecords');
   if (isServerRender()) {
@@ -81,8 +99,24 @@ export function useRecords<R extends object = Row>(
       [Symbol.dispose]: releaseNothing,
     });
   }
-  const store = pageStore();
+  const store = pageStore('useRecords');
   const [version, setVersion] = signal(0);
+  const bump = (): void => setVersion(version() + 1);
+  return isKeyList(select)
+    ? byKeys<R>(store, type, select, version, bump)
+    : ofType<R>(store, type, select, version, bump);
+}
+
+// `Array.isArray` narrows a `readonly` array union to `any[]`; this keeps the element type.
+const isKeyList = (value: unknown): value is readonly string[] => Array.isArray(value);
+
+function byKeys<R extends object>(
+  store: RecordStore,
+  type: string,
+  keys: readonly string[],
+  version: () => number,
+  bump: () => void,
+): RecordsAccessor<R> {
   const targets = new Set(keys.map((key) => recordKey(type, key)));
   const present = (): R[] => {
     const out: R[] = [];
@@ -100,7 +134,7 @@ export function useRecords<R extends object = Row>(
   const unsubscribe = store.subscribe((changed) => {
     if (![...changed].some((key) => targets.has(key))) return;
     if (present().length > 0) seen = true;
-    setVersion(version() + 1);
+    bump();
   });
   const read = (): AsyncState<readonly R[]> => {
     version();
@@ -119,3 +153,48 @@ export function useRecords<R extends object = Row>(
   };
   return Object.assign(read, { release, [Symbol.dispose]: release });
 }
+
+function ofType<R extends object>(
+  store: RecordStore,
+  type: string,
+  selection: RecordSelection<R>,
+  version: () => number,
+  bump: () => void,
+): RecordsAccessor<R> {
+  const prefix = `${type}:`;
+  const { where, order } = selection;
+  store.retainType(type);
+  // Recomputed once per change to this type, never per read: the same answer back is what tells
+  // a fine-grained renderer nothing moved.
+  let answer: AsyncState<readonly R[]> | null = null;
+  let answered = -1;
+  const unsubscribe = store.subscribe((changed) => {
+    for (const rk of changed) {
+      if (!rk.startsWith(prefix)) continue;
+      bump();
+      return;
+    }
+  });
+  const read = (): AsyncState<readonly R[]> => {
+    const at = version();
+    if (answer !== null && answered === at) return answer;
+    // The store holds JSON rows; the caller names the entity row type it reads them as.
+    const keyed = store.keyed(type) as readonly (readonly [string, R])[];
+    const kept = where === undefined ? [...keyed] : keyed.filter(([, row]) => where(row));
+    const rows =
+      order === undefined
+        ? kept.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([, row]) => row)
+        : kept.map(([, row]) => row).sort(order);
+    answer = { status: 'ready', data: rows };
+    answered = at;
+    return answer;
+  };
+  let held = true;
+  const release = (): void => {
+    if (!held) return;
+    held = false;
+    unsubscribe();
+    store.releaseType(type);
+  };
+  return Object.assign(read, { release, [Symbol.dispose]: release });
+}

package/src/wire-channel.ts

@@ -12,7 +12,7 @@ import type {
   ChannelSubscribeTarget,
   ReplayGapFrame,
 } from './channel-wire';
-import { isJsonObject, type JsonObject } from './json';
+import { isParsedJsonObject, type JsonObject } from './json';
 import { fail, list, num, object, str } from './wire-read';
 import { FRAME_LIMITS, PROTOCOL_VERSION } from './wire-version';
 
@@ -77,7 +77,7 @@ export function channelTarget(value: JsonObject): ChannelSubscribeTarget {
 }
 
 function sinceOf(value: unknown): ChannelSince {
-  if (!isJsonObject(value)) throw fail('channel since must be an object');
+  if (!isParsedJsonObject(value)) throw fail('channel since must be an object');
   const seq = num(value, 'seq');
   if (!Number.isInteger(seq) || seq < 0) throw fail('channel since.seq must be a whole number');
   return { epoch: str(value, 'epoch'), seq };
@@ -85,11 +85,11 @@ function sinceOf(value: unknown): ChannelSince {
 
 /** type → key → row. Every row an object, and the whole frame under the snapshot row ceiling. */
 function adoptOf(value: unknown): ChannelAdopt {
-  if (!isJsonObject(value)) throw fail('records.adopt must be an object');
+  if (!isParsedJsonObject(value)) throw fail('records.adopt must be an object');
   let total = 0;
   const out = bare<Readonly<Record<string, Row>>>();
   for (const [type, keyed] of Object.entries(value)) {
-    if (!isJsonObject(keyed)) throw fail(`records.adopt.${type} must be an object`);
+    if (!isParsedJsonObject(keyed)) throw fail(`records.adopt.${type} must be an object`);
     const rows = bare<Row>();
     for (const [key, row] of Object.entries(keyed)) {
       total += 1;
@@ -104,7 +104,7 @@ function adoptOf(value: unknown): ChannelAdopt {
 }
 
 function removeOf(value: unknown): ChannelRemove {
-  if (!isJsonObject(value)) throw fail('records.remove must be an object');
+  if (!isParsedJsonObject(value)) throw fail('records.remove must be an object');
   const out = bare<readonly string[]>();
   for (const type of Object.keys(value)) {
     out[type] = list(value, type, FRAME_LIMITS.rows, `records.remove.${type}`).map((key) => {

package/src/wire-read.ts

@@ -2,7 +2,7 @@
 // refusal is `X_PROTOCOL_VERSION` with the field named. Shared by `sync-protocol.ts` and
 // `wire-channel.ts`, so the channel frames are held to the same ceilings as every other kind.
 
-import { isJsonObject, type JsonObject, type JsonValue } from './json';
+import { isParsedJsonObject, type JsonObject, type JsonValue } from './json';
 import { ProtocolVersionError } from './page-errors';
 import { FRAME_LIMITS, PROTOCOL_VERSION } from './wire-version';
 
@@ -81,6 +81,6 @@ export function bounded(value: JsonValue, label: string): JsonValue {
 }
 
 export function object(value: unknown): JsonObject {
-  if (!isJsonObject(value)) throw fail('expected a JSON object');
+  if (!isParsedJsonObject(value)) throw fail('expected a JSON object');
   return value;
 }

package/src/idb-fake.ts

@@ -1,133 +0,0 @@
-/**
- * An in-memory IndexedDB with exactly the surface `local-store-idb.ts` uses — open with an
- * upgrade, one transaction over named stores, `put` / `delete` / `getAll` / `getAllKeys` — and
- * IndexedDB's own asynchrony: every request answers on a later microtask and a transaction
- * completes after its last request. Bun ships no IndexedDB, and no dependency is worth a test seam.
- * Values are structured-cloned in and out, as the real one does.
- */
-
-import type { IdbDatabaseLike, IdbFactoryLike, IdbRequestLike, IdbStoreLike } from './idb-types';
-
-type Tables = Map<string, Map<string, unknown>>;
-
-export interface FakeIdbOptions {
-  /** `open` fails, as it does in a private window or with storage blocked. */
-  readonly blocked?: boolean;
-  /**
-   * Every write ABORTS its transaction, as a quota refusal does: `abort` fires and nothing else —
-   * no `complete`, no transaction `error` event. Read at write time, so a test can flip it.
-   */
-  quotaExceeded?: boolean;
-}
-
-/** A fresh, empty database server. Share one instance to simulate a reload over the same disk. */
-export function fakeIndexedDb(options: FakeIdbOptions = {}): IdbFactoryLike {
-  const databases = new Map<string, { version: number; tables: Tables }>();
-  return {
-    open(name: string, version: number): IdbRequestLike<IdbDatabaseLike> {
-      const request = pendingRequest<IdbDatabaseLike>();
-      queueMicrotask(() => {
-        if (options.blocked === true) {
-          request.fail(new DOMException('The operation is insecure.', 'SecurityError'));
-          return;
-        }
-        const known = databases.get(name) ?? { version: 0, tables: new Map() };
-        databases.set(name, known);
-        const db = database(known.tables, options);
-        request.result = db;
-        if (known.version < version) {
-          known.version = version;
-          request.onupgradeneeded?.();
-        }
-        request.onsuccess?.();
-      });
-      return request;
-    },
-  };
-}
-
-function database(tables: Tables, options: FakeIdbOptions): IdbDatabaseLike {
-  return {
-    objectStoreNames: { contains: (name: string): boolean => tables.has(name) },
-    createObjectStore: (name: string): void => {
-      tables.set(name, new Map());
-    },
-    transaction(names: string | readonly string[]) {
-      let open = 0;
-      let failed = false;
-      const tx = {
-        oncomplete: null as (() => void) | null,
-        onerror: null as (() => void) | null,
-        onabort: null as (() => void) | null,
-        error: null as unknown,
-        objectStore: (name: string): IdbStoreLike => store(name),
-      };
-      const abort = (): void => {
-        if (failed) return;
-        failed = true;
-        tx.error = new DOMException('The quota has been exceeded.', 'QuotaExceededError');
-        queueMicrotask(() => tx.onabort?.());
-      };
-      const settleLater = (): void => {
-        queueMicrotask(() => {
-          if (open > 0 || failed) return;
-          tx.oncomplete?.();
-        });
-      };
-      const run = <T>(work: () => T): IdbRequestLike<T> => {
-        const request = pendingRequest<T>();
-        open += 1;
-        queueMicrotask(() => {
-          open -= 1;
-          request.result = work();
-          request.onsuccess?.();
-          settleLater();
-        });
-        return request;
-      };
-      const store = (name: string): IdbStoreLike => {
-        const allowed = typeof names === 'string' ? [names] : names;
-        const table = tables.get(name);
-        if (!allowed.includes(name) || table === undefined) {
-          throw new DOMException(`no object store ${name}`, 'NotFoundError');
-        }
-        const sorted = (): [string, unknown][] =>
-          [...table].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-        return {
-          get: (key) => run(() => structuredClone(table.get(key))),
-          put: (value, key) =>
-            run(() => {
-              if (options.quotaExceeded === true) {
-                abort();
-                return;
-              }
-              table.set(key, structuredClone(value));
-            }),
-          delete: (key) => run(() => void table.delete(key)),
-          getAll: () => run(() => sorted().map(([, value]) => structuredClone(value))),
-          getAllKeys: () => run(() => sorted().map(([key]) => key)),
-        };
-      };
-      settleLater();
-      return tx;
-    },
-  };
-}
-
-type PendingRequest<T> = IdbRequestLike<T> & { fail(error: unknown): void };
-
-function pendingRequest<T>(): PendingRequest<T> {
-  const request: PendingRequest<T> = {
-    result: undefined as T,
-    error: null,
-    onsuccess: null,
-    onerror: null,
-    onupgradeneeded: null,
-    onblocked: null,
-    fail(error: unknown): void {
-      request.error = error;
-      request.onerror?.();
-    },
-  };
-  return request;
-}

package/src/policy-fake.ts

@@ -1,14 +0,0 @@
-// A policy that admits every caller, for the tests that declare a channel whose authz is not
-// their subject. Structural, never built with `@ultimat3/policy`: realtime reaches that package
-// only through `@ultimat3/query`'s `guard`, and a direct import would be a second authz path.
-// An app says the same thing with `allow('public')`, which is what this stands in for.
-
-import type { QueryPolicy } from '@ultimat3/query';
-
-export const OPEN_POLICY: QueryPolicy = Object.freeze({
-  kind: 'allow',
-  label: 'public',
-  permissions: [],
-  children: [],
-  run: () => ({ allowed: true as const }),
-});