@ultimat3/realtime 20.2.1 → 22.0.0

package/src/type-pins.ts

@@ -1,83 +1,52 @@
-// Compile-time pins for the typed query hook. Source, not a `.test.ts`, on purpose:
-// `tsconfig.json` excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a
-// type-level assertion written there can never fail. This module emits nothing and exports
-// nothing anybody imports — a regression is a build error, the only enforcement that counts
-// (axiom 3). What it protects is the whole reason `liveHookFor` exists: `useLiveFeed({ orgId })`
-// carrying the query's own input and row types. Lose that and the hook still runs — it just
-// stops catching the typo that makes a subscription match nothing.
+// Compile-time pins for the hook surface. Source, not a `.test.ts`, on purpose: `tsconfig.json`
+// excludes `src/**/*.test.ts`, so `tsc -b` never reads a test file and a type-level assertion
+// written there can never fail. This module emits nothing anybody imports — a regression is a
+// build error, the only enforcement that counts (axiom 3).
 
-import type { Query } from '@ultimat3/query';
-import type { LiveClient, LiveClientLike, LiveHandle, Unsubscribe } from './client';
-import type { LiveRows } from './hooks';
-import type { LiveQueryHook, LiveQuerySource } from './query-hook';
+import type { AsyncState, Row } from '@ultimat3/core';
+import type { LiveHandle, Unsubscribe } from './client-contract';
+import type { QueryAccessor, QueryRef } from './use-query';
+import type { RecordAccessor } from './use-record';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
 type Assert<T extends true> = T;
 
 type Equals<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
 
-/** The input type a `Query` accepts, read off its call signature rather than its schema. */
-type InputOf<Q> = Q extends (input: infer I, options?: never) => unknown ? I : never;
-
-interface FeedInput {
-  readonly orgId: string;
-}
-
 interface FeedRow {
   readonly id: string;
   readonly title: string;
 }
 
-type FeedHook = LiveQueryHook<FeedInput, FeedRow>;
-
-/** The hook takes the query's own input, as a value or as the thunk `useLive` reads once. */
-export type _HookInputIsTheQueryInput = Assert<
-  Equals<Parameters<FeedHook>[0], FeedInput | (() => FeedInput)>
->;
-
-/** …and answers in the query's own row type, not the wire's `Row`. */
-export type _HookRowsAreTheQueryRows = Assert<
-  Equals<ReturnType<ReturnType<FeedHook>>, readonly FeedRow[]>
->;
-
 /**
- * A wrong key is refused. Written as a negative because that is the failure being pinned: a hook
- * whose input widened to `JsonValue` would still compile everywhere and silently accept `orgIdd`.
+ * `useQuery` answers core's `AsyncState` over the caller's own row type — the value `@ultimat3/ui`
+ * takes as `state`, with no adapter between them (plan 101, decision 10).
  */
-export type _WrongInputKeyIsRefused = Assert<
-  [{ readonly orgIdd: string }] extends [Parameters<FeedHook>[0]] ? false : true
+export type _QueryAnswersAsyncState = Assert<
+  Equals<ReturnType<QueryAccessor<FeedRow>>, AsyncState<readonly FeedRow[]>>
 >;
 
-/**
- * The seam itself: a declared `@ultimat3/query` `Query` assigns to the structural shape
- * `liveHookFor` binds. Named structurally rather than imported as a value, so this stays the one
- * place a change to `Query` — losing `isLive`, ceasing to be callable — fails, instead of every
- * component call site in every app.
- */
-export type _DeclaredQueryBindsToTheHook = Assert<
-  [Query] extends [LiveQuerySource<InputOf<Query>, Record<string, unknown>>] ? true : false
+/** …and `useRecord` the same vocabulary, with `undefined` for a record the server removed. */
+export type _RecordAnswersAsyncState = Assert<
+  Equals<ReturnType<RecordAccessor<FeedRow>>, AsyncState<FeedRow | undefined>>
 >;
 
 /**
- * The handle `LiveClient.useLive()` returns must stay `Disposable`, or `using sub =
- * client.useLive(...)` silently degrades to "never unsubscribes" the moment someone drops the
- * `[Symbol.dispose]` member while refactoring `unsubscribe`.
+ * A query ref carries no server field: a `Query` VALUE in an island drags its whole read path into
+ * the bundle, so the ref is a name and two declared facts. A `sql` key is refused.
  */
-export type _LiveHandleIsDisposable = Assert<[LiveHandle] extends [Disposable] ? true : false>;
-
-/** Same pin, one layer up: the hook's callable result set must stay `Disposable` too. */
-export type _LiveRowsIsDisposable = Assert<[LiveRows] extends [Disposable] ? true : false>;
-
-/** `channel.subscribe()`'s return must stay both callable and `Disposable`. */
-export type _UnsubscribeIsDisposable = Assert<[Unsubscribe] extends [Disposable] ? true : false>;
+export type _QueryRefHasNoServerHalf = Assert<
+  [{ readonly name: string; readonly sql: () => unknown }] extends [Required<QueryRef>]
+    ? false
+    : true
+>;
 
