okengine 0.17.2 → 0.18.3

package/src/client/use-live-query.ts

@@ -0,0 +1,154 @@
+/**
+ * Live query client core — reducer + snapshot/SSE ordering primitives.
+ *
+ * Framework-agnostic so React (`useLiveQuery` in `client-react`) and other
+ * renderers share one implementation. The wire taxonomy mirrors the server's
+ * `LiveQueryEvent` exactly: classified per-subscriber RLS verdicts pushed
+ * directly per subscriber (never a shared tape).
+ *
+ * @module
+ */
+
+/** Wire event kinds served by a resource live route (`GET <path>/live`). */
+export type LiveQueryEvent<Row = Record<string, unknown>> =
+  | {
+      readonly kind: "upsert";
+      readonly row: Row;
+      readonly seq?: number;
+      /** Echoed `X-Oke-Mutation-Id` — identifies the write that caused it. */
+      readonly mutationId?: string;
+    }
+  | {
+      readonly kind: "revoked";
+      readonly id: string;
+      readonly reason: "rls" | "query";
+      readonly seq?: number;
+    }
+  | { readonly kind: "delete"; readonly id: string; readonly seq?: number };
+
+/** Error codes surfaced on `error` in hook state. */
+export type LiveQueryError =
+  | { readonly kind: "initial"; readonly error: unknown }
+  | { readonly kind: "connection"; readonly error: unknown };
+
+/** Field names probed for LWW guards when no explicit `versionOf` is given. */
+const VERSION_FIELD_CANDIDATES = ["updatedAt", "updated_at", "version"] as const;
+
+/**
+ * Pure row-list reducer for the three event kinds.
+ *
+ * - `upsert` → replace-or-append by PK (optimistic overrides re-applied)
+ * - `revoked` / `delete` → remove by PK (silent staleness impossible)
+ *
+ * @param rows - Current row list
+ * @param idOf - Primary-key extractor
+ * @param event - Classified server event
+ * @param overrides - Optimistic patches keyed by PK
+ */
+export function reduceLiveQueryRows<Row>(
+  rows: readonly Row[],
+  idOf: (row: Row) => string,
+  event: LiveQueryEvent<Row>,
+  overrides?: ReadonlyMap<string, Partial<Row>>,
+): Row[] {
+  if (event.kind === "upsert") {
+    const id = idOf(event.row);
+    const patch = overrides?.get(id);
+    const patched = patch !== undefined ? ({ ...event.row, ...patch } as Row) : event.row;
+    const idx = rows.findIndex((r) => idOf(r) === id);
+    if (idx === -1) return [...rows, patched];
+    const next = [...rows];
+    next[idx] = patched;
+    return next;
+  }
+  return rows.filter((r) => idOf(r) !== event.id);
+}
+
+/**
+ * Idempotence guard for replayed SSE events: drop anything at or below the
+ * highest sequence number already applied for this subscription (Realtime
+ * correctness contract — reconnect replay must not double-apply). Events
+ * without a `seq` always apply.
+ *
+ * @param lastAppliedSeq - Highest seq applied so far (`0` = none)
+ * @param event - Incoming classified event
+ * @returns True when the event must be ignored
+ */
+export function isReplayedEvent(
+  lastAppliedSeq: number,
+  event: { readonly kind: string; readonly seq?: number },
+): boolean {
+  return event.seq !== undefined && event.seq <= lastAppliedSeq;
+}
+
+/**
+ * LWW guard between an existing row image and an incoming event row.
+ *
+ * True when `incoming` is provably older: both sides expose a comparable
+ * version field (`versionOf` override, else `updatedAt`/`updated_at`/
+ * `version`) and `existing >= incoming`. Uncomparable → never stale.
+ *
+ * @param existing - Row currently held client-side
+ * @param incoming - Row carried by the CDC upsert
+ * @param versionOf - Optional explicit version extractor
+ */
+export function isStaleUpsert<Row>(
+  existing: Row,
+  incoming: Row,
+  versionOf?: ((row: Row) => number | string | null) | undefined,
+): boolean {
+  const extract =
+    versionOf ??
+    ((row: Row): number | string | null => {
+      const bag = row as Record<string, unknown>;
+      for (const f of VERSION_FIELD_CANDIDATES) {
+        const v = bag[f];
+        if (typeof v === "number" || typeof v === "string") return v;
+      }
+      return null;
+    });
+  const a = extract(existing);
+  const b = extract(incoming);
+  if (a === null || b === null) return false;
+  if (typeof a === "number" && typeof b === "number") return a >= b;
+  // ISO-ish strings compare lexicographically; mixed kinds fall back safe.
+  if (typeof a === "string" && typeof b === "string") return a >= b;
+  return false;
+}
+
+/**
+ * Reconcile one row into the optimistic override map.
+ *
+ * The map only carries the fields the caller patched, so a later server
+ * upsert re-applies them over the possibly-older wire image. Cleared when a
+ * PK round-trips (confirm from response or CDC) or rolls back on error.
+ *
+ * @param current - Existing override map (or `undefined`)
+ * @param id - Row PK
+ * @param patch - Fields to overlay
+ */
+export function applyOptimisticPatch<Row>(
+  current: ReadonlyMap<string, Partial<Row>> | undefined,
+  id: string,
+  patch: Partial<Row>,
+): ReadonlyMap<string, Partial<Row>> {
+  const next = new Map(current ?? []);
+  next.set(id, { ...(next.get(id) ?? {}), ...patch });
+  return next;
+}
+
+/**
+ * Drop overrides for ids confirmed gone (delete/revoked, failed mutation).
+ *
+ * @param current - Override map
+ * @param removedIds - Ids to clear
+ */
+export function clearOptimisticPatch<Row>(
+  current: ReadonlyMap<string, Partial<Row>> | undefined,
+  removedIds: readonly string[],
+): ReadonlyMap<string, Partial<Row>> {
+  if (!current || removedIds.length === 0) return current ?? new Map();
+  const next = new Map(current);
+  for (const id of removedIds) next.delete(id);
+  return next;
+}

