@framers/sql-storage-adapter 0.7.1 → 0.7.3

package/dist/cjs/features/sync/conflicts/conflictResolver.js

@@ -0,0 +1,366 @@
+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 conflictResolver_exports = {};
+__export(conflictResolver_exports, {
+  ConflictResolver: () => ConflictResolver,
+  FieldMergers: () => FieldMergers,
+  createConflictResolver: () => createConflictResolver
+});
+module.exports = __toCommonJS(conflictResolver_exports);
+var import_vectorClock = require("../protocol/vectorClock.js");
+const FieldMergers = {
+  /**
+   * Use the most recent value based on timestamp.
+   */
+  lastWriteWins: ((_fieldName, localValue, remoteValue, localTimestamp, remoteTimestamp) => {
+    return localTimestamp >= remoteTimestamp ? localValue : remoteValue;
+  }),
+  /**
+   * For numeric fields, take the maximum value.
+   */
+  max: ((_fieldName, localValue, remoteValue) => {
+    const local = Number(localValue) || 0;
+    const remote = Number(remoteValue) || 0;
+    return Math.max(local, remote);
+  }),
+  /**
+   * For numeric fields, sum the values.
+   */
+  sum: ((_fieldName, localValue, remoteValue) => {
+    const local = Number(localValue) || 0;
+    const remote = Number(remoteValue) || 0;
+    return local + remote;
+  }),
+  /**
+   * For arrays, union the values.
+   */
+  union: ((_fieldName, localValue, remoteValue) => {
+    const local = Array.isArray(localValue) ? localValue : [];
+    const remote = Array.isArray(remoteValue) ? remoteValue : [];
+    return [.../* @__PURE__ */ new Set([...local, ...remote])];
+  }),
+  /**
+   * For strings, concatenate with separator.
+   */
+  concat: ((_fieldName, localValue, remoteValue) => {
+    const local = String(localValue ?? "");
+    const remote = String(remoteValue ?? "");
+    if (!local)
+      return remote;
+    if (!remote)
+      return local;
+    if (local === remote)
+      return local;
+    return `${local}
+---
+${remote}`;
+  })
+};
+function mergeVectorClocks(a, b) {
+  const merged = { ...a };
+  for (const [deviceId, value] of Object.entries(b)) {
+    merged[deviceId] = Math.max(merged[deviceId] ?? 0, value);
+  }
+  return merged;
+}
+function getTotalTicks(clock) {
+  return Object.values(clock).reduce((sum, val) => sum + val, 0);
+}
+class ConflictResolver {
+  constructor(options) {
+    this._pendingConflicts = /* @__PURE__ */ new Map();
+    this._resolvedConflicts = /* @__PURE__ */ new Map();
+    this._options = {
+      defaultStrategy: options.defaultStrategy,
+      tableStrategies: options.tableStrategies ?? {},
+      fieldMergers: options.fieldMergers ?? {},
+      hooks: options.hooks ?? {},
+      manualResolutionTimeout: options.manualResolutionTimeout ?? 3e5,
+      // 5 minutes
+      autoResolveAfter: options.autoResolveAfter ?? 0
+      // Disabled by default
+    };
+  }
+  /**
+   * Detect if there is a conflict between local and remote data.
+   */
+  detectConflict(tableName, recordId, localData, remoteData, localClock, remoteClock, localDeviceId, remoteDeviceId) {
+    const comparison = (0, import_vectorClock.compareClocks)(localClock, remoteClock);
+    if (comparison === "before" || comparison === "after") {
+      return null;
+    }
+    const conflictingFields = this._findConflictingFields(localData, remoteData);
+    if (conflictingFields.length === 0) {
+      return null;
+    }
+    const conflict = {
+      conflictId: `${tableName}:${recordId}:${Date.now()}`,
+      tableName,
+      recordId,
+      localData,
+      remoteData,
+      localClock,
+      remoteClock,
+      localDeviceId,
+      remoteDeviceId,
+      detectedAt: Date.now(),
+      conflictingFields,
+      status: "pending"
+    };
+    this._pendingConflicts.set(conflict.conflictId, conflict);
+    this._options.hooks.onConflictDetected?.(conflict);
+    return conflict;
+  }
+  /**
+   * Resolve a conflict using the configured strategy.
+   */
+  async resolve(conflict) {
+    const strategy = this._getStrategy(conflict.tableName);
+    let resolution;
+    switch (strategy) {
+      case "last-write-wins":
+        resolution = this._resolveLastWriteWins(conflict);
+        break;
+      case "local-wins":
+        resolution = this._resolveLocalWins(conflict);
+        break;
+      case "remote-wins":
+        resolution = this._resolveRemoteWins(conflict);
+        break;
+      case "merge":
+        resolution = this._resolveMerge(conflict);
+        break;
+      case "manual":
+        resolution = await this._resolveManual(conflict);
+        break;
+      default:
+        resolution = this._resolveLastWriteWins(conflict);
+    }
+    conflict.status = resolution.decision === "defer" ? "deferred" : "resolved";
+    this._resolvedConflicts.set(conflict.conflictId, resolution);
+    this._pendingConflicts.delete(conflict.conflictId);
+    this._options.hooks.onConflictResolved?.(conflict, resolution);
+    return resolution;
+  }
+  /**
+   * Get pending conflicts.
+   */
+  getPendingConflicts() {
+    return Array.from(this._pendingConflicts.values());
+  }
+  /**
+   * Get a specific pending conflict.
+   */
+  getConflict(conflictId) {
+    return this._pendingConflicts.get(conflictId);
+  }
+  /**
+   * Manually resolve a conflict with a user decision.
+   */
+  async resolveManually(conflictId, decision, mergedData) {
+    const conflict = this._pendingConflicts.get(conflictId);
+    if (!conflict) {
+      throw new Error(`Conflict not found: ${conflictId}`);
+    }
+    const resolution = {
+      decision,
+      mergedData,
+      mergedClock: mergeVectorClocks(conflict.localClock, conflict.remoteClock),
+      resolvedBy: "user",
+      resolvedAt: Date.now()
+    };
+    conflict.status = "resolved";
+    this._resolvedConflicts.set(conflictId, resolution);
+    this._pendingConflicts.delete(conflictId);
+    this._options.hooks.onConflictResolved?.(conflict, resolution);
+    return resolution;
+  }
+  /**
+   * Auto-resolve old conflicts that have been pending too long.
+   */
+  autoResolveStale() {
+    if (this._options.autoResolveAfter <= 0) {
+      return [];
+    }
+    const now = Date.now();
+    const staleThreshold = now - this._options.autoResolveAfter;
+    const resolutions = [];
+    for (const conflict of this._pendingConflicts.values()) {
+      if (conflict.detectedAt < staleThreshold) {
+        const resolution = this._resolveLastWriteWins(conflict);
+        resolution.reason = "Auto-resolved due to timeout";
+        conflict.status = "resolved";
+        this._resolvedConflicts.set(conflict.conflictId, resolution);
+        this._pendingConflicts.delete(conflict.conflictId);
+        resolutions.push(resolution);
+        this._options.hooks.onConflictResolved?.(conflict, resolution);
+      }
+    }
+    return resolutions;
+  }
+  /**
+   * Get the resolution strategy for a table.
+   */
+  _getStrategy(tableName) {
+    return this._options.tableStrategies[tableName] ?? this._options.defaultStrategy;
+  }
+  /**
+   * Find fields that differ between local and remote data.
+   */
+  _findConflictingFields(localData, remoteData) {
+    const allKeys = /* @__PURE__ */ new Set([
+      ...Object.keys(localData),
+      ...Object.keys(remoteData)
+    ]);
+    const conflicting = [];
+    for (const key of allKeys) {
+      if (key.startsWith("_"))
+        continue;
+      const localValue = localData[key];
+      const remoteValue = remoteData[key];
+      if (!this._valuesEqual(localValue, remoteValue)) {
+        conflicting.push(key);
+      }
+    }
+    return conflicting;
+  }
+  /**
+   * Check if two values are equal (deep comparison for objects/arrays).
+   */
+  _valuesEqual(a, b) {
+    if (a === b)
+      return true;
+    if (a === null || b === null)
+      return false;
+    if (typeof a !== typeof b)
+      return false;
+    if (typeof a === "object") {
+      return JSON.stringify(a) === JSON.stringify(b);
+    }
+    return false;
+  }
+  /**
+   * Resolve using last-write-wins strategy.
+   */
+  _resolveLastWriteWins(conflict) {
+    const localTicks = getTotalTicks(conflict.localClock);
+    const remoteTicks = getTotalTicks(conflict.remoteClock);
+    const useLocal = localTicks > remoteTicks;
+    return {
+      decision: useLocal ? "use_local" : "use_remote",
+      mergedClock: mergeVectorClocks(conflict.localClock, conflict.remoteClock),
+      resolvedBy: "strategy",
+      resolvedAt: Date.now(),
+      reason: `Last-write-wins: ${useLocal ? "local" : "remote"} had higher clock (${useLocal ? localTicks : remoteTicks} ticks)`
+    };
+  }
+  /**
+   * Resolve using local-wins strategy.
+   */
+  _resolveLocalWins(conflict) {
+    return {
+      decision: "use_local",
+      mergedClock: mergeVectorClocks(conflict.localClock, conflict.remoteClock),
+      resolvedBy: "strategy",
+      resolvedAt: Date.now(),
+      reason: "Local-wins strategy"
+    };
+  }
+  /**
+   * Resolve using remote-wins strategy.
+   */
+  _resolveRemoteWins(conflict) {
+    return {
+      decision: "use_remote",
+      mergedClock: mergeVectorClocks(conflict.localClock, conflict.remoteClock),
+      resolvedBy: "strategy",
+      resolvedAt: Date.now(),
+      reason: "Remote-wins strategy"
+    };
+  }
+  /**
+   * Resolve using field-level merge strategy.
+   */
+  _resolveMerge(conflict) {
+    try {
+      const mergedData = { ...conflict.localData };
+      const now = Date.now();
+      for (const field of conflict.conflictingFields) {
+        const merger = this._options.fieldMergers[field] ?? FieldMergers.lastWriteWins;
+        mergedData[field] = merger(field, conflict.localData[field], conflict.remoteData[field], now, now);
+      }
+      return {
+        decision: "use_merged",
+        mergedData,
+        mergedClock: mergeVectorClocks(conflict.localClock, conflict.remoteClock),
+        resolvedBy: "strategy",
+        resolvedAt: Date.now(),
+        reason: `Merged ${conflict.conflictingFields.length} conflicting fields`
+      };
+    } catch (error) {
+      this._options.hooks.onMergeFailed?.(conflict, error);
+      return this._resolveLastWriteWins(conflict);
+    }
+  }
+  /**
+   * Resolve using manual/UI strategy.
+   */
+  async _resolveManual(conflict) {
+    const hook = this._options.hooks.onConflictNeedsResolution;
+    if (!hook) {
+      console.warn("[ConflictResolver] No UI hook for manual resolution, falling back to LWW");
+      return this._resolveLastWriteWins(conflict);
+    }
+    const timeout = new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error("Manual resolution timed out"));
+      }, this._options.manualResolutionTimeout);
+    });
+    try {
+      const resolution = await Promise.race([
+        hook(conflict),
+        timeout
+      ]);
+      return {
+        ...resolution,
+        mergedClock: mergeVectorClocks(conflict.localClock, conflict.remoteClock),
+        resolvedBy: "user",
+        resolvedAt: Date.now()
+      };
+    } catch (error) {
+      console.warn("[ConflictResolver] Manual resolution failed:", error);
+      return {
+        decision: "defer",
+        mergedClock: conflict.localClock,
+        // Keep local for now
+        resolvedBy: "auto",
+        resolvedAt: Date.now(),
+        reason: `Manual resolution failed: ${error.message}`
+      };
+    }
+  }
+}
+const createConflictResolver = (options) => {
+  return new ConflictResolver(options);
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConflictResolver,
+  FieldMergers,
+  createConflictResolver
+});

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

