@framers/sql-storage-adapter 0.7.2 → 0.7.3

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

@@ -0,0 +1,455 @@
+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 syncManager_exports = {};
+__export(syncManager_exports, {
+  SyncManager: () => SyncManager,
+  createSyncManager: () => createSyncManager
+});
+module.exports = __toCommonJS(syncManager_exports);
+var import_database = require("../../core/database.js");
+var import_dataExport = require("../migrations/dataExport.js");
+var import_dataImport = require("../migrations/dataImport.js");
+class SyncManager {
+  constructor(primary, remote, callbacks, syncConfig) {
+    this.callbacks = callbacks;
+    this.remoteDb = null;
+    this.syncTimer = null;
+    this.debounceTimer = null;
+    this.syncQueue = [];
+    this.isSyncing = false;
+    this.isOnline = true;
+    this.lastSyncTime = null;
+    this.pendingWrites = /* @__PURE__ */ new Set();
+    this.primaryDb = primary;
+    this.remoteDb = remote;
+    this.config = {
+      mode: syncConfig.mode ?? "manual",
+      direction: syncConfig.direction ?? "bidirectional",
+      conflictStrategy: syncConfig.conflictStrategy ?? "last-write-wins",
+      interval: syncConfig.interval ?? 3e4,
+      debounce: syncConfig.debounce ?? 500,
+      batchSize: syncConfig.batchSize ?? 100,
+      retryOnError: syncConfig.retryOnError ?? true,
+      maxRetries: syncConfig.maxRetries ?? 3,
+      retryDelay: syncConfig.retryDelay ?? 1e3,
+      tables: syncConfig.tables ?? {},
+      mobileStorageLimit: syncConfig.mobileStorageLimit ?? 50,
+      storageLimitAction: syncConfig.storageLimitAction ?? "warn",
+      includeTables: syncConfig.includeTables,
+      excludeTables: syncConfig.excludeTables
+    };
+  }
+  /**
+   * Get the primary database adapter.
+   * Use this for all database operations.
+   */
+  get db() {
+    return this.primaryDb;
+  }
+  /**
+   * Check if manager is currently syncing.
+   */
+  get syncing() {
+    return this.isSyncing;
+  }
+  /**
+   * Check if currently online.
+   */
+  get online() {
+    return this.isOnline;
+  }
+  /**
+   * Get last successful sync time.
+   */
+  get lastSync() {
+    return this.lastSyncTime;
+  }
+  /**
+   * Trigger manual sync.
+   * Safe to call multiple times - queues if already syncing.
+   */
+  async sync() {
+    if (!this.remoteDb) {
+      throw new Error("No remote database configured for sync");
+    }
+    if (this.isSyncing) {
+      return new Promise((resolve, reject) => {
+        this.syncQueue.push(async () => {
+          try {
+            const result = await this.performSync();
+            resolve(result);
+          } catch (error) {
+            reject(error);
+          }
+        });
+      });
+    }
+    return this.performSync();
+  }
+  /**
+   * Perform the actual sync operation.
+   */
+  async performSync() {
+    if (!this.remoteDb) {
+      throw new Error("No remote database configured");
+    }
+    this.isSyncing = true;
+    const startTime = Date.now();
+    let recordsSynced = 0;
+    let conflicts = 0;
+    const tablesSynced = [];
+    const errors = [];
+    const details = {};
+    try {
+      await this.checkConnection();
+      const tables = await this.getTablesToSync();
+      const totalTables = tables.length;
+      const sortedTables = this.sortTablesByPriority(tables);
+      for (let i = 0; i < sortedTables.length; i++) {
+        const table = sortedTables[i];
+        this.callbacks.onProgress?.({
+          phase: "pulling",
+          percent: Math.round(i / totalTables * 50),
+          // 0-50% for pull
+          currentTable: table,
+          recordsProcessed: recordsSynced,
+          totalRecords: 0
+          // Unknown until we query
+        });
+        try {
+          const tableResult = await this.syncTable(table);
+          details[table] = tableResult;
+          recordsSynced += tableResult.pushed + tableResult.pulled;
+          conflicts += tableResult.conflicts;
+          tablesSynced.push(table);
+        } catch (error) {
+          errors.push(error);
+          this.callbacks.onError?.(error);
+          if (!this.config.retryOnError) {
+            throw error;
+          }
+        }
+      }
+      this.lastSyncTime = /* @__PURE__ */ new Date();
+      const duration = Date.now() - startTime;
+      const result = {
+        success: errors.length === 0,
+        direction: this.config.direction,
+        recordsSynced,
+        conflicts,
+        duration,
+        timestamp: this.lastSyncTime.toISOString(),
+        tables: tablesSynced,
+        errors: errors.length > 0 ? errors : void 0,
+        details
+      };
+      this.callbacks.onSync?.(result);
+      return result;
+    } finally {
+      this.isSyncing = false;
+      this.pendingWrites.clear();
+      if (this.syncQueue.length > 0) {
+        const nextSync = this.syncQueue.shift();
+        nextSync?.();
+      }
+    }
+  }
+  /**
+   * Sync a single table.
+   */
+  async syncTable(table) {
+    const direction = this.config.direction;
+    let pushed = 0;
+    let pulled = 0;
+    let conflicts = 0;
+    if (direction === "bidirectional" || direction === "pull-only") {
+      const pullResult = await this.pullTable(table);
+      pulled = pullResult.records;
+      conflicts += pullResult.conflicts;
+    }
+    if (direction === "bidirectional" || direction === "push-only") {
+      const pushResult = await this.pushTable(table);
+      pushed = pushResult.records;
+      conflicts += pushResult.conflicts;
+    }
+    return { pushed, pulled, conflicts };
+  }
+  /**
+   * Pull table data from remote to local.
+   */
+  async pullTable(table) {
+    if (!this.remoteDb)
+      return { records: 0, conflicts: 0 };
+    const remoteData = await (0, import_dataExport.exportData)(this.remoteDb, {
+      tables: [table],
+      includeSchema: false
+    });
+    if (!remoteData.data[table]?.length) {
+      return { records: 0, conflicts: 0 };
+    }
+    const localData = await (0, import_dataExport.exportData)(this.primaryDb, {
+      tables: [table],
+      includeSchema: false
+    });
+    const localRecords = this.sanitiseRecords(localData.data[table]);
+    const remoteRecords = this.sanitiseRecords(remoteData.data[table]);
+    const conflicts = await this.resolveConflicts(table, localRecords, remoteRecords);
+    await (0, import_dataImport.importData)(this.primaryDb, remoteData, {
+      onConflict: "replace",
+      // We already resolved conflicts
+      skipSchema: true,
+      tables: [table]
+    });
+    return {
+      records: remoteRecords.length,
+      conflicts
+    };
+  }
+  /**
+   * Push table data from local to remote.
+   */
+  async pushTable(table) {
+    if (!this.remoteDb)
+      return { records: 0, conflicts: 0 };
+    const localData = await (0, import_dataExport.exportData)(this.primaryDb, {
+      tables: [table],
+      includeSchema: false
+    });
+    if (!localData.data[table]?.length) {
+      return { records: 0, conflicts: 0 };
+    }
+    await (0, import_dataImport.importData)(this.remoteDb, localData, {
+      onConflict: "replace",
+      skipSchema: true,
+      tables: [table]
+    });
+    return {
+      records: localData.data[table].length,
+      conflicts: 0
+    };
+  }
+  sanitiseRecords(records) {
+    if (!records) {
+      return [];
+    }
+    return records.filter((record) => typeof record === "object" && record !== null).map((record) => record);
+  }
+  /**
+   * Resolve conflicts between local and remote data.
+   */
+  async resolveConflicts(table, local, remote) {
+    const tableConfig = this.config.tables[table];
+    const strategy = tableConfig?.conflictStrategy ?? this.config.conflictStrategy;
+    let conflictCount = 0;
+    const localMap = /* @__PURE__ */ new Map();
+    for (const record of local) {
+      if (record.id !== void 0 && record.id !== null) {
+        const identifier = record.id;
+        localMap.set(identifier, record);
+      }
+    }
+    for (const remoteRecord of remote) {
+      if (remoteRecord.id === void 0 || remoteRecord.id === null) {
+        continue;
+      }
+      const identifier = remoteRecord.id;
+      const localRecord = localMap.get(identifier);
+      if (!localRecord)
+        continue;
+      const localTimestampValue = typeof localRecord.updated_at === "string" ? localRecord.updated_at : typeof localRecord.created_at === "string" ? localRecord.created_at : (/* @__PURE__ */ new Date()).toISOString();
+      const remoteTimestampValue = typeof remoteRecord.updated_at === "string" ? remoteRecord.updated_at : typeof remoteRecord.created_at === "string" ? remoteRecord.created_at : (/* @__PURE__ */ new Date()).toISOString();
+      const localTime = new Date(localTimestampValue);
+      const remoteTime = new Date(remoteTimestampValue);
+      if (localRecord.updated_at || remoteRecord.updated_at) {
+        conflictCount++;
+        const conflict = {
+          table,
+          id: identifier,
+          local: localRecord,
+          remote: remoteRecord,
+          localTimestamp: localTime.toISOString(),
+          remoteTimestamp: remoteTime.toISOString()
+        };
+        this.callbacks.onConflict?.(conflict);
+        switch (strategy) {
+          case "last-write-wins":
+            break;
+          case "local-wins":
+            break;
+          case "remote-wins":
+            break;
+          case "merge":
+            if (tableConfig?.mergeFn) {
+            }
+            break;
+          case "keep-both":
+            break;
+        }
+      }
+    }
+    return conflictCount;
+  }
+  /**
+   * Get list of tables to sync.
+   */
+  async getTablesToSync() {
+    const schema = await (0, import_dataExport.exportData)(this.primaryDb, {
+      includeSchema: true
+    });
+    const allTables = schema.schema?.map((s) => s.name) ?? [];
+    let tables = allTables;
+    if (this.config.includeTables) {
+      tables = tables.filter((t) => this.config.includeTables.includes(t));
+    }
+    if (this.config.excludeTables) {
+      tables = tables.filter((t) => !this.config.excludeTables.includes(t));
+    }
+    tables = tables.filter((t) => !this.config.tables[t]?.skip);
+    return tables;
+  }
+  /**
+   * Sort tables by priority.
+   */
+  sortTablesByPriority(tables) {
+    const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    return tables.sort((a, b) => {
+      const aPriority = this.config.tables[a]?.priority ?? "medium";
+      const bPriority = this.config.tables[b]?.priority ?? "medium";
+      return priorityOrder[aPriority] - priorityOrder[bPriority];
+    });
+  }
+  /**
+   * Check network connection.
+   */
+  async checkConnection() {
+    if (!this.remoteDb)
+      return;
+    try {
+      await this.remoteDb.get("SELECT 1 as ok");
+      if (!this.isOnline) {
+        this.isOnline = true;
+        this.callbacks.onOnline?.();
+      }
+    } catch {
+      if (this.isOnline) {
+        this.isOnline = false;
+        this.callbacks.onOffline?.();
+      }
+      throw new Error("Remote database not accessible");
+    }
+  }
+  /**
+   * Start automatic sync based on mode.
+   */
+  startAutoSync() {
+    if (this.config.mode === "periodic") {
+      this.syncTimer = setInterval(() => {
+        this.sync().catch((error) => {
+          this.callbacks.onError?.(error);
+        });
+      }, this.config.interval);
+    } else if (this.config.mode === "on-reconnect") {
+      if (typeof window !== "undefined") {
+        window.addEventListener("online", () => {
+          this.sync().catch((error) => {
+            this.callbacks.onError?.(error);
+          });
+        });
+      }
+    }
+  }
+  /**
+   * Stop automatic sync.
+   */
+  stop() {
+    if (this.syncTimer) {
+      clearInterval(this.syncTimer);
+      this.syncTimer = null;
+    }
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+  }
+  /**
+   * Close all database connections.
+   */
+  async close() {
+    this.stop();
+    await this.primaryDb.close();
+    if (this.remoteDb) {
+      await this.remoteDb.close();
+    }
+  }
+  /**
+   * Create a sync manager instance.
+   */
+  static async create(config) {
+    let primaryDb;
+    const primaryConfig = typeof config.primary === "string" ? { file: config.primary } : config.primary;
+    try {
+      if (primaryConfig.url) {
+        primaryDb = await (0, import_database.createDatabase)({ url: primaryConfig.url });
+      } else if (primaryConfig.file) {
+        primaryDb = await (0, import_database.openDatabase)(primaryConfig.file);
+      } else {
+        primaryDb = await (0, import_database.createDatabase)();
+      }
+    } catch (error) {
+      if (primaryConfig.fallback) {
+        console.warn("[SyncManager] Primary database failed, using fallback:", error);
+        primaryDb = await (0, import_database.openDatabase)(primaryConfig.fallback);
+      } else {
+        throw error;
+      }
+    }
+    await primaryDb.open();
+    let remoteDb = null;
+    if (config.remote) {
+      const remoteConfig = typeof config.remote === "string" ? { url: config.remote } : config.remote;
+      try {
+        if (remoteConfig.url) {
+          remoteDb = await (0, import_database.connectDatabase)(remoteConfig.url);
+          await remoteDb.open();
+        }
+      } catch (error) {
+        console.warn("[SyncManager] Remote database not available:", error);
+      }
+    }
+    const manager = new SyncManager(primaryDb, remoteDb, {
+      onSync: config.onSync,
+      onConflict: config.onConflict,
+      onOffline: config.onOffline,
+      onOnline: config.onOnline,
+      onError: config.onError,
+      onProgress: config.onProgress
+    }, config.sync ?? {});
+    if (config.sync?.mode && config.sync.mode !== "manual") {
+      manager.startAutoSync();
+    }
+    return manager;
+  }
+}
+async function createSyncManager(config) {
+  return SyncManager.create(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SyncManager,
+  createSyncManager
+});

