@ultimat3/realtime 27.14.1 → 27.16.0

package/README.md

@@ -84,7 +84,7 @@ class — stay on `.`.
 | wire | `.` | `PROTOCOL_VERSION` (3), `encode`, `decode`, `Frame` |
 | the node | `./server` | `syncNode` / `listenSyncNode` (`sync` role) |
 | a socket's identity | `./server` | `SyncAuthenticator`, `SyncGrant`, `GrantBook`, `sweepGrants`, `DEFAULT_REAUTH_INTERVAL_MS` |
-| hooks | `.` | `useQuery`, `useRecord`, `useRecords` (by key, or a whole type: `RecordSelection`), `useMutation`, `useMutationQueue`, `useOutbox`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
+| hooks | `.` | `useQuery`, `useRecord`, `useRecords` (by key, or a whole type: `RecordSelection`), `useRecordChanges`, `useMutation`, `useMutationQueue`, `useOutbox`, `useConnection`, `useChannel`, `usePresence`, `hasPageSocket`, `installRealtime` |
 | channel records, no replicator | `./server` | `recordPublisher` — an app's committed rows as channel `records`, sequenced per producer ([below](#channel-records-with-no-replicator)) |
 | channels | `.` | `channel`, `channelRef`, `ChannelHandle`, `topic`, `readPresence`, the channel frame types |
 | first paint | `.` | `holdFirstPaint`, `FIRST_PAINT_HOLD_MS` (1 s) — what the island bootstrap awaits before `mount`, for an island that reads the store or the outbox: the boot's restore and the open outbox, capped (#506). An island taking only `useChannel` / `usePresence` / `useConnection` never awaits it and is never hidden |
@@ -279,6 +279,7 @@ same type `@ultimat3/ui` renders.
 | A query ref is `{ name, live?, entity? }`, never the query VALUE | importing a `query()` drags its read path into the island (698,801 B measured) |
 | Lists hold keys; rows are the store's | a record updated by any answer or frame re-renders every list showing it, with no refetch |
 | A list that must GROW with the store is `useRecords(type, { where?, order? })` | a `useQuery` list holds its own answer's keys and `useRecords(type, keys)` the keys it was given, so a record a channel's `records` frame adopts reaches neither. The whole-type form is the channel-records counterpart of a live window: `ready` from its first read, every record of the type the store holds (optimistic ones included), default order by key, and none evicted while it is held — a row it alone kept goes when the last reader of the type lets go (#680) |
+| Knowing THAT records moved is `useRecordChanges(types, listener)` | one call per store update, the moved keys per type, and no hold on any row or type, so a page that re-renders on a channel's `records` pins nothing. `useChannel(...).error()` is the node's refusal of a `failed` membership |
 | Every write is HTTP through core's `clientTransport` | one write path: the action's authz, idempotency and contract; the socket carries none |
 | The answer's records are adopted before the overlay goes | a convergent twin never flickers back to the pre-write value |
 | **No `solid-js` import.** Each bundle installs its own `SignalFactory` | every island carries its own solid-js; a signal from another bundle is invisible to its effects |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "27.14.1",
+  "version": "27.16.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -40,10 +40,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.14.1",
-    "@ultimat3/entity": "27.14.1",
-    "@ultimat3/policy": "27.14.1",
-    "@ultimat3/query": "27.14.1",
+    "@ultimat3/core": "27.16.0",
+    "@ultimat3/entity": "27.16.0",
+    "@ultimat3/policy": "27.16.0",
+    "@ultimat3/query": "27.16.0",
     "nats": "2.29.3"
   }
 }

package/src/client.ts

