@pylonsync/react 0.22.47 → 0.22.58

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/useOutbox.test.tsx

@@ -0,0 +1,82 @@
+// `useOutbox` re-renders as writes go pending, reach the server, or fail, and
+// its retry/dismiss act on the failed list.
+
+import { afterEach, describe, 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 { useOutbox } from "./useOutbox";
+
+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;
+  }
+});
+
+let latest: ReturnType<typeof useOutbox> | null = null;
+function Probe({ engine }: { engine: SyncEngine }) {
+  const outbox = useOutbox(engine);
+  latest = outbox;
+  return (
+    <span data-testid="outbox">
+      {`${outbox.pending.length} not synced, ${outbox.failed.length} failed` +
+        (outbox.failed[0] ? `: ${outbox.failed[0].error}` : "")}
+    </span>
+  );
+}
+
+const text = () => screen.getByTestId("outbox").textContent;
+
+describe("useOutbox", () => {
+  test("re-renders when a write goes pending, then reaches the server", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    await env.start();
+    render(<Probe engine={asEngine(env.engine)} />);
+    expect(text()).toBe("0 not synced, 0 failed");
+
+    env.server.primeNextPushOutcome({ kind: "network" });
+    await act(async () => {
+      await env!.engine.insert("Knock", { door: "1" });
+    });
+    expect(text()).toBe("1 not synced, 0 failed");
+
+    await act(async () => {
+      await env!.engine.push();
+    });
+    await waitFor(() => expect(text()).toBe("0 not synced, 0 failed"));
+  });
+
+  test("re-renders when a write fails; retry and dismiss work from the hook", async () => {
+    env = createTestEnv({ transport: "poll" });
+    env.signIn({ userId: "u1" });
+    await env.start();
+    env.server.rejectWritesWhere("Knock", (d) => d.door === "", "VALIDATION_FAILED", "door number is required");
+    render(<Probe engine={asEngine(env.engine)} />);
+
+    await act(async () => {
+      await env!.engine.insert("Knock", { door: "" }).catch(() => {});
+    });
+    expect(text()).toBe("0 not synced, 1 failed: door number is required");
+
+    await act(async () => {
+      await latest!.retry(latest!.failed[0]!.id, { door: "7" });
+    });
+    await waitFor(() => expect(text()).toBe("0 not synced, 0 failed"));
+
+    await act(async () => {
+      await env!.engine.insert("Knock", { door: "" }).catch(() => {});
+    });
+    expect(text()).toBe("0 not synced, 1 failed: door number is required");
+    act(() => {
+      expect(latest!.dismiss(latest!.failed[0]!.id)).toBe(true);
+    });
+    expect(text()).toBe("0 not synced, 0 failed");
+  });
+});

package/src/useOutbox.ts

@@ -0,0 +1,74 @@
+"use client";
+
+import {
+	OUTBOX_CHANNEL,
+	type Outbox,
+	type OutboxItem,
+	type Row,
+	type SyncEngine,
+} from "@pylonsync/sync";
+import { useCallback, useSyncExternalStore } from "react";
+import { db } from "./db";
+
+export type { Outbox, OutboxItem };
+
+export interface UseOutboxReturn {
+	/** Writes the server has not applied yet: made offline, or waiting
+	 *  for a sign-in. Oldest first. */
+	pending: OutboxItem[];
+	/** Writes the server rejected, with `error` and `errorCode`. Oldest
+	 *  first. Each stays until it is retried or dismissed. */
+	failed: OutboxItem[];
+	/** Send a failed write again, with `data` merged over its fields.
+	 *  Resolves once the server applies it or it is queued offline;
+	 *  rejects with a `MutationRejectedError` when the server rejects it
+	 *  again or another user is signed in. */
+	retry: (id: string, data?: Row) => Promise<string>;
+	/** Drop a failed write. */
+	dismiss: (id: string) => boolean;
+}
+
+const EMPTY: Outbox = { pending: [], failed: [] };
+
+/**
+ * The writes on this device that are not on the server: pending writes
+ * (offline, or waiting for a sign-in) and failed writes (the server
+ * rejected them). Re-renders when a write is queued, applied, rejected,
+ * retried or dismissed.
+ *
+ * ```tsx
+ * function Outbox() {
+ *   const { pending, failed, retry, dismiss } = useOutbox();
+ *   return (
+ *     <>
+ *       {pending.length > 0 && <p>{pending.length} not synced</p>}
+ *       {failed.map((w) => (
+ *         <div key={w.id}>
+ *           {w.entity}: {w.error}
+ *           <button onClick={() => retry(w.id)}>Retry</button>
+ *           <button onClick={() => dismiss(w.id)}>Dismiss</button>
+ *         </div>
+ *       ))}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * Pass an explicit `engine` if your app uses a non-default sync
+ * instance; otherwise the hook reads the singleton wired up by `init()`.
+ */
+export function useOutbox(engine?: SyncEngine): UseOutboxReturn {
+	const sync = engine ?? db.sync;
+	const outbox = useSyncExternalStore(
+		(cb) => sync.store.subscribe(cb, OUTBOX_CHANNEL),
+		() => sync.outbox(),
+		// The server has no queue.
+		() => EMPTY,
+	);
+	const retry = useCallback(
+		(id: string, data?: Row) => sync.retryWrite(id, data),
+		[sync],
+	);
+	const dismiss = useCallback((id: string) => sync.dismissWrite(id), [sync]);
+	return { pending: outbox.pending, failed: outbox.failed, retry, dismiss };
+}

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,
+	);
+}