@multiplatform.one/frappe 7.8.0 → 7.11.0

package/src/sync/refreshSubscriptions.spec.ts

@@ -0,0 +1,295 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { createFrappeCollection } from "../collection";
+import { SyncModule as PublicSyncModule } from "../index";
+import { SyncModule } from "./index";
+import { Order, defaultPageLength } from "./types";
+import type { SubscriptionQuery } from "./types";
+
+vi.mock("@multiplatform.one/platform", () => ({
+  isNative: false,
+  isServer: true,
+  isWindowDefined: false,
+  onAppFocus: () => () => {},
+  onOnline: () => () => {},
+  onVisibilityChange: () => () => {},
+}));
+const instances: SyncModule[] = [];
+const cleanups: (() => unknown)[] = [];
+afterEach(async () => {
+  try {
+    for (const cleanup of cleanups.splice(0)) await cleanup();
+  } finally {
+    for (const sync of instances.splice(0)) await sync.dispose();
+  }
+});
+const row = (name: string, title = name) => ({
+  name,
+  title,
+  doctype: "Item",
+  modified: "2026-09-09T01:00:00Z",
+});
+function setup() {
+  const db = { getDocList: vi.fn().mockResolvedValue([row("a"), row("b")]) };
+  const sync = new SyncModule(db as never, undefined);
+  instances.push(sync);
+  return { db, sync };
+}
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}
+it("replaces mounted collection membership and clears authoritative empty snapshots", async () => {
+  const { db, sync } = setup();
+  const subscribe = vi.spyOn(sync, "subscribe");
+  const collection = createFrappeCollection<ReturnType<typeof row>>("Item", { sync });
+  cleanups.push(() => collection.cleanup());
+  await collection.preload();
+  const originalCollection = collection;
+  const id = (await subscribe.mock.results[0].value).subscriptionId;
+  const observed: string[][] = [];
+  cleanups.push(
+    sync.subscribeStore(() => {
+      observed.push(sync.getDocsForSubscription(id!).map((doc) => doc.name));
+    }),
+  );
+  db.getDocList.mockResolvedValue({
+    data: [row("b", "updated"), row("c")],
+    cursor: "replacement-cursor",
+  });
+  const [result] = await sync.refreshSubscriptions();
+  expect(result.ok).toBe(true);
+  expect(result.subscriptionId).toBe(id);
+  expect(collection).toBe(originalCollection);
+  expect(
+    [...collection.state.values()]
+      .map(({ name, title }) => ({ name, title }))
+      .sort((a, b) => a.name.localeCompare(b.name)),
+  ).toEqual([
+    { name: "b", title: "updated" },
+    { name: "c", title: "c" },
+  ]);
+  expect(observed).toEqual([["b", "c"]]);
+  expect(sync.getSubscription(id)?.cursor).toBe("replacement-cursor");
+  expect(sync.getDocFromCache("Item", "a")).toEqual(row("a"));
+  db.getDocList.mockResolvedValue([]);
+  expect(await sync.refreshSubscriptions()).toEqual([result]);
+  expect([...collection.state.values()]).toEqual([]);
+  expect(sync.getSubscription(result.subscriptionId)?.boundaries).toBeUndefined();
+  expect(collection).toBe(originalCollection);
+  expect(observed).toEqual([["b", "c"], []]);
+  expect(subscribe).toHaveBeenCalledTimes(1);
+  expect(sync.getSubscription(id)).toMatchObject({
+    id,
+    docIds: [],
+    metadata: { itemsBeforePage: 0, itemsAfterPage: 0 },
+  });
+  expect(sync.getSubscription(id)?.cursor).toBeUndefined();
+  expect(sync.getSubscription(id)?.checkpoint).toBeUndefined();
+});
+it("retains data and checkpoint on failure and preserves the query", async () => {
+  const { db, sync } = setup();
+  db.getDocList.mockResolvedValue({ data: [row("a"), row("b")], cursor: "committed-cursor" });
+  const query = {
+    doctype: "Item",
+    fields: ["title"],
+    filters: { enabled: 1 },
+    orderBy: [{ field: "title", order: Order.Desc }],
+    limit: 3,
+    limitStart: 6,
+  };
+  const { subscriptionId } = await sync.subscribe(query);
+  const before = structuredClone(sync.getSubscription(subscriptionId));
+  const error = new Error("offline");
+  db.getDocList.mockRejectedValue(error);
+  const results = await sync.refreshSubscriptions();
+  expect(results).toEqual([{ subscriptionId, ok: false, error }]);
+  expect(results[0].error).toBe(error);
+  expect(sync.getSubscription(subscriptionId)).toEqual({ ...before, stale: true });
+  expect(db.getDocList.mock.calls).toEqual(
+    Array(2).fill([
+      "Item",
+      {
+        fields: ["title", "modified", "name"],
+        filters: { enabled: 1 },
+        orderBy: [{ field: "title", order: Order.Desc }],
+        limit: 3,
+        limitStart: 6,
+      },
+    ]),
+  );
+  expect(sync.getDocsForSubscription(subscriptionId)).toEqual([row("a"), row("b")]);
+});
+it("coalesces overlapping requests into a trailing authoritative fetch", async () => {
+  const { db, sync } = setup();
+  const { subscriptionId } = await sync.subscribe({ doctype: "Item" });
+  const first = deferred<ReturnType<typeof row>[]>();
+  const last = deferred<ReturnType<typeof row>[]>();
+  db.getDocList.mockReturnValueOnce(first.promise).mockReturnValueOnce(last.promise);
+  const one = sync.refreshSubscriptions();
+  await vi.waitFor(() => expect(db.getDocList).toHaveBeenCalledTimes(2));
+  const two = sync.refreshSubscriptions();
+  await Promise.resolve();
+  first.resolve([row("old")]);
+  await vi.waitFor(() => expect(db.getDocList).toHaveBeenCalledTimes(3));
+  expect(sync.getDocsForSubscription(subscriptionId)).toEqual([row("a"), row("b")]);
+  last.resolve([row("new")]);
+  expect(await one).toEqual(await two);
+  expect(sync.getDocsForSubscription(subscriptionId)).toEqual([row("new")]);
+});
+it("does not resurrect an unsubscribed request or modify its cached rows", async () => {
+  const { db, sync } = setup();
+  const { subscriptionId } = await sync.subscribe({ doctype: "Item" });
+  const pending = deferred<ReturnType<typeof row>[]>();
+  db.getDocList.mockReturnValueOnce(pending.promise);
+  const refresh = sync.refreshSubscriptions();
+  await vi.waitFor(() => expect(db.getDocList).toHaveBeenCalledTimes(2));
+  sync.unsubscribe(subscriptionId);
+  pending.resolve([row("a", "obsolete")]);
+  expect((await refresh)[0].ok).toBe(false);
+  expect(sync.getSubscription(subscriptionId)).toBeUndefined();
+  expect(sync.getDocFromCache("Item", "a")).toEqual(row("a"));
+});
+it("filters active doctypes and explicitly declines progressive refresh", async () => {
+  const { db, sync } = setup();
+  await sync.subscribe({ doctype: "Item" });
+  const progressive = await sync.subscribe({ doctype: "Paged", progressive: true });
+  const before = structuredClone(sync.getSubscription(progressive.subscriptionId));
+  const pageBefore = structuredClone(sync.getPageInfo(progressive.subscriptionId));
+  expect(db.getDocList).toHaveBeenCalledTimes(2);
+  db.getDocList.mockClear();
+  expect(await sync.refreshSubscriptions({ doctypes: [] })).toEqual([]);
+  expect(await sync.refreshSubscriptions({ doctypes: ["Unknown"] })).toEqual([]);
+  expect(db.getDocList).not.toHaveBeenCalled();
+  expect((await sync.refreshSubscriptions({ doctypes: ["Item"] }))[0].ok).toBe(true);
+  expect(db.getDocList).toHaveBeenCalledTimes(1);
+  const result = await sync.refreshSubscriptions({ doctypes: ["Paged"] });
+  expect(sync.getSubscription(progressive.subscriptionId)).toEqual(before);
+  expect(sync.getPageInfo(progressive.subscriptionId)).toEqual(pageBefore);
+  expect(result).toEqual([
+    {
+      subscriptionId: progressive.subscriptionId,
+      ok: false,
+      error: new Error("Snapshot refresh does not support progressive subscriptions"),
+    },
+  ]);
+  expect(db.getDocList).toHaveBeenCalledTimes(1);
+});
+
+it("exports the public runtime constructor", () => {
+  expect(PublicSyncModule).toBe(SyncModule);
+  expect(PublicSyncModule.prototype.refreshSubscriptions).toBeTypeOf("function");
+});
+
+it.each([
+  [undefined, undefined, defaultPageLength],
+  [undefined, 8, defaultPageLength],
+  [null, 4, defaultPageLength],
+  [0, 0, 0],
+  [7, 2, 7],
+])("preserves query window limit=%s offset=%s", async (limit, limitStart, expectedLimit) => {
+  const { sync, db } = setup();
+  const query = {
+    doctype: "Item",
+    fields: ["title", "name", "title"],
+    filters: { enabled: 1 },
+    orderBy: [{ field: "title", order: Order.Desc }],
+    ...(limit === undefined ? {} : { limit }),
+    ...(limitStart === undefined ? {} : { limitStart }),
+  } as SubscriptionQuery;
+  const { subscriptionId } = await sync.subscribe(query);
+  expect(sync.getSubscription(subscriptionId)?.boundaries?.pageSize).toBe(expectedLimit);
+  db.getDocList.mockResolvedValue({
+    data: [row("z"), { ...row("b"), modified: "2026-09-09T02:00:00Z" }],
+    cursor: "new-cursor",
+  });
+  await sync.refreshSubscriptions();
+  expect(db.getDocList.mock.calls).toEqual(
+    Array(2).fill([
+      "Item",
+      {
+        fields: ["title", "name", "modified"],
+        filters: query.filters,
+        orderBy: query.orderBy,
+        limit: expectedLimit,
+        ...(limitStart === undefined ? {} : { limitStart }),
+      },
+    ]),
+  );
+  expect(sync.getSubscription(subscriptionId)).toMatchObject({
+    docIds: ["z", "b"],
+    cursor: "new-cursor",
+    checkpoint: "2026-09-09T02:00:00Z",
+    boundaries: { pageSize: expectedLimit, offset: limitStart ?? 0 },
+  });
+});
+
+it.each([404, 403])("handles single-name getDoc status %s", async (status) => {
+  const db = { getDoc: vi.fn().mockResolvedValue(row("a")), getDocList: vi.fn() };
+  const sync = new SyncModule(db as never, undefined);
+  instances.push(sync);
+  const { subscriptionId } = await sync.subscribe({ doctype: "Item", filters: { name: "a" } });
+  const before = structuredClone(sync.getSubscription(subscriptionId));
+  const error = Object.assign(new Error("getDoc failed"), { status });
+  db.getDoc.mockRejectedValue(error);
+  expect(await sync.refreshSubscriptions()).toEqual([
+    { subscriptionId, ok: status === 404, ...(status === 404 ? {} : { error }) },
+  ]);
+  expect(db.getDoc.mock.calls).toEqual([
+    ["Item", "a"],
+    ["Item", "a"],
+  ]);
+  expect(db.getDocList).not.toHaveBeenCalled();
+  if (status === 404) {
+    expect(sync.getDocsForSubscription(subscriptionId)).toEqual([]);
+    expect(sync.getSubscription(subscriptionId)?.boundaries).toBeUndefined();
+  } else expect(sync.getSubscription(subscriptionId)).toEqual({ ...before, stale: true });
+  expect(sync.getDocFromCache("Item", "a")).toEqual(row("a"));
+});
+
+it("returns independent success, failure and progressive refusal", async () => {
+  const { sync, db } = setup();
+  const item = await sync.subscribe({ doctype: "Item" });
+  const other = await sync.subscribe({ doctype: "Other" });
+  const progressive = await sync.subscribe({ doctype: "Paged", progressive: true });
+  const before = structuredClone(sync.getSubscription(progressive.subscriptionId));
+  const pageBefore = structuredClone(sync.getPageInfo(progressive.subscriptionId));
+  const error = new Error("offline");
+  db.getDocList.mockRejectedValueOnce(error).mockResolvedValueOnce([row("success")]);
+  expect(await sync.refreshSubscriptions()).toEqual([
+    { subscriptionId: item.subscriptionId, ok: false, error },
+    { subscriptionId: other.subscriptionId, ok: true },
+    {
+      subscriptionId: progressive.subscriptionId,
+      ok: false,
+      error: new Error("Snapshot refresh does not support progressive subscriptions"),
+    },
+  ]);
+  expect(sync.getSubscription(progressive.subscriptionId)).toEqual(before);
+  expect(sync.getPageInfo(progressive.subscriptionId)).toEqual(pageBefore);
+  expect(db.getDocList).toHaveBeenCalledTimes(5);
+});
+
+it.each(["resetCache", "dispose"] as const)(
+  "invalidates a pending refresh on %s",
+  async (action) => {
+    const { sync, db } = setup();
+    const { subscriptionId } = await sync.subscribe({ doctype: "Item" });
+    const pending = deferred<ReturnType<typeof row>[]>();
+    const started = deferred<void>();
+    db.getDocList.mockImplementationOnce(() => {
+      started.resolve();
+      return pending.promise;
+    });
+    const result = sync.refreshSubscriptions();
+    await started.promise;
+    await sync[action]();
+    pending.resolve([row("a", "obsolete"), row("obsolete")]);
+    expect((await result)[0].ok).toBe(false);
+    expect(sync.getSubscription(subscriptionId)).toBeUndefined();
+    expect(sync.getDocFromCache("Item", "a")).toBeUndefined();
+    expect(sync.getDocFromCache("Item", "obsolete")).toBeUndefined();
+  },
+);

