@pylonsync/react 0.3.359 → 0.3.360

package/package.json

@@ -3,24 +3,29 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.359",
+  "version": "0.3.360",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "check": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.3.359",
-    "@pylonsync/sync": "0.3.359"
+    "@pylonsync/sdk": "0.3.360",
+    "@pylonsync/sync": "0.3.360"
   },
   "peerDependencies": {
     "react": ">=19.0.0"
   },
   "devDependencies": {
-    "@types/react": "^19.0.0"
+    "@happy-dom/global-registrator": "^20.10.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
   },
   "files": [
     "src",

package/src/hooks.ts

@@ -50,6 +50,13 @@ export interface UseQueryOneReturn<T> {
 // stable reference.
 const EMPTY_SNAPSHOT: readonly unknown[] = [];
 
+// Server snapshot for the settled signal. On the server there is no engine to
+// have settled, and rendering "not settled" is what makes SSR emit the skeleton
+// the client then replaces — matching what a cold client sees, so hydration
+// doesn't swap the tree. Hoisted for the same reason as EMPTY_SNAPSHOT: a
+// stable identity, though a bare boolean would compare fine.
+const FALSE_SNAPSHOT = (): boolean => false;
+
 // useQuery — high-level hook returning {data, loading, error}
 // ---------------------------------------------------------------------------
 
@@ -80,19 +87,12 @@ export function useQuery<T = Row>(
   entity: string,
   options?: QueryOptions
 ): UseQueryReturn<T> {
-  // `loading` is true only while we genuinely don't know yet — i.e., the
-  // engine doesn't yet have a SERVER-confirmed view. It gates on
-  // `isInitialSyncSettled()`, NOT `isHydrated()`: the latter flips true the
-  // instant IndexedDB loads, which on a cold/empty cache (first visit, or
-  // right after an org switch wipes the replica) is immediate and EMPTY — so
-  // gating on it drops `loading` while the rows are still en route from the
-  // server, flashing the empty state for the seconds until the snapshot lands.
-  // `isInitialSyncSettled()` stays pending until the first pull settles (or
-  // the cache already had rows), so callers render a skeleton instead.
-  const loading = useRef<boolean>(
-    !sync.isInitialSyncSettled() && sync.store.list(entity).length === 0,
-  );
-  const error = useRef<Error | null>(null);
+  // Both are state, not refs. A ref mutated inside an async callback changes
+  // nothing React can see: the old `error` ref was assigned in `pull()`'s catch
+  // and never re-rendered, so a failed refetch surfaced no error until some
+  // unrelated update happened to re-render the component.
+  const [error, setError] = useState<Error | null>(null);
+  const [refetching, setRefetching] = useState(false);
   const optionsKey = JSON.stringify(options || {});
 
   // Subscribe function stable across the lifetime of this entity/options combo.
@@ -121,15 +121,6 @@ export function useQuery<T = Row>(
     if (sig !== snapshotCache.current.sig) {
       snapshotCache.current = { rows: filtered as T[], sig };
     }
-    // Drop loading when rows arrive OR the initial sync settles (first server
-    // pull done / cache had rows / fallback deadline). Gating on the settled
-    // signal — not bare hydration — is what stops the empty-state flash: a
-    // cold cache keeps loading=true until the pull confirms, then an empty
-    // result is a real "no rows" and the empty state renders. No flash, and
-    // (thanks to the fallback) no infinite spinner either.
-    if (loading.current && (rows.length > 0 || sync.isInitialSyncSettled())) {
-      loading.current = false;
-    }
     return snapshotCache.current.rows;
   }, [sync, entity, optionsKey, options]);
 
@@ -137,6 +128,37 @@ export function useQuery<T = Row>(
 
   const data = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 
+  // The settled signal gets its OWN subscription, with a boolean snapshot.
+  //
+  // It used to be a `useRef` flipped inside getSnapshot above, which never
+  // reached the render for an entity with no rows. useSyncExternalStore
+  // re-renders only when getSnapshot returns a value that isn't Object.is-equal
+  // to the last one — and the row snapshot for an empty entity is the same
+  // cached array before and after the pull settles. So markInitialSyncSettled()
+  // notified, getSnapshot ran, the ref flipped to false, React compared the
+  // identical array and bailed out, and the component kept rendering the stale
+  // `loading: true` forever. Every empty list — a new account's first dashboard,
+  // a fresh entity, an org whose rows all soft-deleted — sat on its skeleton
+  // and never reached its empty state.
+  //
+  // Booleans compare by value, so this snapshot genuinely changes when the
+  // engine settles and React re-renders.
+  const settled = useSyncExternalStore(
+    subscribe,
+    useCallback(() => sync.isInitialSyncSettled(), [sync]),
+    FALSE_SNAPSHOT,
+  );
+
+  // Derived, not latched. Loading means "we don't know yet": no server-confirmed
+  // view AND nothing local to show. Gating on the settled signal rather than
+  // bare hydration is what stops the empty-state flash — a cold cache keeps
+  // this true until the pull confirms, and only then is an empty result a real
+  // "no rows". The engine's fallback deadline settles it even offline, so this
+  // can't pin. Deriving it also means a replica wipe (org switch, token flip)
+  // resets the engine's signal and correctly returns callers to a skeleton
+  // instead of flashing "nothing here" over data that is on its way back.
+  const loading = refetching || (!settled && data.length === 0);
+
   // Register interest so the reconcile safety net sweeps this entity
   // even when the local replica has zero rows for it. Without this, a
   // server row in a never-cached entity (created on another surface, a
@@ -148,19 +170,21 @@ export function useQuery<T = Row>(
   }, [sync, entity]);
 
   const refetch = useCallback(() => {
-    loading.current = true;
-    error.current = null;
-    sync.pull().catch((e: unknown) => {
-      error.current = e instanceof Error ? e : new Error(String(e));
-    });
+    setRefetching(true);
+    setError(null);
+    sync
+      .pull()
+      .catch((e: unknown) => {
+        setError(e instanceof Error ? e : new Error(String(e)));
+      })
+      // Clear on settle, success or failure. The old ref-based version set
+      // loading true and left it to getSnapshot to clear, which never ran on a
+      // pull that returned no new rows — a refetch over an empty entity pinned
+      // loading permanently.
+      .finally(() => setRefetching(false));
   }, [sync]);
 
-  return {
-    data,
-    loading: loading.current,
-    error: error.current,
-    refetch,
-  };
+  return { data, loading, error, refetch };
 }
 
 /**
@@ -175,14 +199,14 @@ export function useQueryOne<T = Row>(
   entity: string,
   id: string
 ): UseQueryOneReturn<T> {
-  // Same initial-sync-aware loading semantics as useQuery — see the comment
-  // there. Gates on isInitialSyncSettled() (server-confirmed) so a cold load
-  // shows a skeleton rather than flashing "not found" before the pull lands,
-  // and a refreshed page doesn't flash "Loading…" when the row is cached.
-  const loading = useRef<boolean>(
-    !sync.isInitialSyncSettled() && sync.store.get(entity, id) === null,
-  );
-  const error = useRef<Error | null>(null);
+  // Same initial-sync-aware loading semantics as useQuery — see the long
+  // comment there for why the settled signal needs its own boolean-valued
+  // subscription. This hook had the identical defect and it bit harder: a row
+  // that does not exist yields the same `null` snapshot before and after the
+  // pull, so React bailed out of the re-render and the caller was pinned in
+  // loading instead of ever reaching "not found".
+  const [error, setError] = useState<Error | null>(null);
+  const [refetching, setRefetching] = useState(false);
 
   const subscribe = useMemo(
     () => (onChange: () => void) => {
@@ -206,13 +230,6 @@ export function useQueryOne<T = Row>(
     if (sig !== snapshotCache.current.sig) {
       snapshotCache.current = { row: (row as T) ?? null, sig };
     }
-    // Mirror useQuery: loading flips false once the row arrives OR the initial
-    // sync settles (server-confirmed). Gating on isInitialSyncSettled() — not
-    // bare hydration — keeps a cold load in the skeleton state until the pull
-    // confirms, so a row that exists server-side doesn't flash "not found".
-    if (loading.current && (row !== null || sync.isInitialSyncSettled())) {
-      loading.current = false;
-    }
     return snapshotCache.current.row;
   }, [sync, entity, id]);
 
@@ -220,6 +237,17 @@ export function useQueryOne<T = Row>(
 
   const data = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 
+  const settled = useSyncExternalStore(
+    subscribe,
+    useCallback(() => sync.isInitialSyncSettled(), [sync]),
+    FALSE_SNAPSHOT,
+  );
+
+  // Loading until the row arrives OR the pull confirms it isn't there. Keeping
+  // a cold load in the loading state is what stops a row that DOES exist
+  // server-side from flashing "not found" while it is still in flight.
+  const loading = refetching || (!settled && data === null);
+
   // Register interest so reconcile sweeps this entity even with zero
   // local rows. See SyncEngine.observeEntity.
   useEffect(() => {
@@ -227,14 +255,17 @@ export function useQueryOne<T = Row>(
   }, [sync, entity]);
 
   const refetch = useCallback(() => {
-    loading.current = true;
-    error.current = null;
-    sync.pull().catch((e: unknown) => {
-      error.current = e instanceof Error ? e : new Error(String(e));
-    });
+    setRefetching(true);
+    setError(null);
+    sync
+      .pull()
+      .catch((e: unknown) => {
+        setError(e instanceof Error ? e : new Error(String(e)));
+      })
+      .finally(() => setRefetching(false));
   }, [sync]);
 
-  return { data, loading: loading.current, error: error.current, refetch };
+  return { data, loading, error, refetch };
 }
 
 // ---------------------------------------------------------------------------

package/src/useQuery.loading.test.tsx

@@ -0,0 +1,142 @@
+// Regression coverage for `useQuery` / `useQueryOne` loading state, mounted.
+//
+// The bug: `loading` was a `useRef` flipped inside `getSnapshot`. React's
+// useSyncExternalStore only re-renders when getSnapshot returns a value that
+// isn't Object.is-equal to the previous one — and the snapshot for an entity
+// with NO rows is the same cached array before and after the initial pull
+// settles. So markInitialSyncSettled() notified, getSnapshot ran, the ref
+// flipped to false, React compared the identical array, bailed out of the
+// re-render, and the component kept rendering the stale `loading: true`.
+//
+// Forever. Every empty list in every Pylon app — a new account's first
+// dashboard, a newly added entity, a list whose rows were all deleted — sat on
+// its skeleton and never reached its empty state. It was invisible to the
+// existing tests because the engine-level signal (packages/sync's
+// initial-sync-loading.test.ts) was correct the whole time; only the mounted
+// hook was wrong, and packages/react had no renderer to mount it with.
+//
+// These tests mount the real hook against the real SyncEngine. They fail with
+// the ref-based implementation and pass with the derived one.
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { act, render, screen, waitFor, cleanup } from "@testing-library/react";
+import type { SyncEngine } from "@pylonsync/sync";
+import { createTestEnv, type TestEnv } from "@pylonsync/sync/src/test-harness";
+
+import { useQuery, useQueryOne } from "./hooks";
+
+// @pylonsync/sync points `main` at src/ but `types` at dist/, so the harness
+// (imported by its src path) hands back a SyncEngine whose declaration differs
+// from the one the hooks are typed against — same class at runtime, two
+// nominal types to tsc. One cast here beats reshaping the package's exports.
+const asEngine = (e: TestEnv["engine"]): SyncEngine => e as unknown as SyncEngine;
+
+let env: TestEnv | null = null;
+
+afterEach(async () => {
+  cleanup();
+  if (env) {
+    await env.dispose();
+    env = null;
+  }
+});
+
+function ListProbe({ engine }: { engine: SyncEngine }) {
+  const { data, loading } = useQuery<{ id: string }>(engine, "Todo");
+  // Render the two facts a caller branches on. A component that never
+  // re-renders keeps reporting the values from its last render, which is
+  // exactly the failure being pinned.
+  return (
+    <div>
+      <span data-testid="state">{loading ? "loading" : "settled"}</span>
+      <span data-testid="count">{data.length}</span>
+    </div>
+  );
+}
+
+function RowProbe({ engine, id }: { engine: SyncEngine; id: string }) {
+  const { data, loading } = useQueryOne<{ id: string }>(engine, "Todo", id);
+  return (
+    <span data-testid="state">
+      {loading ? "loading" : data === null ? "not-found" : "found"}
+    </span>
+  );
+}
+
+describe("useQuery loading over an EMPTY entity", () => {
+  test("leaves loading once the initial pull settles, so the empty state renders", async () => {
+    env = createTestEnv();
+    env.signIn({ userId: "u1" });
+
+    render(<ListProbe engine={asEngine(env.engine)} />);
+
+    // Before the pull confirms, an empty local replica is "we don't know yet",
+    // not "there is nothing" — callers must be able to hold a skeleton here
+    // rather than flash an empty state over rows still in flight.
+    expect(screen.getByTestId("state").textContent).toBe("loading");
+
+    await act(async () => {
+      await env!.start();
+    });
+
+    // The crux. The engine settles with ZERO Todo rows, so the row snapshot is
+    // identical across the settle. If `loading` is a ref flipped inside
+    // getSnapshot, React bails out of this re-render and the probe is stuck
+    // reading "loading" — this waitFor times out.
+    await waitFor(() =>
+      expect(screen.getByTestId("state").textContent).toBe("settled"),
+    );
+    expect(screen.getByTestId("count").textContent).toBe("0");
+  });
+
+  test("a replica wipe returns an empty list to loading rather than flashing empty", async () => {
+    env = createTestEnv();
+    env.signIn({ userId: "u1" });
+    render(<ListProbe engine={asEngine(env.engine)} />);
+    await act(async () => {
+      await env!.start();
+    });
+    await waitFor(() =>
+      expect(screen.getByTestId("state").textContent).toBe("settled"),
+    );
+
+    // The org-switch path wipes the replica. The rows are empty on both sides
+    // of that, so a latched `loading` would stay false and the UI would assert
+    // "nothing here" about an org it has not fetched yet.
+    await act(async () => {
+      await env!.engine.resetReplica();
+    });
+    await waitFor(() =>
+      expect(screen.getByTestId("state").textContent).toBe("loading"),
+    );
+
+    await act(async () => {
+      await env!.flush();
+      await env!.engine.pull();
+    });
+    await waitFor(() =>
+      expect(screen.getByTestId("state").textContent).toBe("settled"),
+    );
+  });
+});
+
+describe("useQueryOne loading over a MISSING row", () => {
+  test("reaches not-found instead of pinning on loading", async () => {
+    env = createTestEnv();
+    env.signIn({ userId: "u1" });
+
+    render(<RowProbe engine={asEngine(env.engine)} id="does-not-exist" />);
+    expect(screen.getByTestId("state").textContent).toBe("loading");
+
+    await act(async () => {
+      await env!.start();
+    });
+
+    // Same identical-snapshot trap, and it bit harder here: a row that does
+    // not exist yields `null` before AND after the pull, so nothing ever
+    // re-rendered and "not found" was unreachable.
+    await waitFor(() =>
+      expect(screen.getByTestId("state").textContent).toBe("not-found"),
+    );
+  });
+});