@multiplatform.one/frappe 6.0.0

package/dist/cjs/sync/persistence.cjs

@@ -0,0 +1,627 @@
+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 persistence_exports = {};
+__export(persistence_exports, {
+  PersistenceManager: () => PersistenceManager
+});
+module.exports = __toCommonJS(persistence_exports);
+var import_pacer = require("@tanstack/pacer");
+var import_platform = require("@multiplatform.one/platform");
+var import_storage = require("./storage.cjs");
+function getLocalStorage() {
+  try {
+    return typeof globalThis !== "undefined" && "localStorage" in globalThis ? globalThis.localStorage : void 0;
+  } catch {
+    return void 0;
+  }
+}
+class PersistenceManager {
+  constructor(normalizedCache, mutationJournal, subscriptionManager, mutationEngine, options = {}) {
+    this.normalizedCache = normalizedCache;
+    this.mutationJournal = mutationJournal;
+    this.subscriptionManager = subscriptionManager;
+    this.mutationEngine = mutationEngine;
+    this.options = options;
+    this.tabCoordinationConfig = {
+      activeTabPriority: options.tabCoordination?.activeTabPriority ?? true,
+      leaderTimeout: options.tabCoordination?.leaderTimeout ?? 5e3,
+      handoffGracePeriod: options.tabCoordination?.handoffGracePeriod ?? 2e3
+    };
+    if (typeof window === "undefined" || typeof document === "undefined") {
+      return;
+    }
+    this.setupPersistence();
+    this.setupBroadcastChannel();
+    if (this.tabCoordinationConfig.activeTabPriority) {
+      this.setupTabCoordination();
+    }
+  }
+  normalizedCache;
+  mutationJournal;
+  subscriptionManager;
+  mutationEngine;
+  options;
+  persistenceStorage;
+  saveDebouncer = new import_pacer.Debouncer(() => void this.save(), {
+    wait: 50
+  });
+  broadcastChannel;
+  // Active tab priority leadership state
+  isLeader = false;
+  tabId = this.generateTabId();
+  leaderCheckInterval;
+  visibilityState = "visible";
+  lastVisibilityChange = Date.now();
+  pendingOperations = /* @__PURE__ */new Set();
+  acceptingNewWork = true;
+  handoffInProgress = false;
+  tabCoordinationConfig;
+  leaderKey = "frappe-sync-leader";
+  /** Cleanup function returned by the visibility change lifecycle subscription. */
+  cleanupVisibilityChange;
+  /** Active response timers that need cleanup. */
+  activeResponseTimers = /* @__PURE__ */new Set();
+  /** Flag to prevent operations after destroy. */
+  isDestroyed = false;
+  /**
+   * Sets up persistence storage based on environment and options.
+   */
+  setupPersistence() {
+    if (!this.options.persistKey) return;
+    if (this.options.storage) {
+      this.persistenceStorage = this.options.storage;
+    } else if (typeof indexedDB !== "undefined") {
+      this.persistenceStorage = new import_storage.IndexedDBKV();
+    } else {
+      this.persistenceStorage = new import_storage.PlatformStorageKV();
+    }
+    void this.load();
+  }
+  /**
+   * Sets up BroadcastChannel for cross-tab coordination.
+   * Handles both simple string messages and structured TabMessage types.
+   */
+  setupBroadcastChannel() {
+    if (!this.options.persistKey || typeof BroadcastChannel === "undefined") return;
+    try {
+      this.broadcastChannel = new BroadcastChannel(`frappe-sync:${this.options.persistKey}`);
+    } catch {
+      return;
+    }
+    this.broadcastChannel.onmessage = e => {
+      if (typeof e?.data === "string") {
+        if (e.data === "reset" && this.options.onResetCache) {
+          this.options.onResetCache();
+        }
+        if (e.data === "backfill" && this.options.onBackfillAll) {
+          this.options.onBackfillAll();
+        }
+        return;
+      }
+      const message = e?.data;
+      if (!message || !message.type) return;
+      switch (message.type) {
+        case "visibility-check":
+          if (message.fromTab !== this.tabId) {
+            this.broadcastToTabs({
+              type: "visibility-response",
+              tabId: this.tabId,
+              isVisible: this.visibilityState === "visible"
+            });
+          }
+          break;
+        case "leadership-request":
+          if (this.isLeader && message.visibilityState === "visible" && this.visibilityState === "hidden") {
+            this.initiateGracefulHandoff();
+          }
+          break;
+        case "leadership-handoff":
+          if (message.toTab === this.tabId) {
+            if (message.state) {
+              this.restoreStateFromHandoff(message.state);
+            }
+            this.becomeLeader();
+          }
+          break;
+        case "mutation":
+          if (!this.isLeader && message.mutation) {
+            this.handleRemoteMutation(message.mutation);
+          }
+          break;
+        case "sync-state":
+          if (!this.isLeader && message.state) {
+            this.restoreStateFromHandoff(message.state);
+          }
+          break;
+        case "heartbeat":
+          break;
+        case "visibility-response":
+          break;
+      }
+    };
+  }
+  /**
+   * Handles a mutation relayed from another tab.
+   * Updates local cache with the mutation's effects.
+   */
+  handleRemoteMutation(mutation) {
+    if (mutation.doc) {
+      if (mutation.operation === "delete") {
+        this.normalizedCache.remove({
+          doctype: mutation.doc.doctype,
+          name: mutation.doc.name
+        });
+      } else {
+        this.normalizedCache.upsert(mutation.doc);
+      }
+    }
+  }
+  /**
+   * Broadcasts a mutation to other tabs.
+   * Called by SyncModule after a successful mutation.
+   */
+  broadcastMutation(mutation) {
+    if (!this.isLeader) return;
+    this.broadcastToTabs({
+      type: "mutation",
+      mutation
+    });
+  }
+  /**
+   * Restores state received from a leadership handoff or sync-state message.
+   */
+  restoreStateFromHandoff(state) {
+    if (!state || typeof state !== "object") return;
+    const handoffState = state;
+    if (handoffState.cache) {
+      this.normalizedCache.state = handoffState.cache;
+    }
+    if (handoffState.subscriptions && Array.isArray(handoffState.subscriptions)) {
+      const subscriptions = this.subscriptionManager.getAllSubscriptions();
+      for (const subscription of handoffState.subscriptions) {
+        if (subscription?.id) {
+          subscriptions.set(subscription.id, subscription);
+        }
+      }
+    }
+    if (handoffState.tempMappings && Array.isArray(handoffState.tempMappings)) {
+      const tempMap = this.mutationEngine.getTemporaryIdToRealNameMap();
+      for (const [tempId, realId] of handoffState.tempMappings) {
+        tempMap.set(tempId, realId);
+      }
+    }
+  }
+  /**
+   * Schedules a debounced save operation.
+   */
+  scheduleSave() {
+    if (!this.options.persistKey) return;
+    this.saveDebouncer.maybeExecute();
+  }
+  /**
+   * Persists a snapshot of subscriptions, cache, journal, and temp mappings.
+   */
+  async save() {
+    if (!this.options.persistKey || !this.persistenceStorage) return;
+    try {
+      const snapshot = {
+        subs: [...this.subscriptionManager.getAllSubscriptions().values()].map(s => ({
+          id: s.id,
+          query: s.query,
+          checkpoint: s.checkpoint,
+          docIds: s.docIds
+        })),
+        cache: this.normalizedCache.state,
+        journal: this.mutationJournal.listPending(),
+        temp: [...this.mutationEngine.getTemporaryIdToRealNameMap().entries()]
+      };
+      await this.persistenceStorage.setItem(this.options.persistKey, JSON.stringify(snapshot));
+    } catch (err) {
+      console.warn("Failed to save sync state:", err);
+    }
+  }
+  /**
+   * Loads a previously persisted snapshot if present.
+   */
+  async load() {
+    if (!this.options.persistKey || !this.persistenceStorage) return;
+    try {
+      const raw = await this.persistenceStorage.getItem(this.options.persistKey);
+      if (!raw) return;
+      const snap = JSON.parse(raw);
+      if (snap?.cache) {
+        this.normalizedCache.state = snap.cache;
+      }
+      if (snap?.subs) {
+        const subscriptions = this.subscriptionManager.getAllSubscriptions();
+        for (const subscription of snap.subs) {
+          subscriptions.set(subscription.id, subscription);
+        }
+      }
+      if (snap?.journal && Array.isArray(snap.journal)) {
+        for (const {
+          id,
+          entry
+        } of snap.journal) {
+          this.mutationJournal.add(id, entry);
+        }
+      }
+      if (snap?.temp && Array.isArray(snap.temp)) {
+        const tempMap = this.mutationEngine.getTemporaryIdToRealNameMap();
+        for (const [tempId, realId] of snap.temp) {
+          tempMap.set(tempId, realId);
+        }
+      }
+    } catch (err) {
+      console.warn("Failed to load sync state:", err);
+    }
+  }
+  /**
+   * Broadcasts a reset message to other tabs.
+   */
+  broadcastReset() {
+    if (this.broadcastChannel) {
+      this.broadcastChannel.postMessage("reset");
+    }
+  }
+  /**
+   * Broadcasts a backfill message to other tabs.
+   */
+  broadcastBackfill() {
+    if (this.broadcastChannel) {
+      this.broadcastChannel.postMessage("backfill");
+    }
+  }
+  /**
+   * Broadcasts a generic change message to other tabs.
+   */
+  broadcastChange() {
+    if (this.broadcastChannel) {
+      this.broadcastChannel.postMessage("changed");
+    }
+  }
+  /**
+   * Sets up tab coordination with active tab priority.
+   */
+  setupTabCoordination() {
+    this.visibilityState = document.hidden ? "hidden" : "visible";
+    this.cleanupVisibilityChange = (0, import_platform.onVisibilityChange)(visible => {
+      if (this.isDestroyed) return;
+      const wasVisible = this.visibilityState === "visible";
+      this.visibilityState = visible ? "visible" : "hidden";
+      this.lastVisibilityChange = Date.now();
+      if (!wasVisible && this.visibilityState === "visible") {
+        this.evaluateLeadershipPriority();
+      } else if (wasVisible && this.visibilityState === "hidden" && this.isLeader) {
+        this.considerLeadershipHandoff();
+      }
+    });
+    this.tryBecomeLeader();
+  }
+  /**
+   * Attempts to become the leader tab.
+   */
+  tryBecomeLeader() {
+    if (!getLocalStorage() || this.isDestroyed) return;
+    const now = Date.now();
+    const leaderData = this.getLeaderData();
+    if (!leaderData || now - leaderData.timestamp > this.tabCoordinationConfig.leaderTimeout || this.visibilityState === "visible" && leaderData.visibilityState === "hidden") {
+      this.becomeLeader();
+    } else {
+      if (this.leaderCheckInterval) {
+        clearInterval(this.leaderCheckInterval);
+      }
+      this.leaderCheckInterval = setInterval(() => {
+        if (!this.isDestroyed) {
+          this.checkLeadership();
+        }
+      }, this.tabCoordinationConfig.leaderTimeout / 2);
+    }
+  }
+  /**
+   * Becomes the leader tab.
+   */
+  becomeLeader() {
+    if (this.isDestroyed) return;
+    this.isLeader = true;
+    this.updateLeaderTimestamp();
+    this.onBecomeLeader();
+    if (this.leaderCheckInterval) {
+      clearInterval(this.leaderCheckInterval);
+    }
+    this.leaderCheckInterval = setInterval(() => {
+      if (!this.isDestroyed) {
+        this.updateLeaderTimestamp();
+      }
+    }, this.tabCoordinationConfig.leaderTimeout / 2);
+  }
+  /**
+   * Updates leader timestamp in localStorage.
+   */
+  updateLeaderTimestamp() {
+    const ls = getLocalStorage();
+    if (!ls) return;
+    const leaderData = {
+      tabId: this.tabId,
+      timestamp: Date.now(),
+      visibilityState: this.visibilityState,
+      lastVisibilityChange: this.lastVisibilityChange
+    };
+    try {
+      ls.setItem(this.leaderKey, JSON.stringify(leaderData));
+    } catch (error) {
+      console.warn("[PersistenceManager] Failed to update leader timestamp:", error);
+    }
+  }
+  /**
+   * Checks if this tab should remain leader.
+   */
+  checkLeadership() {
+    const leaderData = this.getLeaderData();
+    if (!leaderData) {
+      this.tryBecomeLeader();
+      return;
+    }
+    const now = Date.now();
+    if (this.isLeader) {
+      if (leaderData.tabId !== this.tabId) {
+        this.isLeader = false;
+        this.onLoseLeadership();
+      }
+    } else {
+      if (now - leaderData.timestamp > this.tabCoordinationConfig.leaderTimeout || this.visibilityState === "visible" && leaderData.visibilityState === "hidden" && now - this.lastVisibilityChange > 1e3) {
+        this.tryBecomeLeader();
+      }
+    }
+  }
+  /**
+   * Gets current leader data from localStorage.
+   */
+  getLeaderData() {
+    const ls = getLocalStorage();
+    if (!ls) return null;
+    try {
+      const data = ls.getItem(this.leaderKey);
+      return data ? JSON.parse(data) : null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Evaluates if this tab should take leadership based on visibility priority.
+   */
+  evaluateLeadershipPriority() {
+    if (this.isLeader) return;
+    const leaderData = this.getLeaderData();
+    if (!leaderData) {
+      this.tryBecomeLeader();
+      return;
+    }
+    if (leaderData.visibilityState === "hidden" && this.visibilityState === "visible") {
+      this.requestLeadershipHandoff();
+    }
+  }
+  /**
+   * Considers handing off leadership when tab becomes hidden.
+   */
+  considerLeadershipHandoff() {
+    if (!this.isLeader) return;
+    this.checkForActiveTabs(hasActiveTabs => {
+      if (hasActiveTabs) {
+        this.initiateGracefulHandoff();
+      }
+    });
+  }
+  /**
+   * Requests leadership handoff from current leader.
+   */
+  requestLeadershipHandoff() {
+    this.broadcastToTabs({
+      type: "leadership-request",
+      tabId: this.tabId,
+      visibilityState: this.visibilityState
+    });
+  }
+  /**
+   * Initiates graceful handoff to another tab.
+   */
+  async initiateGracefulHandoff() {
+    if (!this.isLeader || this.handoffInProgress) return;
+    this.handoffInProgress = true;
+    this.acceptingNewWork = false;
+    await this.waitForPendingOperations();
+    const successor = await this.findSuccessor();
+    if (successor) {
+      const state = await this.captureState();
+      this.broadcastToTabs({
+        type: "leadership-handoff",
+        fromTab: this.tabId,
+        toTab: successor,
+        state
+      });
+      this.isLeader = false;
+      this.onLoseLeadership();
+    }
+    this.handoffInProgress = false;
+    this.acceptingNewWork = true;
+  }
+  /**
+   * Waits for all pending operations to complete.
+   */
+  async waitForPendingOperations() {
+    const timeout = new Promise(resolve => setTimeout(resolve, this.tabCoordinationConfig.handoffGracePeriod));
+    const operations = Promise.all(this.pendingOperations);
+    await Promise.race([operations, timeout]);
+  }
+  /**
+   * Finds a suitable successor for leadership.
+   */
+  async findSuccessor() {
+    return new Promise(resolve => {
+      if (this.isDestroyed) {
+        resolve(null);
+        return;
+      }
+      const responses = [];
+      const handleResponse = event => {
+        if (event.data?.type === "visibility-response") {
+          responses.push({
+            tabId: event.data.tabId,
+            isVisible: event.data.isVisible
+          });
+        }
+      };
+      window.addEventListener("message", handleResponse);
+      this.broadcastToTabs({
+        type: "visibility-check",
+        fromTab: this.tabId
+      });
+      const responseTimer = setTimeout(() => {
+        this.activeResponseTimers.delete(responseTimer);
+        window.removeEventListener("message", handleResponse);
+        const visibleTab = responses.find(r => r.isVisible);
+        resolve(visibleTab ? visibleTab.tabId : responses[0]?.tabId || null);
+      }, 500);
+      this.activeResponseTimers.add(responseTimer);
+    });
+  }
+  /**
+   * Checks if there are other active tabs.
+   */
+  checkForActiveTabs(callback) {
+    if (this.isDestroyed) {
+      callback(false);
+      return;
+    }
+    const responses = [];
+    const handleResponse = event => {
+      if (event.data?.type === "visibility-response") {
+        responses.push(event.data.isVisible);
+      }
+    };
+    window.addEventListener("message", handleResponse);
+    this.broadcastToTabs({
+      type: "visibility-check",
+      fromTab: this.tabId
+    });
+    const responseTimer = setTimeout(() => {
+      this.activeResponseTimers.delete(responseTimer);
+      window.removeEventListener("message", handleResponse);
+      callback(responses.some(isVisible => isVisible));
+    }, 500);
+    this.activeResponseTimers.add(responseTimer);
+  }
+  /**
+   * Captures current state for handoff.
+   */
+  async captureState() {
+    return {
+      cache: this.normalizedCache.state,
+      journal: this.mutationJournal.listPending(),
+      subscriptions: [...this.subscriptionManager.getAllSubscriptions().values()],
+      tempMappings: [...this.mutationEngine.getTemporaryIdToRealNameMap().entries()]
+    };
+  }
+  /**
+   * Broadcasts message to other tabs.
+   */
+  broadcastToTabs(message) {
+    if (this.broadcastChannel) {
+      this.broadcastChannel.postMessage(message);
+    }
+    const ls = getLocalStorage();
+    if (ls) {
+      try {
+        const key = `frappe-sync-msg-${Date.now()}`;
+        ls.setItem(key, JSON.stringify(message));
+        setTimeout(() => ls.removeItem(key), 100);
+      } catch {}
+    }
+  }
+  /**
+   * Handles becoming the leader.
+   */
+  onBecomeLeader() {
+    console.debug(`[PersistenceManager] Tab ${this.tabId} became leader`);
+    if (this.options.onBecomeLeader) {
+      this.options.onBecomeLeader();
+    }
+  }
+  /**
+   * Handles losing leadership.
+   */
+  onLoseLeadership() {
+    console.debug(`[PersistenceManager] Tab ${this.tabId} lost leadership`);
+    if (this.leaderCheckInterval) {
+      clearInterval(this.leaderCheckInterval);
+      this.leaderCheckInterval = void 0;
+    }
+    if (this.options.onLoseLeadership) {
+      this.options.onLoseLeadership();
+    }
+  }
+  /**
+   * Generates a unique tab ID.
+   */
+  generateTabId() {
+    return `tab-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+  }
+  /**
+   * Tracks a pending operation.
+   */
+  trackOperation(operation) {
+    this.pendingOperations.add(operation);
+    operation.finally(() => {
+      this.pendingOperations.delete(operation);
+    }).catch(() => {});
+    return operation;
+  }
+  /**
+   * Gets whether this tab is the leader.
+   */
+  getIsLeader() {
+    return this.isLeader;
+  }
+  /**
+   * Cleans up timers, event listeners, and channels.
+   */
+  destroy() {
+    this.isDestroyed = true;
+    this.saveDebouncer.cancel();
+    if (this.leaderCheckInterval) {
+      clearInterval(this.leaderCheckInterval);
+      this.leaderCheckInterval = void 0;
+    }
+    for (const timer of this.activeResponseTimers) {
+      clearTimeout(timer);
+    }
+    this.activeResponseTimers.clear();
+    this.cleanupVisibilityChange?.();
+    this.cleanupVisibilityChange = void 0;
+    if (this.broadcastChannel) {
+      this.broadcastChannel.close();
+      this.broadcastChannel = void 0;
+    }
+    this.pendingOperations.clear();
+  }
+}