@syncular/react 0.4.0 → 0.5.0

package/dist/use-window.d.ts

@@ -1,33 +1,21 @@
-/**
- * `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 { type WindowBase } from '@syncular/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;
 }
+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;
+}
+/**
+ * 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 declare function useRetainedWindow(base: WindowBase, units: readonly string[]): UseRetainedWindowResult;
 export declare function useWindow(base: WindowBase): UseWindowResult;

package/dist/use-window.js

@@ -1,79 +1,64 @@
+import { canonicalValue, windowComplete, } from '@syncular/client';
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
+import { useReactiveStore } from './use-client.js';
 /**
- * `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).
+ * 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.
  */
-import { windowComplete, } from '@syncular/client';
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { useSyncClient } from './use-client.js';
-const EMPTY = { units: [], pending: [] };
-export function useWindow(base) {
-    const client = useSyncClient();
-    const [state, setState] = useState(EMPTY);
-    // 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;
-    // `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
+export function useRetainedWindow(base, units) {
+    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({
+        isPending: true,
+        error: undefined,
+    });
     useEffect(() => {
-        let cancelled = false;
-        const read = () => {
-            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) => {
+            if (!active)
+                return;
+            setState({
+                isPending: false,
+                error: caught instanceof Error ? caught : new Error(String(caught)),
             });
-        };
-        read();
-        // Re-read when the base's table changes locally: a deferred eviction
-        // (E1) completing or a re-entry bootstrapping both invalidate it.
-        const unsubscribe = client.onInvalidate((event) => {
-            if (event.tables.has(baseRef.current.table))
-                read();
         });
         return () => {
-            cancelled = true;
-            unsubscribe();
+            active = false;
+            retention.release();
         };
-    }, [client, baseKey]);
-    const setWindow = useCallback((next) => {
-        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]);
+    }, [stableBase, stableUnits, store]);
+    return state;
+}
+export function useWindow(base) {
+    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) => store.setWindowClaim(owner.current, stableBase, units), [stableBase, store]);
     const isComplete = useCallback((unit) => windowComplete(state, unit), [state]);
