@multiplatform.one/frappe 6.0.0

package/dist/cjs/sync/virtualPageManager.cjs

@@ -0,0 +1,821 @@
+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 virtualPageManager_exports = {};
+__export(virtualPageManager_exports, {
+  PlacementStrategy: () => PlacementStrategy,
+  VirtualPageManager: () => VirtualPageManager,
+  VirtualSubscription: () => VirtualSubscription
+});
+module.exports = __toCommonJS(virtualPageManager_exports);
+var import_types = require("./types.cjs");
+function calculateCheckpointFromDocs(docs) {
+  if (docs.length === 0) return void 0;
+  let maxTimestamp = "";
+  let maxDate = null;
+  for (const doc of docs) {
+    const modified = doc.modified;
+    if (!modified) continue;
+    try {
+      const date = new Date(modified);
+      if (Number.isNaN(date.getTime())) continue;
+      if (!maxDate || date > maxDate) {
+        maxDate = date;
+        maxTimestamp = modified;
+      }
+    } catch {
+      if (!maxTimestamp || modified > maxTimestamp) {
+        maxTimestamp = modified;
+      }
+    }
+  }
+  return maxTimestamp || void 0;
+}
+var PlacementStrategy = /* @__PURE__ */(PlacementStrategy2 => {
+  PlacementStrategy2["AfterRange"] = "after-range";
+  PlacementStrategy2["BeforeRange"] = "before-range";
+  PlacementStrategy2["Uncertain"] = "uncertain";
+  PlacementStrategy2["WithinRange"] = "within-range";
+  return PlacementStrategy2;
+})(PlacementStrategy || {});
+class VirtualSubscription {
+  progressiveCache;
+  needsRehydration;
+  pendingBackfill;
+  viewWindow;
+  // Subscription interface properties
+  id;
+  query;
+  checkpoint;
+  cursor;
+  docIds;
+  boundaries;
+  lockExpiry;
+  pendingRehydration;
+  metadata;
+  tombstones;
+  constructor(subscription, progressiveCache, viewWindow) {
+    this.id = subscription.id;
+    this.query = subscription.query;
+    this.checkpoint = subscription.checkpoint;
+    this.cursor = subscription.cursor;
+    this.docIds = subscription.docIds;
+    this.boundaries = subscription.boundaries;
+    this.lockExpiry = subscription.lockExpiry;
+    this.pendingRehydration = subscription.pendingRehydration;
+    this.metadata = subscription.metadata;
+    this.tombstones = subscription.tombstones;
+    this.progressiveCache = progressiveCache;
+    this.viewWindow = viewWindow;
+  }
+  /**
+   * Update progressive cache with new data
+   */
+  updateProgressiveCache(options) {
+    if (options.docIds) {
+      this.progressiveCache.docIds = options.docIds;
+    }
+    if (options.nextCursor !== void 0) {
+      this.progressiveCache.nextCursor = options.nextCursor;
+    }
+    if (options.hasMore !== void 0) {
+      this.progressiveCache.hasMore = options.hasMore;
+    }
+    if (options.lastFetchedAt) {
+      this.progressiveCache.lastFetchedAt = options.lastFetchedAt;
+    }
+    if (typeof options.totalCount === "number") {
+      this.progressiveCache.totalCount = options.totalCount;
+    }
+  }
+  /**
+   * Get the progressive cache (read-only access)
+   */
+  getProgressiveCache() {
+    return {
+      ...this.progressiveCache
+    };
+  }
+  /**
+   * Process documents and update caches
+   */
+  processDocuments(docs, normalizedCache, options = {}) {
+    const {
+      calculateCheckpoint = true,
+      updateNormalizedCache = true
+    } = options;
+    this.updateProgressiveCache({
+      docIds: docs.map(doc => doc.name),
+      nextCursor: docs.length > 0 ? docs[docs.length - 1].name : void 0,
+      lastFetchedAt: /* @__PURE__ */new Date()
+    });
+    if (updateNormalizedCache) {
+      for (const doc of docs) {
+        normalizedCache.upsert(doc);
+      }
+    }
+    if (calculateCheckpoint) {
+      this.checkpoint = calculateCheckpointFromDocs(docs);
+    }
+  }
+  /**
+   * Remove documents from progressive cache
+   */
+  removeDocuments(docIds, normalizedCache) {
+    for (const docId of docIds) {
+      const index = this.progressiveCache.docIds.indexOf(docId);
+      if (index !== -1) {
+        this.progressiveCache.docIds.splice(index, 1);
+      }
+    }
+    for (const docId of docIds) {
+      normalizedCache.remove({
+        doctype: this.query.doctype,
+        name: docId
+      });
+    }
+  }
+}
+class VirtualPageManager {
+  constructor(normalizedCache, db, options = {}) {
+    this.normalizedCache = normalizedCache;
+    this.db = db;
+    this.batchSize = options.batchSize || 100;
+  }
+  normalizedCache;
+  db;
+  subscriptions = /* @__PURE__ */new Map();
+  pageCache = /* @__PURE__ */new Map();
+  cacheGeneration = 0;
+  batchSize;
+  islands = /* @__PURE__ */new Map();
+  /**
+   * Helper to get the primary sort field from OrderBy
+   */
+  getOrderByField(subscription) {
+    const orderBy = subscription.query.orderBy;
+    if (!orderBy) return void 0;
+    return Array.isArray(orderBy) ? orderBy[0] : orderBy;
+  }
+  /**
+   * Registers a subscription with pre-fetched data, avoiding a duplicate
+   * initial fetch. Used by SubscriptionManager when `progressive: true`.
+   */
+  registerSubscription(subscriptionId, subscription, initialDocIds, cursor, hasMore) {
+    const pageSize = subscription.query.limit || 20;
+    const virtualSub = new VirtualSubscription(subscription, {
+      docIds: [...initialDocIds],
+      nextCursor: cursor ?? (initialDocIds.length > 0 ? initialDocIds[initialDocIds.length - 1] : void 0),
+      hasMore: hasMore ?? initialDocIds.length >= pageSize,
+      totalCount: void 0,
+      lastFetchedAt: /* @__PURE__ */new Date()
+    }, {
+      currentPage: 1,
+      pageSize
+    });
+    this.subscriptions.set(subscriptionId, virtualSub);
+    if (initialDocIds.length > 0) {
+      this.recordIsland(subscriptionId, {
+        startPage: 1,
+        endPage: Math.ceil(initialDocIds.length / pageSize) || 1,
+        startIndex: 0,
+        endIndex: initialDocIds.length,
+        fetchedVia: "cursor"
+      });
+    }
+    return virtualSub;
+  }
+  async initializeSubscription(subscriptionId, query) {
+    const subscription = new VirtualSubscription({
+      id: subscriptionId,
+      query,
+      docIds: []
+    }, {
+      docIds: [],
+      nextCursor: void 0,
+      hasMore: true,
+      totalCount: void 0
+    }, {
+      currentPage: 1,
+      pageSize: query.limit || 20
+    });
+    this.subscriptions.set(subscriptionId, subscription);
+    await this.fetchInitialBatch(subscription);
+    return subscription;
+  }
+  async getPage(subscriptionId, page) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return [];
+    const pageSize = subscription.viewWindow.pageSize;
+    const start = (page - 1) * pageSize;
+    const end = start + pageSize;
+    const cache = subscription.getProgressiveCache();
+    if (cache.docIds.length >= start) {
+      await this.ensureCached(subscription, end);
+    } else {
+      await this.fetchPageByOffset(subscription, page);
+    }
+    subscription.viewWindow.currentPage = page;
+    const pageDocIds = subscription.getProgressiveCache().docIds.slice(start, end);
+    return this.mapIdsToDocuments(subscription.query.doctype, pageDocIds);
+  }
+  async getNextBatch(subscriptionId, cursorDocId, limit) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return [];
+    let index = subscription.getProgressiveCache().docIds.indexOf(cursorDocId);
+    if (index === -1) {
+      await this.fetchFromCursor(subscription, cursorDocId);
+      index = subscription.getProgressiveCache().docIds.indexOf(cursorDocId);
+      if (index === -1) {
+        return [];
+      }
+    }
+    const start = index + 1;
+    const end = start + limit;
+    await this.ensureCached(subscription, end);
+    const docIds = subscription.getProgressiveCache().docIds.slice(start, end);
+    return this.mapIdsToDocuments(subscription.query.doctype, docIds);
+  }
+  /**
+   * Get page information for UI
+   */
+  getPageInfo(subscriptionId) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) {
+      return {
+        currentPage: 1,
+        knownPages: 0,
+        totalPages: "unknown",
+        hasMore: false,
+        itemsInCache: 0,
+        pageSize: 20
+      };
+    }
+    const knownPages = Math.ceil(subscription.getProgressiveCache().docIds.length / subscription.viewWindow.pageSize);
+    return {
+      currentPage: subscription.viewWindow.currentPage,
+      knownPages,
+      totalPages: subscription.getProgressiveCache().totalCount !== void 0 ? Math.ceil(subscription.getProgressiveCache().totalCount / subscription.viewWindow.pageSize) : "unknown",
+      hasMore: subscription.getProgressiveCache().hasMore,
+      itemsInCache: subscription.getProgressiveCache().docIds.length,
+      pageSize: subscription.viewWindow.pageSize
+    };
+  }
+  /**
+   * Get total page count (expensive - may require server call)
+   */
+  async getTotalPages(subscriptionId) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return "unknown";
+    if (subscription.getProgressiveCache().totalCount === void 0) {
+      if (!subscription.getProgressiveCache().hasMore) {
+        subscription.updateProgressiveCache({
+          totalCount: subscription.getProgressiveCache().docIds.length
+        });
+      } else {
+        try {
+          const count = await this.db.getCount(subscription.query.doctype, subscription.query.filters);
+          subscription.updateProgressiveCache({
+            totalCount: count
+          });
+        } catch {
+          return "unknown";
+        }
+      }
+    }
+    return Math.ceil(subscription.getProgressiveCache().totalCount / subscription.viewWindow.pageSize);
+  }
+  /**
+   * Handle optimistic document placement
+   */
+  determineOptimisticPlacement(subscription, newDoc) {
+    const orderByField = this.getOrderByField(subscription);
+    const sortField = orderByField?.field;
+    if (!sortField || !(sortField in newDoc)) {
+      return {
+        strategy: "uncertain" /* Uncertain */
+      };
+    }
+    const newValue = newDoc[sortField];
+    const docIds = subscription.getProgressiveCache().docIds;
+    if (docIds.length === 0) {
+      return {
+        strategy: "within-range" /* WithinRange */,
+        position: 0
+      };
+    }
+    const firstDoc = this.normalizedCache.get({
+      doctype: subscription.query.doctype,
+      name: docIds[0]
+    });
+    const lastDoc = this.normalizedCache.get({
+      doctype: subscription.query.doctype,
+      name: docIds[docIds.length - 1]
+    });
+    if (!firstDoc || !lastDoc) {
+      return {
+        strategy: "uncertain" /* Uncertain */
+      };
+    }
+    const firstValue = firstDoc[sortField];
+    const lastValue = lastDoc[sortField];
+    const isAscending = orderByField?.order === import_types.Order.Asc;
+    if (isAscending) {
+      if (newValue != null && firstValue != null && newValue < firstValue) {
+        return {
+          strategy: "before-range" /* BeforeRange */
+        };
+      }
+      if (newValue != null && lastValue != null && newValue > lastValue) {
+        return {
+          strategy: "after-range" /* AfterRange */
+        };
+      }
+    } else {
+      if (newValue != null && firstValue != null && newValue > firstValue) {
+        return {
+          strategy: "before-range" /* BeforeRange */
+        };
+      }
+      if (newValue != null && lastValue != null && newValue < lastValue) {
+        return {
+          strategy: "after-range" /* AfterRange */
+        };
+      }
+    }
+    const position = this.binarySearchPosition(subscription, newDoc, sortField);
+    return {
+      strategy: "within-range" /* WithinRange */,
+      position
+    };
+  }
+  /**
+   * Update subscription after remote create
+   */
+  async handleRemoteCreate(subscriptionId, newDoc) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return false;
+    const placement = this.determineOptimisticPlacement(subscription, newDoc);
+    switch (placement.strategy) {
+      case "within-range" /* WithinRange */:
+        if (placement.position !== void 0) {
+          const currentDocIds = subscription.getProgressiveCache().docIds;
+          const newDocIds = [...currentDocIds];
+          newDocIds.splice(placement.position, 0, newDoc.name);
+          subscription.updateProgressiveCache({
+            docIds: newDocIds
+          });
+          return true;
+        }
+        break;
+      case "before-range" /* BeforeRange */:
+        {
+          const currentDocIds = subscription.getProgressiveCache().docIds;
+          const newDocIds = [newDoc.name, ...currentDocIds];
+          if (this.shouldLimitCacheSize(subscription)) {
+            newDocIds.pop();
+          }
+          subscription.updateProgressiveCache({
+            docIds: newDocIds
+          });
+          return true;
+        }
+      case "after-range" /* AfterRange */:
+        if (this.isViewingLastPage(subscription)) {
+          await this.fetchMorePages(subscription, 1);
+        }
+        return false;
+      case "uncertain" /* Uncertain */:
+        subscription.needsRehydration = true;
+        return false;
+    }
+    return false;
+  }
+  /**
+   * Update subscription after remote delete
+   */
+  async handleRemoteDelete(subscriptionId, docName) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return false;
+    const currentDocIds = subscription.getProgressiveCache().docIds;
+    const index = currentDocIds.indexOf(docName);
+    if (index === -1) return false;
+    const newDocIds = [...currentDocIds];
+    newDocIds.splice(index, 1);
+    subscription.updateProgressiveCache({
+      docIds: newDocIds
+    });
+    subscription.pendingBackfill = true;
+    return true;
+  }
+  /**
+   * Update subscription after remote update
+   */
+  async handleRemoteUpdate(subscriptionId, updatedDoc) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return false;
+    const currentIndex = subscription.getProgressiveCache().docIds.indexOf(updatedDoc.name);
+    const orderByField = this.getOrderByField(subscription);
+    const sortField = orderByField?.field;
+    if (!sortField || !(sortField in updatedDoc)) {
+      return currentIndex !== -1;
+    }
+    if (currentIndex === -1) {
+      const placement = this.determineOptimisticPlacement(subscription, updatedDoc);
+      if (placement.strategy === "within-range" /* WithinRange */ && placement.position !== void 0) {
+        const currentDocIds = subscription.getProgressiveCache().docIds;
+        const newDocIds = [...currentDocIds];
+        newDocIds.splice(placement.position, 0, updatedDoc.name);
+        subscription.updateProgressiveCache({
+          docIds: newDocIds
+        });
+        return true;
+      }
+      return false;
+    }
+    const oldDoc = this.normalizedCache.get({
+      doctype: subscription.query.doctype,
+      name: updatedDoc.name
+    });
+    if (oldDoc && oldDoc[sortField] !== updatedDoc[sortField]) {
+      const currentDocIds = subscription.getProgressiveCache().docIds;
+      const newDocIds = [...currentDocIds];
+      newDocIds.splice(currentIndex, 1);
+      const placement = this.determineOptimisticPlacement(subscription, updatedDoc);
+      if (placement.strategy === "within-range" /* WithinRange */ && placement.position !== void 0) {
+        newDocIds.splice(placement.position, 0, updatedDoc.name);
+        subscription.updateProgressiveCache({
+          docIds: newDocIds
+        });
+      } else {
+        subscription.updateProgressiveCache({
+          docIds: newDocIds
+        });
+        subscription.pendingBackfill = true;
+      }
+    }
+    return true;
+  }
+  /**
+   * Invalidate page cache (call after any change)
+   */
+  invalidateCache() {
+    this.cacheGeneration++;
+    this.pageCache.clear();
+  }
+  /**
+   * Get subscription by ID
+   */
+  getSubscription(subscriptionId) {
+    return this.subscriptions.get(subscriptionId);
+  }
+  getPageIslands(subscriptionId) {
+    return this.islands.get(subscriptionId) || [];
+  }
+  /**
+   * Check if a specific index is within a cached island
+   */
+  isIndexCached(subscriptionId, index) {
+    const islands = this.islands.get(subscriptionId) || [];
+    return islands.some(island => index >= island.startIndex && index < island.endIndex);
+  }
+  /**
+   * Find all gaps between cached islands
+   */
+  findGaps(subscriptionId) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return [];
+    const islands = this.islands.get(subscriptionId) || [];
+    if (islands.length === 0) return [];
+    const gaps = [];
+    const pageSize = subscription.viewWindow.pageSize;
+    const sorted = [...islands].sort((a, b) => a.startIndex - b.startIndex);
+    if (sorted[0].startIndex > 0) {
+      gaps.push({
+        startIndex: 0,
+        endIndex: sorted[0].startIndex,
+        startPage: 1,
+        endPage: Math.ceil(sorted[0].startIndex / pageSize)
+      });
+    }
+    for (let i = 0; i < sorted.length - 1; i++) {
+      const currentEnd = sorted[i].endIndex;
+      const nextStart = sorted[i + 1].startIndex;
+      if (nextStart > currentEnd) {
+        gaps.push({
+          startIndex: currentEnd,
+          endIndex: nextStart,
+          startPage: Math.floor(currentEnd / pageSize) + 1,
+          endPage: Math.ceil(nextStart / pageSize)
+        });
+      }
+    }
+    return gaps;
+  }
+  /**
+   * Get the gap that contains a specific index, if any
+   */
+  getGapForIndex(subscriptionId, index) {
+    const gaps = this.findGaps(subscriptionId);
+    return gaps.find(gap => index >= gap.startIndex && index < gap.endIndex) || null;
+  }
+  /**
+   * Clear all islands for a subscription (used during full refresh)
+   */
+  clearIslands(subscriptionId) {
+    this.islands.delete(subscriptionId);
+  }
+  /**
+   * Get coverage statistics for a subscription
+   */
+  getIslandCoverage(subscriptionId) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    const islands = this.islands.get(subscriptionId) || [];
+    if (!subscription || islands.length === 0) {
+      return {
+        totalCached: 0,
+        islandCount: 0,
+        gaps: 0,
+        largestGap: 0
+      };
+    }
+    const gaps = this.findGaps(subscriptionId);
+    const totalCached = islands.reduce((sum, island) => sum + (island.endIndex - island.startIndex), 0);
+    const largestGap = gaps.length > 0 ? Math.max(...gaps.map(g => g.endIndex - g.startIndex)) : 0;
+    return {
+      totalCached,
+      islandCount: islands.length,
+      gaps: gaps.length,
+      largestGap
+    };
+  }
+  /**
+   * Update subscription's progressive cache
+   */
+  updateProgressiveCache(subscriptionId, docIds, nextCursor, hasMore) {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return;
+    const updates = {};
+    if (docIds !== void 0) updates.docIds = docIds;
+    if (nextCursor !== void 0) updates.nextCursor = nextCursor ?? void 0;
+    if (hasMore !== void 0) updates.hasMore = hasMore;
+    if (Object.keys(updates).length > 0) {
+      subscription.updateProgressiveCache(updates);
+    }
+    this.invalidateCache();
+  }
+  // Private helper methods
+  async fetchInitialBatch(subscription) {
+    let fetchedDocs = [];
+    let hasMore = true;
+    let currentCursor;
+    const targetSize = subscription.viewWindow.pageSize;
+    while (fetchedDocs.length < targetSize && hasMore) {
+      const res = await this.db.getDocList(subscription.query.doctype, {
+        fields: subscription.query.fields,
+        filters: subscription.query.filters,
+        orderBy: subscription.query.orderBy,
+        cursor: currentCursor,
+        limit: this.batchSize
+      });
+      if (res.length === 0) {
+        hasMore = false;
+        break;
+      }
+      fetchedDocs = [...fetchedDocs, ...res];
+      currentCursor = res.length > 0 ? res[res.length - 1].name : void 0;
+      hasMore = res.length === this.batchSize;
+    }
+    subscription.processDocuments(fetchedDocs, this.normalizedCache);
+    subscription.updateProgressiveCache({
+      hasMore
+    });
+    const pagesLoaded = Math.ceil(fetchedDocs.length / subscription.viewWindow.pageSize) || 1;
+    this.recordIsland(subscription.id, {
+      startPage: 1,
+      endPage: pagesLoaded,
+      startIndex: 0,
+      endIndex: fetchedDocs.length,
+      fetchedVia: "cursor"
+    });
+  }
+  async fetchMorePages(subscription, pageCount) {
+    const cache = subscription.getProgressiveCache();
+    if (!cache.hasMore) return;
+    const targetDocCount = subscription.viewWindow.pageSize * pageCount;
+    const currentCount = cache.docIds.length;
+    const neededCount = targetDocCount - currentCount;
+    if (neededCount <= 0) return;
+    let fetchedDocs = [];
+    let hasMore = cache.hasMore;
+    let currentCursor = cache.nextCursor;
+    while (fetchedDocs.length < neededCount && hasMore) {
+      const remainingNeeded = neededCount - fetchedDocs.length;
+      const fetchSize = Math.min(this.batchSize, remainingNeeded);
+      const response = await this.db.getDocList(subscription.query.doctype, {
+        fields: subscription.query.fields,
+        filters: subscription.query.filters,
+        orderBy: subscription.query.orderBy,
+        cursor: currentCursor || void 0,
+        limit: fetchSize
+      });
+      if (response.length === 0) {
+        hasMore = false;
+        break;
+      }
+      fetchedDocs = [...fetchedDocs, ...response];
+      currentCursor = response.length > 0 ? response[response.length - 1].name : void 0;
+      hasMore = response.length === fetchSize && fetchedDocs.length < neededCount;
+    }
+    const newDocIds = fetchedDocs.map(doc => doc.name);
+    const currentDocIds = subscription.getProgressiveCache().docIds;
+    const updatedDocIds = [...currentDocIds, ...newDocIds];
+    subscription.updateProgressiveCache({
+      docIds: updatedDocIds,
+      nextCursor: fetchedDocs.length > 0 ? fetchedDocs[fetchedDocs.length - 1].name : void 0,
+      hasMore,
+      lastFetchedAt: /* @__PURE__ */new Date()
+    });
+    for (const doc of fetchedDocs) {
+      this.normalizedCache.upsert(doc);
+    }
+    const startIndex = currentCount;
+    const endIndex = startIndex + fetchedDocs.length;
+    const pageSize = subscription.viewWindow.pageSize;
+    const startPage = Math.floor(startIndex / pageSize) + 1;
+    const endPage = Math.ceil(endIndex / pageSize);
+    this.recordIsland(subscription.id, {
+      startPage,
+      endPage,
+      startIndex,
+      endIndex,
+      fetchedVia: "cursor"
+    });
+  }
+  async fetchPageByOffset(subscription, page) {
+    const pageSize = subscription.viewWindow.pageSize;
+    const limitStart = (page - 1) * pageSize;
+    const response = await this.db.getDocList(subscription.query.doctype, {
+      fields: subscription.query.fields,
+      filters: subscription.query.filters,
+      orderBy: subscription.query.orderBy,
+      limitStart,
+      limit: pageSize
+    });
+    for (const doc of response) {
+      if (!doc.doctype) doc.doctype = subscription.query.doctype;
+      this.normalizedCache.upsert(doc);
+    }
+    const currentDocIds = [...subscription.getProgressiveCache().docIds];
+    while (currentDocIds.length < limitStart) {
+      currentDocIds.push("");
+    }
+    for (let i = 0; i < response.length; i++) {
+      currentDocIds[limitStart + i] = response[i].name;
+    }
+    subscription.updateProgressiveCache({
+      docIds: currentDocIds,
+      nextCursor: response.length > 0 ? response[response.length - 1].name : void 0,
+      hasMore: response.length === pageSize,
+      lastFetchedAt: /* @__PURE__ */new Date()
+    });
+    this.recordIsland(subscription.id, {
+      startPage: page,
+      endPage: page,
+      startIndex: limitStart,
+      endIndex: limitStart + response.length,
+      fetchedVia: "offset"
+    });
+  }
+  async fetchFromCursor(subscription, cursorDocId) {
+    const response = await this.db.getDocList(subscription.query.doctype, {
+      fields: subscription.query.fields,
+      filters: subscription.query.filters,
+      orderBy: subscription.query.orderBy,
+      cursor: cursorDocId,
+      limit: this.batchSize
+    });
+    if (response.length === 0) return;
+    const existingIds = new Set(subscription.getProgressiveCache().docIds);
+    const newDocs = response.filter(doc => !existingIds.has(doc.name));
+    for (const doc of newDocs) {
+      if (!doc.doctype) doc.doctype = subscription.query.doctype;
+      this.normalizedCache.upsert(doc);
+    }
+    const newDocIds = newDocs.map(doc => doc.name);
+    const updatedDocIds = [...subscription.getProgressiveCache().docIds, ...newDocIds];
+    subscription.updateProgressiveCache({
+      docIds: updatedDocIds,
+      nextCursor: response.length > 0 ? response[response.length - 1].name : void 0,
+      hasMore: response.length === this.batchSize,
+      lastFetchedAt: /* @__PURE__ */new Date()
+    });
+  }
+  async ensureCached(subscription, requiredIndex) {
+    let cache = subscription.getProgressiveCache();
+    if (cache.docIds.length >= requiredIndex || !cache.hasMore) return;
+    const pageSize = subscription.viewWindow.pageSize;
+    const pagesNeeded = Math.ceil(requiredIndex / pageSize);
+    await this.fetchMorePages(subscription, pagesNeeded);
+  }
+  recordIsland(subscriptionId, island) {
+    let existing = this.islands.get(subscriptionId) || [];
+    existing.push(island);
+    existing.sort((a, b) => a.startIndex - b.startIndex);
+    const merged = [];
+    for (const current of existing) {
+      if (merged.length === 0) {
+        merged.push({
+          ...current
+        });
+        continue;
+      }
+      const last = merged[merged.length - 1];
+      const indexOverlap = current.startIndex <= last.endIndex + 1;
+      const pageOverlap = current.startPage <= last.endPage + 1;
+      if (indexOverlap || pageOverlap) {
+        last.endIndex = Math.max(last.endIndex, current.endIndex);
+        last.startIndex = Math.min(last.startIndex, current.startIndex);
+        last.endPage = Math.max(last.endPage, current.endPage);
+        last.startPage = Math.min(last.startPage, current.startPage);
+        if (current.fetchedVia === "cursor" && last.fetchedVia === "offset") {
+          last.fetchedVia = "cursor";
+        }
+      } else {
+        merged.push({
+          ...current
+        });
+      }
+    }
+    this.islands.set(subscriptionId, merged);
+  }
+  mapIdsToDocuments(doctype, docIds) {
+    return docIds.filter(id => id !== "").map(id => this.normalizedCache.get({
+      doctype,
+      name: id
+    })).filter(Boolean);
+  }
+  binarySearchPosition(subscription, newDoc, sortField) {
+    const docIds = subscription.getProgressiveCache().docIds;
+    const orderByField = this.getOrderByField(subscription);
+    const isAscending = orderByField?.order === import_types.Order.Asc;
+    let left = 0;
+    let right = docIds.length - 1;
+    while (left <= right) {
+      const mid = Math.floor((left + right) / 2);
+      const midDoc = this.normalizedCache.get({
+        doctype: subscription.query.doctype,
+        name: docIds[mid]
+      });
+      if (!midDoc) {
+        left = mid + 1;
+        continue;
+      }
+      const midValue = midDoc[sortField];
+      const newValue = newDoc[sortField];
+      const comparison = this.compareValues(midValue, newValue, isAscending);
+      if (comparison < 0) {
+        left = mid + 1;
+      } else {
+        right = mid - 1;
+      }
+    }
+    return left;
+  }
+  compareValues(a, b, ascending) {
+    if (a === b) return 0;
+    if (a == null) return ascending ? -1 : 1;
+    if (b == null) return ascending ? 1 : -1;
+    const result = a < b ? -1 : 1;
+    return ascending ? result : -result;
+  }
+  shouldLimitCacheSize(subscription) {
+    const maxItems = Math.max(1e3, subscription.viewWindow.pageSize * 50);
+    return subscription.getProgressiveCache().docIds.length > maxItems;
+  }
+  isViewingLastPage(subscription) {
+    const totalCached = subscription.getProgressiveCache().docIds.length;
+    const pageSize = subscription.viewWindow.pageSize;
+    const lastPage = Math.ceil(totalCached / pageSize);
+    return subscription.viewWindow.currentPage >= lastPage;
+  }
+}