package/dist/cjs/features/sync/tables/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sync Tables Module.
+ *
+ * Manages sync-related database tables including change logs,
+ * device registry, and conflict tracking.
+ *
+ * @packageDocumentation
+ */
+export * from './syncLogManager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/features/sync/tables/index.js

@@ -0,0 +1,21 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var tables_exports = {};
+module.exports = __toCommonJS(tables_exports);
+__reExport(tables_exports, require("./syncLogManager.js"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./syncLogManager.js")
+});

package/dist/cjs/features/sync/tables/syncLogManager.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Sync Log Manager - Tracks database changes for delta synchronization.
+ *
+ * Maintains a change log with vector clocks for each modification,
+ * enabling efficient delta sync between devices.
+ *
+ * @example
+ * ```typescript
+ * const syncLog = new SyncLogManager(adapter, 'device-123');
+ * await syncLog.initialize();
+ *
+ * // Log a change
+ * await syncLog.logChange({
+ *   table: 'users',
+ *   recordId: 'user-1',
+ *   operation: 'UPDATE',
+ *   oldData: { name: 'Old' },
+ *   newData: { name: 'New' },
+ * });
+ *
+ * // Get changes since a clock
+ * const changes = await syncLog.getChangesSince(remoteVectorClock);
+ * ```
+ */
+import type { StorageAdapter } from '../../../core/contracts/index.js';
+import type { VectorClockData } from '../protocol/vectorClock.js';
+import { VectorClock } from '../protocol/vectorClock.js';
+import type { ChangeRecord, ChangeOperation, DeviceInfo, DeviceType } from '../protocol/messages.js';
+/**
+ * Change log entry as stored in database.
+ */
+export interface ChangeLogEntry {
+    logId: number;
+    changeId: string;
+    tableName: string;
+    recordId: string;
+    operation: ChangeOperation;
+    vectorClock: string;
+    deviceId: string;
+    oldData: string | null;
+    newData: string | null;
+    createdAt: number;
+    syncedAt: number | null;
+}
+/**
+ * Device registry entry.
+ */
+export interface DeviceEntry {
+    deviceId: string;
+    deviceType: DeviceType;
+    deviceName: string | null;
+    vectorClock: string;
+    lastSeenAt: number;
+    createdAt: number;
+}
+/**
+ * Conflict entry.
+ */
+export interface ConflictEntry {
+    conflictId: string;
+    tableName: string;
+    recordId: string;
+    localData: string;
+    remoteData: string;
+    localClock: string;
+    remoteClock: string;
+    status: 'pending' | 'resolved' | 'deferred';
+    resolution: string | null;
+    createdAt: number;
+    resolvedAt: number | null;
+}
+/**
+ * Sync log manager configuration.
+ */
+export interface SyncLogManagerConfig {
+    /** Maximum log entries to keep (auto-prune) */
+    maxLogEntries?: number;
+    /** Auto-prune synced entries after N days */
+    pruneSyncedAfterDays?: number;
+    /** Tables to track (undefined = all) */
+    includeTables?: string[];
+    /** Tables to exclude from tracking */
+    excludeTables?: string[];
+}
+/**
+ * Manages the sync change log and device registry.
+ */
+export declare class SyncLogManager {
+    private readonly adapter;
+    private readonly deviceId;
+    private readonly config;
+    private vectorClock;
+    private isInitialized;
+    constructor(adapter: StorageAdapter, deviceId?: string, config?: SyncLogManagerConfig);
+    /**
+     * Initialize sync tables.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Create sync tracking tables.
+     */
+    private createSyncTables;
+    /**
+     * Load vector clock from database or create new one.
+     */
+    private loadVectorClock;
+    /**
+     * Log a database change.
+     */
+    logChange(change: {
+        table: string;
+        recordId: string;
+        operation: ChangeOperation;
+        oldData?: Record<string, unknown>;
+        newData?: Record<string, unknown>;
+    }): Promise<ChangeRecord>;
+    /**
+     * Get changes since a vector clock.
+     */
+    getChangesSince(sinceClock: VectorClockData, options?: {
+        tables?: string[];
+        limit?: number;
+    }): Promise<ChangeRecord[]>;
+    /**
+     * Mark changes as synced.
+     */
+    markSynced(changeIds: string[]): Promise<void>;
+    /**
+     * Get unsynced change count.
+     */
+    getUnsyncedCount(): Promise<number>;
+    /**
+     * Register a device.
+     */
+    registerDevice(device: DeviceInfo): Promise<void>;
+    /**
+     * Get all registered devices.
+     */
+    getDevices(): Promise<DeviceInfo[]>;
+    /**
+     * Update a device's vector clock.
+     */
+    updateDeviceClockFor(deviceId: string, clock: VectorClockData): Promise<void>;
+    /**
+     * Record a conflict.
+     */
+    recordConflict(conflict: {
+        table: string;
+        recordId: string;
+        localData: Record<string, unknown>;
+        remoteData: Record<string, unknown>;
+        localClock: VectorClockData;
+        remoteClock: VectorClockData;
+    }): Promise<string>;
+    /**
+     * Get pending conflicts.
+     */
+    getPendingConflicts(): Promise<ConflictEntry[]>;
+    /**
+     * Resolve a conflict.
+     */
+    resolveConflict(conflictId: string, resolution: string): Promise<void>;
+    /**
+     * Get current vector clock.
+     */
+    getVectorClock(): VectorClock;
+    /**
+     * Get vector clock data.
+     */
+    getVectorClockData(): VectorClockData;
+    /**
+     * Merge a remote clock into ours.
+     */
+    mergeVectorClock(remoteClock: VectorClockData): void;
+    /**
+     * Get device ID.
+     */
+    getDeviceId(): string;
+    /**
+     * Update this device's clock in database.
+     */
+    private updateDeviceClock;
+    /**
+     * Check if table should be tracked.
+     */
+    private shouldTrackTable;
+    /**
+     * Check if clock A is after clock B.
+     */
+    private isClockAfter;
+    /**
+     * Generate unique change ID.
+     */
+    private generateChangeId;
+    /**
+     * Generate unique conflict ID.
+     */
+    private generateConflictId;
+    /**
+     * Detect device type from environment.
+     */
+    private detectDeviceType;
+    /**
+     * Get device name.
+     */
+    private getDeviceName;
+    /**
+     * Prune old synced entries if over limit.
+     */
+    private pruneIfNeeded;
+}
+/**
+ * Create a sync log manager.
+ */
+export declare function createSyncLogManager(adapter: StorageAdapter, deviceId?: string, config?: SyncLogManagerConfig): SyncLogManager;
+//# sourceMappingURL=syncLogManager.d.ts.map