-/**
- * The hook seam takes `LiveClientLike`, not `LiveClient` — a structural shape, so the server
- * render's client can satisfy it without dragging the connection lifecycle into every island that
- * calls `useLive` (measured: 8,368 B → 26,571 B). This is what keeps the two in step: a member
- * `hooks.ts` needs and `LiveClient` stops providing fails HERE, at the build, rather than at the
- * one app that registered a real client.
- */
-export type _LiveClientSatisfiesTheHookSeam = Assert<
-  [LiveClient] extends [LiveClientLike] ? true : false
+/** Every handle a caller gets back stays `Disposable`, so `using` releases it on scope exit. */
+export type _LiveHandleIsDisposable = Assert<[LiveHandle] extends [Disposable] ? true : false>;
+export type _QueryAccessorIsDisposable = Assert<
+  [QueryAccessor] extends [Disposable] ? true : false
 >;
+export type _RecordAccessorIsDisposable = Assert<
+  [RecordAccessor<Row>] extends [Disposable] ? true : false
+>;
+export type _UnsubscribeIsDisposable = Assert<[Unsubscribe] extends [Disposable] ? true : false>;

package/src/use-channel.ts

@@ -0,0 +1,88 @@
+// 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.
+
+import type { ChannelHandlers, ChannelRef, ChannelState } from './client-channels';
+import { pageSocket } from './page-socket';
+import { isServerRender, signalFor } from './reactivity';
+import type { PresenceMember } from './sync-protocol';
+
+/** The membership's state, callable, plus its release (Solid: `onCleanup`). */
+export type ChannelAccessor = (() => ChannelState) & {
+  release(): void;
+  [Symbol.dispose](): void;
+};
+
+const nothing = (): void => undefined;
+
+/**
+ * Takes the `channel()` DECLARATION (any `ChannelRef` — a declaration is one), never a topic
+ * string: the declaration is the only thing that may spell a topic (`bun run channel-literals`
+ * holds it), so both halves spell it one way.
+ */
+export function useChannel<K extends string>(
+  declared: ChannelRef<K>,
+  params: Readonly<Record<K, string>>,
+  handlers?: ChannelHandlers,
+): ChannelAccessor {
+  const signal = signalFor('useChannel');
+  if (isServerRender()) {
+    return Object.assign((): ChannelState => 'joining', {
+      release: nothing,
+      [Symbol.dispose]: nothing,
+    });
+  }
+  const membership = pageSocket('useChannel').holdChannel(declared, params, handlers);
+  const [version, setVersion] = signal(0);
+  const off = membership.onChange(() => setVersion(version() + 1));
+  const read = (): ChannelState => {
+    version();
+    return membership.state();
+  };
+  const release = (): void => {
+    off();
+    membership.release();
+  };
+  return Object.assign(read, { release, [Symbol.dispose]: release });
+}
+
+/** Who is in a channel's room, as the node's presence set says — one entry per member id. */
+export type PresenceAccessor = (() => readonly PresenceMember[]) & {
+  release(): void;
+  [Symbol.dispose](): void;
+};
+
+/**
+ * The roster of a channel declared with `events: true`: a `sync` replaces it, `join` / `update`
+ * upsert a member, `leave` removes one. It is a membership of the channel like any other — the
+ * same one `useChannel` holds, shared on the page — so holding both costs one subscribe.
+ */
+export function usePresence<K extends string>(
+  declared: ChannelRef<K>,
+  params: Readonly<Record<K, string>>,
+): PresenceAccessor {
+  const signal = signalFor('usePresence');
+  if (isServerRender()) {
+    return Object.assign((): readonly PresenceMember[] => [], {
+      release: nothing,
+      [Symbol.dispose]: nothing,
+    });
+  }
+  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 read = (): readonly PresenceMember[] => {
+    version();
+    return [...members.values()];
+  };
+  return Object.assign(read, { release: membership.release, [Symbol.dispose]: membership.release });
+}

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,227 @@
+// 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);
+    // Older writes still wait in the outbox: this one queues BEHIND them rather than overtaking
+    // them over HTTP — a like queued offline and the unlike made once the network was back could
+    // otherwise land swapped. The replay sends the queue in order, this write last, under its key.
+    const queued = peekOutbox();
+    if (queued !== undefined && queued.pending().length > 0) {
+      try {
+        await queued.enqueue({ key, name: mutator.name, input });
+        void queued.replay().catch(() => undefined);
+        return undefined;
+      } finally {
+        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;
+    },
+  };
+}