@syncular/react 0.4.1 → 0.5.0

package/src/use-sync-status.ts

@@ -1,87 +1,34 @@
-/**
- * `useSyncStatus` — the client's operational status: outbox depth,
- * upgrading (§7.4.5), leaseState (§7.3.5), schemaFloor (§1.6), and
- * syncNeeded (§8.4). Status is derived by polling the normalized accessors
- * after every apply batch (invalidation is the natural "something changed"
- * signal) plus an initial read; `refresh()` re-reads on demand.
- *
- * `online` is not a protocol concept the client exposes directly (§1.3
- * transport-owned), so it is reported as `undefined` unless a future
- * accessor lands — the hook surfaces what the core actually knows, never a
- * guessed value.
- */
-
 import type { LeaseState, SchemaFloor } from '@syncular/client';
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { useSyncClient } from './use-client';
+import { useCallback, useSyncExternalStore } from 'react';
+import { useReactiveStore } from './use-client';
 
 export interface SyncStatus {
-  /** Pending outbox commits (unpushed local writes). */
   readonly outbox: number;
-  /** §7.4.5: a schema-bump reset + first re-bootstrap is in flight. */
   readonly upgrading: boolean;
-  /** §7.3.5: opaque auth-lease state, or undefined. */
   readonly leaseState: LeaseState | undefined;
-  /** §1.6: server-declared schema floor (syncing stopped), or undefined. */
   readonly schemaFloor: SchemaFloor | undefined;
-  /** §8.4: the host loop should run a pull soon. */
   readonly syncNeeded: boolean;
-  /** True until the first status read resolves. */
   readonly isLoading: boolean;
+  readonly error: Error | undefined;
   readonly refresh: () => void;
 }
 
-const INITIAL: Omit<SyncStatus, 'refresh'> = {
-  outbox: 0,
-  upgrading: false,
-  leaseState: undefined,
-  schemaFloor: undefined,
-  syncNeeded: false,
-  isLoading: true,
-};
-
 export function useSyncStatus(): SyncStatus {
-  const client = useSyncClient();
-  const [state, setState] = useState(INITIAL);
-  // `refresh` re-reads through a ref set by the effect (identity-stable, no
-  // tick state — biome-clean deps).
-  const readRef = useRef<() => void>(() => {});
-  const refresh = useCallback(() => readRef.current(), []);
-
-  useEffect(() => {
-    let cancelled = false;
-    const read = () => {
-      Promise.all([
-        client.pendingCommits(),
-        client.upgrading(),
-        client.leaseState(),
-        client.schemaFloor(),
-        client.syncNeeded(),
-      ])
-        .then(([pending, upgrading, leaseState, schemaFloor, syncNeeded]) => {
-          if (cancelled) return;
-          setState({
-            outbox: pending.length,
-            upgrading,
-            leaseState,
-            schemaFloor,
-            syncNeeded,
-            isLoading: false,
-          });
-        })
-        .catch(() => {
-          if (!cancelled) setState((s) => ({ ...s, isLoading: false }));
-        });
-    };
-    readRef.current = read;
-    read();
-    // Re-read on every apply batch — the "state changed" edge.
-    const unsubscribe = client.onInvalidate(read);
-    return () => {
-      cancelled = true;
-      unsubscribe();
-    };
-  }, [client]);
-
-  return { ...state, refresh };
+  const entry = useReactiveStore().status;
+  const snapshot = useSyncExternalStore(
+    entry.subscribe,
+    entry.getSnapshot,
+    entry.getSnapshot,
+  );
+  const refresh = useCallback(() => entry.refresh(), [entry]);
+  return {
+    outbox: snapshot.status?.outbox ?? 0,
+    upgrading: snapshot.status?.upgrading ?? false,
+    leaseState: snapshot.status?.leaseState,
+    schemaFloor: snapshot.status?.schemaFloor,
+    syncNeeded: snapshot.status?.syncNeeded ?? false,
+    isLoading: snapshot.isLoading,
+    error: snapshot.error,
+    refresh,
+  };
 }

package/src/use-window.ts

