@framers/sql-storage-adapter 0.7.1 → 0.7.3

package/dist/cjs/adapters/electron/electronMainAdapter.js

@@ -0,0 +1,392 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var electronMainAdapter_exports = {};
+__export(electronMainAdapter_exports, {
+  ElectronMainAdapter: () => ElectronMainAdapter,
+  createElectronMainAdapter: () => createElectronMainAdapter
+});
+module.exports = __toCommonJS(electronMainAdapter_exports);
+var import_path = __toESM(require("path"));
+var import_electron = require("electron");
+var import_betterSqliteAdapter = require("../betterSqliteAdapter.js");
+var import_protocol = require("./ipc/protocol.js");
+var import_channels = require("./ipc/channels.js");
+var import_segment = require("../../shared/segment.js");
+const DEFAULT_WAL_CONFIG = {
+  enabled: true,
+  checkpointInterval: 3e5,
+  // 5 minutes
+  autoCheckpointPages: 1e3,
+  synchronous: "NORMAL"
+};
+const DEFAULT_RECOVERY_CONFIG = {
+  enabled: true,
+  checkOnOpen: true,
+  autoRepair: true,
+  integrityCheckTimeout: 3e4
+};
+const DEFAULT_MULTI_WINDOW_CONFIG = {
+  enabled: true,
+  broadcastChanges: true
+};
+class ElectronMainAdapter {
+  constructor(options) {
+    this.kind = "electron-main";
+    this.isInitialized = false;
+    this.walCheckpointTimer = null;
+    this.backupTimer = null;
+    this.options = options;
+    this.walConfig = { ...DEFAULT_WAL_CONFIG, ...options.wal };
+    this.recoveryConfig = { ...DEFAULT_RECOVERY_CONFIG, ...options.recovery };
+    this.multiWindowConfig = { ...DEFAULT_MULTI_WINDOW_CONFIG, ...options.multiWindow };
+    this.filePath = (0, import_segment.segmentFilePath)(options.filePath, options.segment);
+    this.innerAdapter = (0, import_betterSqliteAdapter.createBetterSqliteAdapter)(options.filePath, { segment: options.segment });
+    const baseCapabilities = new Set(this.innerAdapter.capabilities);
+    baseCapabilities.add("batch");
+    this.capabilities = baseCapabilities;
+  }
+  // ============================================================================
+  // Lifecycle Methods
+  // ============================================================================
+  /**
+   * Open the database and initialize all subsystems.
+   */
+  async open(openOptions) {
+    if (this.isInitialized) {
+      this.log("Already initialized, skipping open()");
+      return;
+    }
+    try {
+      await this.innerAdapter.open(openOptions);
+      if (this.recoveryConfig.enabled && this.recoveryConfig.checkOnOpen) {
+        await this.runIntegrityCheck();
+      }
+      if (this.walConfig.enabled) {
+        await this.configureWalMode();
+        this.startWalCheckpointTimer();
+      }
+      if (this.options.segment === void 0) {
+        (0, import_protocol.initializeIpcProtocol)(this);
+      }
+      if (this.options.backup?.enabled && this.options.backup.provider) {
+        this.startBackupScheduler();
+      }
+      this.isInitialized = true;
+      this.log("Electron Main Adapter initialized successfully");
+    } catch (error) {
+      this.log(`Failed to initialize: ${error}`);
+      throw error;
+    }
+  }
+  /**
+   * Close the database and cleanup all subsystems.
+   */
+  async close() {
+    if (!this.isInitialized) {
+      return;
+    }
+    try {
+      if (this.walCheckpointTimer) {
+        clearInterval(this.walCheckpointTimer);
+        this.walCheckpointTimer = null;
+      }
+      if (this.backupTimer) {
+        clearInterval(this.backupTimer);
+        this.backupTimer = null;
+      }
+      if (this.walConfig.enabled) {
+        await this.runWalCheckpoint();
+      }
+      if (this.options.segment === void 0) {
+        (0, import_protocol.disposeIpcProtocol)();
+      }
+      await this.innerAdapter.close();
+      this.isInitialized = false;
+      this.log("Electron Main Adapter closed");
+    } catch (error) {
+      this.log(`Error during close: ${error}`);
+      throw error;
+    }
+  }
+  // ============================================================================
+  // Storage Adapter Interface
+  // ============================================================================
+  async run(statement, parameters) {
+    const result = await this.innerAdapter.run(statement, parameters);
+    if (this.multiWindowConfig.enabled && this.multiWindowConfig.broadcastChanges) {
+      this.broadcastChange({
+        type: this.detectMutationType(statement),
+        tables: this.extractTables(statement),
+        changes: result.changes,
+        timestamp: Date.now()
+      });
+    }
+    return result;
+  }
+  async get(statement, parameters) {
+    return this.innerAdapter.get(statement, parameters);
+  }
+  async all(statement, parameters) {
+    return this.innerAdapter.all(statement, parameters);
+  }
+  async exec(script) {
+    await this.innerAdapter.exec(script);
+    if (this.multiWindowConfig.enabled && this.multiWindowConfig.broadcastChanges) {
+      this.broadcastChange({
+        type: "transaction",
+        tables: [],
+        changes: 0,
+        timestamp: Date.now()
+      });
+    }
+  }
+  async transaction(fn) {
+    const result = await this.innerAdapter.transaction(fn);
+    if (this.multiWindowConfig.enabled && this.multiWindowConfig.broadcastChanges) {
+      this.broadcastChange({
+        type: "transaction",
+        tables: [],
+        changes: 0,
+        timestamp: Date.now()
+      });
+    }
+    return result;
+  }
+  async batch(operations) {
+    if (!this.innerAdapter.batch) {
+      throw new Error("Batch operations not supported");
+    }
+    const result = await this.innerAdapter.batch(operations);
+    if (this.multiWindowConfig.enabled && this.multiWindowConfig.broadcastChanges) {
+      this.broadcastChange({
+        type: "transaction",
+        tables: operations.flatMap((op) => this.extractTables(op.statement)),
+        changes: result.successful,
+        timestamp: Date.now()
+      });
+    }
+    return result;
+  }
+  prepare(statement) {
+    if (!this.innerAdapter.prepare) {
+      throw new Error("Prepared statements not supported");
+    }
+    return this.innerAdapter.prepare(statement);
+  }
+  // ============================================================================
+  // WAL Management
+  // ============================================================================
+  /**
+   * Configure WAL mode on the database.
+   */
+  async configureWalMode() {
+    await this.innerAdapter.exec(`
+      PRAGMA journal_mode = WAL;
+      PRAGMA synchronous = ${this.walConfig.synchronous};
+      PRAGMA wal_autocheckpoint = ${this.walConfig.autoCheckpointPages};
+    `);
+    this.log("WAL mode configured");
+  }
+  /**
+   * Start the WAL checkpoint timer.
+   */
+  startWalCheckpointTimer() {
+    if (this.walCheckpointTimer) {
+      clearInterval(this.walCheckpointTimer);
+    }
+    this.walCheckpointTimer = setInterval(() => this.runWalCheckpoint().catch((err) => this.log(`WAL checkpoint error: ${err}`)), this.walConfig.checkpointInterval);
+  }
+  /**
+   * Run a WAL checkpoint.
+   */
+  async runWalCheckpoint() {
+    const result = await this.innerAdapter.get("PRAGMA wal_checkpoint(PASSIVE)");
+    const checkpointResult = {
+      framesCheckpointed: result?.checkpointed ?? 0,
+      totalFrames: result?.log ?? 0
+    };
+    this.log(`WAL checkpoint: ${checkpointResult.framesCheckpointed}/${checkpointResult.totalFrames} frames`);
+    return checkpointResult;
+  }
+  // ============================================================================
+  // Integrity Check & Recovery
+  // ============================================================================
+  /**
+   * Run an integrity check on the database.
+   */
+  async runIntegrityCheck() {
+    const results = await this.innerAdapter.all("PRAGMA integrity_check");
+    const issues = results.map((r) => r.integrity_check).filter((msg) => msg !== "ok");
+    const ok = issues.length === 0;
+    if (!ok) {
+      this.log(`Integrity check found ${issues.length} issues`);
+      if (this.recoveryConfig.autoRepair) {
+        await this.attemptRepair();
+      }
+    } else {
+      this.log("Integrity check passed");
+    }
+    return { ok, issues };
+  }
+  /**
+   * Attempt to repair the database.
+   */
+  async attemptRepair() {
+    this.log("Attempting database repair...");
+    try {
+      await this.innerAdapter.exec("VACUUM");
+      this.log("VACUUM completed successfully");
+    } catch (error) {
+      this.log(`Repair failed: ${error}`);
+      throw new Error(`Database repair failed: ${error}`);
+    }
+  }
+  // ============================================================================
+  // Backup Management
+  // ============================================================================
+  /**
+   * Start the backup scheduler.
+   */
+  startBackupScheduler() {
+    const interval = this.options.backup?.interval ?? 36e5;
+    this.backupTimer = setInterval(() => this.runBackup().catch((err) => this.log(`Backup error: ${err}`)), interval);
+  }
+  /**
+   * Run a backup.
+   */
+  async runBackup() {
+    if (!this.options.backup?.provider) {
+      throw new Error("No backup provider configured");
+    }
+    const backupPath = `${this.filePath}.backup`;
+    const remotePath = `backups/${import_path.default.basename(this.filePath)}_${Date.now()}.db`;
+    await this.innerAdapter.exec(`VACUUM INTO '${backupPath}'`);
+    await this.options.backup.provider.upload(backupPath, remotePath);
+    await this.cleanupOldBackups();
+    this.log(`Backup completed: ${remotePath}`);
+  }
+  /**
+   * Cleanup old backups beyond the retention limit.
+   */
+  async cleanupOldBackups() {
+    if (!this.options.backup?.provider)
+      return;
+    const maxBackups = this.options.backup.maxBackups ?? 7;
+    const backups = await this.options.backup.provider.list();
+    if (backups.length > maxBackups) {
+      backups.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+      const toDelete = backups.slice(0, backups.length - maxBackups);
+      for (const backup of toDelete) {
+        await this.options.backup.provider.delete(backup.path);
+        this.log(`Deleted old backup: ${backup.path}`);
+      }
+    }
+  }
+  // ============================================================================
+  // Multi-Window Broadcasting
+  // ============================================================================
+  /**
+   * Broadcast a database change to all windows.
+   */
+  broadcastChange(change) {
+    const allWindows = import_electron.BrowserWindow.getAllWindows();
+    for (const win of allWindows) {
+      if (!win.isDestroyed()) {
+        win.webContents.send(import_channels.BROADCAST_CHANNELS.DB_CHANGE, change);
+      }
+    }
+  }
+  // ============================================================================
+  // Helper Methods
+  // ============================================================================
+  /**
+   * Detect mutation type from SQL statement.
+   */
+  detectMutationType(statement) {
+    const upper = statement.trim().toUpperCase();
+    if (upper.startsWith("INSERT"))
+      return "insert";
+    if (upper.startsWith("UPDATE"))
+      return "update";
+    if (upper.startsWith("DELETE"))
+      return "delete";
+    return "transaction";
+  }
+  /**
+   * Extract table names from SQL statement.
+   */
+  extractTables(statement) {
+    const tables = [];
+    const patterns = [
+      /FROM\s+([^\s,;(]+)/gi,
+      /INSERT\s+INTO\s+([^\s(]+)/gi,
+      /UPDATE\s+([^\s]+)/gi,
+      /DELETE\s+FROM\s+([^\s]+)/gi
+    ];
+    for (const pattern of patterns) {
+      const matches = statement.matchAll(pattern);
+      for (const match of matches) {
+        if (match[1]) {
+          tables.push(match[1].toLowerCase().replace(/["`[\]]/g, ""));
+        }
+      }
+    }
+    return [...new Set(tables)];
+  }
+  /**
+   * Log a message if verbose mode is enabled.
+   */
+  log(message) {
+    if (this.options.verbose) {
+      console.log(`[ElectronMainAdapter] ${message}`);
+    }
+  }
+  // ============================================================================
+  // Public Utilities
+  // ============================================================================
+  /**
+   * Check if the adapter is initialized.
+   */
+  isOpen() {
+    return this.isInitialized;
+  }
+  /**
+   * Get the database file path.
+   */
+  getFilePath() {
+    return this.filePath;
+  }
+}
+function createElectronMainAdapter(options) {
+  return new ElectronMainAdapter(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ElectronMainAdapter,
+  createElectronMainAdapter
+});

package/dist/cjs/adapters/electron/electronRendererAdapter.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Electron Renderer Process Storage Adapter.
+ *
+ * Provides the same StorageAdapter interface to renderer processes
+ * by proxying all operations to the main process via IPC.
+ *
+ * ## Architecture
+ * This adapter runs in renderer processes and communicates with
+ * ElectronMainAdapter in the main process via the preload script API.
+ *
+ * ## Requirements
+ * - Preload script must be loaded and expose `window.sqlStorage`
+ * - Main process must have ElectronMainAdapter initialized
+ *
+ * ## Usage
+ * ```typescript
+ * import { createElectronRendererAdapter } from '@framers/sql-storage-adapter/electron';
+ *
+ * const db = createElectronRendererAdapter({
+ *   onDatabaseChange: (change) => {
+ *     console.log('Database changed:', change);
+ *     // React to changes from other windows
+ *   },
+ * });
+ *
+ * await db.open();
+ * const users = await db.all('SELECT * FROM users');
+ * ```
+ */
+import type { StorageAdapter, StorageCapability, StorageOpenOptions, StorageParameters, StorageRunResult, BatchOperation, BatchResult, PreparedStatement } from '../../core/contracts/index.js';
+import type { DbChangeEvent, SyncStatus } from './ipc/types.js';
+/**
+ * Options for ElectronRendererAdapter.
+ */
+export interface ElectronRendererAdapterOptions {
+    /**
+     * Callback when database changes from another window.
+     * Use this to invalidate caches or refresh UI.
+     */
+    onDatabaseChange?: (event: DbChangeEvent) => void;
+    /**
+     * Callback when sync progress updates.
+     */
+    onSyncProgress?: (progress: number) => void;
+    /**
+     * Callback when sync completes.
+     */
+    onSyncComplete?: () => void;
+    /**
+     * Callback when sync encounters an error.
+     */
+    onSyncError?: (error: Error) => void;
+    /**
+     * Enable verbose logging (default: false).
+     */
+    verbose?: boolean;
+}
+/**
+ * Storage adapter for Electron renderer processes.
+ *
+ * Proxies all database operations to the main process via IPC.
+ * Implements the same StorageAdapter interface as other adapters.
+ */
+export declare class ElectronRendererAdapter implements StorageAdapter {
+    readonly kind = "electron-renderer";
+    capabilities: ReadonlySet<StorageCapability>;
+    private readonly options;
+    private eventUnsubscribers;
+    private isInitialized;
+    private cachedCapabilities;
+    constructor(options?: ElectronRendererAdapterOptions);
+    /**
+     * Get the preload API, throwing if not available.
+     */
+    private getApi;
+    /**
+     * Log a message if verbose mode is enabled.
+     */
+    private log;
+    /**
+     * Open connection to the database via main process.
+     */
+    open(options?: StorageOpenOptions): Promise<void>;
+    /**
+     * Close connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Subscribe to database events from main process.
+     */
+    private subscribeToEvents;
+    /**
+     * Execute a mutation statement (INSERT, UPDATE, DELETE).
+     */
+    run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
+    /**
+     * Get a single row.
+     */
+    get<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T | null>;
+    /**
+     * Get all matching rows.
+     */
+    all<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T[]>;
+    /**
+     * Execute a SQL script.
+     */
+    exec(script: string): Promise<void>;
+    /**
+     * Execute operations within a transaction.
+     */
+    transaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
+    /**
+     * Execute batch operations.
+     */
+    batch(operations: BatchOperation[]): Promise<BatchResult>;
+    /**
+     * Prepared statements are not directly supported in renderer.
+     * Use the main process adapter for prepared statements.
+     */
+    prepare?<T = unknown>(_statement: string): PreparedStatement<T>;
+    /**
+     * Get current sync status.
+     */
+    getSyncStatus(): Promise<SyncStatus>;
+    /**
+     * Trigger a manual sync.
+     */
+    triggerSync(): Promise<void>;
+    /**
+     * Assert that the adapter is open.
+     */
+    private assertOpen;
+    /**
+     * Check if the adapter is open.
+     */
+    isOpen(): boolean;
+    /**
+     * Check if the main process database is open.
+     */
+    isMainProcessOpen(): Promise<boolean>;
+    /**
+     * Add an event listener for database changes.
+     */
+    onDatabaseChange(callback: (event: DbChangeEvent) => void): () => void;
+}
+/**
+ * Create an Electron Renderer Process Storage Adapter.
+ *
+ * This adapter proxies all database operations to the main process
+ * via IPC. Use it in renderer processes to access the shared database.
+ *
+ * @param options - Adapter configuration
+ * @returns ElectronRendererAdapter instance
+ *
+ * @example
+ * ```typescript
+ * const db = createElectronRendererAdapter({
+ *   onDatabaseChange: (change) => {
+ *     console.log('Database changed:', change);
+ *     // Refresh data or invalidate caches
+ *   },
+ * });
+ *
+ * await db.open();
+ * const users = await db.all('SELECT * FROM users');
+ * ```
+ */
+export declare function createElectronRendererAdapter(options?: ElectronRendererAdapterOptions): ElectronRendererAdapter;
+/**
+ * Helper to detect if running in Electron renderer.
+ */
+export declare function isElectronRenderer(): boolean;
+/**
+ * Helper to check if preload API is available.
+ */
+export declare function isPreloadApiAvailable(): boolean;
+//# sourceMappingURL=electronRendererAdapter.d.ts.map