@@ -62,6 +62,8 @@ export class LiveClient {
   #attempt = 0;
   /** The armed reconnect's canceller, and the flag for "one timer in flight, the first wins". */
   #reconnectTimer: (() => void) | null = null;
+  /** The armed wait is a node's drain slot: `wake()` leaves it alone, or the herd re-clusters. */
+  #armedByNode = false;
   /** Set by `close()`: an explicit teardown must not be undone by the close it just triggered. */
   #closed = false;
   #connected = false;
@@ -157,7 +159,6 @@ export class LiveClient {
       // and the one handler that had none. A replaced socket opening late would otherwise mark the
       // live connection up and replay every subscription onto whatever socket is current.
       if (this.#socket !== socket) return;
-      this.#attempt = 0;
       this.#setStatus({ connected: true, reconnectAt: null });
       // `hello` announces the connection and nothing else. Each cursor rides its own `subscribe`
       // frame below, which is the only place resume is decided — sending it here too shipped every
@@ -174,6 +175,10 @@ export class LiveClient {
       // that is still draining bytes would otherwise fold its patches into the live registrations
       // a second time, over newer state.
       if (this.#socket !== socket) return;
+      // The curve resets on the node's first word, not on the open: a proxy or an overloaded node
+      // that accepts the upgrade and drops it at once would otherwise reset it every time, and the
+      // tab redialled every half second for as long as that lasted.
+      this.#attempt = 0;
       this.#heartbeat.saw(this.#clock.now().getTime());
       applyFrame(decode(data), this.#frameTarget);
     });
@@ -227,6 +232,24 @@ export class LiveClient {
     this.#offline();
   }
 
+  /**
+   * The network or the tab is back (`online`, a tab made visible): dial now instead of sitting out
+   * the armed backoff. Only a local backoff is cut short — a node's drain slot is how a deploy's
+   * herd is spread, so it is kept — and only while a reconnect is actually armed.
+   */
+  wake(): void {
+    if (this.#closed || this.#connected || this.#reconnectTimer === null || this.#armedByNode)
+      return;
+    this.#cancelReconnect();
+    this.#attempt = 0;
+    try {
+      this.connect();
+    } catch (error) {
+      this.#scheduleReconnect(null);
+      this.#onError(error);
+    }
+  }
+
   /**
    * Subscribe to a live query. The window holds ids; the rows are the page store's, so a record
    * updated by an HTTP response or another window re-renders here too, with no second copy.
@@ -411,6 +434,7 @@ export class LiveClient {
       // `#attempt` counts reconnects already scheduled, from 0; the wait being armed is the next one.
       serverDelayMs ?? policyDelay(this.#options.backoff ?? browserBackoff, this.#attempt + 1, rng);
     this.#attempt += 1;
+    this.#armedByNode = serverDelayMs !== null;
     this.#setStatus({ reconnectAt: this.#clock.now().getTime() + delay });
     const schedule = this.#options.scheduler ?? timeoutScheduler;
     this.#reconnectTimer = schedule(() => {

package/src/index.ts

@@ -202,3 +202,8 @@ export {
   useRecord,
   useRecords,
 } from './use-record';
+export {
+  type RecordChanges,
+  type RecordChangesHandle,
+  useRecordChanges,
+} from './use-record-changes';

package/src/page-socket.ts

@@ -66,16 +66,24 @@ export function pageSocket(hook: string): LiveClient {
     host.rehost();
     client.connect();
   };
+  // The network or the tab came back: dial now, not at the end of a backoff armed while it was gone.
+  const wake = (): void => {
+    if (typeof document === 'undefined' || document.visibilityState !== 'hidden') client.wake();
+  };
   const listens = typeof addEventListener === 'function';
   if (listens) {
     addEventListener('pagehide', bye);
     addEventListener('pageshow', restored);
+    addEventListener('online', wake);
+    if (typeof document !== 'undefined') document.addEventListener('visibilitychange', wake);
   }
   teardowns.add(() => {
     offRescope();
     if (listens) {
       removeEventListener('pagehide', bye);
       removeEventListener('pageshow', restored);
+      removeEventListener('online', wake);
+      if (typeof document !== 'undefined') document.removeEventListener('visibilitychange', wake);
     }
     client.close();
     host.bye();

package/src/use-channel.ts

@@ -8,8 +8,10 @@ import { installedPage } from './page-store';
 import { isServerRender, signalFor } from './reactivity';
 import type { PresenceMember } from './sync-protocol';
 
-/** The membership's state, callable, plus its release (Solid: `onCleanup`). */
+/** The membership's state, callable, plus its refusal and its release (Solid: `onCleanup`). */
 export type ChannelAccessor = (() => ChannelState) & {
+  /** What the node answered when it refused the membership (`failed`); `undefined` otherwise. */
+  error(): unknown;
   release(): void;
   [Symbol.dispose](): void;
 };
@@ -29,6 +31,7 @@ export function useChannel<K extends string>(
   const signal = signalFor('useChannel');
   if (isServerRender()) {
     return Object.assign((): ChannelState => 'joining', {
+      error: (): unknown => undefined,
       release: nothing,
       [Symbol.dispose]: nothing,
     });
@@ -42,11 +45,16 @@ export function useChannel<K extends string>(
     version();
     return membership.state();
   };
+  // Read through the same version, so a component rendering the refusal re-renders with it.
+  const error = (): unknown => {
+    version();
+    return membership.error();
+  };
   const release = (): void => {
     off();
     membership.release();
   };
-  return Object.assign(read, { release, [Symbol.dispose]: release });
+  return Object.assign(read, { error, release, [Symbol.dispose]: release });
 }
 
 /** Who is in a channel's room, as the node's presence set says — one entry per member id. */

package/src/use-record-changes.ts

@@ -0,0 +1,47 @@
+// Which records of some types moved, without holding any of them. A whole-type `useRecords` is the
+// way to SHOW every record of a type, and holding the type is its price: none of its rows is
+// evicted while the reader lives. A reader that only wants to know THAT something moved — re-render
+// a server page, flash a counter — pays nothing here: it holds no row and no type.
+
+import { pageStore } from './page-store';
+import { isServerRender } from './reactivity';
+
+/** Per type, the keys of its records that one store update moved (written, removed or evicted). */
+export type RecordChanges = ReadonlyMap<string, readonly string[]>;
+
+/** The listener's undo — call it, `release()` it or `using` it (Solid: `onCleanup`). */
+export type RecordChangesHandle = (() => void) & { release(): void; [Symbol.dispose](): void };
+
+const nothing = (): void => undefined;
+
+/**
+ * Calls `listener` once per store update that moved at least one record of `types`, with what
+ * moved, grouped by type. Holds nothing: a record no other reader holds is evicted as before.
+ */
+export function useRecordChanges(
+  types: readonly string[],
+  listener: (changed: RecordChanges) => void,
+): RecordChangesHandle {
+  if (isServerRender())
+    return Object.assign(nothing, { release: nothing, [Symbol.dispose]: nothing });
+  const watched = new Set(types);
+  const unsubscribe = pageStore('useRecordChanges').subscribe((changed) => {
+    const moved = new Map<string, string[]>();
+    for (const rk of changed) {
+      const at = rk.indexOf(':');
+      const type = rk.slice(0, at);
+      if (!watched.has(type)) continue;
+      const keys = moved.get(type) ?? [];
+      keys.push(rk.slice(at + 1));
+      moved.set(type, keys);
+    }
+    if (moved.size > 0) listener(moved);
+  });
+  let held = true;
+  const release = (): void => {
+    if (!held) return;
+    held = false;
+    unsubscribe();
+  };
+  return Object.assign(release, { release, [Symbol.dispose]: release });
+}