@multiplatform.one/frappe 6.0.0

package/dist/cjs/sync/filters.spec.native.js

@@ -0,0 +1,173 @@
+"use strict";
+
+var import_vitest = require("vitest");
+var import_filters = require("./filters.native.js");
+(0, import_vitest.describe)("matchesFilters", function () {
+  var testDoc = {
+    name: "TEST-001",
+    doctype: "Task",
+    status: "Open",
+    priority: 5,
+    tags: ["urgent", "customer"],
+    assignee: "john@example.com",
+    created: "2024-01-01",
+    amount: 1e3,
+    description: "Test document for filter testing",
+    parent: "PARENT-001"
+  };
+  (0, import_vitest.describe)("array-style filters", function () {
+    (0, import_vitest.it)("should handle equals operator", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "=", "Open"]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "=", "Closed"]])).toBe(false);
+    });
+    (0, import_vitest.it)("should handle not equals operator", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "!=", "Closed"]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "!=", "Open"]])).toBe(false);
+    });
+    (0, import_vitest.it)("should handle greater than operators", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["priority", ">", 3]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["priority", ">", 5]])).toBe(false);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["priority", ">=", 5]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["priority", ">=", 6]])).toBe(false);
+    });
+    (0, import_vitest.it)("should handle less than operators", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["priority", "<", 10]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["priority", "<", 5]])).toBe(false);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["priority", "<=", 5]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["priority", "<=", 4]])).toBe(false);
+    });
+    (0, import_vitest.it)("should handle 'in' operator", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "in", ["Open", "Closed"]]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "in", ["Closed", "Cancelled"]]])).toBe(false);
+    });
+    (0, import_vitest.it)("should handle 'not in' operator", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "not in", ["Closed", "Cancelled"]]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "not in", ["Open", "Closed"]]])).toBe(false);
+    });
+    (0, import_vitest.it)("should handle 'like' operator", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["assignee", "like", "%john%"]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["assignee", "like", "%jane%"]])).toBe(false);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["description", "like", "%filter%"]])).toBe(true);
+    });
+    (0, import_vitest.it)("should handle 'not like' operator", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["assignee", "not like", "%jane%"]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["assignee", "not like", "%john%"]])).toBe(false);
+    });
+    (0, import_vitest.it)("should handle 'between' operator", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["priority", "between", [1, 10]]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["priority", "between", [6, 10]]])).toBe(false);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["amount", "between", [500, 1500]]])).toBe(true);
+    });
+    (0, import_vitest.it)("should handle multiple filters (AND logic)", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "=", "Open"], ["priority", ">", 3]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "=", "Open"], ["priority", ">", 10]])).toBe(false);
+    });
+    (0, import_vitest.it)("should handle FilterOperator enum values", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", import_filters.FilterOperator.Equals, "Open"]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["priority", import_filters.FilterOperator.GreaterThan, 3]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["assignee", import_filters.FilterOperator.Like, "%john%"]])).toBe(true);
+    });
+    (0, import_vitest.it)("should handle 'is' operator for null/not null", function () {
+      var docWithNull = {
+        ...testDoc,
+        nullField: null,
+        notNullField: "value"
+      };
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(docWithNull, [["nullField", "is", null]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(docWithNull, [["notNullField", "is", null]])).toBe(false);
+    });
+    (0, import_vitest.it)("should handle 'ancestors of' operator", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["parent", "ancestors of", "PARENT-001"]])).toBe(false);
+    });
+    (0, import_vitest.it)("should return false for unsupported operators", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "unknown-operator", "Open"]])).toBe(false);
+    });
+  });
+  (0, import_vitest.describe)("object-style filters", function () {
+    (0, import_vitest.it)("should handle simple equality filters", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, {
+        status: "Open"
+      })).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, {
+        status: "Closed"
+      })).toBe(false);
+    });
+    (0, import_vitest.it)("should handle multiple fields (AND logic)", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, {
+        status: "Open",
+        priority: 5
+      })).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, {
+        status: "Open",
+        priority: 10
+      })).toBe(false);
+    });
+  });
+  (0, import_vitest.describe)("edge cases", function () {
+    (0, import_vitest.it)("should handle empty filters", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, {})).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, null)).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, void 0)).toBe(true);
+    });
+    (0, import_vitest.it)("should handle missing fields in document", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["nonExistentField", "=", "value"]])).toBe(false);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["nonExistentField", "!=", "value"]])).toBe(true);
+    });
+    (0, import_vitest.it)("should handle array fields in documents", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["tags", "in", ["urgent"]]])).toBe(false);
+      var docWithArrayCheck = {
+        ...testDoc,
+        singleTag: "urgent"
+      };
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(docWithArrayCheck, [["singleTag", "in", ["urgent", "low"]]])).toBe(true);
+    });
+    (0, import_vitest.it)("should handle case sensitivity", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "LIKE", "%Open%"]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["priority", "BETWEEN", [1, 10]]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "=", "open"]])).toBe(false);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["status", "=", "Open"]])).toBe(true);
+    });
+    (0, import_vitest.it)("should handle type coercion in comparisons", function () {
+      var docWithStringNumber = {
+        ...testDoc,
+        stringPriority: "5"
+      };
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(docWithStringNumber, [["stringPriority", ">", 3]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(docWithStringNumber, [["stringPriority", "<", 10]])).toBe(true);
+    });
+    (0, import_vitest.it)("should handle date comparisons", function () {
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["created", "=", "2024-01-01"]])).toBe(true);
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(testDoc, [["created", "!=", "2024-01-02"]])).toBe(true);
+    });
+    (0, import_vitest.it)("should handle complex nested documents", function () {
+      var nestedDoc = {
+        name: "NESTED-001",
+        doctype: "NestedDoc",
+        data: {
+          level1: {
+            level2: {
+              value: "deep-value"
+            }
+          }
+        }
+      };
+      (0, import_vitest.expect)((0, import_filters.matchesFilters)(nestedDoc, [["data.level1.level2.value", "=", "deep-value"]])).toBe(false);
+    });
+  });
+  (0, import_vitest.describe)("performance considerations", function () {
+    (0, import_vitest.it)("should handle large filter arrays efficiently", function () {
+      var largeFilterArray = Array.from({
+        length: 100
+      }, function (_, i) {
+        return ["status", "!=", `status-${i}`];
+      });
+      var start = Date.now();
+      var result = (0, import_filters.matchesFilters)(testDoc, largeFilterArray);
+      var duration = Date.now() - start;
+      (0, import_vitest.expect)(result).toBe(true);
+      (0, import_vitest.expect)(duration).toBeLessThan(100);
+    });
+  });
+});
+//# sourceMappingURL=filters.spec.native.js.map

