@multiplatform.one/frappe 7.8.0 → 7.11.0

package/src/sync/index.ts

@@ -8,6 +8,8 @@ import { NormalizedCache } from "./normalizedCache";
 import { PersistenceManager } from "./persistence";
 import { RealtimeHandler } from "./realtime";
 import { RehydrationManager } from "./rehydration";
+import type { SubscriptionRefreshOptions, SubscriptionRefreshResult } from "./subscriptionManager";
+export type { SubscriptionRefreshOptions, SubscriptionRefreshResult } from "./subscriptionManager";
 import { SubscriptionManager } from "./subscriptionManager";
 import { BackfillScope, Status } from "./types";
 import type {
@@ -15,6 +17,7 @@ import type {
   DebugMutationEntry,
   DebugSubscription,
   SyncOptions,
+  SyncCatchUpState,
   FrappeDebugState,
   Mutation,
   RealtimeEventType,
@@ -40,6 +43,12 @@ function getBrowserJournalStorage(): Storage | undefined {
   }
 }
 
+const idleCatchUpState: SyncCatchUpState = Object.freeze({
+  refreshing: false,
+  stale: false,
+  error: null,
+});
+
 /**
  * Synchronization engine that provides Zero-style UX on top of Frappe's REST API.
  *
@@ -111,6 +120,14 @@ export class SyncModule {
   private readonly db: DbModule;
   private readonly realtime?: RealtimeModule;
   private readonly options: SyncOptions;
+  private catchUpState = idleCatchUpState;
+  private catchUpEpoch = 0;
+  private disposed = false;
+  private catchUpRun?: {
+    trailing: boolean;
+    attempt: number;
+    promise: Promise<SyncCatchUpState>;
+  };
 
   constructor(db: DbModule, realtime?: RealtimeModule, options: SyncOptions = {}) {
     this.db = db;
@@ -157,7 +174,9 @@ export class SyncModule {
     const realtimeOptions: SyncOptions = {
       ...this.options,
       onResetCache: () => this.resetCache(),
-      onBackfillAll: () => this.backfill({ scope: BackfillScope.All }),
+      onBackfillAll: () => {
+        void this.catchUp();
+      },
       // Realtime reconciliation mutates cache/membership outside the public
       // mutate/backfill entry points — bridge those changes to store listeners.
       onStoreChange: () => this.emit(),
@@ -192,7 +211,9 @@ export class SyncModule {
    * Stores cleanup functions returned by each subscription.
    */
   private setupWindowEvents() {
-    this.cleanupFocus = onAppFocus(() => this.backfill({ scope: BackfillScope.All }));
+    this.cleanupFocus = onAppFocus(() => {
+      void this.catchUp();
+    });
     // Journal replay on foreground: React Native never fires `online`
     // (AppState is its only lifecycle signal), and on web this recovers
     // server-restart cases where connectivity never flipped. Guarded so it
@@ -200,14 +221,15 @@ export class SyncModule {
     this.cleanupFocusReplay = onAppFocus(() => {
       if (this.mutationJournal.listPending().length > 0) void this.replayPending();
     });
-    this.cleanupOnlineBackfill = onOnline(() => this.backfill({ scope: BackfillScope.All }));
+    this.cleanupOnlineBackfill = onOnline(() => {
+      void this.catchUp();
+    });
     this.cleanupOnlineReplay = onOnline(() => this.replayPending());
 
     if (this.options.cdcInterval && this.options.cdcInterval > 0) {
-      this.cdcIntervalHandle = setInterval(
-        () => this.backfill({ scope: BackfillScope.All }),
-        this.options.cdcInterval,
-      );
+      this.cdcIntervalHandle = setInterval(() => {
+        void this.catchUp();
+      }, this.options.cdcInterval);
     }
   }
 
@@ -221,6 +243,9 @@ export class SyncModule {
    * the subscription is marked stale until the next successful backfill.
    */
   async subscribe<Data extends FrappeDocData>(query: SubscriptionQuery) {
+    if (this.options.catchUpStrategy === "snapshot" && query.progressive) {
+      throw new Error("Snapshot catch-up does not support progressive subscriptions");
+    }
     // Wait for any persisted snapshot restore so a matching restored
     // subscription can be adopted instead of racing the async load.
     await this.persistenceManager.whenReady();
@@ -261,12 +286,83 @@ export class SyncModule {
     this.emit();
   }
 
+  /** Refresh active query snapshots in place. Failures retain the last committed data. */
+  async refreshSubscriptions(
+    options?: SubscriptionRefreshOptions,
+  ): Promise<SubscriptionRefreshResult[]> {
+    const epoch = this.catchUpEpoch;
+    await this.persistenceManager.whenReady();
+    if (this.disposed || epoch !== this.catchUpEpoch) return [];
+    const results = await this.subscriptionManager.refreshSubscriptions(options);
+    if (!this.disposed && epoch === this.catchUpEpoch) this.emit();
+    return results;
+  }
+
+  getCatchUpState(): SyncCatchUpState {
+    return this.catchUpState;
+  }
+
+  private publishCatchUp(state: SyncCatchUpState) {
+    this.catchUpState = Object.freeze(state);
+    for (const listener of this.storeListeners) listener();
+  }
+
+  /** Observes lifecycle/retry failures in state; explicit backfill still rejects. */
+  catchUp(): Promise<SyncCatchUpState> {
+    if (this.disposed) return Promise.resolve(this.catchUpState);
+    if (this.catchUpRun) {
+      if (this.catchUpRun.attempt === 0) this.catchUpRun.trailing = true;
+      return this.catchUpRun.promise;
+    }
+    const epoch = this.catchUpEpoch;
+    const run = { trailing: false, attempt: 0, promise: Promise.resolve(this.catchUpState) };
+    this.catchUpRun = run;
+    run.promise = Promise.resolve().then(async () => {
+      let error: unknown = null;
+      const active = () => !this.disposed && this.catchUpEpoch === epoch;
+      do {
+        if (!active()) return this.catchUpState;
+        run.trailing = false;
+        error = null;
+        try {
+          if (this.options.catchUpStrategy === "snapshot") {
+            const results = await this.refreshSubscriptions();
+            const failures = results.filter(
+              (result) =>
+                !result.ok &&
+                this.subscriptionManager.getSubscription(result.subscriptionId) &&
+                !this.subscriptionManager.isRestoredSubscription(result.subscriptionId),
+            );
+            if (failures.length)
+              error = new AggregateError(
+                failures.map((failure) => failure.error),
+                "Some subscriptions could not refresh. Showing previous data.",
+              );
+          } else {
+            await this.backfill({ scope: BackfillScope.All });
+          }
+        } catch (caught) {
+          error = caught;
+        }
+        // Bound a burst to one trailing read, including triggers during that read.
+      } while (active() && run.trailing && run.attempt++ === 0);
+      if (active()) {
+        this.catchUpRun = undefined;
+        this.publishCatchUp({ refreshing: false, stale: error !== null, error });
+      }
+      return this.catchUpState;
+    });
+    this.publishCatchUp({ ...this.catchUpState, refreshing: true });
+    return run.promise;
+  }
+
   /**
    * Reconciles local state by fetching changes since stored cursors.
    */
   async backfill(args: BackfillArgs) {
+    const epoch = this.catchUpEpoch;
     await this.subscriptionManager.backfill(args);
-    this.emit();
+    if (!this.disposed && epoch === this.catchUpEpoch) this.emit();
   }
 
   /**
@@ -438,6 +534,9 @@ export class SyncModule {
 
   /** Clears subscriptions, cache, journal, and temp id mappings. */
   resetCache() {
+    this.catchUpEpoch++;
+    this.catchUpRun = undefined;
+    this.catchUpState = idleCatchUpState;
     // Leave all realtime doctype rooms alongside dropping the subscriptions
     this.realtimeHandler.unwatchAll();
     // Drop all live subs, in-memory cache, journal, and temp mappings
@@ -451,6 +550,7 @@ export class SyncModule {
 
   /** Cleanup and dispose of resources */
   async dispose() {
+    this.disposed = true;
     // Clear all listeners
     this.storeListeners.clear();
     this.realtimeEventListeners.clear();

package/src/sync/refreshSubscriptions.lifecycle.spec.ts

@@ -0,0 +1,268 @@
+import { describe, expect, it, vi } from "vitest";
+import { NormalizedCache } from "./normalizedCache";
+import { SubscriptionManager } from "./subscriptionManager";
+import type { SyncOptions } from "./types";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((yes, no) => {
+    resolve = yes;
+    reject = no;
+  });
+  return { promise, resolve, reject };
+}
+const row = (name: string, title = name) => ({
+  name,
+  title,
+  doctype: "Item",
+  modified: "2026-09-09T01:00:00Z",
+});
+const query = { doctype: "Item" };
+async function setup(options: SyncOptions = {}) {
+  const db = { getDocList: vi.fn().mockResolvedValue([row("a")]) };
+  const cache = new NormalizedCache();
+  const manager = new SubscriptionManager(db as never, cache, options);
+  const { subscriptionId: id } = await manager.subscribe(query);
+  return { db, cache, manager, id };
+}
+function pending(db: Awaited<ReturnType<typeof setup>>["db"]) {
+  const response = deferred<ReturnType<typeof row>[]>();
+  const started = deferred<void>();
+  db.getDocList.mockImplementationOnce(() => {
+    started.resolve();
+    return response.promise;
+  });
+  return { ...response, started: started.promise };
+}
+
+describe("snapshot refresh lifecycle", () => {
+  it.each(["resolve", "reject"] as const)(
+    "invalidates pre-detach refresh that later %ss after re-adoption",
+    async (outcome) => {
+      const { manager, db, cache, id } = await setup({ persistKey: "lifecycle" });
+      const old = pending(db);
+      const oldResult = manager.refreshSubscriptions();
+      await old.started;
+      manager.unsubscribe(id);
+      const fresh = pending(db);
+      const adopted = await manager.subscribe(query);
+      expect(adopted.subscriptionId).toBe(id);
+      expect(adopted.rows).toEqual([row("a")]);
+      await fresh.started;
+      fresh.resolve([row("a", "new-adoption")]);
+      expect(await adopted.refresh).toMatchObject({ ok: true });
+      if (outcome === "resolve") old.resolve([row("a", "obsolete-before-detach"), row("obsolete")]);
+      else old.reject(new Error("old failure"));
+      expect((await oldResult)[0].ok).toBe(false);
+      expect(manager.getDocsForSubscription(id)).toEqual([row("a", "new-adoption")]);
+      expect(cache.get({ doctype: "Item", name: "obsolete" })).toBeUndefined();
+      expect(manager.getSubscription(id)?.stale).toBe(false);
+    },
+  );
+
+  it("does not let an old finally erase the new adoption operation", async () => {
+    const { manager, db, cache, id } = await setup({ persistKey: "lifecycle" });
+    const old = pending(db);
+    const oldResult = manager.refreshSubscriptions();
+    await old.started;
+    manager.unsubscribe(id);
+    const adoption = pending(db);
+    const adopted = await manager.subscribe(query);
+    await adoption.started;
+    old.resolve([row("obsolete")]);
+    expect((await oldResult)[0].ok).toBe(false);
+    const trailing = pending(db);
+    const explicit = manager.refreshSubscriptions();
+    expect(db.getDocList).toHaveBeenCalledTimes(3);
+    adoption.resolve([row("discarded-adoption")]);
+    await trailing.started;
+    expect(cache.get({ doctype: "Item", name: "discarded-adoption" })).toBeUndefined();
+    expect(manager.getDocsForSubscription(id)).toEqual([row("a")]);
+    trailing.resolve([row("final")]);
+    expect(await adopted.refresh).toEqual((await explicit)[0]);
+    expect(manager.getDocsForSubscription(id)).toEqual([row("final")]);
+    expect(db.getDocList).toHaveBeenCalledTimes(4);
+  });
+
+  it.each([false, true])(
+    "coalesces requests and retains the committed snapshot when trailing fails=%s",
+    async (fails) => {
+      const { manager, db, cache, id } = await setup();
+      const before = structuredClone(manager.getSubscription(id));
+      const first = pending(db);
+      const one = manager.refreshSubscriptions();
+      await first.started;
+      const last = pending(db);
+      const two = manager.refreshSubscriptions();
+      const three = manager.refreshSubscriptions();
+      first.resolve([row("a", "discarded"), row("obsolete")]);
+      await last.started;
+      expect(cache.get({ doctype: "Item", name: "obsolete" })).toBeUndefined();
+      expect(manager.getDocsForSubscription(id)).toEqual([row("a")]);
+      const error = new Error("trailing failed");
+      if (fails) last.reject(error);
+      else last.resolve([row("final")]);
+      const results = await Promise.all([one, two, three]);
+      expect(results).toEqual(
+        Array(3).fill([{ subscriptionId: id, ok: !fails, ...(fails ? { error } : {}) }]),
+      );
+      if (fails) for (const result of results) expect(result[0].error).toBe(error);
+      expect(db.getDocList).toHaveBeenCalledTimes(3);
+      if (fails) expect(manager.getSubscription(id)).toEqual({ ...before, stale: true });
+      else expect(manager.getDocsForSubscription(id)).toEqual([row("final")]);
+      await manager.refreshSubscriptions();
+      expect(db.getDocList).toHaveBeenCalledTimes(4);
+    },
+  );
+
+  it("trails a failed attempt only when another caller requested it", async () => {
+    const { manager, db, id } = await setup();
+    const first = pending(db);
+    const one = manager.refreshSubscriptions();
+    await first.started;
+    const last = pending(db);
+    const two = manager.refreshSubscriptions();
+    first.reject(new Error("superseded failure"));
+    await last.started;
+    last.resolve([row("final")]);
+    expect(await one).toEqual(await two);
+    expect(manager.getDocsForSubscription(id)).toEqual([row("final")]);
+    expect(db.getDocList).toHaveBeenCalledTimes(3);
+  });
+
+  it("joins an adoption already fetching and discards its superseded rows", async () => {
+    const { manager, db, cache, id } = await setup({ persistKey: "lifecycle" });
+    manager.unsubscribe(id);
+    const adoption = pending(db);
+    const adopted = await manager.subscribe(query);
+    await adoption.started;
+    const last = pending(db);
+    const explicit = manager.refreshSubscriptions();
+    adoption.resolve([row("obsolete")]);
+    await last.started;
+    expect(cache.get({ doctype: "Item", name: "obsolete" })).toBeUndefined();
+    last.resolve([row("final")]);
+    expect(await adopted.refresh).toEqual((await explicit)[0]);
+    expect(manager.getDocsForSubscription(id)).toEqual([row("final")]);
+  });
+
+  it("invalidates the last release without corrupting cached documents", async () => {
+    const { manager, db, cache, id } = await setup();
+    const read = pending(db);
+    const result = manager.refreshSubscriptions();
+    await read.started;
+    manager.unsubscribe(id);
+    read.resolve([row("a", "obsolete"), row("new")]);
+    expect((await result)[0].ok).toBe(false);
+    expect(manager.getSubscription(id)).toBeUndefined();
+    expect(cache.get({ doctype: "Item", name: "a" })).toEqual(row("a"));
+    expect(cache.get({ doctype: "Item", name: "new" })).toBeUndefined();
+  });
+
+  it("keeps shared refreshes active until the last consumer releases", async () => {
+    const { manager, db, id } = await setup();
+    expect((await manager.subscribe(query)).subscriptionId).toBe(id);
+    const first = pending(db);
+    const one = manager.refreshSubscriptions();
+    await first.started;
+    manager.unsubscribe(id);
+    first.resolve([row("updated")]);
+    expect(await one).toEqual([{ subscriptionId: id, ok: true }]);
+    const last = pending(db);
+    const two = manager.refreshSubscriptions();
+    await last.started;
+    manager.unsubscribe(id);
+    last.resolve([row("obsolete")]);
+    expect((await two)[0].ok).toBe(false);
+    expect(manager.getSubscription(id)).toBeUndefined();
+  });
+
+  it("invalidates clear and allows a subsequent activation", async () => {
+    const { manager, db, cache, id } = await setup();
+    const old = pending(db);
+    const result = manager.refreshSubscriptions();
+    await old.started;
+    manager.clear();
+    cache.clear();
+    const fresh = await manager.subscribe(query);
+    old.resolve([row("a", "obsolete"), row("obsolete")]);
+    expect((await result)[0].ok).toBe(false);
+    expect(manager.getSubscription(id)).toBeUndefined();
+    expect(manager.getDocsForSubscription(fresh.subscriptionId)).toEqual([row("a")]);
+    expect(cache.get({ doctype: "Item", name: "obsolete" })).toBeUndefined();
+  });
+
+  it("does not seed in the microtask between HTTP completion and acceptance", async () => {
+    const { manager, db, cache, id } = await setup();
+    const first = pending(db);
+    const one = manager.refreshSubscriptions();
+    await first.started;
+    const last = pending(db);
+    first.resolve([row("obsolete")]);
+    const two = Promise.resolve().then(() => manager.refreshSubscriptions());
+    await last.started;
+    expect(cache.get({ doctype: "Item", name: "obsolete" })).toBeUndefined();
+    expect(manager.getDocsForSubscription(id)).toEqual([row("a")]);
+    last.resolve([row("final")]);
+    expect(await one).toEqual(await two);
+  });
+
+  it("allows different subscriptions to finish independently", async () => {
+    const { manager, db, id } = await setup();
+    const second = await manager.subscribe({ doctype: "Other" });
+    const slow = pending(db);
+    const fast = pending(db);
+    const result = manager.refreshSubscriptions();
+    await Promise.all([slow.started, fast.started]);
+    fast.resolve([row("fast")]);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(manager.getSubscription(second.subscriptionId)?.docIds).toEqual(["fast"]);
+    expect(manager.getSubscription(id)?.docIds).toEqual(["a"]);
+    slow.resolve([row("slow")]);
+    expect((await result).every((entry) => entry.ok)).toBe(true);
+  });
+});
+
+it("excludes dormant restored subscriptions and selects each shared id once", async () => {
+  const { manager, db, id } = await setup();
+  await manager.subscribe(query);
+  manager.restoreSubscription({ id: "dormant", query: { doctype: "Dormant" }, docIds: ["cached"] });
+  expect(await manager.refreshSubscriptions({ doctypes: ["Dormant"] })).toEqual([]);
+  expect(await manager.refreshSubscriptions({ doctypes: [] })).toEqual([]);
+  expect(db.getDocList).toHaveBeenCalledTimes(1);
+  expect(await manager.refreshSubscriptions()).toEqual([{ subscriptionId: id, ok: true }]);
+  expect(db.getDocList).toHaveBeenCalledTimes(2);
+  manager.unsubscribe(id);
+  manager.unsubscribe(id);
+  expect(manager.getSubscription(id)).toBeUndefined();
+});
+
+it("retains cached projections and documents outside the refreshed membership", async () => {
+  const { manager, db, cache, id } = await setup();
+  cache.upsert({ ...row("a"), detail: "other view" });
+  db.getDocList.mockResolvedValueOnce([row("b")]);
+  const other = await manager.subscribe({ doctype: "Item", filters: { enabled: 1 } });
+  db.getDocList
+    .mockResolvedValueOnce([{ name: "a", title: "projected" }])
+    .mockResolvedValueOnce([]);
+  await manager.refreshSubscriptions();
+  expect(manager.getDocsForSubscription(id)).toEqual([
+    { ...row("a", "projected"), detail: "other view" },
+  ]);
+  expect(manager.getDocsForSubscription(other.subscriptionId)).toEqual([]);
+  expect(cache.get({ doctype: "Item", name: "b" })).toEqual(row("b"));
+});
+
+it("shares the first read when callers arrive before it starts", async () => {
+  const { manager, db, id } = await setup();
+  const first = pending(db);
+  const one = manager.refreshSubscriptions();
+  const two = manager.refreshSubscriptions();
+  await first.started;
+  first.resolve([row("final")]);
+  expect(await one).toEqual(await two);
+  expect(manager.getDocsForSubscription(id)).toEqual([row("final")]);
+  expect(db.getDocList).toHaveBeenCalledTimes(2);
+});