@pylonsync/react 0.22.50 → 0.22.59

package/src/index.ts

@@ -190,6 +190,8 @@ export type { UseSessionReturn, ResolvedSession } from "./useSession";
 
 export { useSyncStatus } from "./useSyncStatus";
 export type { SyncConnectionStatus } from "./useSyncStatus";
+export { useSyncProgress } from "./useSyncProgress";
+export type { SyncProgress } from "./useSyncProgress";
 
 // Writes not yet on the server, and writes the server rejected.
 export { useOutbox } from "./useOutbox";
@@ -205,6 +207,14 @@ export { UploadQueueFullError, UploadRejectedError } from "@pylonsync/sync";
 export { registerOfflineWorker } from "./offlineWorker";
 export type { OfflineWorkerOptions } from "./offlineWorker";
 
+// App updates: a newer build is deployed, load it.
+export { useAppUpdate } from "./useAppUpdate";
+export type { UseAppUpdateReturn } from "./useAppUpdate";
+export { AppUpdateBar } from "./AppUpdateBar";
+export type { AppUpdateBarProps } from "./AppUpdateBar";
+export { createAppUpdate, AppUpdater } from "./appUpdate";
+export type { AppBuild, AppUpdateState, AppUpdateEnv } from "./appUpdate";
+
 // One-liner API
 export { db, init, getSync, setSessionToken } from "./db";
 

package/src/offlineWorker.test.ts

@@ -85,3 +85,26 @@ test("a browser without service workers is a no-op", async () => {
     await registerOfflineWorker({ optedIn: true, production: true, navigator: {} }),
   ).toBeNull();
 });
+
+test("passes the page's build to useAppUpdate, in production and in dev", async () => {
+  const { appUpdate } = await import("./appUpdate");
+  const f = fakeContainer();
+  await registerOfflineWorker({
+    optedIn: true,
+    production: true,
+    navigator: { serviceWorker: f.container },
+    whenLoaded: loaded,
+    build: { version: "abc", builtAt: "2026-10-22T10:00:00.000Z" },
+  });
+  expect(appUpdate.getSnapshot().version).toBe("abc");
+  expect(appUpdate.getSnapshot().builtAt).toBe("2026-10-22T10:00:00.000Z");
+
+  // Under pylon dev the updater stays empty.
+  await registerOfflineWorker({
+    optedIn: true,
+    production: false,
+    navigator: { serviceWorker: f.container },
+    build: { version: "abc", builtAt: null },
+  });
+  expect(appUpdate.getSnapshot().version).toBeNull();
+});

package/src/offlineWorker.ts

@@ -7,6 +7,8 @@
 // `pylon dev`: a worker serves cached build files first, which would hide
 // every edit until the next install.
 