package/src/client-react/index.ts

@@ -1,9 +1,23 @@
 /**
- * React helpers for okengine clients — `useSession` / `useLive` over {@link createClient}.
+ * React helpers for okengine clients — `useSession` / `useLive` /
+ * `useLiveQuery` over {@link createClient}.
  *
  * @module
  */
 
+export {
+  subscribeLiveResource,
+  type ResourceStreamHandlers,
+  type ResourceStreamOptions,
+  type ResourceStreamStop,
+} from "./live-resource.ts";
+export type { LiveRouteContract } from "./use-live-query.ts";
+export {
+  useLiveQuery,
+  type UseLiveQueryOptions,
+  type UseLiveQueryState,
+} from "./use-live-query.ts";
+
 import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
 import type { MemorySession } from "../client/auth.ts";
 import type { ClientLive, LiveInput, LiveSignalHandle } from "../client/types.ts";

package/src/client-react/live-resource.ts

@@ -0,0 +1,246 @@
+/**
+ * SSE subscription to a resource live route (`GET <path>/live`).
+ *
+ * Same fetch-SSE physics as `client/live.ts` (frame parsing, backoff,
+ * auth), typed for the classified row-event taxonomy. Classified events are
+ * per-connection — there is no shared tape, so gaps cannot resume by
+ * cursor; consumers heal with a list refetch instead.
+ *
+ * @module
+ */
+
+import type { ClientFetch, ClientHeaders } from "../client/types.ts";
+import type { LiveQueryEvent } from "../client/use-live-query.ts";
+
+/** First reconnect wait after a drop (mirrors `LIVE_RESUBSCRIBE_INITIAL_MS`). */
+const RESUBSCRIBE_INITIAL_MS = 500;
+
+/** Reconnect cap (mirrors `LIVE_RESUBSCRIBE_MAX_MS`). */
+const RESUBSCRIBE_MAX_MS = 30_000;
+
+/** Frames accepted by {@link subscribeLiveResource}. */
+export interface ResourceStreamHandlers<Row> {
+  readonly onEvent: (event: LiveQueryEvent<Row>) => void;
+  readonly onOpen?: () => void;
+  /** Stream error or close while `autoResubscribe` recovers (or terminally). */
+  readonly onError?: (error: unknown) => void;
+}
+
+/** Options for {@link subscribeLiveResource}. */
+export interface ResourceStreamOptions {
+  /** Re-open after a drop with 500ms→30s backoff. Default false. */
+  readonly autoResubscribe?: boolean;
+  /** Headers or per-request getter (Bearer token etc.). */
+  readonly headers?: ClientHeaders | (() => ClientHeaders | Promise<ClientHeaders>);
+  /** Auth token getter (`opts.auth.getToken` passthrough). */
+  readonly getToken?: () => string | null | undefined | Promise<string | null | undefined>;
+  /** Override `globalThis.fetch`. */
+  readonly fetch?: ClientFetch;
+  /** Cross-cutting abort (component teardown uses the returned stop fn). */
+  readonly signal?: AbortSignal;
+}
+
+/** Stop consuming and close the stream. Idempotent. */
+export type ResourceStreamStop = () => void;
+
+/**
+ * Open an SSE subscription to one resource's live route.
+ *
+ * Query fields serialize onto the URL exactly like the list request
+ * (`restGet` grammar: `:param` substitution then query string), so the
+ * server re-derives the identical list window for classification.
+ *
+ * @param base - App origin
+ * @param route - `{ method, path }` from `$routes`
+ * @param query - List filters
+ * @param handlers - Event callbacks
+ * @param options - Backoff / headers / auth token / fetch
+ */
+export function subscribeLiveResource<Row extends Record<string, unknown>>(
+  base: string,
+  route: { readonly method: string; readonly path: string },
+  query: unknown,
+  handlers: ResourceStreamHandlers<Row>,
+  options: ResourceStreamOptions = {},
+): ResourceStreamStop {
+  const ctrl = new AbortController();
+  const outerAbort = (): void => {
+    ctrl.abort();
+  };
+  options.signal?.addEventListener("abort", outerAbort, { once: true });
+  void pump(base, route, query, handlers, options, ctrl.signal);
+  return () => {
+    options.signal?.removeEventListener("abort", outerAbort);
+    ctrl.abort();
+  };
+}
+
+async function pump<Row>(
+  base: string,
+  route: { readonly method: string; readonly path: string },
+  query: unknown,
+  handlers: ResourceStreamHandlers<Row>,
+  options: ResourceStreamOptions,
+  signal: AbortSignal,
+): Promise<void> {
+  const auto = options.autoResubscribe === true;
+  let delayMs = RESUBSCRIBE_INITIAL_MS;
+  let first = true;
+  for (;;) {
+    if (signal.aborted) return;
+    if (!first && auto) {
+      await sleep(delayMs, signal);
+      if (signal.aborted) return;
+      delayMs = Math.min(delayMs * 2, RESUBSCRIBE_MAX_MS);
+    }
+    first = false;
+    try {
+      const res = await openSse(base, route, query, options, signal);
+      if (signal.aborted) return;
+      handlers.onOpen?.();
+      await consume(res, handlers, signal);
+      if (signal.aborted) return;
+      handlers.onError?.(new Error("live connection closed"));
+      if (!auto) return;
+    } catch (err) {
+      if (signal.aborted) return;
+      handlers.onError?.(err);
+      if (!auto) return;
+    }
+  }
+}
+
+async function openSse(
+  base: string,
+  route: { readonly method: string; readonly path: string },
+  query: unknown,
+  options: ResourceStreamOptions,
+  signal: AbortSignal,
+): Promise<Response> {
+  const url = streamUrl(base, route.path, query);
+  const headers = new Headers({ accept: "text/event-stream" });
+  const extra = typeof options.headers === "function" ? await options.headers() : options.headers;
+  if (Array.isArray(extra)) {
+    for (const [k, v] of extra) headers.set(k, v);
+  } else if (extra) {
+    for (const [k, v] of Object.entries(extra)) headers.set(k, v);
+  }
+  const token = options.getToken ? await options.getToken() : undefined;
+  if (token && !headers.has("authorization")) {
+    headers.set("authorization", `Bearer ${token}`);
+  }
+  const fetchFn: ClientFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  return fetchFn(url, { method: "GET", headers, signal });
+}
+
+function streamUrl(base: string, path: string, query: unknown): string {
+  const params = query !== null && typeof query === "object" ? query : {};
+  let out = path;
+  const qs: string[] = [];
+  for (const [k, v] of Object.entries(params)) {
+    const token = `:${k}`;
+    if (out.includes(token)) {
+      out = out.replaceAll(token, encodeURIComponent(String(v)));
+    } else if (v !== undefined) {
+      qs.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+  }
+  return `${base}${out}${qs.length > 0 ? `?${qs.join("&")}` : ""}`;
+}
+
+async function consume<Row>(
+  res: Response,
+  handlers: ResourceStreamHandlers<Row>,
+  signal: AbortSignal,
+): Promise<void> {
+  if (!res.ok || !res.body) {
+    const text = await res.text().catch(() => "");
+    throw sseError(res.status, text);
+  }
+  const ct = res.headers.get("content-type") ?? "";
+  if (!ct.includes("text/event-stream")) {
+    throw sseError(res.status, "");
+  }
+  const reader = res.body.getReader();
+  const dec = new TextDecoder();
+  let buf = "";
+  try {
+    for (;;) {
+      if (signal.aborted) return;
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += dec.decode(value, { stream: true });
+      let sep = buf.indexOf("\n\n");
+      while (sep >= 0) {
+        const raw = buf.slice(0, sep);
+        buf = buf.slice(sep + 2);
+        dispatchFrame(raw, handlers, signal);
+        if (signal.aborted) return;
+        sep = buf.indexOf("\n\n");
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function dispatchFrame<Row>(
+  raw: string,
+  handlers: ResourceStreamHandlers<Row>,
+  signal: AbortSignal,
+): void {
+  const dataLines: string[] = [];
+  for (const line of raw.split("\n")) {
+    if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
+  }
+  if (dataLines.length === 0 || signal.aborted) return;
+  const data = dataLines.join("\n");
+  if (data === "[DONE]") return;
+  try {
+    const parsed: unknown = JSON.parse(data);
+    if (!isLiveQueryEvent(parsed)) return;
+    handlers.onEvent(parsed as LiveQueryEvent<Row>);
+  } catch {
+    // Malformed frame — skip; next valid frame keeps state convergent.
+  }
+}
+
+function isLiveQueryEvent(value: unknown): boolean {
+  if (value === null || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  if (typeof v.kind !== "string") return false;
+  if (v.kind === "upsert") return typeof v.row === "object" && v.row !== null;
+  return (v.kind === "revoked" || v.kind === "delete") && typeof v.id === "string";
+}
+
+function sseError(status: number, body: string): Error {
+  let message = `HTTP ${status}`;
+  if (body) {
+    try {
+      const json: unknown = JSON.parse(body);
+      if (json !== null && typeof json === "object" && "error" in json) {
+        const err = (json as { error?: { code?: string; data?: { message?: string } } }).error;
+        message = err?.data?.message ?? err?.code ?? message;
+      }
+    } catch {
+      message = body.slice(0, 200);
+    }
+  }
+  const e = new Error(message);
+  (e as Error & { status?: number }).status = status;
+  return e;
+}
+
+function sleep(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted || ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    function finish(): void {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", finish);
+      resolve();
+    }
+    const timer = setTimeout(finish, ms);
+    signal.addEventListener("abort", finish, { once: true });
+    if (signal.aborted) finish();
+  });
+}