@framers/sql-storage-adapter 0.7.1 → 0.7.3

package/dist/cjs/features/sync/crossPlatformSync.js

@@ -0,0 +1,551 @@
+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 crossPlatformSync_exports = {};
+__export(crossPlatformSync_exports, {
+  CrossPlatformSync: () => CrossPlatformSync,
+  createCrossPlatformSync: () => createCrossPlatformSync
+});
+module.exports = __toCommonJS(crossPlatformSync_exports);
+var import_vectorClock = require("./protocol/vectorClock.js");
+var import_messages = require("./protocol/messages.js");
+var import_websocketTransport = require("./transport/websocketTransport.js");
+var import_httpTransport = require("./transport/httpTransport.js");
+var import_conflictResolver = require("./conflicts/conflictResolver.js");
+var import_deviceManager = require("./devices/deviceManager.js");
+var import_syncLogManager = require("./tables/syncLogManager.js");
+function toProtocolDeviceType(deviceType) {
+  if (deviceType === "unknown") {
+    return "browser";
+  }
+  return deviceType;
+}
+function capabilitiesToArray(capabilities) {
+  const result = [];
+  if (capabilities.realTimeSync)
+    result.push("realtime");
+  if (capabilities.backgroundSync)
+    result.push("background");
+  if (capabilities.pushNotifications)
+    result.push("push");
+  if (capabilities.offlineMode)
+    result.push("offline");
+  result.push("gzip", "delta");
+  return result;
+}
+class CrossPlatformSync {
+  constructor(options) {
+    this._transport = null;
+    this._syncTimer = null;
+    this._isSyncing = false;
+    this._disposed = false;
+    this._adapter = options.localAdapter;
+    this._deviceId = (0, import_vectorClock.generateDeviceId)();
+    this._options = {
+      localAdapter: options.localAdapter,
+      endpoint: options.endpoint,
+      authToken: options.authToken ?? "",
+      device: options.device ?? {},
+      tables: options.tables,
+      transport: options.transport ?? "auto",
+      transportOptions: options.transportOptions ?? {},
+      defaultConflictStrategy: options.defaultConflictStrategy ?? "last-write-wins",
+      hooks: options.hooks ?? {},
+      syncInterval: options.syncInterval ?? 0,
+      realTime: options.realTime ?? true,
+      batchSize: options.batchSize ?? 100,
+      compression: options.compression ?? true
+    };
+    this._deviceManager = new import_deviceManager.DeviceManager({
+      adapter: this._adapter,
+      deviceName: options.device?.name,
+      autoDetect: true
+    });
+    this._syncLogManager = new import_syncLogManager.SyncLogManager(this._adapter, this._deviceId);
+    this._conflictResolver = new import_conflictResolver.ConflictResolver({
+      defaultStrategy: this._options.defaultConflictStrategy,
+      tableStrategies: this._buildTableStrategies(),
+      fieldMergers: this._buildFieldMergers(),
+      hooks: {
+        onConflictDetected: this._options.hooks.onConflictDetected,
+        onConflictNeedsResolution: this._options.hooks.onConflictNeedsResolution,
+        onConflictResolved: this._options.hooks.onConflictResolved,
+        onMergeFailed: this._options.hooks.onMergeFailed
+      }
+    });
+    this._status = {
+      state: "idle",
+      connected: false,
+      pendingChanges: 0,
+      pendingConflicts: 0,
+      peers: []
+    };
+  }
+  /**
+   * Initialize the sync manager.
+   */
+  async initialize() {
+    await this._deviceManager.initialize();
+    await this._syncLogManager.initialize();
+    await this._initializeTransport();
+    this._setupDeviceManagerListeners();
+    this._status.device = this._deviceManager.getCurrentDevice() ?? void 0;
+    this._status.peers = await this._deviceManager.getPeers();
+    if (this._options.syncInterval > 0) {
+      this._startSyncTimer();
+    }
+  }
+  /**
+   * Perform a sync operation.
+   */
+  async sync() {
+    if (this._isSyncing) {
+      throw new Error("Sync already in progress");
+    }
+    if (this._disposed) {
+      throw new Error("Sync manager has been disposed");
+    }
+    this._isSyncing = true;
+    this._status.state = "syncing";
+    const startTime = Date.now();
+    this._options.hooks.onSyncStart?.();
+    const result = {
+      success: false,
+      pushed: 0,
+      pulled: 0,
+      conflicts: 0,
+      conflictsResolved: 0,
+      duration: 0,
+      errors: [],
+      vectorClock: this._syncLogManager.getVectorClockData()
+    };
+    try {
+      if (!this._transport?.isConnected) {
+        await this._transport?.connect();
+      }
+      const pushResult = await this._pushChanges();
+      result.pushed = pushResult.pushed;
+      result.conflicts += pushResult.conflicts;
+      const pullResult = await this._pullChanges();
+      result.pulled = pullResult.pulled;
+      result.conflicts += pullResult.conflicts;
+      const resolveResult = await this._resolveConflicts();
+      result.conflictsResolved = resolveResult.resolved;
+      result.vectorClock = this._syncLogManager.getVectorClockData();
+      result.success = true;
+      this._status.lastSyncAt = Date.now();
+    } catch (error) {
+      result.errors.push(error);
+      this._status.state = "error";
+      this._options.hooks.onSyncError?.(error);
+    }
+    result.duration = Date.now() - startTime;
+    this._isSyncing = false;
+    this._status.state = result.success ? "idle" : "error";
+    this._status.lastResult = result;
+    this._status.pendingChanges = await this._getPendingChangesCount();
+    this._status.pendingConflicts = this._conflictResolver.getPendingConflicts().length;
+    this._options.hooks.onSyncComplete?.(result);
+    return result;
+  }
+  /**
+   * Push a single change immediately (for real-time sync).
+   */
+  async pushChange(tableName, recordId, operation, data) {
+    if (!this._options.realTime)
+      return;
+    if (!this._transport?.isConnected)
+      return;
+    const device = this._deviceManager.getCurrentDevice();
+    if (!device)
+      return;
+    const loggedChange = await this._syncLogManager.logChange({
+      table: tableName,
+      recordId,
+      operation,
+      oldData: operation === "DELETE" ? data : void 0,
+      newData: operation !== "DELETE" ? data : void 0
+    });
+    const vectorClock = this._syncLogManager.getVectorClockData();
+    const message = (0, import_messages.createDeltaPushMessage)(device.deviceId, [loggedChange], vectorClock);
+    await this._transport.send(message);
+    this._options.hooks.onChangePushed?.(loggedChange);
+  }
+  /**
+   * Get current sync status.
+   */
+  getStatus() {
+    return { ...this._status };
+  }
+  /**
+   * Get pending conflicts.
+   */
+  getPendingConflicts() {
+    return this._conflictResolver.getPendingConflicts();
+  }
+  /**
+   * Resolve a conflict manually.
+   */
+  async resolveConflict(conflictId, decision, mergedData) {
+    return this._conflictResolver.resolveManually(conflictId, decision, mergedData);
+  }
+  /**
+   * Connect to sync server.
+   */
+  async connect() {
+    await this._transport?.connect();
+  }
+  /**
+   * Disconnect from sync server.
+   */
+  async disconnect() {
+    await this._transport?.disconnect();
+  }
+  /**
+   * Dispose of the sync manager.
+   */
+  async dispose() {
+    if (this._disposed)
+      return;
+    this._disposed = true;
+    if (this._syncTimer) {
+      clearInterval(this._syncTimer);
+      this._syncTimer = null;
+    }
+    await this._transport?.dispose();
+    await this._deviceManager.dispose();
+  }
+  /**
+   * Initialize the transport layer.
+   */
+  async _initializeTransport() {
+    const transportType = this._options.transport;
+    const baseOptions = {
+      endpoint: this._options.endpoint,
+      authToken: this._options.authToken,
+      compression: this._options.compression,
+      ...this._options.transportOptions
+    };
+    if (transportType === "websocket" || transportType === "auto") {
+      try {
+        this._transport = new import_websocketTransport.WebSocketTransport(baseOptions);
+        await this._transport.connect();
+        this._setupTransportListeners();
+        return;
+      } catch (error) {
+        if (transportType === "websocket") {
+          throw error;
+        }
+        console.warn("[CrossPlatformSync] WebSocket failed, falling back to HTTP");
+      }
+    }
+    this._transport = new import_httpTransport.HttpTransport(baseOptions);
+    this._setupTransportListeners();
+  }
+  /**
+   * Set up transport event listeners.
+   */
+  _setupTransportListeners() {
+    if (!this._transport)
+      return;
+    this._transport.on("connected", () => {
+      this._status.connected = true;
+      this._status.state = "idle";
+      this._options.hooks.onConnectionStateChange?.(true);
+      this._sendHandshake().catch((error) => {
+        console.error("[CrossPlatformSync] Handshake failed:", error);
+      });
+    });
+    this._transport.on("disconnected", () => {
+      this._status.connected = false;
+      this._status.state = "offline";
+      this._options.hooks.onConnectionStateChange?.(false);
+    });
+    this._transport.on("message", ({ message }) => {
+      this._handleIncomingMessage(message).catch((error) => {
+        console.error("[CrossPlatformSync] Message handling error:", error);
+      });
+    });
+    this._transport.on("error", ({ error }) => {
+      console.error("[CrossPlatformSync] Transport error:", error);
+      this._status.state = "error";
+    });
+  }
+  /**
+   * Set up device manager listeners.
+   */
+  _setupDeviceManagerListeners() {
+    this._deviceManager.on("peerDiscovered", (peer) => {
+      this._status.peers.push(peer);
+      this._options.hooks.onPeerDiscovered?.(peer);
+    });
+    this._deviceManager.on("presenceChanged", async (event) => {
+      const peer = this._status.peers.find((p) => p.deviceId === event.deviceId);
+      if (peer) {
+        peer.presence = event.currentStatus;
+      }
+      const currentDevice = this._deviceManager.getCurrentDevice();
+      if (event.deviceId === currentDevice?.deviceId) {
+        if (this._transport?.isConnected && currentDevice) {
+          const deviceInfo = {
+            deviceId: currentDevice.deviceId,
+            deviceType: toProtocolDeviceType(currentDevice.deviceType),
+            deviceName: currentDevice.deviceName
+          };
+          const message = (0, import_messages.createPresenceMessage)(deviceInfo, event.currentStatus);
+          await this._transport.send(message);
+        }
+      }
+    });
+  }
+  /**
+   * Send handshake to server.
+   */
+  async _sendHandshake() {
+    const device = this._deviceManager.getCurrentDevice();
+    if (!device || !this._transport)
+      return;
+    const deviceInfo = {
+      deviceId: device.deviceId,
+      deviceType: toProtocolDeviceType(device.deviceType),
+      deviceName: device.deviceName
+    };
+    const vectorClock = this._syncLogManager.getVectorClockData();
+    const request = (0, import_messages.createHandshakeRequest)(deviceInfo, vectorClock, Object.keys(this._options.tables), capabilitiesToArray(device.capabilities));
+    const response = await this._transport.request(request, 3e4);
+    if (response.type === "handshake_response") {
+      const responseData = response;
+      if (responseData.vectorClock) {
+        this._syncLogManager.mergeVectorClock(responseData.vectorClock);
+      }
+    }
+  }
+  /**
+   * Handle incoming sync message.
+   */
+  async _handleIncomingMessage(message) {
+    switch (message.type) {
+      case "delta_push": {
+        const pushMessage = message;
+        await this._applyRemoteChanges(pushMessage.batch.changes);
+        break;
+      }
+      case "conflict": {
+        break;
+      }
+      case "presence": {
+        const presenceMsg = message;
+        const peer = this._status.peers.find((p) => p.deviceId === presenceMsg.device.deviceId);
+        if (peer) {
+          peer.presence = presenceMsg.status;
+        }
+        break;
+      }
+    }
+  }
+  /**
+   * Push local changes to server.
+   */
+  async _pushChanges() {
+    const device = this._deviceManager.getCurrentDevice();
+    if (!device || !this._transport?.isConnected) {
+      return { pushed: 0, conflicts: 0 };
+    }
+    const vectorClock = this._syncLogManager.getVectorClockData();
+    const changes = await this._syncLogManager.getChangesSince(vectorClock, { limit: this._options.batchSize });
+    if (changes.length === 0) {
+      return { pushed: 0, conflicts: 0 };
+    }
+    const pushMessage = (0, import_messages.createDeltaPushMessage)(device.deviceId, changes, vectorClock);
+    const response = await this._transport.request(pushMessage, 3e4);
+    let conflicts = 0;
+    if (response.type === "ack") {
+      const changeIds = changes.map((c) => c.changeId);
+      await this._syncLogManager.markSynced(changeIds);
+      for (const change of changes) {
+        this._options.hooks.onChangePushed?.(change);
+      }
+    } else if (response.type === "conflict") {
+      conflicts = 1;
+    }
+    return { pushed: changes.length, conflicts };
+  }
+  /**
+   * Pull remote changes from server.
+   */
+  async _pullChanges() {
+    const device = this._deviceManager.getCurrentDevice();
+    if (!device || !this._transport?.isConnected) {
+      return { pulled: 0, conflicts: 0 };
+    }
+    const vectorClock = this._syncLogManager.getVectorClockData();
+    const request = (0, import_messages.createDeltaPullRequest)(device.deviceId, vectorClock, Object.keys(this._options.tables), this._options.batchSize);
+    const response = await this._transport.request(request, 3e4);
+    if (response.type !== "delta_pull_response") {
+      return { pulled: 0, conflicts: 0 };
+    }
+    const { applied, conflicts } = await this._applyRemoteChanges(response.batch.changes);
+    if (response.vectorClock) {
+      this._syncLogManager.mergeVectorClock(response.vectorClock);
+    }
+    return { pulled: applied, conflicts };
+  }
+  /**
+   * Apply remote changes to local database.
+   */
+  async _applyRemoteChanges(changes) {
+    let applied = 0;
+    let conflicts = 0;
+    const device = this._deviceManager.getCurrentDevice();
+    const localClock = this._syncLogManager.getVectorClockData();
+    for (const change of changes) {
+      try {
+        const localData = await this._getLocalRecord(change.table, change.recordId);
+        if (localData && device) {
+          const conflict = this._conflictResolver.detectConflict(change.table, change.recordId, localData, change.newData ?? {}, localClock, change.vectorClock, device.deviceId, change.deviceId);
+          if (conflict) {
+            conflicts++;
+            continue;
+          }
+        }
+        await this._applyChange(change);
+        applied++;
+        this._options.hooks.onChangePulled?.(change);
+      } catch (error) {
+        console.error("[CrossPlatformSync] Failed to apply change:", error);
+      }
+    }
+    return { applied, conflicts };
+  }
+  /**
+   * Apply a single change to local database.
+   */
+  async _applyChange(change) {
+    const tableConfig = this._options.tables[change.table];
+    const primaryKey = tableConfig?.primaryKey ?? "id";
+    const data = change.newData ?? change.oldData ?? {};
+    switch (change.operation) {
+      case "INSERT": {
+        const columns = Object.keys(data);
+        const placeholders = columns.map(() => "?").join(", ");
+        const values = columns.map((col) => data[col]);
+        await this._adapter.run(`INSERT OR REPLACE INTO ${change.table} (${columns.join(", ")}) VALUES (${placeholders})`, values);
+        break;
+      }
+      case "UPDATE": {
+        const columns = Object.keys(data).filter((c) => c !== primaryKey);
+        const setClause = columns.map((col) => `${col} = ?`).join(", ");
+        const values = columns.map((col) => data[col]);
+        values.push(change.recordId);
+        await this._adapter.run(`UPDATE ${change.table} SET ${setClause} WHERE ${primaryKey} = ?`, values);
+        break;
+      }
+      case "DELETE": {
+        await this._adapter.run(`DELETE FROM ${change.table} WHERE ${primaryKey} = ?`, [change.recordId]);
+        break;
+      }
+    }
+  }
+  /**
+   * Get a local record by table and ID.
+   */
+  async _getLocalRecord(tableName, recordId) {
+    const tableConfig = this._options.tables[tableName];
+    const primaryKey = tableConfig?.primaryKey ?? "id";
+    const row = await this._adapter.get(`SELECT * FROM ${tableName} WHERE ${primaryKey} = ?`, [recordId]);
+    return row ?? null;
+  }
+  /**
+   * Resolve pending conflicts.
+   */
+  async _resolveConflicts() {
+    const pending = this._conflictResolver.getPendingConflicts();
+    let resolved = 0;
+    for (const conflict of pending) {
+      try {
+        const resolution = await this._conflictResolver.resolve(conflict);
+        if (resolution.decision === "use_local" || resolution.decision === "use_remote") {
+          const data = resolution.decision === "use_local" ? conflict.localData : conflict.remoteData;
+          const changeRecord = (0, import_messages.createChangeRecord)(conflict.tableName, conflict.recordId, "UPDATE", conflict.localDeviceId, resolution.mergedClock, data);
+          await this._applyChange(changeRecord);
+        } else if (resolution.decision === "use_merged" && resolution.mergedData) {
+          const changeRecord = (0, import_messages.createChangeRecord)(conflict.tableName, conflict.recordId, "UPDATE", conflict.localDeviceId, resolution.mergedClock, resolution.mergedData);
+          await this._applyChange(changeRecord);
+        }
+        await this._syncLogManager.resolveConflict(conflict.conflictId, resolution.decision);
+        resolved++;
+      } catch (error) {
+        console.error("[CrossPlatformSync] Failed to resolve conflict:", error);
+      }
+    }
+    return { resolved };
+  }
+  /**
+   * Get count of pending changes.
+   */
+  async _getPendingChangesCount() {
+    return this._syncLogManager.getUnsyncedCount();
+  }
+  /**
+   * Start sync timer.
+   */
+  _startSyncTimer() {
+    if (this._syncTimer)
+      return;
+    this._syncTimer = setInterval(async () => {
+      if (!this._isSyncing && this._status.connected) {
+        await this.sync().catch((error) => {
+          console.error("[CrossPlatformSync] Scheduled sync failed:", error);
+        });
+      }
+    }, this._options.syncInterval);
+  }
+  /**
+   * Build table strategies map.
+   */
+  _buildTableStrategies() {
+    const strategies = {};
+    for (const [table, config] of Object.entries(this._options.tables)) {
+      if (config.conflictStrategy) {
+        strategies[table] = config.conflictStrategy;
+      }
+    }
+    return strategies;
+  }
+  /**
+   * Build field mergers map.
+   */
+  _buildFieldMergers() {
+    const mergers = {};
+    for (const [_table, config] of Object.entries(this._options.tables)) {
+      if (config.fieldMergers) {
+        Object.assign(mergers, config.fieldMergers);
+      }
+    }
+    return mergers;
+  }
+}
+const createCrossPlatformSync = async (options) => {
+  const sync = new CrossPlatformSync(options);
+  await sync.initialize();
+  return sync;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CrossPlatformSync,
+  createCrossPlatformSync
+});