@@ -1,129 +1,116 @@
-/**
- * `useWindow(base)` — the windowed-sync surface for a component
- * (SPEC.md §4.8 / DESIGN-eviction.md W1, I3). It manages the live window
- * units for a base and exposes the **completeness oracle**: which scope
- * values are held locally in full, so a consumer can render "this data may
- * be partial" honestly instead of silently serving a partial replica as
- * complete.
- *
- * - `setWindow(units)` swaps the live set (added units bootstrap via the
- *   image lane; removed units are evicted, fused with unsubscription).
- * - `units` is the current windowed-in set, `pending` the subset whose
- *   bootstrap has not yet landed (re-read on mount and whenever the base's
- *   table is invalidated — a deferred eviction draining, a re-entry
- *   bootstrapping, or a bootstrap completing all update the verdict).
- * - `isComplete(unit)` is the per-value verdict: registered AND
- *   bootstrap-complete. A live query whose scope footprint includes a
- *   non-`isComplete` unit is a **window miss or still loading** — widen,
- *   wait, or show partial, never claim complete. Between `setWindow` and
- *   the unit's bootstrap landing the verdict is `false` (the local replica
- *   is empty or partial there — never a false "empty" render).
- */
 import {
+  canonicalValue,
   type WindowBase,
-  type WindowState,
   windowComplete,
 } from '@syncular/client';
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { FrameScheduler } from './query-churn';
-import { useSyncClient } from './use-client';
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+import { useReactiveStore } from './use-client';
 
 export interface UseWindowResult {
-  /** The scope values currently windowed-in for this base. */
   readonly units: readonly string[];
-  /** Registered units whose bootstrap has not yet completed (§4.8). */
   readonly pending: readonly string[];
-  /** Set the live units (widen/shrink diff, §4.8). */
+  /** Update this component's claim; the store applies the union of all claims. */
   readonly setWindow: (units: readonly string[]) => Promise<void>;
-  /** True iff `unit` is windowed-in AND bootstrapped (answerable, I3). */
   readonly isComplete: (unit: string) => boolean;
 }
 