package/dist/cjs/sync/filters.spec.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["import_vitest","require","import_filters","describe","testDoc","name","doctype","status","priority","tags","assignee","created","amount","description","parent","it","expect","matchesFilters","toBe"],"sources":["../../../src/sync/filters.spec.ts"],"sourcesContent":[null],"mappings":"AAAA;;AACA,IAAAA,aAAA,GAAAC,OAA+C;AAAA,IAE/CC,cAAA,GAAAD,OAAS;AACP,IAAAD,aAAM,CAAUG,QAAA;EAAA,IACdC,OAAM;IACNC,IAAA,YAAS;IACTC,OAAA,EAAQ;IACRC,MAAA,QAAU;IACVC,QAAO;IACPC,IAAA,GACA,QAAS,EACT,UAAQ,CACR;IACAC,QAAQ;IACVC,OAAA;IAEAC,MAAA;IACEC,WAAA,oCAAG;IACDC,MAAA;EACA;EAAuE,EACzE,EAACd,aAAA,CAAAG,QAAA;IAED,IAAAH,aAAA,CAAAe,EAAA,EAAG,6CAA2C;MAC5C,IAAAf,aAAA,CAAAgB,MAAA,MAAOd,cAAA,CAAAe,cAAA,EAAeb,OAAA,EAAS,CAC/B,CACD,UAED,KACE,OACA,CACA,GAAAc,IAAA;MACA,IAAAlB,aAAA,CAAAgB,MAAA,MAAOd,cAAA,CAAAe,cAAA,EAAeb,OAAA,EAAS,CAChC,CAED,UACE,KACA,SACA,CACA,GAAAc,IAAA;IACF,CAAC;IAED,IAAAlB,aAAA,CAAAe,EAAA,EAAG,mCAA+B,EAAM;MACtC,IAAAf,aAAA,CAAAgB,MAAA,MAAOd,cAAA,CAAAe,cAAA,EAAeb,OAAA,EAAS,CAC/B,CACD,UAED,MACE,SACA,CACD,GAAAc,IAAA;MAED,IAAAlB,aAAA,CAAAgB,MAAG,MAAAd,cAAA,CAAAe,cAAuC,EAAAb,OAAA,GACxC,CACA,UACA,MACD,OAED,CACE,GAAAc,IAAA;IACA;IACF,CAAC,GAAAlB,aAAA,CAAAe,EAAA;MAED,IAAAf,aAAA,CAAAgB,MAAG,MAAAd,cAAA,CAAAe,cAAoC,EAAAb,OAAM,GAC3C,CACA,YACA,KACD,EAED,CACE,GAAAc,IAAA;MAAA,IAAAlB,aACE,CAAAgB,MAAA,MAAAd,cAAe,CAAAe,cAAS,EAAAb,OAAA,IAEtB,UAAC,EACF,KACD,EAEF,IAAAc,IACE;MAAwB,IACtBlB,aAAW,CAAAgB,MAAK,EAAM,IAAAd,cAAA,CAAAe,cAAA,EAAAb,OAAA,IAEvB,YACD,IAAK,EACR,EAED,CACE,GAAAc,IAAA;MACA,IAAAlB,aAAA,CAAAgB,MAAA,MAAOd,cAAA,CAAAe,cAAA,EAAeb,OAAA,EAAS,CAC/B,CACD,YAED,MACE,EACE,CAAG,CACH,EAAAc,IAAA,MAAW;IAAA;IACG,EAChB,EAAAlB,aAAA,CAAAe,EAAA;MAIA,IAAAf,aAAA,CAAAgB,MAAA,MAAOd,cAAA,CAAAe,cAAA,EAAeb,OAAA,GACtB,CACD,YAED,KAGE,GACD,CAED,GAAAc,IAAA;MACE,IAAAlB,aAAA,CAAAgB,MAAA,MAAOd,cAAA,CAAAe,cAAA,EAAeb,OAAA,EAAS,CAChC,CACF,YAED,KACE,EACE,CACA,GAAAc,IAAA;MACD,IAAAlB,aAAA,CAAAgB,MAAA,MAAAd,cAAA,CAAAe,cAAA,EAAAb,OAAA,GAED,CACE,gBACE,EACE,EAAQ,CACE,CACZ,CAAC,CAAAc,IAAA;MACH,EAAE,EAAAlB,aAAS,CAAAgB,MAAA,MAAAd,cAAA,CAAAe,cAAA,EAAAb,OAAA,GAEX,WACE,EACE,MACA,EACD,CACH,CAAE,EAAAc,IAAK,MAAK;IACd,CAAC;IACF,IAAAlB,aAAA,CAAAe,EAAA;MAED,IAAAf,aAAA,CAAAgB,MAAS,MAAAd,cAAoB,CAAAe,cAAA,EAAAb,OAAA,GAC3B,CACE,UACA,MACA,CACA,QACD,SAED,CACE,CACA,GAAAc,IAAA;MACD,IAAAlB,aAAA,CAAAgB,MAAA,MAAAd,cAAA,CAAAe,cAAA,EAAAb,OAAA,GAED,CACE,UAGA,IAAM,EACN,CACE,UACF,YACD,CAED,CAEE,GAAAc,IAAA;IACA;IAGA,IAAAlB,aAAA,CAAAe,EAAA,mCAAO,cAAe;MACtB,IAAAf,aAAA,CAAAgB,MAAA,MAAOd,cAAA,CAAAe,cAAA,EAAeb,OAAA,EAAS,CAChC,CAED,UACE,QAAM,EAGN,CACA,UACD,YAED,CAEE,CACA,GAAAc,IAAA;MACD,IAAAlB,aAAA,CAAAgB,MAAA,MAAAd,cAAA,CAAAe,cAAA,EAAAb,OAAA,GAED,CACE,QAAM,EACJ,QAAM,EACN,CACA,MAAM,EACJ,QAAQ,EACE,CACC,GAAAc,IACT;IAAA;IACF,IACFlB,aAAA,CAAAe,EAAA;MACF,IAAAf,aAAA,CAAAgB,MAAA,MAAAd,cAAA,CAAAe,cAAA,EAAAb,OAAA,GAIA,CACE,YACF,QACD,SACF,CAED,GAAAc,IAAA;MACE,IAAAlB,aAAA,CAAAgB,MAAG,MAAAd,cAAA,CAAAe,cAAA,EAAAb,OAAA,EAAiD,CAClD,CACE,YACA,QACA,QAAU,CACX,CAED,GAAAc,IAAM,MAAQ;MACd,IAAAlB,aAAM,CAAAgB,MAAS,MAAAd,cAAA,CAAAe,cAAwB,EAAAb,OAAA,GACvC,CAEA,eACA,QACD,WACF,CACF,GAAAc,IAAA","ignoreList":[]}