@@ -0,0 +1,9 @@
+/**
+ * Conflict Resolution Module.
+ *
+ * Provides conflict detection and resolution for cross-platform sync.
+ *
+ * @packageDocumentation
+ */
+export * from './conflictResolver.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/features/sync/conflicts/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 conflicts_exports = {};
+module.exports = __toCommonJS(conflicts_exports);
+__reExport(conflicts_exports, require("./conflictResolver.js"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("./conflictResolver.js")
+});

package/dist/cjs/features/sync/crossPlatformSync.d.ts

@@ -0,0 +1,281 @@
+/**
+ * Cross-Platform Sync Entry Point.
+ *
+ * Main API for synchronizing data across Electron, Capacitor,
+ * browser, and server platforms.
+ *
+ * @packageDocumentation
+ */
+import type { StorageAdapter } from '../../core/contracts/index.js';
+import type { VectorClockData } from './protocol/vectorClock.js';
+import type { ChangeRecord } from './protocol/messages.js';
+import type { TransportOptions } from './transport/transport.js';
+import type { SyncConflict, ConflictResolution, ConflictStrategy, ConflictUIHooks, FieldMerger } from './conflicts/conflictResolver.js';
+import type { DeviceInfo, DeviceType } from './devices/deviceManager.js';
+/**
+ * Table sync configuration.
+ */
+export interface TableSyncConfig {
+    /** Sync priority (higher = synced first) */
+    priority?: 'critical' | 'high' | 'normal' | 'low';
+    /** Conflict resolution strategy for this table */
+    conflictStrategy?: ConflictStrategy;
+    /** Maximum records to sync per batch */
+    maxRecords?: number;
+    /** Custom field mergers for merge strategy */
+    fieldMergers?: Record<string, FieldMerger>;
+    /** Whether to track deletes */
+    trackDeletes?: boolean;
+    /** Primary key column (default: 'id') */
+    primaryKey?: string;
+}
+/**
+ * Cross-platform sync options.
+ */
+export interface CrossPlatformSyncOptions {
+    /** Local storage adapter */
+    localAdapter: StorageAdapter;
+    /** Sync server endpoint */
+    endpoint: string;
+    /** Authentication token */
+    authToken?: string;
+    /** Device information */
+    device?: {
+        name?: string;
+        type?: DeviceType;
+    };
+    /** Tables to sync with their configuration */
+    tables: Record<string, TableSyncConfig>;
+    /** Transport type preference */
+    transport?: 'websocket' | 'http' | 'auto';
+    /** Transport options */
+    transportOptions?: Partial<TransportOptions>;
+    /** Default conflict strategy */
+    defaultConflictStrategy?: ConflictStrategy;
+    /** Conflict resolution UI hooks */
+    hooks?: CrossPlatformSyncHooks;
+    /** Sync interval in milliseconds (0 = manual only) */
+    syncInterval?: number;
+    /** Enable real-time sync (push changes immediately) */
+    realTime?: boolean;
+    /** Batch size for sync operations */
+    batchSize?: number;
+    /** Enable compression for sync payloads */
+    compression?: boolean;
+}
+/**
+ * Hooks for sync events and conflict resolution.
+ */
+export interface CrossPlatformSyncHooks extends ConflictUIHooks {
+    /** Called before sync starts */
+    onSyncStart?: () => void;
+    /** Called after sync completes */
+    onSyncComplete?: (result: SyncResult) => void;
+    /** Called when sync fails */
+    onSyncError?: (error: Error) => void;
+    /** Called when a change is pushed */
+    onChangePushed?: (change: ChangeRecord) => void;
+    /** Called when a change is pulled */
+    onChangePulled?: (change: ChangeRecord) => void;
+    /** Called when connection state changes */
+    onConnectionStateChange?: (connected: boolean) => void;
+    /** Called when a peer device is discovered */
+    onPeerDiscovered?: (peer: DeviceInfo) => void;
+}
+/**
+ * Sync operation result.
+ */
+export interface SyncResult {
+    /** Whether sync was successful */
+    success: boolean;
+    /** Number of records pushed */
+    pushed: number;
+    /** Number of records pulled */
+    pulled: number;
+    /** Number of conflicts detected */
+    conflicts: number;
+    /** Number of conflicts resolved */
+    conflictsResolved: number;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Errors encountered */
+    errors: Error[];
+    /** Resulting vector clock */
+    vectorClock: VectorClockData;
+}
+/**
+ * Sync status information.
+ */
+export interface SyncStatus {
+    /** Current sync state */
+    state: 'idle' | 'syncing' | 'error' | 'offline';
+    /** Whether connected to sync server */
+    connected: boolean;
+    /** Last successful sync time */
+    lastSyncAt?: number;
+    /** Last sync result */
+    lastResult?: SyncResult;
+    /** Pending changes count */
+    pendingChanges: number;
+    /** Pending conflicts count */
+    pendingConflicts: number;
+    /** Current device info */
+    device?: DeviceInfo;
+    /** Known peer devices */
+    peers: DeviceInfo[];
+}
+/**
+ * Cross-platform sync manager.
+ *
+ * Orchestrates synchronization between local database and remote
+ * sync server across all platforms.
+ *
+ * @example
+ * ```typescript
+ * const sync = await createCrossPlatformSync({
+ *   localAdapter: db,
+ *   endpoint: 'wss://sync.example.com',
+ *   authToken: 'token',
+ *   device: { name: 'MacBook Pro', type: 'electron' },
+ *   tables: {
+ *     notes: { priority: 'high', conflictStrategy: 'merge' },
+ *     settings: { priority: 'critical', conflictStrategy: 'local-wins' },
+ *   },
+ *   hooks: {
+ *     onConflictNeedsResolution: (conflict) => showConflictDialog(conflict),
+ *     onSyncComplete: (result) => console.log('Synced:', result),
+ *   },
+ * });
+ *
+ * await sync.sync();
+ * ```
+ */
+export declare class CrossPlatformSync {
+    private _adapter;
+    private _transport;
+    private _conflictResolver;
+    private _deviceManager;
+    private _syncLogManager;
+    private _options;
+    private _syncTimer;
+    private _status;
+    private _isSyncing;
+    private _disposed;
+    private _deviceId;
+    constructor(options: CrossPlatformSyncOptions);
+    /**
+     * Initialize the sync manager.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Perform a sync operation.
+     */
+    sync(): Promise<SyncResult>;
+    /**
+     * Push a single change immediately (for real-time sync).
+     */
+    pushChange(tableName: string, recordId: string, operation: 'INSERT' | 'UPDATE' | 'DELETE', data: Record<string, unknown>): Promise<void>;
+    /**
+     * Get current sync status.
+     */
+    getStatus(): SyncStatus;
+    /**
+     * Get pending conflicts.
+     */
+    getPendingConflicts(): SyncConflict[];
+    /**
+     * Resolve a conflict manually.
+     */
+    resolveConflict(conflictId: string, decision: 'use_local' | 'use_remote' | 'use_merged' | 'keep_both' | 'defer', mergedData?: Record<string, unknown>): Promise<ConflictResolution>;
+    /**
+     * Connect to sync server.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from sync server.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Dispose of the sync manager.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Initialize the transport layer.
+     */
+    private _initializeTransport;
+    /**
+     * Set up transport event listeners.
+     */
+    private _setupTransportListeners;
+    /**
+     * Set up device manager listeners.
+     */
+    private _setupDeviceManagerListeners;
+    /**
+     * Send handshake to server.
+     */
+    private _sendHandshake;
+    /**
+     * Handle incoming sync message.
+     */
+    private _handleIncomingMessage;
+    /**
+     * Push local changes to server.
+     */
+    private _pushChanges;
+    /**
+     * Pull remote changes from server.
+     */
+    private _pullChanges;
+    /**
+     * Apply remote changes to local database.
+     */
+    private _applyRemoteChanges;
+    /**
+     * Apply a single change to local database.
+     */
+    private _applyChange;
+    /**
+     * Get a local record by table and ID.
+     */
+    private _getLocalRecord;
+    /**
+     * Resolve pending conflicts.
+     */
+    private _resolveConflicts;
+    /**
+     * Get count of pending changes.
+     */
+    private _getPendingChangesCount;
+    /**
+     * Start sync timer.
+     */
+    private _startSyncTimer;
+    /**
+     * Build table strategies map.
+     */
+    private _buildTableStrategies;
+    /**
+     * Build field mergers map.
+     */
+    private _buildFieldMergers;
+}
+/**
+ * Create a cross-platform sync instance.
+ *
+ * @example
+ * ```typescript
+ * const sync = await createCrossPlatformSync({
+ *   localAdapter: db,
+ *   endpoint: 'wss://sync.example.com',
+ *   tables: {
+ *     notes: { priority: 'high', conflictStrategy: 'merge' },
+ *     settings: { priority: 'critical', conflictStrategy: 'local-wins' },
+ *   },
+ * });
+ *
+ * await sync.sync();
+ * ```
+ */
+export declare const createCrossPlatformSync: (options: CrossPlatformSyncOptions) => Promise<CrossPlatformSync>;
+//# sourceMappingURL=crossPlatformSync.d.ts.map