package/src/sync/subscriptionManager.ts

@@ -30,7 +30,24 @@ export interface SubscribeResult<Data extends FrappeDocData> {
   refresh?: Promise<{ ok: boolean; error?: unknown }>;
 }
 
+export interface SubscriptionRefreshOptions {
+  doctypes?: string[];
+}
+
+export interface SubscriptionRefreshResult {
+  subscriptionId: string;
+  ok: boolean;
+  error?: unknown;
+}
+
 export class SubscriptionManager {
+  private refreshes = new Map<
+    string,
+    {
+      requested: boolean;
+      promise: Promise<SubscriptionRefreshResult>;
+    }
+  >();
   private subscriptions = new Map<string, Subscription>();
   private virtualPageManager: VirtualPageManager;
   private backfillManager: BackfillManager;
@@ -85,6 +102,7 @@ export class SubscriptionManager {
 
     const subscriptionId = cryptoRandomId();
     const { rows, cursor, checkpoint } = await this.fetchInitialRows<Data>(query);
+    this.seedRows(query, rows);
     // Materialize the in-memory subscription record with initial membership
     const subscription: Subscription = {
       id: subscriptionId,
@@ -100,8 +118,8 @@ export class SubscriptionManager {
       subscription.boundaries = {
         firstItem: rows[0] as unknown as FrappeDoc<Data>,
         lastItem: rows[rows.length - 1] as unknown as FrappeDoc<Data>,
-        offset: query.limitStart || 0,
-        pageSize: query.limit || 20,
+        offset: query.limitStart ?? 0,
+        pageSize: query.limit ?? defaultPageLength,
       };
     }
 
@@ -130,9 +148,85 @@ export class SubscriptionManager {
     return { subscriptionId: subscriptionId, rows, checkpoint };
   }
 
+  async refreshSubscriptions(
+    options: SubscriptionRefreshOptions = {},
+  ): Promise<SubscriptionRefreshResult[]> {
+    const subscriptions = [...this.subscriptions.values()].filter(
+      (subscription) =>
+        (this.subRefCounts.get(subscription.id) ?? 0) > 0 &&
+        (!options.doctypes || options.doctypes.includes(subscription.query.doctype)),
+    );
+    return Promise.all(subscriptions.map((subscription) => this.refreshSubscription(subscription)));
+  }
+
+  private refreshSubscription(subscription: Subscription): Promise<SubscriptionRefreshResult> {
+    const subscriptionId = subscription.id;
+    if (subscription.query.progressive) {
+      return Promise.resolve({
+        subscriptionId,
+        ok: false,
+        error: new Error("Snapshot refresh does not support progressive subscriptions"),
+      });
+    }
+    const existing = this.refreshes.get(subscriptionId);
+    if (existing) {
+      existing.requested = true;
+      return existing.promise;
+    }
+    const state = {
+      requested: false,
+      promise: Promise.resolve<SubscriptionRefreshResult>({ subscriptionId, ok: false }),
+    };
+    const active = () =>
+      this.refreshes.get(subscriptionId) === state &&
+      this.subscriptions.get(subscriptionId) === subscription &&
+      (this.subRefCounts.get(subscriptionId) ?? 0) > 0;
+    state.promise = Promise.resolve().then(async () => {
+      try {
+        while (true) {
+          state.requested = false;
+          try {
+            const { rows, cursor, checkpoint } = await this.fetchInitialRows(subscription.query);
+            if (!active()) {
+              return {
+                subscriptionId,
+                ok: false,
+                error: new Error("Subscription is no longer active"),
+              };
+            }
+            if (state.requested) continue;
+            this.seedRows(subscription.query, rows);
+            subscription.docIds = rows.map((row) => row.name);
+            subscription.cursor = cursor;
+            subscription.checkpoint = checkpoint;
+            subscription.boundaries = rows.length
+              ? {
+                  firstItem: rows[0],
+                  lastItem: rows[rows.length - 1],
+                  offset: subscription.query.limitStart ?? 0,
+                  pageSize: subscription.query.limit ?? defaultPageLength,
+                }
+              : undefined;
+            subscription.metadata = { itemsBeforePage: 0, itemsAfterPage: 0 };
+            subscription.stale = false;
+            return { subscriptionId, ok: true };
+          } catch (error) {
+            if (active() && state.requested) continue;
+            if (active()) subscription.stale = true;
+            return { subscriptionId, ok: false, error };
+          }
+        }
+      } finally {
+        if (this.refreshes.get(subscriptionId) === state) this.refreshes.delete(subscriptionId);
+      }
+    });
+    this.refreshes.set(subscriptionId, state);
+    return state.promise;
+  }
+
   /**
    * Performs the initial subscription fetch (single doc via getDoc, lists via
-   * getDocList), seeds the normalized cache, and computes the CDC checkpoint
+   * getDocList) and computes the CDC checkpoint
    * as the max `modified` across returned rows. Shared by fresh subscribes
    * and adopted-subscription refreshes so both have identical semantics.
    */
@@ -186,13 +280,6 @@ export class SubscriptionManager {
         rows = response;
       }
     }
-    // Seed the normalized cache with every returned row for instant local reads.
-    // Frappe's standard get_list API omits `doctype` from each row, so inject
-    // it from the subscription query to ensure the cache keys correctly.
-    for (const row of rows) {
-      if (!row.doctype) row.doctype = query.doctype;
-      this.normalizedCache.upsert(row);
-    }
     // Compute checkpoint for CDC as the max `modified` across returned rows (robust to server ordering)
     let checkpoint: string | undefined = undefined;
     for (const row of rows) {
@@ -202,6 +289,13 @@ export class SubscriptionManager {
     return { rows, cursor, checkpoint };
   }
 
+  private seedRows<Data extends FrappeDocData>(query: SubscriptionQuery, rows: FrappeDoc<Data>[]) {
+    for (const row of rows) {
+      if (!row.doctype) row.doctype = query.doctype;
+      this.normalizedCache.upsert(row);
+    }
+  }
+
   /**
    * Re-adopts a subscription restored from a persisted snapshot when an
    * identical query subscribes: the cached membership renders immediately and
@@ -225,44 +319,11 @@ export class SubscriptionManager {
     this.queryKeyToSubId.set(queryKey, restoredId);
     this.subRefCounts.set(restoredId, 1);
 
-    const refresh = this.refreshAdoptedSubscription<Data>(subscription);
+    const refresh = this.refreshSubscription(subscription);
     const rows = this.getDocsForSubscription<Data>(restoredId);
     return { subscriptionId: restoredId, rows, checkpoint: subscription.checkpoint, refresh };
   }
 
-  /**
-   * Network refresh for an adopted subscription with fresh-subscribe
-   * semantics: an authoritative page fetch replaces membership and recomputes
-   * the checkpoint (identical to what a brand-new subscribe would produce).
-   * On failure (offline) the cached membership and the restored CDC
-   * checkpoint are kept and the subscription is marked stale — the next
-   * backfill trigger drains changes from that checkpoint. Never rejects.
-   */
-  private async refreshAdoptedSubscription<Data extends FrappeDocData>(
-    subscription: Subscription,
-  ): Promise<{ ok: boolean; error?: unknown }> {
-    try {
-      const { rows, cursor, checkpoint } = await this.fetchInitialRows<Data>(subscription.query);
-      subscription.checkpoint = checkpoint;
-      subscription.cursor = cursor;
-      subscription.docIds = rows.map((row) => row.name);
-      if (rows.length > 0) {
-        subscription.boundaries = {
-          firstItem: rows[0] as unknown as FrappeDoc<FrappeDocData>,
-          lastItem: rows[rows.length - 1] as unknown as FrappeDoc<FrappeDocData>,
-          offset: subscription.query.limitStart || 0,
-          pageSize: subscription.query.limit || 20,
-        };
-      }
-      subscription.metadata = { itemsBeforePage: 0, itemsAfterPage: 0 };
-      subscription.stale = false;
-      return { ok: true };
-    } catch (error) {
-      subscription.stale = true;
-      return { ok: false, error };
-    }
-  }
-
   /**
    * Registers a subscription restored from a persisted snapshot. Restored
    * subscriptions are dormant: they hold the persisted query, CDC checkpoint,
@@ -343,6 +404,7 @@ export class SubscriptionManager {
       this.subRefCounts.set(subscriptionId, refCount);
       return;
     }
+    this.refreshes.delete(subscriptionId);
     // Last consumer released — clean up
     this.subRefCounts.delete(subscriptionId);
     let queryKey: string | undefined;
@@ -753,6 +815,7 @@ export class SubscriptionManager {
   }
 
   clear() {
+    this.refreshes.clear();
     this.subscriptions.clear();
     this.queryKeyToSubId.clear();
     this.subRefCounts.clear();

package/src/sync/types.ts

@@ -197,7 +197,15 @@ export enum RealtimeEventType {
   PermEpochBump = "perm_epoch_bump",
 }
 
+export interface SyncCatchUpState {
+  readonly refreshing: boolean;
+  readonly stale: boolean;
+  readonly error: unknown | null;
+}
+
 export interface SyncOptions {
+  /** Lifecycle catch-up uses CDC by default; snapshot requires only resource reads. */
+  catchUpStrategy?: "cdc" | "snapshot";
   pageSize?: number;
   persistKey?: string;
   onConflict?: (info: { doctype: string; name?: string }) => void;
@@ -261,7 +269,7 @@ export interface SyncOptions {
   /** Rate limit for mutation replay - max mutations per second (default: 10) */
   replayRateLimit?: number;
   /**
-   * Optional interval (in milliseconds) for periodic CDC polling.
+   * Optional interval (in milliseconds) for the selected catch-up strategy.
    * Acts as a safety net for silent socket drops. Set to 0 or omit
    * to rely solely on event-driven backfill (focus, online, reconnect).
    * Recommended: 30000 (30 seconds) for production.

package/src/syncOptionsKey.spec.ts

@@ -0,0 +1,46 @@
+import { expect, it } from "vitest";
+import { syncOptionsKey } from "./syncOptionsKey";
+
+it("normalizes lifecycle defaults and plain options independent of key order", () => {
+  expect(syncOptionsKey()).toBe(syncOptionsKey({ catchUpStrategy: "cdc", cdcInterval: 0 }));
+  expect(syncOptionsKey({ cdcInterval: -1 })).toBe(syncOptionsKey());
+  expect(
+    syncOptionsKey({ versionFields: { Task: "modified", Item: "version" }, pageSize: 20 }),
+  ).toBe(
+    syncOptionsKey({
+      pageSize: 20,
+      versionFields: { Item: "version", Task: "modified" },
+      persistKey: undefined,
+    }),
+  );
+});
+
+it("separates strategy, interval, persistence and cursor capabilities", () => {
+  const keys = [
+    undefined,
+    { catchUpStrategy: "snapshot" as const },
+    { cdcInterval: 1000 },
+    { persistKey: "one" },
+    { useCursorPagination: true },
+  ].map(syncOptionsKey);
+  expect(new Set(keys).size).toBe(keys.length);
+});
+
+it("keeps callback and storage identities without dropping functions", () => {
+  const callback = () => 0;
+  const storage = {
+    getItem: async () => null,
+    setItem: async () => {},
+    removeItem: async () => {},
+  };
+  expect(syncOptionsKey({ onBackfill: callback, storage })).toBe(
+    syncOptionsKey({ storage, onBackfill: callback }),
+  );
+  expect(syncOptionsKey({ onBackfill: callback })).not.toBe(
+    syncOptionsKey({ onBackfill: () => {} }),
+  );
+  expect(syncOptionsKey({ storage })).not.toBe(syncOptionsKey({ storage: { ...storage } }));
+  expect(syncOptionsKey({ fieldMergeConfig: { Task: { value: callback } } })).not.toBe(
+    syncOptionsKey(),
+  );
+});

package/src/syncOptionsKey.ts

@@ -0,0 +1,45 @@
+import type { SyncOptions } from "./sync/types";
+
+const identities = new WeakMap<object, number>();
+let nextIdentity = 0;
+function identity(value: object) {
+  let id = identities.get(value);
+  if (id === undefined) {
+    id = ++nextIdentity;
+    identities.set(value, id);
+  }
+  return ["reference", id];
+}
+
+function stableValue(value: unknown, ancestors = new Set<object>()): unknown {
+  if (typeof value === "function") return identity(value);
+  if (value === null || typeof value !== "object") return [typeof value, String(value)];
+  const prototype = Object.getPrototypeOf(value);
+  if (
+    ancestors.has(value) ||
+    (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null)
+  ) {
+    return identity(value);
+  }
+  const nested = new Set(ancestors).add(value);
+  if (Array.isArray(value)) return ["array", value.map((item) => stableValue(item, nested))];
+  return [
+    "record",
+    Object.entries(value)
+      .filter(([, item]) => item !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => [key, stableValue(item, nested)]),
+  ];
+}
+
+export function syncOptionsKey(options: SyncOptions = {}): string {
+  const { storage, ...values } = options;
+  return JSON.stringify([
+    stableValue({
+      ...values,
+      catchUpStrategy: options.catchUpStrategy ?? "cdc",
+      cdcInterval: options.cdcInterval && options.cdcInterval > 0 ? options.cdcInterval : 0,
+    }),
+    storage ? identity(storage) : null,
+  ]);
+}

package/types/frappeReact.d.ts

@@ -1,7 +1,7 @@
 import type { Collection } from "@tanstack/db";
 import { type FrappeCollectionOptionsConfig } from "./collection";
 import { SyncModule } from "./sync";
-import type { DebugMutationEntry } from "./sync/types";
+import type { DebugMutationEntry, SyncCatchUpState } from "./sync/types";
 /**
  * Configuration for creating a Frappe collection with connection details.
  */
@@ -115,6 +115,11 @@ export declare function useFrappeCollection<TDoc extends object & {
     name: string;
     doctype: string;
 }>(config: UseFrappeCollectionConfig | undefined, doctype: string, options?: Omit<FrappeCollectionOptionsConfig<TDoc>, "sync">): Collection<TDoc, string> | undefined;
+export interface UseFrappeCatchUpResult extends SyncCatchUpState {
+    retry: () => Promise<SyncCatchUpState>;
+}
+/** Connection-level refresh qualification. Retry resolves with state, including failures. */
+export declare function useFrappeCatchUp(config: UseFrappeCollectionConfig | undefined): UseFrappeCatchUpResult;
 /** Snapshot returned by {@link useFrappeConnection}. */
 export interface FrappeConnectionState {
     /** Socket connected right now. */

package/types/frappeReact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frappeReact.d.ts","sourceRoot":"","sources":["../src/frappeReact.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"frappeReact.d.ts","sourceRoot":"","sources":["../src/frappeReact.ts"],"names":[],"mappings":"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"}