@syncular/react 0.4.0 → 0.4.1

package/dist/use-window.js

@@ -21,6 +21,7 @@
  */
 import { windowComplete, } from '@syncular/client';
 import { useCallback, useEffect, useRef, useState } from 'react';
+import { FrameScheduler } from './query-churn.js';
 import { useSyncClient } from './use-client.js';
 const EMPTY = { units: [], pending: [] };
 export function useWindow(base) {
@@ -38,25 +39,45 @@ export function useWindow(base) {
     // biome-ignore lint/correctness/useExhaustiveDependencies: baseKey re-keys the effect for a fresh base object
     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 */
-            });
-        };
-        read();
+        const read = () => Promise.resolve(client.windowState(baseRef.current))
+            .then((next) => {
+            if (!cancelled)
+                setState(next);
+        })
+            .catch(() => {
+            /* transient — the next invalidation re-reads */
+        });
+        void read();
         // Re-read when the base's table changes locally: a deferred eviction
-        // (E1) completing or a re-entry bootstrapping both invalidate it.
+        // (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))
-                read();
+                scheduler.schedule();
         });
         return () => {
             cancelled = true;
+            scheduler.dispose();
             unsubscribe();
         };
     }, [client, baseKey]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/react",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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.4.1"
   },
   "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.4.1",
+    "@syncular/server": "0.4.1",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^18.3.0",
     "react": "^18.3.1",

package/src/use-window.ts

@@ -25,6 +25,7 @@ import {
   windowComplete,
 } from '@syncular/client';
 import { useCallback, useEffect, useRef, useState } from 'react';
+import { FrameScheduler } from './query-churn';
 import { useSyncClient } from './use-client';
 
 export interface UseWindowResult {
@@ -59,7 +60,7 @@ export function useWindow(base: WindowBase): UseWindowResult {
   // biome-ignore lint/correctness/useExhaustiveDependencies: baseKey re-keys the effect for a fresh base object
   useEffect(() => {
     let cancelled = false;
-    const read = () => {
+    const read = (): Promise<void> =>
       Promise.resolve(client.windowState(baseRef.current))
         .then((next) => {
           if (!cancelled) setState(next);
@@ -67,15 +68,36 @@ export function useWindow(base: WindowBase): UseWindowResult {
         .catch(() => {
           /* transient — the next invalidation re-reads */
         });
-    };
-    read();
+    void read();
     // Re-read when the base's table changes locally: a deferred eviction
-    // (E1) completing or a re-entry bootstrapping both invalidate it.
+    // (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)) read();
+      if (event.tables.has(baseRef.current.table)) scheduler.schedule();
     });
     return () => {
       cancelled = true;
+      scheduler.dispose();
       unsubscribe();
     };
   }, [client, baseKey]);