package/dist/cjs/sync/index.cjs

@@ -0,0 +1,303 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all) __defProp(target, name, {
+    get: all[name],
+    enumerable: true
+  });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    });
+  }
+  return to;
+};
+var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
+  value: true
+}), mod);
+var sync_exports = {};
+__export(sync_exports, {
+  SyncModule: () => SyncModule
+});
+module.exports = __toCommonJS(sync_exports);
+var import_platform = require("@multiplatform.one/platform");
+var import_mutationEngine = require("./mutationEngine.cjs");
+var import_mutationJournal = require("./mutationJournal.cjs");
+var import_normalizedCache = require("./normalizedCache.cjs");
+var import_persistence = require("./persistence.cjs");
+var import_realtime = require("./realtime.cjs");
+var import_rehydration = require("./rehydration.cjs");
+var import_subscriptionManager = require("./subscriptionManager.cjs");
+var import_types = require("./types.cjs");
+class SyncModule {
+  constructor(db, realtime, options = {}) {
+    this.db = db;
+    this.realtime = realtime;
+    this.options = options;
+    this.normalizedCache = new import_normalizedCache.NormalizedCache({
+      maxSize: this.options.maxCacheSize
+    });
+    this.mutationJournal = new import_mutationJournal.MutationJournal({
+      ttl: this.options.mutationTTL,
+      enableAutoCleanup: true,
+      storage: typeof localStorage !== "undefined" ? localStorage : void 0
+    });
+    this.subscriptionManager = new import_subscriptionManager.SubscriptionManager(this.db, this.normalizedCache, this.options);
+    this.rehydrationManager = new import_rehydration.RehydrationManager(this.db, this.normalizedCache, this.subscriptionManager, this.mutationJournal);
+    this.mutationEngine = new import_mutationEngine.MutationEngine(this.db, this.realtime, this.normalizedCache, this.mutationJournal, this.subscriptionManager, this.rehydrationManager, this.options);
+    const realtimeOptions = {
+      ...this.options,
+      onResetCache: () => this.resetCache(),
+      onBackfillAll: () => this.backfill({
+        scope: import_types.BackfillScope.All
+      })
+    };
+    this.realtimeHandler = new import_realtime.RealtimeHandler(this.db, this.realtime, this.normalizedCache, this.subscriptionManager, this.rehydrationManager, realtimeOptions);
+    this.persistenceManager = new import_persistence.PersistenceManager(this.normalizedCache, this.mutationJournal, this.subscriptionManager, this.mutationEngine, realtimeOptions);
+    this.setupWindowEvents();
+  }
+  db;
+  realtime;
+  options;
+  normalizedCache;
+  mutationJournal;
+  storeListeners = /* @__PURE__ */new Set();
+  subscriptionManager;
+  /** Mutation engine for optimistic updates and conflict resolution. */
+  mutationEngine;
+  /** Realtime event handler for Socket.IO integration. */
+  realtimeHandler;
+  /** Persistence manager for state snapshots. */
+  persistenceManager;
+  /** Rehydration manager for intelligent subscription updates. */
+  rehydrationManager;
+  /** Cleanup functions returned by lifecycle subscriptions. */
+  cleanupFocus;
+  cleanupOnlineBackfill;
+  cleanupOnlineReplay;
+  /** Timer handle for periodic CDC polling. */
+  cdcIntervalHandle;
+  /**
+   * Sets up lifecycle event listeners for sync triggers.
+   * Stores cleanup functions returned by each subscription.
+   */
+  setupWindowEvents() {
+    this.cleanupFocus = (0, import_platform.onAppFocus)(() => this.backfill({
+      scope: import_types.BackfillScope.All
+    }));
+    this.cleanupOnlineBackfill = (0, import_platform.onOnline)(() => this.backfill({
+      scope: import_types.BackfillScope.All
+    }));
+    this.cleanupOnlineReplay = (0, import_platform.onOnline)(() => this.replayPending());
+    if (this.options.cdcInterval && this.options.cdcInterval > 0) {
+      this.cdcIntervalHandle = setInterval(() => this.backfill({
+        scope: import_types.BackfillScope.All
+      }), this.options.cdcInterval);
+    }
+  }
+  /**
+   * Creates a subscription, seeds cache with initial rows, and stores a backfill checkpoint.
+   */
+  async subscribe(query) {
+    const result = await this.subscriptionManager.subscribe(query);
+    this.emit();
+    return result;
+  }
+  /**
+   * Removes a subscription by id.
+   */
+  unsubscribe(subscriptionId) {
+    this.subscriptionManager.unsubscribe(subscriptionId);
+    this.emit();
+  }
+  async mutate(mutation) {
+    await this.mutationEngine.mutate(mutation);
+    this.persistenceManager.broadcastMutation(mutation);
+    this.emit();
+  }
+  /**
+   * Reconciles local state by fetching changes since stored cursors.
+   */
+  async backfill(args) {
+    await this.subscriptionManager.backfill(args);
+    this.emit();
+  }
+  /**
+   * Replays pending mutations with error handling.
+   */
+  async replayPending() {
+    await this.mutationEngine.replayPending();
+    this.emit();
+  }
+  /** Reads a single document from the local cache. */
+  getDocFromCache(doctype, name) {
+    return this.normalizedCache.get({
+      doctype,
+      name
+    });
+  }
+  /** Returns subscription metadata by id. */
+  getSubscription(id) {
+    return this.subscriptionManager.getSubscription(id);
+  }
+  /**
+   * Returns current rows for a subscription from the cache.
+   */
+  getDocsForSubscription(id) {
+    return this.subscriptionManager.getDocsForSubscription(id);
+  }
+  /**
+   * Get a specific page of documents using virtual pagination.
+   * Requires the subscription to have been created with `progressive: true`.
+   */
+  async getPage(subscriptionId, page) {
+    const result = await this.subscriptionManager.getPage(subscriptionId, page);
+    this.emit();
+    return result;
+  }
+  /**
+   * Get the next batch of documents after a cursor for infinite scroll.
+   * Requires the subscription to have been created with `progressive: true`.
+   */
+  async getNextBatch(subscriptionId, cursorDocId, limit) {
+    const result = await this.subscriptionManager.getNextBatch(subscriptionId, cursorDocId, limit);
+    this.emit();
+    return result;
+  }
+  /**
+   * Get page information for a subscription.
+   */
+  getPageInfo(subscriptionId) {
+    return this.subscriptionManager.getPageInfo(subscriptionId);
+  }
+  /** Refetches authoritative copies for specific documents and updates cache. */
+  async refetchDocs(docs) {
+    await this.subscriptionManager.backfill({
+      scope: import_types.BackfillScope.Docs,
+      docs
+    });
+    this.emit();
+  }
+  /** Adds a store listener; returns an unsubscribe function. */
+  subscribeStore(listener) {
+    this.storeListeners.add(listener);
+    return () => {
+      this.storeListeners.delete(listener);
+    };
+  }
+  /** Notifies listeners, schedules persistence, and broadcasts cross-tab changes. */
+  emit() {
+    for (const listener of this.storeListeners) listener();
+    this.persistenceManager.scheduleSave();
+    this.persistenceManager.broadcastChange();
+  }
+  /** Clears subscriptions, cache, journal, and temp id mappings. */
+  resetCache() {
+    this.subscriptionManager.clear();
+    this.normalizedCache.clear();
+    this.mutationJournal.clear();
+    this.mutationEngine.clearTemporaryMappings();
+    this.emit();
+  }
+  /** Cleanup and dispose of resources */
+  async dispose() {
+    this.storeListeners.clear();
+    this.resetCache();
+    this.mutationJournal.dispose();
+    this.mutationEngine.dispose();
+    this.realtimeHandler.dispose();
+    this.persistenceManager.destroy();
+    this.rehydrationManager.clear();
+    this.cleanupFocus?.();
+    this.cleanupOnlineBackfill?.();
+    this.cleanupOnlineReplay?.();
+    this.cleanupFocus = void 0;
+    this.cleanupOnlineBackfill = void 0;
+    this.cleanupOnlineReplay = void 0;
+    if (this.cdcIntervalHandle) {
+      clearInterval(this.cdcIntervalHandle);
+      this.cdcIntervalHandle = void 0;
+    }
+  }
+  /**
+   * Returns a snapshot of internal state for devtools inspection.
+   * Prefixed with __ to signal internal/debug use only.
+   */
+  __debug() {
+    const allSubs = this.subscriptionManager.getAllSubscriptions();
+    const vpm = this.subscriptionManager.getVirtualPageManager();
+    const subscriptions = [];
+    for (const [, sub] of allSubs) {
+      const virtualSub = vpm.getSubscription(sub.id);
+      const pageInfo = vpm.getPageInfo(sub.id);
+      const islands = vpm.getPageIslands(sub.id);
+      const debugSub = {
+        id: sub.id,
+        query: sub.query,
+        docCount: sub.docIds.length,
+        tombstoneCount: sub.tombstones?.size ?? 0,
+        checkpoint: sub.checkpoint,
+        cursor: sub.cursor,
+        pageInfo
+      };
+      if (virtualSub) {
+        const pc = virtualSub.getProgressiveCache();
+        debugSub.progressiveCache = {
+          docIds: pc.docIds,
+          nextCursor: pc.nextCursor,
+          hasMore: pc.hasMore,
+          totalCount: pc.totalCount,
+          lastFetchedAt: pc.lastFetchedAt?.toISOString(),
+          islands
+        };
+      }
+      subscriptions.push(debugSub);
+    }
+    const cacheStats = this.normalizedCache.getStats();
+    const allEntries = this.mutationJournal.getAllEntries();
+    const pending = [];
+    const confirmed = [];
+    const failed = [];
+    for (const {
+      id,
+      entry
+    } of allEntries) {
+      const debugEntry = {
+        id,
+        operation: entry.operation,
+        doctype: entry.doctype,
+        docname: entry.docname,
+        status: entry.status,
+        createdAt: entry.createdAt ?? 0,
+        retryCount: entry.retryCount ?? 0,
+        error: entry.error ? entry.error.message ?? String(entry.error) : void 0
+      };
+      if (entry.status === import_types.Status.Pending) pending.push(debugEntry);else if (entry.status === import_types.Status.Confirmed) confirmed.push(debugEntry);else if (entry.status === import_types.Status.Failed) failed.push(debugEntry);
+    }
+    return {
+      subscriptions,
+      normalizedCache: cacheStats,
+      mutationJournal: {
+        pending,
+        confirmed,
+        failed
+      },
+      connection: {
+        socketConnected: this.realtimeHandler.getIsConnected(),
+        isLeader: this.persistenceManager.getIsLeader(),
+        isOnline: typeof navigator !== "undefined" ? navigator.onLine : true
+      }
+    };
+  }
+  /**
+   * Checks if this tab is the leader for multi-tab coordination.
+   */
+  isLeader() {
+    return this.persistenceManager.getIsLeader();
+  }
+}