+import { configureAppUpdate, type AppBuild } from "./appUpdate";
+
 const WORKER_URL = "/pylon-sw.js";
 
 export interface OfflineWorkerOptions {
@@ -23,6 +25,9 @@ export interface OfflineWorkerOptions {
   /** Resolves when the page has loaded, so the worker's downloads do not
    *  compete with the page's own. Defaults to the window `load` event. */
   whenLoaded?: () => Promise<void>;
+  /** The build this page runs, from `__PYLON_DATA__`. `useAppUpdate`
+   *  compares it with the latest build. */
+  build?: AppBuild;
 }
 
 /** The parts of `ServiceWorkerContainer` this module uses. */
@@ -69,6 +74,9 @@ function isPylonWorker(reg: RegistrationLike): boolean {
 export async function registerOfflineWorker(
   opts: OfflineWorkerOptions,
 ): Promise<unknown | null> {
+  // Before the service worker checks: a browser without service workers
+  // still learns about new builds from `/_pylon/version`.
+  if (opts.build) configureAppUpdate(opts.build, opts.optedIn && opts.production);
   const nav =
     opts.navigator ??
     (typeof navigator !== "undefined" ? (navigator as any) : undefined);

package/src/query-filter-cases.json

@@ -0,0 +1,23 @@
+{
+  "about": "Filters answered from the local replica must match the server's answer. packages/react/src/queryFilter.test.ts runs these on the client; crates/runtime/tests/query_filter_parity.rs runs them on the server. Rows are stored as the server returns them (datetimes in canonical UTC form).",
+  "rows": [
+    { "key": "k1", "title": "apple", "occurredAt": "2026-09-30T23:59:59.999Z", "rank": 1 },
+    { "key": "k2", "title": "Banana", "occurredAt": "2026-10-01T00:00:00.000Z", "rank": 2 },
+    { "key": "k3", "title": "cherry", "occurredAt": "2026-10-01T12:30:00.000Z", "rank": 3 },
+    { "key": "k4", "title": "banana", "occurredAt": "2026-10-02T00:00:00.000Z", "rank": 4 },
+    { "key": "k5", "title": "", "occurredAt": null, "rank": 5 }
+  ],
+  "cases": [
+    { "where": { "occurredAt": { "$gte": "2026-10-01T00:00:00Z" } }, "keys": ["k2", "k3", "k4"] },
+    { "where": { "occurredAt": { "$lt": "2026-10-02T00:00:00.000Z" } }, "keys": ["k1", "k2", "k3"] },
+    { "where": { "occurredAt": { "$gte": "2026-09-30T20:00:00-04:00" } }, "keys": ["k2", "k3", "k4"] },
+    { "where": { "occurredAt": { "$gte": "2026-10-01T00:00:00.000Z", "$lt": "2026-10-01T23:00:00Z" } }, "keys": ["k2", "k3"] },
+    { "where": { "occurredAt": { "$lte": "2026-09-30T23:59:59.999Z" } }, "keys": ["k1"] },
+    { "where": { "occurredAt": { "$gt": "2026-10-01T00:00:00.000Z" } }, "keys": ["k3", "k4"] },
+    { "where": { "occurredAt": { "$gte": "2026-10-01" } }, "keys": ["k2", "k3", "k4"] },
+    { "where": { "title": { "$gte": "b" } }, "keys": ["k3", "k4"] },
+    { "where": { "title": { "$lt": "a" } }, "keys": ["k2", "k5"] },
+    { "where": { "rank": { "$gt": 2 } }, "keys": ["k3", "k4", "k5"] },
+    { "where": { "rank": { "$gte": 2, "$lte": 3 } }, "keys": ["k2", "k3"] }
+  ]
+}

package/src/queryFilter.test.ts

@@ -0,0 +1,45 @@
+// The local replica answers a filter the way the server does. The cases in
+// query-filter-cases.json also run against the server
+// (crates/runtime/tests/query_filter_parity.rs), so both sides are held to
+// the same answers.
+
+import { expect, spyOn, test } from "bun:test";
+import cases from "./query-filter-cases.json";
+import { compareForOrder, compileWhere } from "./queryFilter";
+
+for (const { where, keys } of cases.cases) {
+  test(`where ${JSON.stringify(where)}`, () => {
+    const match = compileWhere(where);
+    const got = cases.rows.filter((r) => match(r)).map((r) => r.key);
+    expect(got).toEqual(keys);
+  });
+}
+
+test("an operator that cannot apply matches nothing and warns once in dev", () => {
+  const warn = spyOn(console, "warn").mockImplementation(() => {});
+  const match = compileWhere({ rank: { $gt: "2" } });
+  expect(cases.rows.filter((r) => match(r))).toEqual([]);
+  expect(cases.rows.filter((r) => match(r))).toEqual([]);
+  expect(warn).toHaveBeenCalledTimes(1);
+  expect(String(warn.mock.calls[0]?.[0])).toContain("where.rank.$gt");
+
+  const unknown = compileWhere({ rank: { $between: [1, 2] } });
+  expect(cases.rows.filter((r) => unknown(r))).toEqual([]);
+  expect(warn).toHaveBeenCalledTimes(2);
+  warn.mockRestore();
+});
+
+test("ordering follows the server: code units, not locale; datetimes by time", () => {
+  const titles = ["banana", "Banana", "apple", "cherry"];
+  expect([...titles].sort((a, b) => compareForOrder(a, b, "asc"))).toEqual([
+    "Banana",
+    "apple",
+    "banana",
+    "cherry",
+  ]);
+  const times = ["2026-10-01T12:00:00Z", "2026-10-01T08:00:00-05:00"];
+  expect([...times].sort((a, b) => compareForOrder(a, b, "asc"))).toEqual([
+    "2026-10-01T12:00:00Z",
+    "2026-10-01T08:00:00-05:00",
+  ]);
+});

package/src/queryFilter.ts

@@ -0,0 +1,138 @@
+// Where-filter evaluation for queries answered from the local replica.
+//
+// The server answers the same filter in SQL, so these comparisons follow
+// the server's:
+//
+//   - Numbers compare numerically.
+//   - Strings compare by code unit, like SQLite's BINARY collation (not by
+//     locale).
+//   - Two RFC 3339 timestamps compare as instants. The server stores every
+//     `datetime` value in one canonical UTC form and canonicalizes a filter
+//     operand the same way, so `occurredAt: { $gte: "2026-10-01T00:00:00Z" }`
+//     matches by time whatever offset or precision either side was written
+//     with.
+//   - A missing or null value matches no range (SQL `NULL > x` is not true).
+//
+// An operator that cannot apply (a number against a string, an unknown
+// operator) matches nothing, as on the server, and warns once in dev, so
+// a filter that silently empties a screen shows up in the console.
+
+const RFC3339 = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+
+/** Epoch milliseconds of an RFC 3339 timestamp, or null. */
+function instant(value: string): number | null {
+  if (!RFC3339.test(value)) return null;
+  const ms = Date.parse(value);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+/**
+ * Order two values the way the server's SQL does: negative, zero or
+ * positive; `null` when they cannot be compared (different types, or an
+ * object). Null and undefined are not handled here.
+ */
+export function compareValues(a: unknown, b: unknown): number | null {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "string" && typeof b === "string") {
+    const ta = instant(a);
+    const tb = ta === null ? null : instant(b);
+    if (ta !== null && tb !== null) return ta - tb;
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+  if (typeof a === "boolean" && typeof b === "boolean") return Number(a) - Number(b);
+  return null;
+}
+
+const warned = new Set<string>();
+
+function warnOnce(field: string, op: string, reason: string): void {
+  if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") return;
+  const key = `${field}:${op}:${reason}`;
+  if (warned.has(key)) return;
+  warned.add(key);
+  // eslint-disable-next-line no-console
+  console.warn(`[pylon] where.${field}.${op} cannot apply (${reason}); it matches no rows.`);
+}
+
+type Row = Record<string, unknown>;
+
+const RANGE: Record<string, (c: number) => boolean> = {
+  $gt: (c) => c > 0,
+  $gte: (c) => c >= 0,
+  $lt: (c) => c < 0,
+  $lte: (c) => c <= 0,
+};
+
+/** A predicate for `where` (keys other than `$order` and `$limit`). */
+export function compileWhere(where: Record<string, unknown>): (row: Row) => boolean {
+  const fields = Object.entries(where)
+    .filter(([key]) => key !== "$order" && key !== "$limit")
+    .map(([key, val]) => ({
+      key,
+      val,
+      operators:
+        val !== null && typeof val === "object" && !Array.isArray(val)
+          ? Object.entries(val as Record<string, unknown>).map(([op, opVal]) => ({
+              op,
+              opVal,
+              members: op === "$in" && Array.isArray(opVal) ? new Set(opVal) : undefined,
+            }))
+          : undefined,
+    }));
+  return (row) => {
+    for (const { key, val, operators } of fields) {
+      const rowVal = row[key];
+      if (!operators) {
+        if (rowVal !== val) return false;
+        continue;
+      }
+      for (const { op, opVal, members } of operators) {
+        const range = RANGE[op];
+        if (range) {
+          if (rowVal === null || rowVal === undefined) return false;
+          if (opVal === null || opVal === undefined) {
+            warnOnce(key, op, "the operand is null");
+            return false;
+          }
+          const c = compareValues(rowVal, opVal);
+          if (c === null) {
+            warnOnce(key, op, `a ${typeof rowVal} value against a ${typeof opVal} operand`);
+            return false;
+          }
+          if (!range(c)) return false;
+          continue;
+        }
+        switch (op) {
+          case "$not":
+            if (rowVal === opVal) return false;
+            break;
+          case "$like":
+            if (!(typeof rowVal === "string" && typeof opVal === "string" && rowVal.includes(opVal)))
+              return false;
+            break;
+          case "$in":
+            if (!members?.has(rowVal)) return false;
+            break;
+          default:
+            warnOnce(key, op, "unknown operator");
+            return false;
+        }
+      }
+    }
+    return true;
+  };
+}
+
+/** Sort comparator for `$order` / `orderBy`: nulls last ascending, the
+ *  server's value order otherwise. */
+export function compareForOrder(a: unknown, b: unknown, dir: "asc" | "desc"): number {
+  const mult = dir === "desc" ? -1 : 1;
+  if (a === b) return 0;
+  if (a === undefined || a === null) return mult;
+  if (b === undefined || b === null) return -mult;
+  const c = compareValues(a, b);
+  if (c !== null) return Math.sign(c) * mult;
+  const sa = String(a);
+  const sb = String(b);
+  return (sa < sb ? -1 : sa > sb ? 1 : 0) * mult;
+}

package/src/useAppUpdate.test.tsx

@@ -0,0 +1,98 @@
+// useAppUpdate re-renders when a new build appears, and AppUpdateBar shows
+// the notice and runs apply().
+
+import { afterEach, expect, test } from "bun:test";
+import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { renderToString } from "react-dom/server";
+
+import { AppUpdateBar } from "./AppUpdateBar";
+import { createAppUpdate, type AppUpdateEnv } from "./appUpdate";
+import { useAppUpdate } from "./useAppUpdate";
+
+afterEach(cleanup);
+
+function env(latest: { version: string; install?: string }, reloads: { n: number }) {
+  const e: AppUpdateEnv = {
+    serviceWorker: null,
+    fetch: async () => ({ ok: true, json: async () => latest }),
+    document: null,
+    setInterval: () => 0,
+    clearInterval: () => {},
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (h) => clearTimeout(h as any),
+    now: () => Date.now(),
+    reload: () => {
+      reloads.n++;
+    },
+    sessionStorage: null,
+    localStorage: null,
+    iosStandalone: false,
+    pendingWrites: () => null,
+    askVersion: async () => null,
+    warn: () => {},
+  };
+  return e;
+}
+
+function Probe({ updater }: { updater: ReturnType<typeof createAppUpdate> }) {
+  const u = useAppUpdate(updater);
+  return <span data-testid="state">{`${u.version} -> ${u.latestVersion} ready=${u.updateReady}`}</span>;
+}
+
+test("re-renders when the server reports a new build", async () => {
+  const latest = { version: "v1" };
+  const updater = createAppUpdate({
+    build: { version: "v1", builtAt: null },
+    production: true,
+    env: env(latest, { n: 0 }),
+  });
+  render(<Probe updater={updater} />);
+  await waitFor(() =>
+    expect(screen.getByTestId("state").textContent).toBe("v1 -> v1 ready=false"),
+  );
+  latest.version = "v2";
+  await act(async () => {
+    await updater.check();
+  });
+  expect(screen.getByTestId("state").textContent).toBe("v1 -> v2 ready=true");
+});
+
+test("renders the empty state on the server", () => {
+  const updater = createAppUpdate({
+    build: { version: "v1", builtAt: null },
+    production: true,
+    env: env({ version: "v2" }, { n: 0 }),
+  });
+  expect(renderToString(<Probe updater={updater} />)).toContain("null -&gt; null ready=false");
+  expect(renderToString(<AppUpdateBar updater={updater} />)).toBe("");
+});
+
+test("AppUpdateBar shows the notice when a build is ready, and the button applies it", async () => {
+  const reloads = { n: 0 };
+  const updater = createAppUpdate({
+    build: { version: "v1", builtAt: null },
+    production: true,
+    env: env({ version: "v2" }, reloads),
+  });
+  render(<AppUpdateBar updater={updater} className="bar" />);
+  const button = await screen.findByRole("button", { name: "Update" });
+  expect(screen.getByRole("status").getAttribute("data-pylon-app-update")).toBe("ready");
+  expect(screen.getByRole("status").className).toBe("bar");
+  await act(async () => {
+    fireEvent.click(button);
+  });
+  await waitFor(() => expect(reloads.n).toBe(1));
+});
+
+test("AppUpdateBar renders nothing without an update", async () => {
+  const updater = createAppUpdate({
+    build: { version: "v1", builtAt: null },
+    production: true,
+    env: env({ version: "v1" }, { n: 0 }),
+  });
+  const { container } = render(<AppUpdateBar updater={updater} />);
+  await act(async () => {
+    await updater.check();
+  });
+  expect(container.innerHTML).toBe("");
+});

package/src/useAppUpdate.ts

@@ -0,0 +1,49 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+import {
+  appUpdate,
+  INERT_APP_UPDATE_STATE,
+  type AppUpdater,
+  type AppUpdateState,
+} from "./appUpdate";
+
+export interface UseAppUpdateReturn extends AppUpdateState {
+  /** Wait until the outbox has no pending writes, then load the newest
+   *  build (the page reloads). */
+  apply: () => Promise<void>;
+  /** Ask the server for the latest build now. The hook also checks when
+   *  the page becomes visible and every five minutes. */
+  check: () => Promise<void>;
+}
+
+const serverSnapshot = () => INERT_APP_UPDATE_STATE;
+
+/**
+ * Whether a newer build of the app is deployed, and a way to load it.
+ * Works in apps that set `buildManifest({ offline })`; elsewhere, under
+ * `pylon dev` and during SSR, `updateReady` stays false and `apply()` does
+ * nothing.
+ *
+ * ```tsx
+ * function UpdateNotice() {
+ *   const { updateReady, applying, waitingForSync, apply } = useAppUpdate();
+ *   if (!updateReady) return null;
+ *   return (
+ *     <div role="status">
+ *       A new version of the app is available.
+ *       <button onClick={apply} disabled={applying}>
+ *         {waitingForSync ? "Saving changes" : "Update"}
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * Pass an explicit `updater` (from `createAppUpdate`) to use one other than
+ * the page's.
+ */
+export function useAppUpdate(updater: AppUpdater = appUpdate): UseAppUpdateReturn {
+  const state = useSyncExternalStore(updater.subscribe, updater.getSnapshot, serverSnapshot);
+  return { ...state, apply: updater.apply, check: updater.check };
+}

package/src/useSession.ts

@@ -69,9 +69,11 @@ export function useSession(sync: SyncEngine): UseSessionReturn {
   // app writes a new token without going through `notifySessionChanged`,
   // our cached session still matches the old identity until the next
   // pull. A `storage` event covers the cross-tab case; a mount-time
-  // refresh covers the same-tab write-then-mount race.
+  // check covers the same-tab write-then-mount race. The check fetches
+  // only when the session is not known for the current token, and joins
+  // a request in flight, so a screen of session readers makes one call.
   useEffect(() => {
-    void sync.notifySessionChanged();
+    void sync.refreshSessionIfStale();
     const onStorage = (e: StorageEvent) => {
       // Only refresh when the key that actually changed looks like a
       // pylon token. Skip unrelated keys so we don't generate an

package/src/useSyncProgress.test.tsx

@@ -0,0 +1,37 @@
+// useSyncProgress re-renders as a pull runs and ends.
+
+import { afterEach, expect, test } from "bun:test";
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+import type { SyncEngine } from "@pylonsync/sync";
+import { createTestEnv, type TestEnv } from "@pylonsync/sync/src/test-harness";
+
+import { useSyncProgress } from "./useSyncProgress";
+
+let env: TestEnv | null = null;
+afterEach(async () => {
+  cleanup();
+  if (env) {
+    await env.dispose();
+    env = null;
+  }
+});
+
+function Probe({ engine }: { engine: SyncEngine }) {
+  const p = useSyncProgress(engine);
+  return <span data-testid="p">{`${p.pulling} ${p.snapshot} ${p.rows} ${p.synced}`}</span>;
+}
+
+test("reports a snapshot pull's rows, then synced", async () => {
+  env = createTestEnv({ transport: "poll" });
+  env.server.snapshotMode = true;
+  env.server.seed("Lead", Array.from({ length: 1500 }, (_, i) => ({ id: `l${i}` })));
+  env.signIn({ userId: "u1" });
+  const engine = env.engine as unknown as SyncEngine;
+  render(<Probe engine={engine} />);
+  expect(screen.getByTestId("p").textContent).toBe("false false 0 false");
+
+  await act(async () => {
+    await env!.engine.start();
+  });
+  await waitFor(() => expect(screen.getByTestId("p").textContent).toBe("false true 1500 true"));
+});

package/src/useSyncProgress.ts

@@ -0,0 +1,46 @@
+"use client";
+
+import {
+	SYNC_PROGRESS_CHANNEL,
+	type SyncEngine,
+	type SyncProgress,
+} from "@pylonsync/sync";
+import { useSyncExternalStore } from "react";
+import { db } from "./db";
+
+export type { SyncProgress };
+
+const SERVER: SyncProgress = {
+	pulling: false,
+	snapshot: false,
+	rows: 0,
+	pages: 0,
+	synced: false,
+};
+
+/**
+ * How far the sync engine's current pull has got: `pulling`, `snapshot`
+ * (a first sync or a far-behind catch-up), `rows` and `pages` received,
+ * and `synced` (a pull completed since the last replica reset).
+ *
+ * The session resolves as soon as `/api/auth/me` answers, before the
+ * replica has filled. Render the signed-in screen from `useSession()` and
+ * use this for a progress line while the data arrives. `useSyncStatus()`
+ * reports the connection instead.
+ *
+ * ```tsx
+ * function SyncLine() {
+ *   const { pulling, snapshot, rows } = useSyncProgress();
+ *   if (!pulling || !snapshot) return null;
+ *   return <p>Loading data: {rows} records</p>;
+ * }
+ * ```
+ */
+export function useSyncProgress(engine?: SyncEngine): SyncProgress {
+	const sync = engine ?? db.sync;
+	return useSyncExternalStore(
+		(cb) => sync.store.subscribe(cb, SYNC_PROGRESS_CHANNEL),
+		() => sync.syncProgress(),
+		() => SERVER,
+	);
+}