-const EMPTY: WindowState = { units: [], pending: [] };
-
-export function useWindow(base: WindowBase): UseWindowResult {
-  const client = useSyncClient();
-  const [state, setState] = useState<WindowState>(EMPTY);
+export interface UseRetainedWindowResult {
+  /** True until the retained working set has reached the core window. */
+  readonly isPending: boolean;
+  /** Registration failure, if the host rejects the window change. */
+  readonly error: Error | undefined;
+}
 
-  // A stable key so the effects re-run only when the base identity changes,
-  // not on every render's fresh object. The latest `base` is read via a ref
-  // inside the closures (the useRawSql pattern), so the dep list stays on
-  // primitive keys.
-  const baseKey = `${base.table} ${base.variable} ${JSON.stringify(
-    base.fixedScopes ?? {},
-  )} ${base.params ?? ''}`;
-  const baseRef = useRef(base);
-  baseRef.current = base;
+/**
+ * Retain a known working set for the lifetime of this component. Retention
+ * composes with generated query coverage and other owners; cleanup releases
+ * only this hook's claim. Ordinary selected queries still claim themselves.
+ */
+export function useRetainedWindow(
+  base: WindowBase,
+  units: readonly string[],
+): UseRetainedWindowResult {
+  const store = useReactiveStore();
+  const baseIdentity = canonicalValue(base);
+  const unitsIdentity = canonicalValue([...new Set(units)].sort());
+  // biome-ignore lint/correctness/useExhaustiveDependencies: canonical identities represent the complete values
+  const stableBase = useMemo(() => base, [baseIdentity]);
+  // biome-ignore lint/correctness/useExhaustiveDependencies: unitsIdentity represents the normalized unit set
+  const stableUnits = useMemo(
+    () => [...new Set(units)].sort(),
+    [unitsIdentity],
+  );
+  const [state, setState] = useState<UseRetainedWindowResult>({
+    isPending: true,
+    error: undefined,
+  });
 
-  // `baseKey` re-keys the effect without being read in the body (biome cannot
-  // see the ref indirection) — the dep list is pinned deliberately.
-  // biome-ignore lint/correctness/useExhaustiveDependencies: baseKey re-keys the effect for a fresh base object
   useEffect(() => {
-    let cancelled = false;
-    const read = (): Promise<void> =>
-      Promise.resolve(client.windowState(baseRef.current))
-        .then((next) => {
-          if (!cancelled) setState(next);
-        })
-        .catch(() => {
-          /* transient — the next invalidation re-reads */
+    let active = true;
+    setState((current) =>
+      current.isPending && current.error === undefined
+        ? current
+        : { isPending: true, error: undefined },
+    );
+    const retention = store.retainWindow(stableBase, stableUnits);
+    void retention.ready.then(
+      () => {
+        if (active) setState({ isPending: false, error: undefined });
+      },
+      (caught: unknown) => {
+        if (!active) return;
+        setState({
+          isPending: false,
+          error: caught instanceof Error ? caught : new Error(String(caught)),
         });
-    void read();
-    // Re-read when the base's table changes locally: a deferred eviction
-    // (E1) completing, a re-entry bootstrapping, or a bootstrap completing
-    // all invalidate it. The re-read is frame-coalesced like the query
-    // hooks' re-runs, then deferred ONE MORE boundary before issuing: every
-    // query re-run for the same event has issued its read by then, so on
-    // the in-order client channel the pendency verdict resolves AFTER the
-    // rows it vouches for. Bootstrap-completion commit order is therefore
-    // rows first, pending→complete second — a consumer gating "empty" on
-    // `isComplete` never paints a false empty over a stale result (§4.8
-    // honesty at the render boundary, not just in the oracle). Both
-    // boundaries run INSIDE the scheduler (a two-phase callback re-arming
-    // itself once) so a fire parked in a suspended rAF stays covered by the
-    // hidden-document rescue — a bare second rAF would not be.
-    let armed = false;
-    const scheduler = new FrameScheduler(() => {
-      if (!armed) {
-        armed = true;
-        scheduler.schedule(); // boundary two via the dirty/re-run contract
-        return;
-      }
-      armed = false;
-      return read();
-    });
-    const unsubscribe = client.onInvalidate((event) => {
-      if (event.tables.has(baseRef.current.table)) scheduler.schedule();
-    });
+      },
+    );
     return () => {
-      cancelled = true;
-      scheduler.dispose();
-      unsubscribe();
+      active = false;
+      retention.release();
     };
-  }, [client, baseKey]);
+  }, [stableBase, stableUnits, store]);
 
-  const setWindow = useCallback(
-    (next: readonly string[]) => {
-      const result = Promise.resolve(client.setWindow(baseRef.current, next));
-      // Optimistically reflect the new set; the invalidation-driven re-read
-      // reconciles against the registry (e.g. a pinned unit lingering). The
-      // optimistic update MUST NOT claim completeness: a unit stays (or
-      // becomes) pending unless the previous snapshot already had it
-      // complete — entering units are mid-bootstrap until the re-read
-      // confirms otherwise (§4.8: registration ≠ completeness).
-      setState((prev) => ({
-        units: next,
-        pending: next.filter((unit) => !windowComplete(prev, unit)),
-      }));
-      return result;
-    },
-    [client],
+  return state;
+}
+
+export function useWindow(base: WindowBase): UseWindowResult {
+  const store = useReactiveStore();
+  const owner = useRef(Symbol('useWindow'));
+  const baseIdentity = canonicalValue(base);
+  // Window bases are value objects commonly recreated during render. Preserve
+  // the prior object while its canonical value is unchanged.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: baseIdentity represents the complete value
+  const stableBase = useMemo(() => base, [baseIdentity]);
+  const entry = useMemo(() => store.window(stableBase), [store, stableBase]);
+  const state = useSyncExternalStore(
+    entry.subscribe,
+    entry.getSnapshot,
+    entry.getSnapshot,
   );
 
+  useEffect(() => () => store.releaseWindowClaims(owner.current), [store]);
+
+  const setWindow = useCallback(
+    (units: readonly string[]) =>
+      store.setWindowClaim(owner.current, stableBase, units),
+    [stableBase, store],
+  );
   const isComplete = useCallback(
     (unit: string) => windowComplete(state, unit),
     [state],
   );
-
-  return { units: state.units, pending: state.pending, setWindow, isComplete };
+  return {
+    units: state.units,
+    pending: state.pending,
+    setWindow,
+    isComplete,
+  };
 }

package/dist/query-churn.d.ts

@@ -1,109 +0,0 @@
-/**
- * Live-query churn hardening — the three cheap levers the query hooks share
- * (block 4 "live-query churn" item). Under constant sync churn a naive live
- * query re-renders and re-queries once per invalidation event; these levers
- * cap both without reaching for IVM:
- *
- * 1. {@link reconcileRows} — result stability. After a re-run, compare the new
- *    result to the previous one. Whole-result equal → the caller skips
- *    `setRows` entirely (zero re-render). Otherwise build the new array but
- *    REUSE the previous row object for every row whose content is unchanged,
- *    so `React.memo`'d row components keyed by row identity skip re-render.
- * 2. {@link FrameScheduler} — frame-coalesced re-query scheduling. Many
- *    invalidation events between paints collapse to ONE re-run per query.
- * 3. scope-key filtering lives in {@link ../use-raw-sql} `eventMatches`
- *    (it needs the event + the hook's options), documented there.
- *
- * Row identity mechanism (the honest key): the hook knows no primary key —
- * rows are plain JSON-able objects out of SQLite — so per-row content equality
- * IS the identity. We hash each row once with a stable JSON serialization
- * (sorted keys, so column order can't spuriously differ) and match by index:
- * a live query's ORDER BY makes index the stable position, and an unchanged
- * row at position i keeps its object so memoized components skip. This is O(n)
- * in the row count with one string hash per row — bounded and measured (~0.2ms
- * for 1k narrow rows in bun; see query-churn.test.ts).
- */
-/**
- * A stable content hash for one row: JSON with keys sorted, so two rows with
- * the same columns in a different order hash equal (SQLite projection order is
- * stable per query, but sorting removes any dependence on it and is cheap for
- * the narrow rows a row-component renders). Uint8Array values (rare in a
- * projection) serialize by byte view so a fresh copy of equal bytes hashes
- * equal rather than to `{}`.
- */
-export declare function hashRow(row: unknown): string;
-/** The precomputed hash carrier for the previous result, so we hash once. */
-export interface HashedRows<Row> {
-    readonly rows: readonly Row[];
-    readonly hashes: readonly string[];
-}
-export declare function hashRows<Row>(rows: readonly Row[]): HashedRows<Row>;
-export interface ReconcileResult<Row> {
-    /**
-     * `undefined` → the whole result is unchanged; the caller MUST NOT call
-     * setRows (zero re-render, lever 1a). Otherwise the reconciled array to set,
-     * with previous row objects reused wherever a row's content was unchanged
-     * (lever 1b).
-     */
-    readonly next: HashedRows<Row> | undefined;
-}
-/**
- * Reconcile a freshly-queried result against the previous hashed result.
- * Returns `next: undefined` when nothing changed at all; otherwise a new
- * hashed result whose row objects are the PREVIOUS objects wherever content is
- * unchanged (matched by index), so identity-keyed memo components skip.
- */
-export declare function reconcileRows<Row>(prev: HashedRows<Row> | undefined, fresh: readonly Row[]): ReconcileResult<Row>;
-/**
- * A per-query re-run scheduler that coalesces bursts of invalidation events
- * into ONE run per paint. Multiple `schedule()` calls before the next flush
- * run the callback once. A `schedule()` that arrives WHILE the callback is
- * running (re-entrant, or an event during an async re-query) marks dirty and
- * runs the callback exactly once more after — never lost, never concurrent.
- *
- * Timing source: `requestAnimationFrame` when the host has it AND the document
- * is visible (a real browser paints one frame; the coalescing window is a
- * frame), else a microtask via a resolved promise (bun tests have no rAF —
- * this keeps them deterministic and timer-free, honoring the no-timers
- * doctrine: it's a readiness turn, not a wall-clock sleep). {@link flush} runs
- * any pending callback synchronously for tests, so no arbitrary sleeps are
- * needed to observe coalescing.
- *
- * Hidden documents: browsers SUSPEND rAF while a page is hidden (background
- * tab, occluded webview, headless embed), so a frame parked there fires only
- * when the page becomes visible again — and a page that is never visible would
- * freeze its live queries forever while invalidations keep arriving. Two
- * guards keep the schedule honest: a `schedule()` issued while hidden goes to
- * the microtask boundary (there is no paint to coalesce against anyway), and a
- * visible → hidden transition re-dispatches any frame already parked in rAF to
- * a microtask (the stale rAF callback later no-ops via the `#scheduled` guard
- * in {@link #fire}).
- */
-export declare class FrameScheduler {
-    #private;
-    constructor(callback: () => void | Promise<void>);
-    /** Request a run. Coalesces until the next frame/microtask boundary. */
-    schedule(): void;
-    /**
-     * @internal — the visible → hidden transition hands a frame parked in the
-     * (now suspended) rAF to the microtask boundary, so live queries keep
-     * converging off-screen. A no-op when nothing is pending.
-     */
-    redispatchPending(): void;
-    /**
-     * Synchronously run any pending scheduled callback NOW (test determinism).
-     * Returns whatever the callback returned (a Promise for the async host path)
-     * so a test can await the re-query settling without a sleep. A no-op when
-     * nothing is pending.
-     */
-    flush(): void | Promise<void>;
-    /** Drop the callback so a torn-down hook's pending frame is a no-op. */
-    dispose(): void;
-}
-/**
- * TEST-ONLY: synchronously flush every live scheduler's pending frame, so a
- * test can observe the coalesced re-query without a wall-clock sleep (the
- * no-timers doctrine — a readiness flush, injected, not a timer). Returns a
- * Promise that settles when every flushed async re-query has settled.
- */
-export declare function flushQuerySchedulers(): Promise<void>;