@framers/sql-storage-adapter 0.7.2 → 0.7.3

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

@@ -0,0 +1,423 @@
+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 syncLogManager_exports = {};
+__export(syncLogManager_exports, {
+  SyncLogManager: () => SyncLogManager,
+  createSyncLogManager: () => createSyncLogManager
+});
+module.exports = __toCommonJS(syncLogManager_exports);
+var import_vectorClock = require("../protocol/vectorClock.js");
+const DEFAULT_CONFIG = {
+  maxLogEntries: 1e4,
+  pruneSyncedAfterDays: 30,
+  includeTables: [],
+  excludeTables: ["_sync_log", "_sync_devices", "_sync_conflicts"]
+};
+class SyncLogManager {
+  constructor(adapter, deviceId = (0, import_vectorClock.generateDeviceId)(), config = {}) {
+    this.adapter = adapter;
+    this.deviceId = deviceId;
+    this.isInitialized = false;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.vectorClock = new import_vectorClock.VectorClock(deviceId);
+  }
+  // ============================================================================
+  // Initialization
+  // ============================================================================
+  /**
+   * Initialize sync tables.
+   */
+  async initialize() {
+    if (this.isInitialized)
+      return;
+    await this.createSyncTables();
+    await this.loadVectorClock();
+    this.isInitialized = true;
+  }
+  /**
+   * Create sync tracking tables.
+   */
+  async createSyncTables() {
+    await this.adapter.exec(`
+      CREATE TABLE IF NOT EXISTS _sync_log (
+        log_id INTEGER PRIMARY KEY AUTOINCREMENT,
+        change_id TEXT NOT NULL UNIQUE,
+        table_name TEXT NOT NULL,
+        record_id TEXT NOT NULL,
+        operation TEXT NOT NULL CHECK (operation IN ('INSERT', 'UPDATE', 'DELETE')),
+        vector_clock TEXT NOT NULL,
+        device_id TEXT NOT NULL,
+        old_data TEXT,
+        new_data TEXT,
+        created_at INTEGER NOT NULL,
+        synced_at INTEGER
+      )
+    `);
+    await this.adapter.exec(`
+      CREATE INDEX IF NOT EXISTS idx_sync_log_table ON _sync_log(table_name)
+    `);
+    await this.adapter.exec(`
+      CREATE INDEX IF NOT EXISTS idx_sync_log_synced ON _sync_log(synced_at)
+    `);
+    await this.adapter.exec(`
+      CREATE INDEX IF NOT EXISTS idx_sync_log_device ON _sync_log(device_id)
+    `);
+    await this.adapter.exec(`
+      CREATE TABLE IF NOT EXISTS _sync_devices (
+        device_id TEXT PRIMARY KEY,
+        device_type TEXT NOT NULL,
+        device_name TEXT,
+        vector_clock TEXT NOT NULL,
+        last_seen_at INTEGER NOT NULL,
+        created_at INTEGER NOT NULL
+      )
+    `);
+    await this.adapter.exec(`
+      CREATE TABLE IF NOT EXISTS _sync_conflicts (
+        conflict_id TEXT PRIMARY KEY,
+        table_name TEXT NOT NULL,
+        record_id TEXT NOT NULL,
+        local_data TEXT NOT NULL,
+        remote_data TEXT NOT NULL,
+        local_clock TEXT NOT NULL,
+        remote_clock TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'resolved', 'deferred')),
+        resolution TEXT,
+        created_at INTEGER NOT NULL,
+        resolved_at INTEGER
+      )
+    `);
+    await this.adapter.exec(`
+      CREATE INDEX IF NOT EXISTS idx_sync_conflicts_status ON _sync_conflicts(status)
+    `);
+  }
+  /**
+   * Load vector clock from database or create new one.
+   */
+  async loadVectorClock() {
+    const device = await this.adapter.get("SELECT * FROM _sync_devices WHERE device_id = ?", [this.deviceId]);
+    if (device) {
+      const clockData = JSON.parse(device.vectorClock);
+      this.vectorClock = new import_vectorClock.VectorClock(this.deviceId);
+      this.vectorClock.observe(clockData);
+    } else {
+      await this.registerDevice({
+        deviceId: this.deviceId,
+        deviceType: this.detectDeviceType(),
+        deviceName: this.getDeviceName()
+      });
+    }
+  }
+  // ============================================================================
+  // Change Logging
+  // ============================================================================
+  /**
+   * Log a database change.
+   */
+  async logChange(change) {
+    if (!this.shouldTrackTable(change.table)) {
+      throw new Error(`Table ${change.table} is not tracked`);
+    }
+    this.vectorClock.tick();
+    const changeId = this.generateChangeId();
+    const clockData = this.vectorClock.getValues();
+    const record = {
+      changeId,
+      table: change.table,
+      recordId: change.recordId,
+      operation: change.operation,
+      vectorClock: clockData,
+      deviceId: this.deviceId,
+      oldData: change.oldData,
+      newData: change.newData,
+      timestamp: Date.now()
+    };
+    await this.adapter.run(`INSERT INTO _sync_log
+       (change_id, table_name, record_id, operation, vector_clock, device_id, old_data, new_data, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      changeId,
+      change.table,
+      change.recordId,
+      change.operation,
+      JSON.stringify(clockData),
+      this.deviceId,
+      change.oldData ? JSON.stringify(change.oldData) : null,
+      change.newData ? JSON.stringify(change.newData) : null,
+      Date.now()
+    ]);
+    await this.updateDeviceClock();
+    await this.pruneIfNeeded();
+    return record;
+  }
+  /**
+   * Get changes since a vector clock.
+   */
+  async getChangesSince(sinceClock, options = {}) {
+    const { tables, limit = 1e3 } = options;
+    let query = `
+      SELECT * FROM _sync_log
+      WHERE synced_at IS NULL
+    `;
+    const params = [];
+    if (tables && tables.length > 0) {
+      query += ` AND table_name IN (${tables.map(() => "?").join(", ")})`;
+      params.push(...tables);
+    }
+    query += ` ORDER BY log_id ASC LIMIT ?`;
+    params.push(limit);
+    const entries = await this.adapter.all(query, params);
+    const changes = [];
+    for (const entry of entries) {
+      const entryClock = JSON.parse(entry.vectorClock);
+      if (this.isClockAfter(entryClock, sinceClock)) {
+        changes.push({
+          changeId: entry.changeId,
+          table: entry.tableName,
+          recordId: entry.recordId,
+          operation: entry.operation,
+          vectorClock: entryClock,
+          deviceId: entry.deviceId,
+          oldData: entry.oldData ? JSON.parse(entry.oldData) : void 0,
+          newData: entry.newData ? JSON.parse(entry.newData) : void 0,
+          timestamp: entry.createdAt
+        });
+      }
+    }
+    return changes;
+  }
+  /**
+   * Mark changes as synced.
+   */
+  async markSynced(changeIds) {
+    if (changeIds.length === 0)
+      return;
+    const placeholders = changeIds.map(() => "?").join(", ");
+    await this.adapter.run(`UPDATE _sync_log SET synced_at = ? WHERE change_id IN (${placeholders})`, [Date.now(), ...changeIds]);
+  }
+  /**
+   * Get unsynced change count.
+   */
+  async getUnsyncedCount() {
+    const result = await this.adapter.get("SELECT COUNT(*) as count FROM _sync_log WHERE synced_at IS NULL");
+    return result?.count ?? 0;
+  }
+  // ============================================================================
+  // Device Registry
+  // ============================================================================
+  /**
+   * Register a device.
+   */
+  async registerDevice(device) {
+    const existing = await this.adapter.get("SELECT * FROM _sync_devices WHERE device_id = ?", [device.deviceId]);
+    const clockData = this.vectorClock.getValues();
+    const now = Date.now();
+    if (existing) {
+      await this.adapter.run(`UPDATE _sync_devices
+         SET device_type = ?, device_name = ?, vector_clock = ?, last_seen_at = ?
+         WHERE device_id = ?`, [device.deviceType, device.deviceName ?? null, JSON.stringify(clockData), now, device.deviceId]);
+    } else {
+      await this.adapter.run(`INSERT INTO _sync_devices (device_id, device_type, device_name, vector_clock, last_seen_at, created_at)
+         VALUES (?, ?, ?, ?, ?, ?)`, [device.deviceId, device.deviceType, device.deviceName ?? null, JSON.stringify(clockData), now, now]);
+    }
+  }
+  /**
+   * Get all registered devices.
+   */
+  async getDevices() {
+    const entries = await this.adapter.all("SELECT * FROM _sync_devices ORDER BY last_seen_at DESC");
+    return entries.map((entry) => ({
+      deviceId: entry.deviceId,
+      deviceType: entry.deviceType,
+      deviceName: entry.deviceName ?? void 0,
+      lastSeen: entry.lastSeenAt,
+      firstSeen: entry.createdAt
+    }));
+  }
+  /**
+   * Update a device's vector clock.
+   */
+  async updateDeviceClockFor(deviceId, clock) {
+    await this.adapter.run("UPDATE _sync_devices SET vector_clock = ?, last_seen_at = ? WHERE device_id = ?", [JSON.stringify(clock), Date.now(), deviceId]);
+    this.vectorClock.observe(clock);
+  }
+  // ============================================================================
+  // Conflicts
+  // ============================================================================
+  /**
+   * Record a conflict.
+   */
+  async recordConflict(conflict) {
+    const conflictId = this.generateConflictId();
+    await this.adapter.run(`INSERT INTO _sync_conflicts
+       (conflict_id, table_name, record_id, local_data, remote_data, local_clock, remote_clock, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+      conflictId,
+      conflict.table,
+      conflict.recordId,
+      JSON.stringify(conflict.localData),
+      JSON.stringify(conflict.remoteData),
+      JSON.stringify(conflict.localClock),
+      JSON.stringify(conflict.remoteClock),
+      Date.now()
+    ]);
+    return conflictId;
+  }
+  /**
+   * Get pending conflicts.
+   */
+  async getPendingConflicts() {
+    return this.adapter.all("SELECT * FROM _sync_conflicts WHERE status = 'pending' ORDER BY created_at ASC");
+  }
+  /**
+   * Resolve a conflict.
+   */
+  async resolveConflict(conflictId, resolution) {
+    await this.adapter.run("UPDATE _sync_conflicts SET status = 'resolved', resolution = ?, resolved_at = ? WHERE conflict_id = ?", [resolution, Date.now(), conflictId]);
+  }
+  // ============================================================================
+  // Vector Clock
+  // ============================================================================
+  /**
+   * Get current vector clock.
+   */
+  getVectorClock() {
+    return this.vectorClock;
+  }
+  /**
+   * Get vector clock data.
+   */
+  getVectorClockData() {
+    return this.vectorClock.getValues();
+  }
+  /**
+   * Merge a remote clock into ours.
+   */
+  mergeVectorClock(remoteClock) {
+    this.vectorClock.merge(remoteClock);
+  }
+  // ============================================================================
+  // Utilities
+  // ============================================================================
+  /**
+   * Get device ID.
+   */
+  getDeviceId() {
+    return this.deviceId;
+  }
+  /**
+   * Update this device's clock in database.
+   */
+  async updateDeviceClock() {
+    await this.adapter.run("UPDATE _sync_devices SET vector_clock = ?, last_seen_at = ? WHERE device_id = ?", [JSON.stringify(this.vectorClock.getValues()), Date.now(), this.deviceId]);
+  }
+  /**
+   * Check if table should be tracked.
+   */
+  shouldTrackTable(table) {
+    if (this.config.excludeTables.includes(table)) {
+      return false;
+    }
+    if (this.config.includeTables.length > 0) {
+      return this.config.includeTables.includes(table);
+    }
+    return true;
+  }
+  /**
+   * Check if clock A is after clock B.
+   */
+  isClockAfter(a, b) {
+    let aGreater = false;
+    let bGreater = false;
+    const allDevices = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const deviceId of allDevices) {
+      const aValue = a[deviceId] ?? 0;
+      const bValue = b[deviceId] ?? 0;
+      if (aValue > bValue)
+        aGreater = true;
+      if (bValue > aValue)
+        bGreater = true;
+    }
+    return aGreater && !bGreater;
+  }
+  /**
+   * Generate unique change ID.
+   */
+  generateChangeId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 8);
+    return `chg_${timestamp}_${random}`;
+  }
+  /**
+   * Generate unique conflict ID.
+   */
+  generateConflictId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 8);
+    return `cnf_${timestamp}_${random}`;
+  }
+  /**
+   * Detect device type from environment.
+   */
+  detectDeviceType() {
+    if (typeof process !== "undefined" && process.versions?.electron) {
+      return "electron";
+    }
+    if (typeof window !== "undefined" && window.Capacitor) {
+      return "capacitor";
+    }
+    if (typeof window !== "undefined") {
+      return "browser";
+    }
+    return "server";
+  }
+  /**
+   * Get device name.
+   */
+  getDeviceName() {
+    if (typeof navigator !== "undefined") {
+      return navigator.userAgent.split("/")[0];
+    }
+    if (typeof process !== "undefined") {
+      return process.platform;
+    }
+    return void 0;
+  }
+  /**
+   * Prune old synced entries if over limit.
+   */
+  async pruneIfNeeded() {
+    const count = await this.adapter.get("SELECT COUNT(*) as count FROM _sync_log");
+    if ((count?.count ?? 0) > this.config.maxLogEntries) {
+      const deleteCount = (count?.count ?? 0) - this.config.maxLogEntries + 100;
+      await this.adapter.run(`DELETE FROM _sync_log WHERE log_id IN (
+          SELECT log_id FROM _sync_log
+          WHERE synced_at IS NOT NULL
+          ORDER BY log_id ASC
+          LIMIT ?
+        )`, [deleteCount]);
+    }
+  }
+}
+function createSyncLogManager(adapter, deviceId, config) {
+  return new SyncLogManager(adapter, deviceId, config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SyncLogManager,
+  createSyncLogManager
+});