-    return { units: state.units, pending: state.pending, setWindow, isComplete };
+    return {
+        units: state.units,
+        pending: state.pending,
+        setWindow,
+        isComplete,
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/react",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "React hooks for Syncular offline-first sync",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -48,15 +48,15 @@
     "test": "bun test --preload ./test/setup.ts"
   },
   "dependencies": {
-    "@syncular/client": "0.3.1"
+    "@syncular/client": "0.5.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^15.11.0",
-    "@syncular/core": "0.3.1",
-    "@syncular/server": "0.3.1",
+    "@syncular/core": "0.5.0",
+    "@syncular/server": "0.5.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.0",
     "react": "^18.3.1",

package/src/client.ts

@@ -12,15 +12,19 @@
  * never has to care which core it holds.
  */
 import type {
+  ClientChangeListener,
   ConflictRecord,
   InvalidationListener,
   LeaseState,
   MutationInput,
   PresencePeer,
+  QueryReadSpec,
+  QuerySnapshot,
   RejectionRecord,
   SchemaFloor,
   SqlRow,
   SqlValue,
+  SyncStatusSnapshot,
   WindowBase,
   WindowState,
 } from '@syncular/client';
@@ -32,6 +36,7 @@ import type {
  * never reach past this surface.
  */
 export interface SyncClientLike {
+  onChange(listener: ClientChangeListener): () => void;
   onInvalidate(listener: InvalidationListener): () => void;
   onPresence(listener: (scopeKey: string) => void): () => void;
   query(
@@ -39,6 +44,16 @@ export interface SyncClientLike {
     params?: readonly SqlValue[],
   ): SqlRow[] | Promise<SqlRow[]>;
   mutate(mutations: readonly MutationInput[]): string | Promise<string>;
+  patch(
+    table: string,
+    rowId: string,
+    partial: Readonly<Record<string, unknown>>,
+    options?: { readonly baseVersion?: number },
+  ): string | Promise<string>;
+  querySnapshot<Row = SqlRow>(
+    spec: QueryReadSpec,
+  ): QuerySnapshot<Row> | Promise<QuerySnapshot<Row>>;
+  statusSnapshot(): SyncStatusSnapshot | Promise<SyncStatusSnapshot>;
   conflicts:
     | readonly ConflictRecord[]
     | (() => readonly ConflictRecord[] | Promise<readonly ConflictRecord[]>);
@@ -88,10 +103,19 @@ function resolveMember<T>(
 
 /** The uniform async facade the hooks actually call. */
 export interface NormalizedClient {
+  onChange(listener: ClientChangeListener): () => void;
   onInvalidate(listener: InvalidationListener): () => void;
   onPresence(listener: (scopeKey: string) => void): () => void;
   query(sql: string, params?: readonly SqlValue[]): Promise<SqlRow[]>;
   mutate(mutations: readonly MutationInput[]): Promise<string>;
+  patch(
+    table: string,
+    rowId: string,
+    partial: Readonly<Record<string, unknown>>,
+    options?: { readonly baseVersion?: number },
+  ): Promise<string>;
+  querySnapshot<Row = SqlRow>(spec: QueryReadSpec): Promise<QuerySnapshot<Row>>;
+  statusSnapshot(): Promise<SyncStatusSnapshot>;
   conflicts(): Promise<readonly ConflictRecord[]>;
   rejections(): Promise<readonly RejectionRecord[]>;
   schemaFloor(): Promise<SchemaFloor | undefined>;
@@ -110,10 +134,15 @@ export interface NormalizedClient {
 
 export function normalizeClient(client: SyncClientLike): NormalizedClient {
   return {
+    onChange: (listener) => client.onChange(listener),
     onInvalidate: (listener) => client.onInvalidate(listener),
     onPresence: (listener) => client.onPresence(listener),
     query: (sql, params) => Promise.resolve(client.query(sql, params)),
     mutate: (mutations) => Promise.resolve(client.mutate(mutations)),
+    patch: (table, rowId, partial, options) =>
+      Promise.resolve(client.patch(table, rowId, partial, options)),
+    querySnapshot: (spec) => Promise.resolve(client.querySnapshot(spec)),
+    statusSnapshot: () => Promise.resolve(client.statusSnapshot()),
     conflicts: () => resolveMember(client, 'conflicts'),
     rejections: () => resolveMember(client, 'rejections'),
     schemaFloor: () => resolveMember(client, 'schemaFloor'),

package/src/index.ts

@@ -16,10 +16,27 @@ export type {
 // the exact normalizer the bindings use.
 export { normalizeClient } from './client';
 export { inferTables } from './infer-tables';
-export { SyncContext, SyncProvider, type SyncProviderProps } from './provider';
-export { useSyncClient } from './use-client';
+export {
+  SyncContext,
+  SyncProvider,
+  type SyncProviderProps,
+  SyncStoreContext,
+} from './provider';
+export {
+  createSyncClientResource,
+  isSyncClientResource,
+  type SyncClientResource,
+  type SyncClientResourceSnapshot,
+} from './resource';
+export { useReactiveStore, useSyncClient } from './use-client';
 export { type UseConflictsResult, useConflicts } from './use-conflicts';
-export { type UseMutationResult, useMutation } from './use-mutation';
+export {
+  type SyncTableDescriptor,
+  type UseMutationOptions,
+  type UseMutationResult,
+  type UseTableMutationResult,
+  useMutation,
+} from './use-mutation';
 export { usePresence } from './use-presence';
 export {
   type NamedQueryDescriptor,
@@ -31,4 +48,9 @@ export {
   useRawSql,
 } from './use-raw-sql';
 export { type SyncStatus, useSyncStatus } from './use-sync-status';
-export { type UseWindowResult, useWindow } from './use-window';
+export {
+  type UseRetainedWindowResult,
+  type UseWindowResult,
+  useRetainedWindow,
+  useWindow,
+} from './use-window';

package/src/provider.ts

@@ -5,32 +5,114 @@
  * package typechecks under the repo's `.ts`-only root tsconfig with no jsx
  * setting — the bindings are plain function components either way.
  */
-import { createContext, createElement, type ReactNode, useMemo } from 'react';
+import { ReactiveClientStore } from '@syncular/client';
+import {
+  createContext,
+  createElement,
+  type ReactNode,
+  useEffect,
+  useMemo,
+  useSyncExternalStore,
+} from 'react';
 import {
   type NormalizedClient,
   normalizeClient,
   type SyncClientLike,
 } from './client';
+import { isSyncClientResource, type SyncClientResource } from './resource';
 
 export const SyncContext = createContext<NormalizedClient | undefined>(
   undefined,
 );
+export const SyncStoreContext = createContext<ReactiveClientStore | undefined>(
+  undefined,
+);
 
 export interface SyncProviderProps {
   /** A `SyncClient` (direct) or `SyncClientHandle` (worker) — both satisfy it. */
+  readonly client: SyncClientLike | SyncClientResource;
+  readonly children?: ReactNode;
+  readonly fallback?: ReactNode;
+  readonly renderError?: (error: Error) => ReactNode;
+}
+
+interface ClientRecord {
+  readonly normalized: NormalizedClient;
+  readonly store: ReactiveClientStore;
+  refs: number;
+}
+
+const stores = new WeakMap<object, ClientRecord>();
+
+function recordFor(client: SyncClientLike): ClientRecord {
+  const key = client as object;
+  let record = stores.get(key);
+  if (record === undefined) {
+    const normalized = normalizeClient(client);
+    record = {
+      normalized,
+      store: new ReactiveClientStore(normalized),
+      refs: 0,
+    };
+    stores.set(key, record);
+  }
+  return record;
+}
+
+interface ReadySyncProviderProps {
   readonly client: SyncClientLike;
   readonly children?: ReactNode;
 }
 
-export function SyncProvider(props: SyncProviderProps): ReactNode {
-  // Re-normalize only when the client identity changes.
-  const normalized = useMemo(
-    () => normalizeClient(props.client),
-    [props.client],
-  );
+function ReadySyncProvider(props: ReadySyncProviderProps): ReactNode {
+  const record = useMemo(() => recordFor(props.client), [props.client]);
+  const { normalized, store } = record;
+  useEffect(() => {
+    record.refs += 1;
+    store.start();
+    return () => {
+      record.refs -= 1;
+      queueMicrotask(() => {
+        if (record.refs === 0) store.dispose();
+      });
+    };
+  }, [record, store]);
   return createElement(
     SyncContext.Provider,
     { value: normalized },
+    createElement(SyncStoreContext.Provider, { value: store }, props.children),
+  );
+}
+
+const noSubscribe = (): (() => void) => () => {};
+
+export function SyncProvider(props: SyncProviderProps): ReactNode {
+  const resource = isSyncClientResource(props.client)
+    ? props.client
+    : undefined;
+  const readySnapshot = useMemo(
+    () =>
+      resource === undefined
+        ? ({ phase: 'ready', client: props.client as SyncClientLike } as const)
+        : undefined,
+    [props.client, resource],
+  );
+  const snapshot = useSyncExternalStore(
+    resource?.subscribe ?? noSubscribe,
+    resource?.getSnapshot ??
+      (() => readySnapshot as NonNullable<typeof readySnapshot>),
+    resource?.getSnapshot ??
+      (() => readySnapshot as NonNullable<typeof readySnapshot>),
+  );
+  if (snapshot.phase === 'pending') return props.fallback ?? null;
+  if (snapshot.phase === 'error') {
+    if (props.renderError !== undefined)
+      return props.renderError(snapshot.error);
+    throw snapshot.error;
+  }
+  return createElement(
+    ReadySyncProvider,
+    { client: snapshot.client },
     props.children,
   );
 }

package/src/resource.ts

@@ -0,0 +1,77 @@
+import type { SyncClientLike } from './client';
+
+export type SyncClientResourceSnapshot =
+  | { readonly phase: 'pending' }
+  | { readonly phase: 'ready'; readonly client: SyncClientLike }
+  | { readonly phase: 'error'; readonly error: Error };
+
+export interface SyncClientResource {
+  readonly kind: 'syncular-client-resource';
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): SyncClientResourceSnapshot;
+  dispose(): Promise<void>;
+}
+
+export function createSyncClientResource(
+  factory: () => SyncClientLike | Promise<SyncClientLike>,
+): SyncClientResource {
+  const listeners = new Set<() => void>();
+  let snapshot: SyncClientResourceSnapshot = { phase: 'pending' };
+  let disposed = false;
+  let closed = false;
+  const initialized = Promise.resolve()
+    .then(factory)
+    .then(
+      async (client) => {
+        if (disposed) {
+          const close = (client as { close?: () => void | Promise<void> })
+            .close;
+          if (close !== undefined && !closed) {
+            closed = true;
+            await close.call(client);
+          }
+          return;
+        }
+        snapshot = { phase: 'ready', client };
+        for (const listener of listeners) listener();
+      },
+      (error: unknown) => {
+        if (disposed) return;
+        snapshot = {
+          phase: 'error',
+          error: error instanceof Error ? error : new Error(String(error)),
+        };
+        for (const listener of listeners) listener();
+      },
+    );
+
+  return {
+    kind: 'syncular-client-resource',
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    getSnapshot: () => snapshot,
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      await initialized;
+      if (snapshot.phase === 'ready' && !closed) {
+        const close = (
+          snapshot.client as { close?: () => void | Promise<void> }
+        ).close;
+        if (close !== undefined) {
+          closed = true;
+          await close.call(snapshot.client);
+        }
+      }
+      listeners.clear();
+    },
+  };
+}
+
+export function isSyncClientResource(
+  value: SyncClientLike | SyncClientResource,
+): value is SyncClientResource {
+  return (value as { kind?: unknown }).kind === 'syncular-client-resource';
+}

package/src/use-client.ts

@@ -1,6 +1,7 @@
+import type { ReactiveClientStore } from '@syncular/client';
 import { useContext } from 'react';
 import type { NormalizedClient } from './client';
-import { SyncContext } from './provider';
+import { SyncContext, SyncStoreContext } from './provider';
 
 /** Read the normalized client from context; throws outside a `SyncProvider`. */
 export function useSyncClient(): NormalizedClient {
@@ -12,3 +13,13 @@ export function useSyncClient(): NormalizedClient {
   }
   return client;
 }
+
+export function useReactiveStore(): ReactiveClientStore {
+  const store = useContext(SyncStoreContext);
+  if (store === undefined) {
+    throw new Error(
+      '@syncular/react: no client in context (reactive store unavailable) — wrap your tree in <SyncProvider client={…}>',
+    );
+  }
+  return store;
+}

package/src/use-conflicts.ts

@@ -1,47 +1,28 @@
-/**
- * `useConflicts` — the accumulated conflict records (§6.2/§6.5) and
- * rejections (§6.3) the client has surfaced. Re-read after every apply
- * batch (a push result lands through the same choke point) plus on mount.
- */
-
 import type { ConflictRecord, RejectionRecord } 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 UseConflictsResult {
   readonly conflicts: readonly ConflictRecord[];
   readonly rejections: readonly RejectionRecord[];
+  readonly isLoading: boolean;
+  readonly error: Error | undefined;
   readonly refresh: () => void;
 }
 
 export function useConflicts(): UseConflictsResult {
-  const client = useSyncClient();
-  const [conflicts, setConflicts] = useState<readonly ConflictRecord[]>([]);
-  const [rejections, setRejections] = useState<readonly RejectionRecord[]>([]);
-  const readRef = useRef<() => void>(() => {});
-  const refresh = useCallback(() => readRef.current(), []);
-
-  useEffect(() => {
-    let cancelled = false;
-    const read = () => {
-      Promise.all([client.conflicts(), client.rejections()])
-        .then(([c, r]) => {
-          if (cancelled) return;
-          setConflicts(c);
-          setRejections(r);
-        })
-        .catch(() => {
-          /* transient read failure — the next batch re-reads */
-        });
-    };
-    readRef.current = read;
-    read();
-    const unsubscribe = client.onInvalidate(read);
-    return () => {
-      cancelled = true;
-      unsubscribe();
-    };
-  }, [client]);
-
-  return { conflicts, rejections, refresh };
+  const entry = useReactiveStore().conflicts;
+  const snapshot = useSyncExternalStore(
+    entry.subscribe,
+    entry.getSnapshot,
+    entry.getSnapshot,
+  );
+  const refresh = useCallback(() => entry.refresh(), [entry]);
+  return {
+    conflicts: snapshot.conflicts as readonly ConflictRecord[],
+    rejections: snapshot.rejections as readonly RejectionRecord[],
+    isLoading: snapshot.isLoading,
+    error: snapshot.error,
+    refresh,
+  };
 }