@syncular/client-react 0.0.6-135 → 0.0.6-138

package/src/createSyncularReact.tsx

@@ -15,6 +15,7 @@ import type {
   MutationsCommitFn,
   MutationsTx,
   OutboxCommitMeta,
+  PushResultInfo,
   SubscriptionState,
   SyncAwaitBootstrapOptions,
   SyncAwaitPhaseOptions,
@@ -54,6 +55,7 @@ import { type Kysely, sql } from 'kysely';
 import {
   createContext,
   type ReactNode,
+  startTransition,
   useCallback,
   useContext,
   useEffect,
@@ -151,7 +153,25 @@ export interface SyncProviderProps<
   realtimeFallbackPollMs?: number;
   onError?: (error: SyncError) => void;
   onConflict?: (conflict: ConflictInfo) => void;
+  onPushResult?: (result: PushResultInfo) => void;
   onDataChange?: (scopes: string[]) => void;
+  /**
+   * Debounce window (ms) for coalescing `data:change` events.
+   * - `0` (default): emit immediately
+   * - `>0`: merge scopes and emit once per window
+   */
+  dataChangeDebounceMs?: number;
+  /**
+   * Debounce override while sync is actively running.
+   * Falls back to `dataChangeDebounceMs` when omitted.
+   */
+  dataChangeDebounceMsWhenSyncing?: number;
+  /**
+   * Debounce override while connection is reconnecting.
+   * Falls back to `dataChangeDebounceMsWhenSyncing` (if syncing) and then
+   * `dataChangeDebounceMs` when omitted.
+   */
+  dataChangeDebounceMsWhenReconnecting?: number;
   plugins?: SyncClientPlugin[];
   /** Custom SHA-256 hash function (for platforms without crypto.subtle, e.g. React Native) */
   sha256?: (bytes: Uint8Array) => Promise<string>;
@@ -289,6 +309,22 @@ export interface UseConflictsResult {
   refresh: () => Promise<void>;
 }
 
+export interface UseNewConflictsOptions {
+  /**
+   * Max number of buffered conflict notifications kept in memory.
+   * Oldest notifications are dropped once the buffer reaches this size.
+   */
+  maxBuffered?: number;
+}
+
+export interface UseNewConflictsResult {
+  conflicts: ConflictInfo[];
+  latest: ConflictInfo | null;
+  count: number;
+  clear: () => void;
+  dismiss: (conflictId: string) => void;
+}
+
 export type ConflictResolution = 'accept' | 'reject' | 'merge';
 
 export interface UseResolveConflictResult {
@@ -317,6 +353,13 @@ export interface UseSyncQueryResult<T> {
   refetch: () => Promise<void>;
 }
 
+interface UseSyncQueryMetrics {
+  executions: number;
+  coalescedRefreshes: number;
+  skippedDataUpdates: number;
+  lastDurationMs: number | null;
+}
+
 export interface UseSyncQueryOptions {
   enabled?: boolean;
   deps?: unknown[];
@@ -324,6 +367,15 @@ export interface UseSyncQueryOptions {
   watchTables?: string[];
   pollIntervalMs?: number;
   staleAfterMs?: number;
+  /**
+   * If true (default), non-urgent hook state updates are scheduled in
+   * `startTransition` to keep UI interactions responsive under bursty sync.
+   */
+  transitionUpdates?: boolean;
+  /**
+   * Optional low-overhead instrumentation callback for query executions.
+   */
+  onMetrics?: (metrics: UseSyncQueryMetrics) => void;
 }
 
 export interface UseQueryResult<T> {
@@ -428,6 +480,24 @@ export interface UseOutboxResult {
   clearAll: () => Promise<number>;
 }
 
+interface UseOutboxMetrics {
+  refreshes: number;
+  coalescedRefreshes: number;
+  lastDurationMs: number | null;
+}
+
+interface UseOutboxOptions {
+  /**
+   * If true (default), non-urgent outbox state updates are scheduled in
+   * `startTransition` to reduce render contention during sync bursts.
+   */
+  transitionUpdates?: boolean;
+  /**
+   * Optional low-overhead instrumentation callback for outbox refreshes.
+   */
+  onMetrics?: (metrics: UseOutboxMetrics) => void;
+}
+
 export interface UsePresenceResult<TMetadata = Record<string, unknown>> {
   presence: PresenceEntry<TMetadata>[];
   isLoading: boolean;
@@ -472,7 +542,11 @@ export function createSyncularReact<
     realtimeFallbackPollMs,
     onError,
     onConflict,
+    onPushResult,
     onDataChange,
+    dataChangeDebounceMs,
+    dataChangeDebounceMsWhenSyncing,
+    dataChangeDebounceMsWhenReconnecting,
     plugins,
     sha256,
     autoStart = true,
@@ -504,7 +578,11 @@ export function createSyncularReact<
         realtimeFallbackPollMs,
         onError,
         onConflict,
+        onPushResult,
         onDataChange,
+        dataChangeDebounceMs,
+        dataChangeDebounceMsWhenSyncing,
+        dataChangeDebounceMsWhenReconnecting,
         plugins,
         sha256,
       }),
@@ -527,7 +605,11 @@ export function createSyncularReact<
         realtimeFallbackPollMs,
         onError,
         onConflict,
+        onPushResult,
         onDataChange,
+        dataChangeDebounceMs,
+        dataChangeDebounceMsWhenSyncing,
+        dataChangeDebounceMsWhenReconnecting,
         plugins,
         sha256,
       ]
@@ -793,23 +875,19 @@ export function createSyncularReact<
   function useTransportHealth(): UseTransportHealthResult {
     const engine = useEngine();
 
+    const getSnapshot = useCallback(
+      () => engine.getTransportHealth(),
+      [engine]
+    );
     const health = useSyncExternalStore(
       useCallback(
         (callback) => {
-          const unsubscribers = [
-            engine.subscribe(callback),
-            engine.on('connection:change', callback),
-            engine.on('sync:complete', callback),
-            engine.on('sync:error', callback),
-          ];
-          return () => {
-            for (const unsubscribe of unsubscribers) unsubscribe();
-          };
+          return engine.subscribeSelector(getSnapshot, callback);
         },
-        [engine]
+        [engine, getSnapshot]
       ),
-      useCallback(() => engine.getTransportHealth(), [engine]),
-      useCallback(() => engine.getTransportHealth(), [engine])
+      getSnapshot,
+      getSnapshot
     );
 
     return useMemo(() => ({ health }), [health]);
@@ -823,6 +901,7 @@ export function createSyncularReact<
     refreshOn: readonly SyncEngineEventName[];
     pollIntervalMs?: number;
     shouldPoll?: (value: T) => boolean;
+    transitionUpdates?: boolean;
   }): {
     value: T;
     isLoading: boolean;
@@ -830,8 +909,14 @@ export function createSyncularReact<
     refresh: () => Promise<void>;
   } {
     const engine = useEngine();
-    const { initialValue, load, refreshOn, pollIntervalMs, shouldPoll } =
-      options;
+    const {
+      initialValue,
+      load,
+      refreshOn,
+      pollIntervalMs,
+      shouldPoll,
+      transitionUpdates = true,
+    } = options;
 
     const loadRef = useRef(load);
     loadRef.current = load;
@@ -841,8 +926,20 @@ export function createSyncularReact<
     const [error, setError] = useState<Error | null>(null);
     const loadedRef = useRef(false);
     const versionRef = useRef(0);
+    const inFlightRefreshRef = useRef<Promise<void> | null>(null);
+    const refreshQueuedRef = useRef(false);
+    const applyUpdate = useCallback(
+      (update: () => void) => {
+        if (transitionUpdates) {
+          startTransition(update);
+          return;
+        }
+        update();
+      },
+      [transitionUpdates]
+    );
 
-    const refresh = useCallback(async () => {
+    const refreshOnce = useCallback(async () => {
       const version = ++versionRef.current;
       const isCurrent = () => version === versionRef.current;
 
@@ -853,18 +950,45 @@ export function createSyncularReact<
       try {
         const next = await loadRef.current();
         if (!isCurrent()) return;
-        setValue(next);
-        setError(null);
+        applyUpdate(() => {
+          setValue(next);
+          setError(null);
+        });
       } catch (err) {
         if (!isCurrent()) return;
-        setError(err instanceof Error ? err : new Error(String(err)));
+        applyUpdate(() => {
+          setError(err instanceof Error ? err : new Error(String(err)));
+        });
       } finally {
         if (isCurrent()) {
           loadedRef.current = true;
-          setIsLoading(false);
+          applyUpdate(() => {
+            setIsLoading(false);
+          });
         }
       }
-    }, []);
+    }, [applyUpdate]);
+
+    const refresh = useCallback(async () => {
+      refreshQueuedRef.current = true;
+      if (inFlightRefreshRef.current) {
+        await inFlightRefreshRef.current;
+        return;
+      }
+
+      const runLoop = async () => {
+        while (refreshQueuedRef.current) {
+          refreshQueuedRef.current = false;
+          await refreshOnce();
+        }
+      };
+
+      const inFlight = runLoop().finally(() => {
+        inFlightRefreshRef.current = null;
+      });
+      inFlightRefreshRef.current = inFlight;
+      await inFlight;
+    }, [refreshOnce]);
 
     useEffect(() => {
       void refresh();
@@ -1021,7 +1145,7 @@ export function createSyncularReact<
     } = useAsyncEngineResource<ConflictInfo[]>({
       initialValue: [],
       load: () => engine.getConflicts(),
-      refreshOn: ['sync:complete', 'sync:error'],
+      refreshOn: ['sync:complete', 'sync:error', 'conflict:new'],
     });
 
     return useMemo(
@@ -1036,6 +1160,50 @@ export function createSyncularReact<
     );
   }
 
+  function useNewConflicts(
+    options: UseNewConflictsOptions = {}
+  ): UseNewConflictsResult {
+    const engine = useEngine();
+    const maxBuffered = Math.max(1, Math.min(500, options.maxBuffered ?? 100));
+    const [conflicts, setConflicts] = useState<ConflictInfo[]>([]);
+
+    useEffect(() => {
+      setConflicts([]);
+      const unsubscribe = engine.on('conflict:new', (conflict) => {
+        setConflicts((previous) => {
+          if (previous.some((item) => item.id === conflict.id)) {
+            return previous;
+          }
+          const next = [...previous, conflict];
+          const overflow = next.length - maxBuffered;
+          return overflow > 0 ? next.slice(overflow) : next;
+        });
+      });
+      return unsubscribe;
+    }, [engine, maxBuffered]);
+
+    const clear = useCallback(() => {
+      setConflicts([]);
+    }, []);
+
+    const dismiss = useCallback((conflictId: string) => {
+      setConflicts((previous) =>
+        previous.filter((conflict) => conflict.id !== conflictId)
+      );
+    }, []);
+
+    return useMemo(
+      () => ({
+        conflicts,
+        latest: conflicts[conflicts.length - 1] ?? null,
+        count: conflicts.length,
+        clear,
+        dismiss,
+      }),
+      [conflicts, clear, dismiss]
+    );
+  }
+
   function useResolveConflict(
     options: UseResolveConflictOptions = {}
   ): UseResolveConflictResult {
@@ -1118,6 +1286,8 @@ export function createSyncularReact<
       watchTables = [],
       pollIntervalMs,
       staleAfterMs,
+      transitionUpdates = true,
+      onMetrics,
     } = options;
     const { db } = useSyncContext();
     const engine = useEngine();
@@ -1139,16 +1309,46 @@ export function createSyncularReact<
     const fingerprintCollectorRef = useRef(new FingerprintCollector());
     const previousFingerprintRef = useRef<string>('');
     const hasLoadedRef = useRef(false);
+    const inFlightQueryRef = useRef<Promise<void> | null>(null);
+    const queryQueuedRef = useRef(false);
+    const metricsRef = useRef<UseSyncQueryMetrics>({
+      executions: 0,
+      coalescedRefreshes: 0,
+      skippedDataUpdates: 0,
+      lastDurationMs: null,
+    });
+    const onMetricsRef = useRef(onMetrics);
+    onMetricsRef.current = onMetrics;
+    const emitMetrics = useCallback(() => {
+      onMetricsRef.current?.({ ...metricsRef.current });
+    }, []);
+    const applyUpdate = useCallback(
+      (update: () => void) => {
+        if (transitionUpdates) {
+          startTransition(update);
+          return;
+        }
+        update();
+      },
+      [transitionUpdates]
+    );
 
-    const executeQuery = useCallback(async () => {
+    const executeQueryOnce = useCallback(async () => {
+      const startedAt = Date.now();
+      metricsRef.current.executions += 1;
       if (!enabled) {
         if (previousFingerprintRef.current !== 'disabled') {
           previousFingerprintRef.current = 'disabled';
-          setData(undefined);
         }
-        setLastSyncAt(engine.getState().lastSyncAt);
-        setIsLoading(false);
+        const snapshotLastSyncAt = engine.getState().lastSyncAt;
+        applyUpdate(() => {
+          setData(undefined);
+          setLastSyncAt(snapshotLastSyncAt);
+          setIsLoading(false);
+        });
         hasLoadedRef.current = true;
+        metricsRef.current.lastDurationMs = Date.now() - startedAt;
+        emitMetrics();
         return;
       }
 
@@ -1176,52 +1376,88 @@ export function createSyncularReact<
 
         if (version === versionRef.current) {
           watchedScopesRef.current = scopeCollector;
-          setLastSyncAt(engine.getState().lastSyncAt);
+          const snapshotLastSyncAt = engine.getState().lastSyncAt;
 
           const fingerprint = fingerprintCollectorRef.current.getCombined();
-          if (
+          const didFingerprintChange =
             fingerprint !== previousFingerprintRef.current ||
-            fingerprint === ''
-          ) {
+            fingerprint === '';
+          if (didFingerprintChange) {
             previousFingerprintRef.current = fingerprint;
-            setData(result);
+          } else {
+            metricsRef.current.skippedDataUpdates += 1;
           }
-          setError(null);
+
+          applyUpdate(() => {
+            setLastSyncAt(snapshotLastSyncAt);
+            if (didFingerprintChange) {
+              setData(result);
+            }
+            setError(null);
+          });
         }
       } catch (err) {
         if (version === versionRef.current) {
-          setError(err instanceof Error ? err : new Error(String(err)));
+          applyUpdate(() => {
+            setError(err instanceof Error ? err : new Error(String(err)));
+          });
         }
       } finally {
         if (version === versionRef.current) {
-          setIsLoading(false);
+          applyUpdate(() => {
+            setIsLoading(false);
+          });
           hasLoadedRef.current = true;
+          metricsRef.current.lastDurationMs = Date.now() - startedAt;
+          emitMetrics();
         }
       }
-    }, [db, enabled, engine, keyField]);
+    }, [db, enabled, engine, keyField, applyUpdate, emitMetrics]);
+
+    const executeQuery = useCallback(async () => {
+      queryQueuedRef.current = true;
+      if (inFlightQueryRef.current) {
+        metricsRef.current.coalescedRefreshes += 1;
+        emitMetrics();
+        await inFlightQueryRef.current;
+        return;
+      }
+
+      const runLoop = async () => {
+        while (queryQueuedRef.current) {
+          queryQueuedRef.current = false;
+          await executeQueryOnce();
+        }
+      };
+
+      const inFlight = runLoop().finally(() => {
+        inFlightQueryRef.current = null;
+      });
+      inFlightQueryRef.current = inFlight;
+      await inFlight;
+    }, [executeQueryOnce, emitMetrics]);
 
     useEffect(() => {
       executeQuery();
       // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [executeQuery, ...deps]);
 
+    const getLastSyncAtSnapshot = useCallback(
+      () => engine.getState().lastSyncAt,
+      [engine]
+    );
     useEffect(() => {
-      const unsubscribe = engine.subscribe(() => {
-        const nextLastSyncAt = engine.getState().lastSyncAt;
-        setLastSyncAt((previous) =>
-          previous === nextLastSyncAt ? previous : nextLastSyncAt
-        );
-      });
-      return unsubscribe;
-    }, [engine]);
-
-    useEffect(() => {
-      if (!enabled) return;
-      const unsubscribe = engine.on('sync:complete', () => {
-        void executeQuery();
-      });
+      const unsubscribe = engine.subscribeSelector(
+        getLastSyncAtSnapshot,
+        () => {
+          const snapshotLastSyncAt = getLastSyncAtSnapshot();
+          applyUpdate(() => {
+            setLastSyncAt(snapshotLastSyncAt);
+          });
+        }
+      );
       return unsubscribe;
-    }, [engine, enabled, executeQuery]);
+    }, [engine, getLastSyncAtSnapshot, applyUpdate]);
 
     useEffect(() => {
       if (!enabled) return;
@@ -1609,9 +1845,10 @@ export function createSyncularReact<
     );
   }
 
-  function useOutbox(): UseOutboxResult {
+  function useOutbox(options: UseOutboxOptions = {}): UseOutboxResult {
     const { db } = useSyncContext();
     const engine = useEngine();
+    const { transitionUpdates = true, onMetrics } = options;
 
     const [stats, setStats] = useState<OutboxStats>({
       pending: 0,
@@ -1623,13 +1860,36 @@ export function createSyncularReact<
     const [pending, setPending] = useState<OutboxCommit[]>([]);
     const [failed, setFailed] = useState<OutboxCommit[]>([]);
     const [isLoading, setIsLoading] = useState(true);
+    const inFlightRefreshRef = useRef<Promise<void> | null>(null);
+    const refreshQueuedRef = useRef(false);
+    const metricsRef = useRef<UseOutboxMetrics>({
+      refreshes: 0,
+      coalescedRefreshes: 0,
+      lastDurationMs: null,
+    });
+    const onMetricsRef = useRef(onMetrics);
+    onMetricsRef.current = onMetrics;
+    const emitMetrics = useCallback(() => {
+      onMetricsRef.current?.({ ...metricsRef.current });
+    }, []);
+    const applyUpdate = useCallback(
+      (update: () => void) => {
+        if (transitionUpdates) {
+          startTransition(update);
+          return;
+        }
+        update();
+      },
+      [transitionUpdates]
+    );
 
-    const refresh = useCallback(async () => {
+    const refreshOnce = useCallback(async () => {
+      const startedAt = Date.now();
+      metricsRef.current.refreshes += 1;
       try {
         setIsLoading(true);
 
         const newStats = await engine.refreshOutboxStats({ emit: false });
-        setStats(newStats);
 
         const rowsResult = await sql<{
           id: string;
@@ -1683,14 +1943,46 @@ export function createSyncularReact<
           };
         });
 
-        setPending(commits.filter((c) => c.status === 'pending'));
-        setFailed(commits.filter((c) => c.status === 'failed'));
+        const nextPending = commits.filter((c) => c.status === 'pending');
+        const nextFailed = commits.filter((c) => c.status === 'failed');
+        applyUpdate(() => {
+          setStats(newStats);
+          setPending(nextPending);
+          setFailed(nextFailed);
+        });
       } catch (err) {
         console.error('[useOutbox] Failed to refresh:', err);
       } finally {
-        setIsLoading(false);
+        applyUpdate(() => {
+          setIsLoading(false);
+        });
+        metricsRef.current.lastDurationMs = Date.now() - startedAt;
+        emitMetrics();
       }
-    }, [db, engine]);
+    }, [db, engine, applyUpdate, emitMetrics]);
+
+    const refresh = useCallback(async () => {
+      refreshQueuedRef.current = true;
+      if (inFlightRefreshRef.current) {
+        metricsRef.current.coalescedRefreshes += 1;
+        emitMetrics();
+        await inFlightRefreshRef.current;
+        return;
+      }
+
+      const runLoop = async () => {
+        while (refreshQueuedRef.current) {
+          refreshQueuedRef.current = false;
+          await refreshOnce();
+        }
+      };
+
+      const inFlight = runLoop().finally(() => {
+        inFlightRefreshRef.current = null;
+      });
+      inFlightRefreshRef.current = inFlight;
+      await inFlight;
+    }, [refreshOnce, emitMetrics]);
 
     useEffect(() => {
       refresh();
@@ -1703,13 +1995,6 @@ export function createSyncularReact<
       return unsubscribe;
     }, [engine, refresh]);
 
-    useEffect(() => {
-      const unsubscribe = engine.on('sync:complete', () => {
-        refresh();
-      });
-      return unsubscribe;
-    }, [engine, refresh]);
-
     const hasUnsent = stats.pending > 0 || stats.failed > 0;
 
     const clearFailed = useCallback(async () => {
@@ -1874,6 +2159,7 @@ export function createSyncularReact<
     useMutations,
     useOutbox,
     useConflicts,
+    useNewConflicts,
     useResolveConflict,
     usePresence,
     usePresenceWithJoin,

package/src/index.ts

@@ -21,6 +21,8 @@ export type {
   UseMutationOptions,
   UseMutationResult,
   UseMutationsOptions,
+  UseNewConflictsOptions,
+  UseNewConflictsResult,
   UseOutboxResult,
   UsePresenceResult,
   UsePresenceWithJoinOptions,

package/src/useSyncGroup.ts

@@ -53,13 +53,9 @@ export function useSyncGroup<DB extends SyncClientDb = SyncClientDb>(args: {
 
   const subscribe = useCallback(
     (callback: () => void) => {
-      const unsubs = channels.flatMap((channel) => [
-        channel.engine.subscribe(callback),
-        channel.engine.on('connection:change', callback),
-        channel.engine.on('sync:complete', callback),
-        channel.engine.on('sync:error', callback),
-        channel.engine.on('outbox:change', callback),
-      ]);
+      const unsubs = channels.map((channel) =>
+        channel.engine.subscribe(callback)
+      );
 
       return () => {
         for (const unsubscribe of unsubs) unsubscribe();