package/dist/cjs/features/sync/transport/httpTransport.d.ts

@@ -0,0 +1,123 @@
+/**
+ * HTTP Polling Transport Implementation.
+ *
+ * Fallback sync transport using HTTP long-polling.
+ * Works through firewalls and proxies that block WebSocket.
+ *
+ * @packageDocumentation
+ */
+import { BaseTransport, type TransportOptions } from './transport.js';
+import type { SyncMessage } from '../protocol/messages.js';
+/**
+ * HTTP-specific transport options.
+ */
+export interface HttpTransportOptions extends TransportOptions {
+    /** Polling interval in milliseconds */
+    pollingInterval?: number;
+    /** Maximum messages to fetch per poll */
+    maxMessagesPerPoll?: number;
+    /** Enable long-polling (server holds connection) */
+    longPolling?: boolean;
+    /** Long-polling timeout in milliseconds */
+    longPollTimeout?: number;
+    /** Use fetch or XMLHttpRequest */
+    fetchImplementation?: typeof fetch;
+}
+/**
+ * HTTP transport for sync with polling.
+ *
+ * Provides reliable sync over HTTP with:
+ * - Regular or long-polling modes
+ * - Automatic retry with exponential backoff
+ * - Request batching
+ * - Configurable polling intervals
+ *
+ * @example
+ * ```typescript
+ * const transport = new HttpTransport({
+ *   endpoint: 'https://sync.example.com/api/sync',
+ *   authToken: 'bearer-token',
+ *   pollingInterval: 5000,
+ *   longPolling: true,
+ * });
+ *
+ * transport.on('message', ({ message }) => {
+ *   handleSyncMessage(message);
+ * });
+ *
+ * await transport.connect();
+ * ```
+ */
+export declare class HttpTransport extends BaseTransport {
+    readonly type: "http";
+    private _pollTimer;
+    private _abortController;
+    private _isPolling;
+    private _httpOptions;
+    private _lastEventId;
+    private _messageQueue;
+    private _flushTimer;
+    private _pendingRequests;
+    constructor(options: HttpTransportOptions);
+    /**
+     * Connect (start polling).
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect (stop polling).
+     */
+    disconnect(reason?: string): Promise<void>;
+    /**
+     * Send a sync message.
+     */
+    send(message: SyncMessage): Promise<void>;
+    /**
+     * Send a message and wait for a response.
+     */
+    request(message: SyncMessage, timeout?: number): Promise<SyncMessage>;
+    /**
+     * Perform initial sync check to verify connectivity.
+     */
+    private _syncCheck;
+    /**
+     * Start the polling loop.
+     */
+    private _startPolling;
+    /**
+     * Stop the polling loop.
+     */
+    private _stopPolling;
+    /**
+     * Poll for new messages.
+     */
+    private _poll;
+    /**
+     * Fetch messages from server.
+     */
+    private _fetchMessages;
+    /**
+     * Handle an incoming message.
+     */
+    private _handleMessage;
+    /**
+     * Schedule message queue flush.
+     */
+    private _scheduleFlush;
+    /**
+     * Flush the message queue to server.
+     */
+    private _flushQueue;
+    /**
+     * Make an HTTP request.
+     */
+    private _fetch;
+    /**
+     * Clear all pending requests.
+     */
+    private _clearPendingRequests;
+}
+/**
+ * Create an HTTP transport instance.
+ */
+export declare const createHttpTransport: (options: HttpTransportOptions) => HttpTransport;
+//# sourceMappingURL=httpTransport.d.ts.map