@framers/sql-storage-adapter 0.7.2 → 0.7.3

package/dist/cjs/features/sync/devices/deviceManager.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Device Registry and Presence Management.
+ *
+ * Manages device registration, presence tracking, and peer discovery
+ * for cross-platform sync.
+ *
+ * @packageDocumentation
+ */
+import type { StorageAdapter } from '../../../core/contracts/index.js';
+import type { VectorClock } from '../protocol/vectorClock.js';
+/**
+ * Device types supported for sync.
+ */
+export type DeviceType = 'electron' | 'capacitor' | 'browser' | 'server' | 'unknown';
+/**
+ * Device presence status.
+ */
+export type PresenceStatus = 'online' | 'away' | 'offline' | 'syncing';
+/**
+ * Information about a registered device.
+ */
+export interface DeviceInfo {
+    /** Unique device identifier */
+    deviceId: string;
+    /** Device type/platform */
+    deviceType: DeviceType;
+    /** Human-readable device name */
+    deviceName: string;
+    /** Device's current vector clock */
+    vectorClock: VectorClock;
+    /** When the device was first registered */
+    createdAt: number;
+    /** When the device was last seen */
+    lastSeenAt: number;
+    /** Current presence status */
+    presence: PresenceStatus;
+    /** Device capabilities */
+    capabilities: DeviceCapabilities;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Capabilities a device supports.
+ */
+export interface DeviceCapabilities {
+    /** Supports real-time sync */
+    realTimeSync: boolean;
+    /** Supports background sync */
+    backgroundSync: boolean;
+    /** Supports push notifications */
+    pushNotifications: boolean;
+    /** Supports offline mode */
+    offlineMode: boolean;
+    /** Maximum batch size */
+    maxBatchSize: number;
+}
+/**
+ * Device registration options.
+ */
+export interface DeviceRegistrationOptions {
+    /** Device name (auto-generated if not provided) */
+    name?: string;
+    /** Device type (auto-detected if not provided) */
+    type?: DeviceType;
+    /** Device capabilities */
+    capabilities?: Partial<DeviceCapabilities>;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Device presence event.
+ */
+export interface PresenceEvent {
+    deviceId: string;
+    previousStatus: PresenceStatus;
+    currentStatus: PresenceStatus;
+    timestamp: number;
+}
+/**
+ * Device manager event types.
+ */
+export type DeviceManagerEventType = 'deviceRegistered' | 'deviceUpdated' | 'deviceRemoved' | 'presenceChanged' | 'peerDiscovered' | 'peerLost';
+/**
+ * Device manager event payloads.
+ */
+export interface DeviceManagerEvents {
+    deviceRegistered: DeviceInfo;
+    deviceUpdated: {
+        device: DeviceInfo;
+        changes: Partial<DeviceInfo>;
+    };
+    deviceRemoved: {
+        deviceId: string;
+        reason: string;
+    };
+    presenceChanged: PresenceEvent;
+    peerDiscovered: DeviceInfo;
+    peerLost: {
+        deviceId: string;
+        lastSeenAt: number;
+    };
+}
+/**
+ * Device manager configuration.
+ */
+export interface DeviceManagerOptions {
+    /** Storage adapter for persisting device registry */
+    adapter: StorageAdapter;
+    /** Presence timeout in milliseconds (default: 60000) */
+    presenceTimeout?: number;
+    /** Heartbeat interval in milliseconds (default: 30000) */
+    heartbeatInterval?: number;
+    /** Auto-detect device info */
+    autoDetect?: boolean;
+    /** Initial device name */
+    deviceName?: string;
+}
+/**
+ * Device registry and presence manager.
+ *
+ * Manages device registration, presence tracking, and peer discovery
+ * across all connected devices in a sync cluster.
+ *
+ * @example
+ * ```typescript
+ * const manager = new DeviceManager({
+ *   adapter: db,
+ *   deviceName: 'MacBook Pro',
+ * });
+ *
+ * await manager.initialize();
+ *
+ * // Get current device
+ * const thisDevice = manager.getCurrentDevice();
+ *
+ * // Get all known peers
+ * const peers = await manager.getPeers();
+ *
+ * // Listen for presence changes
+ * manager.on('presenceChanged', (event) => {
+ *   console.log(`${event.deviceId} is now ${event.currentStatus}`);
+ * });
+ * ```
+ */
+export declare class DeviceManager {
+    private _adapter;
+    private _options;
+    private _currentDevice;
+    private _peers;
+    private _heartbeatTimer;
+    private _listeners;
+    private _initialized;
+    constructor(options: DeviceManagerOptions);
+    /**
+     * Initialize the device manager.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get the current device.
+     */
+    getCurrentDevice(): DeviceInfo | null;
+    /**
+     * Get all known peer devices.
+     */
+    getPeers(): Promise<DeviceInfo[]>;
+    /**
+     * Get online peers only.
+     */
+    getOnlinePeers(): Promise<DeviceInfo[]>;
+    /**
+     * Get a specific device by ID.
+     */
+    getDevice(deviceId: string): Promise<DeviceInfo | null>;
+    /**
+     * Update the current device's presence.
+     */
+    updatePresence(status: PresenceStatus): Promise<void>;
+    /**
+     * Update the current device's vector clock.
+     */
+    updateVectorClock(clock: VectorClock): Promise<void>;
+    /**
+     * Register or update a peer device.
+     */
+    registerPeer(peerInfo: DeviceInfo): Promise<void>;
+    /**
+     * Remove a device from the registry.
+     */
+    removeDevice(deviceId: string, reason?: string): Promise<void>;
+    /**
+     * Check for stale peers and update their presence.
+     */
+    checkStaleDevices(): Promise<void>;
+    /**
+     * Listen for device manager events.
+     */
+    on<T extends DeviceManagerEventType>(event: T, listener: (data: DeviceManagerEvents[T]) => void): () => void;
+    /**
+     * Dispose of the device manager.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Emit an event to listeners.
+     */
+    private _emit;
+    /**
+     * Ensure device tables exist.
+     */
+    private _ensureTables;
+    /**
+     * Initialize the current device.
+     */
+    private _initializeCurrentDevice;
+    /**
+     * Load stored device ID.
+     */
+    private _loadStoredDeviceId;
+    /**
+     * Store device ID for persistence.
+     */
+    private _storeDeviceId;
+    /**
+     * Load a device from the database.
+     */
+    private _loadDevice;
+    /**
+     * Save a device to the database.
+     */
+    private _saveDevice;
+    /**
+     * Load all peer devices.
+     */
+    private _loadPeers;
+    /**
+     * Start heartbeat timer.
+     */
+    private _startHeartbeat;
+}
+/**
+ * Create a device manager instance.
+ */
+export declare const createDeviceManager: (options: DeviceManagerOptions) => DeviceManager;
+//# sourceMappingURL=deviceManager.d.ts.map

package/dist/cjs/features/sync/devices/deviceManager.js

@@ -0,0 +1,450 @@
+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 deviceManager_exports = {};
+__export(deviceManager_exports, {
+  DeviceManager: () => DeviceManager,
+  createDeviceManager: () => createDeviceManager
+});
+module.exports = __toCommonJS(deviceManager_exports);
+var import_vectorClock = require("../protocol/vectorClock.js");
+const detectDeviceType = () => {
+  if (typeof process !== "undefined" && process.versions?.electron) {
+    return "electron";
+  }
+  if (typeof window !== "undefined") {
+    const win = window;
+    if (win.Capacitor?.isNativePlatform?.()) {
+      return "capacitor";
+    }
+  }
+  if (typeof process !== "undefined" && process.versions?.node && typeof window === "undefined") {
+    return "server";
+  }
+  if (typeof window !== "undefined") {
+    return "browser";
+  }
+  return "unknown";
+};
+const generateDeviceName = (type) => {
+  const timestamp = Date.now().toString(36).slice(-4);
+  switch (type) {
+    case "electron":
+      return `Desktop-${timestamp}`;
+    case "capacitor":
+      return `Mobile-${timestamp}`;
+    case "browser":
+      return `Browser-${timestamp}`;
+    case "server":
+      return `Server-${timestamp}`;
+    default:
+      return `Device-${timestamp}`;
+  }
+};
+const getDefaultCapabilities = (type) => {
+  switch (type) {
+    case "electron":
+      return {
+        realTimeSync: true,
+        backgroundSync: true,
+        pushNotifications: true,
+        offlineMode: true,
+        maxBatchSize: 1e3
+      };
+    case "capacitor":
+      return {
+        realTimeSync: true,
+        backgroundSync: true,
+        pushNotifications: true,
+        offlineMode: true,
+        maxBatchSize: 500
+      };
+    case "browser":
+      return {
+        realTimeSync: true,
+        backgroundSync: false,
+        pushNotifications: false,
+        offlineMode: true,
+        maxBatchSize: 500
+      };
+    case "server":
+      return {
+        realTimeSync: true,
+        backgroundSync: true,
+        pushNotifications: false,
+        offlineMode: false,
+        maxBatchSize: 1e4
+      };
+    default:
+      return {
+        realTimeSync: false,
+        backgroundSync: false,
+        pushNotifications: false,
+        offlineMode: false,
+        maxBatchSize: 100
+      };
+  }
+};
+class DeviceManager {
+  constructor(options) {
+    this._currentDevice = null;
+    this._peers = /* @__PURE__ */ new Map();
+    this._heartbeatTimer = null;
+    this._listeners = /* @__PURE__ */ new Map();
+    this._initialized = false;
+    this._adapter = options.adapter;
+    this._options = {
+      adapter: options.adapter,
+      presenceTimeout: options.presenceTimeout ?? 6e4,
+      heartbeatInterval: options.heartbeatInterval ?? 3e4,
+      autoDetect: options.autoDetect ?? true,
+      deviceName: options.deviceName ?? ""
+    };
+  }
+  /**
+   * Initialize the device manager.
+   */
+  async initialize() {
+    if (this._initialized)
+      return;
+    await this._ensureTables();
+    await this._initializeCurrentDevice();
+    await this._loadPeers();
+    this._startHeartbeat();
+    this._initialized = true;
+  }
+  /**
+   * Get the current device.
+   */
+  getCurrentDevice() {
+    return this._currentDevice;
+  }
+  /**
+   * Get all known peer devices.
+   */
+  async getPeers() {
+    return Array.from(this._peers.values());
+  }
+  /**
+   * Get online peers only.
+   */
+  async getOnlinePeers() {
+    const now = Date.now();
+    const timeout = this._options.presenceTimeout;
+    return Array.from(this._peers.values()).filter((peer) => {
+      return now - peer.lastSeenAt < timeout;
+    });
+  }
+  /**
+   * Get a specific device by ID.
+   */
+  async getDevice(deviceId) {
+    if (deviceId === this._currentDevice?.deviceId) {
+      return this._currentDevice;
+    }
+    return this._peers.get(deviceId) ?? null;
+  }
+  /**
+   * Update the current device's presence.
+   */
+  async updatePresence(status) {
+    if (!this._currentDevice)
+      return;
+    const previous = this._currentDevice.presence;
+    this._currentDevice.presence = status;
+    this._currentDevice.lastSeenAt = Date.now();
+    await this._saveDevice(this._currentDevice);
+    this._emit("presenceChanged", {
+      deviceId: this._currentDevice.deviceId,
+      previousStatus: previous,
+      currentStatus: status,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Update the current device's vector clock.
+   */
+  async updateVectorClock(clock) {
+    if (!this._currentDevice)
+      return;
+    this._currentDevice.vectorClock = clock;
+    this._currentDevice.lastSeenAt = Date.now();
+    await this._saveDevice(this._currentDevice);
+  }
+  /**
+   * Register or update a peer device.
+   */
+  async registerPeer(peerInfo) {
+    const existing = this._peers.get(peerInfo.deviceId);
+    if (existing) {
+      const changes = {};
+      if (peerInfo.lastSeenAt > existing.lastSeenAt) {
+        Object.assign(existing, peerInfo);
+        this._emit("deviceUpdated", { device: existing, changes: peerInfo });
+      }
+    } else {
+      this._peers.set(peerInfo.deviceId, peerInfo);
+      await this._saveDevice(peerInfo);
+      this._emit("peerDiscovered", peerInfo);
+    }
+  }
+  /**
+   * Remove a device from the registry.
+   */
+  async removeDevice(deviceId, reason = "removed") {
+    if (deviceId === this._currentDevice?.deviceId) {
+      throw new Error("Cannot remove current device");
+    }
+    const device = this._peers.get(deviceId);
+    if (!device)
+      return;
+    this._peers.delete(deviceId);
+    await this._adapter.run("DELETE FROM _sync_devices WHERE device_id = ?", [deviceId]);
+    this._emit("deviceRemoved", { deviceId, reason });
+  }
+  /**
+   * Check for stale peers and update their presence.
+   */
+  async checkStaleDevices() {
+    const now = Date.now();
+    const timeout = this._options.presenceTimeout;
+    for (const peer of this._peers.values()) {
+      if (peer.presence !== "offline" && now - peer.lastSeenAt > timeout) {
+        const previousStatus = peer.presence;
+        peer.presence = "offline";
+        this._emit("presenceChanged", {
+          deviceId: peer.deviceId,
+          previousStatus,
+          currentStatus: "offline",
+          timestamp: now
+        });
+        this._emit("peerLost", {
+          deviceId: peer.deviceId,
+          lastSeenAt: peer.lastSeenAt
+        });
+      }
+    }
+  }
+  /**
+   * Listen for device manager events.
+   */
+  on(event, listener) {
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    const listeners = this._listeners.get(event);
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+  /**
+   * Dispose of the device manager.
+   */
+  async dispose() {
+    if (this._heartbeatTimer) {
+      clearInterval(this._heartbeatTimer);
+      this._heartbeatTimer = null;
+    }
+    if (this._currentDevice) {
+      await this.updatePresence("offline");
+    }
+    this._listeners.clear();
+    this._peers.clear();
+    this._currentDevice = null;
+    this._initialized = false;
+  }
+  /**
+   * Emit an event to listeners.
+   */
+  _emit(event, data) {
+    const listeners = this._listeners.get(event);
+    if (!listeners)
+      return;
+    for (const listener of listeners) {
+      try {
+        listener(data);
+      } catch (error) {
+        console.error(`[DeviceManager] Error in ${event} listener:`, error);
+      }
+    }
+  }
+  /**
+   * Ensure device tables exist.
+   */
+  async _ensureTables() {
+    await this._adapter.exec(`
+      CREATE TABLE IF NOT EXISTS _sync_devices (
+        device_id TEXT PRIMARY KEY,
+        device_type TEXT NOT NULL,
+        device_name TEXT NOT NULL,
+        vector_clock TEXT NOT NULL,
+        capabilities TEXT NOT NULL,
+        metadata TEXT,
+        presence TEXT DEFAULT 'offline',
+        created_at INTEGER NOT NULL,
+        last_seen_at INTEGER NOT NULL
+      )
+    `);
+  }
+  /**
+   * Initialize the current device.
+   */
+  async _initializeCurrentDevice() {
+    const storedId = await this._loadStoredDeviceId();
+    if (storedId) {
+      const device2 = await this._loadDevice(storedId);
+      if (device2) {
+        device2.presence = "online";
+        device2.lastSeenAt = Date.now();
+        await this._saveDevice(device2);
+        this._currentDevice = device2;
+        return;
+      }
+    }
+    const deviceType = this._options.autoDetect ? detectDeviceType() : "unknown";
+    const deviceName = this._options.deviceName || generateDeviceName(deviceType);
+    const deviceId = (0, import_vectorClock.generateDeviceId)();
+    const device = {
+      deviceId,
+      deviceType,
+      deviceName,
+      vectorClock: (0, import_vectorClock.createVectorClock)(deviceId),
+      createdAt: Date.now(),
+      lastSeenAt: Date.now(),
+      presence: "online",
+      capabilities: getDefaultCapabilities(deviceType)
+    };
+    await this._saveDevice(device);
+    await this._storeDeviceId(deviceId);
+    this._currentDevice = device;
+    this._emit("deviceRegistered", device);
+  }
+  /**
+   * Load stored device ID.
+   */
+  async _loadStoredDeviceId() {
+    try {
+      if (typeof localStorage !== "undefined") {
+        return localStorage.getItem("_sync_device_id");
+      }
+      const result = await this._adapter.get("SELECT value FROM _sync_settings WHERE key = ?", ["device_id"]);
+      return result?.value ?? null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Store device ID for persistence.
+   */
+  async _storeDeviceId(deviceId) {
+    try {
+      if (typeof localStorage !== "undefined") {
+        localStorage.setItem("_sync_device_id", deviceId);
+        return;
+      }
+      await this._adapter.exec(`
+        CREATE TABLE IF NOT EXISTS _sync_settings (
+          key TEXT PRIMARY KEY,
+          value TEXT NOT NULL
+        )
+      `);
+      await this._adapter.run("INSERT OR REPLACE INTO _sync_settings (key, value) VALUES (?, ?)", ["device_id", deviceId]);
+    } catch (error) {
+      console.warn("[DeviceManager] Failed to persist device ID:", error);
+    }
+  }
+  /**
+   * Load a device from the database.
+   */
+  async _loadDevice(deviceId) {
+    const row = await this._adapter.get("SELECT * FROM _sync_devices WHERE device_id = ?", [deviceId]);
+    if (!row)
+      return null;
+    return {
+      deviceId: row.device_id,
+      deviceType: row.device_type,
+      deviceName: row.device_name,
+      vectorClock: JSON.parse(row.vector_clock),
+      capabilities: JSON.parse(row.capabilities),
+      metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
+      presence: row.presence,
+      createdAt: row.created_at,
+      lastSeenAt: row.last_seen_at
+    };
+  }
+  /**
+   * Save a device to the database.
+   */
+  async _saveDevice(device) {
+    await this._adapter.run(`INSERT OR REPLACE INTO _sync_devices
+       (device_id, device_type, device_name, vector_clock, capabilities, metadata, presence, created_at, last_seen_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+      device.deviceId,
+      device.deviceType,
+      device.deviceName,
+      JSON.stringify(device.vectorClock),
+      JSON.stringify(device.capabilities),
+      device.metadata ? JSON.stringify(device.metadata) : null,
+      device.presence,
+      device.createdAt,
+      device.lastSeenAt
+    ]);
+  }
+  /**
+   * Load all peer devices.
+   */
+  async _loadPeers() {
+    const rows = await this._adapter.all("SELECT * FROM _sync_devices WHERE device_id != ?", [this._currentDevice?.deviceId ?? ""]);
+    for (const row of rows) {
+      const device = {
+        deviceId: row.device_id,
+        deviceType: row.device_type,
+        deviceName: row.device_name,
+        vectorClock: JSON.parse(row.vector_clock),
+        capabilities: JSON.parse(row.capabilities),
+        metadata: row.metadata ? JSON.parse(row.metadata) : void 0,
+        presence: row.presence,
+        createdAt: row.created_at,
+        lastSeenAt: row.last_seen_at
+      };
+      this._peers.set(device.deviceId, device);
+    }
+  }
+  /**
+   * Start heartbeat timer.
+   */
+  _startHeartbeat() {
+    if (this._heartbeatTimer)
+      return;
+    this._heartbeatTimer = setInterval(async () => {
+      if (this._currentDevice) {
+        this._currentDevice.lastSeenAt = Date.now();
+        await this._saveDevice(this._currentDevice);
+      }
+      await this.checkStaleDevices();
+    }, this._options.heartbeatInterval);
+  }
+}
+const createDeviceManager = (options) => {
+  return new DeviceManager(options);
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DeviceManager,
+  createDeviceManager
+});

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

@@ -0,0 +1,10 @@
+/**
+ * Device Management Module.
+ *
+ * Provides device registry and presence management
+ * for cross-platform sync.
+ *
+ * @packageDocumentation
+ */
+export * from './deviceManager.js';
+//# sourceMappingURL=index.d.ts.map