@multiplatform.one/frappe 7.7.6 → 7.10.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.spec.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { FrappeDoc, FrappeDocData } from "../common/types";
 import { SubscriptionManager } from "./subscriptionManager";
-import { BackfillScope } from "./types";
+import { BackfillScope, defaultPageLength } from "./types";
 import { Order } from "./types";
 import type { SubscriptionQuery, SyncOptions } from "./types";
 
@@ -156,7 +156,10 @@ describe("SubscriptionManager", () => {
       });
     });
 
-    it("omits limit from the initial fetch when the query has none", async () => {
+    it("sends the default page length when the query has no limit", async () => {
+      // MPO-238: leaving limit_page_length off let the bench clamp to 20
+      // while fixture mode returned every row, so a no-limit collection read
+      // one count in development and another in production.
       const query: SubscriptionQuery = {
         doctype: "TestDoc",
         fields: ["title"],
@@ -168,6 +171,42 @@ describe("SubscriptionManager", () => {
         fields: ["title", "modified", "name"],
         filters: undefined,
         orderBy: undefined,
+        limit: defaultPageLength,
+      });
+    });
+
+    it("passes limit 0 through as Frappe's every-row page length", async () => {
+      const query: SubscriptionQuery = {
+        doctype: "TestDoc",
+        fields: ["title"],
+        limit: 0,
+      };
+
+      await subscriptionManager.subscribe(query);
+
+      expect(mockDb.getDocList).toHaveBeenCalledWith("TestDoc", {
+        fields: ["title", "modified", "name"],
+        filters: undefined,
+        orderBy: undefined,
+        limit: 0,
+      });
+    });
+
+    it("applies limitStart without an explicit limit", async () => {
+      const query: SubscriptionQuery = {
+        doctype: "TestDoc",
+        fields: ["title"],
+        limitStart: 20,
+      };
+
+      await subscriptionManager.subscribe(query);
+
+      expect(mockDb.getDocList).toHaveBeenCalledWith("TestDoc", {
+        fields: ["title", "modified", "name"],
+        filters: undefined,
+        orderBy: undefined,
+        limit: defaultPageLength,
+        limitStart: 20,
       });
     });
 

package/src/sync/subscriptionManager.ts

@@ -4,7 +4,7 @@ import type { DbModule } from "../db";
 import { BackfillManager } from "./backfill";
 import { extractSingleName, matchesFilters } from "./filters";
 import type { NormalizedCache } from "./normalizedCache";
-import { BackfillScope, Order } from "./types";
+import { BackfillScope, defaultPageLength, Order } from "./types";
 import type {
   BackfillArgs,
   OrderByField,
@@ -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.
    */
@@ -168,16 +262,13 @@ export class SubscriptionManager {
         filters: query.filters,
         orderBy: query.orderBy,
       };
-      // Honor an explicit subscription limit on the INITIAL fetch. Without
-      // this the request carries no limit_page_length and the bench clamps
-      // to its default page length (20) — collections created with
-      // `limit: N` silently truncated to 20 rows (surfaced by the pokemon
-      // moves accordion once rosters grew past 20 junction rows). No
-      // explicit limit keeps the previous no-param behavior.
-      if (query.limit != null) {
-        listOptions.limit = query.limit;
-        if (query.limitStart != null) listOptions.limitStart = query.limitStart;
-      }
+      // Always send a page length on the INITIAL fetch. A request with no
+      // limit_page_length is clamped to 20 rows by the bench while a fixture
+      // provider returns every row, so an absent limit made development and
+      // production disagree with nothing on screen to say so. `limit: 0`
+      // (every row) passes through untouched.
+      listOptions.limit = query.limit ?? defaultPageLength;
+      if (query.limitStart != null) listOptions.limitStart = query.limitStart;
       if (this.options.useCursorPagination) listOptions.cursor = undefined;
       const response = await this.db.getDocList<Data>(query.doctype, listOptions);
 
@@ -189,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) {
@@ -205,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
@@ -228,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,
@@ -346,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;
@@ -756,6 +815,7 @@ export class SubscriptionManager {
   }
 
   clear() {
+    this.refreshes.clear();
     this.subscriptions.clear();
     this.queryKeyToSubId.clear();
     this.subRefCounts.clear();

package/src/sync/types.ts

@@ -13,10 +13,20 @@ export interface OrderByField {
 
 export type OrderBy = OrderByField | OrderByField[];
 
+/**
+ * Page length used when a subscription (and so a collection) carries no
+ * explicit `limit`. Frappe's /api/resource clamps a request with no
+ * `limit_page_length` to 20 rows while a fixture provider slices only when
+ * asked, so both paths send this value explicitly and return the same rows.
+ * `limit: 0` is Frappe's "every row" and means the same in fixture mode.
+ */
+export const defaultPageLength = 20;
+
 export interface SubscriptionQuery {
   doctype: string;
   fields?: readonly string[];
   filters?: Array<[string, string, unknown]> | Record<string, unknown>;
+  /** Rows per page. Absent means {@link defaultPageLength}; `0` means every row. */
   limit?: number;
   limitStart?: number;
   orderBy?: OrderBy;