@framers/sql-storage-adapter 0.7.2 → 0.7.4

package/dist/cjs/adapters/electron/recovery/walCheckpoint.js

@@ -0,0 +1,263 @@
+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 walCheckpoint_exports = {};
+__export(walCheckpoint_exports, {
+  WalCheckpointManager: () => WalCheckpointManager,
+  createWalCheckpointManager: () => createWalCheckpointManager
+});
+module.exports = __toCommonJS(walCheckpoint_exports);
+const DEFAULT_CONFIG = {
+  checkpointInterval: 3e5,
+  // 5 minutes
+  strategy: "PASSIVE",
+  maxWalSize: 50 * 1024 * 1024,
+  // 50MB
+  pageSize: 4096,
+  autoCheckpointPages: 1e3,
+  synchronous: "NORMAL",
+  verbose: false
+};
+class WalCheckpointManager {
+  constructor(adapter, config = {}) {
+    this.adapter = adapter;
+    this.checkpointTimer = null;
+    this.lastCheckpoint = null;
+    this.totalCheckpoints = 0;
+    this.isRunning = false;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+  // ============================================================================
+  // Lifecycle Methods
+  // ============================================================================
+  /**
+   * Start the checkpoint manager.
+   */
+  async start() {
+    if (this.isRunning) {
+      this.log("Already running");
+      return;
+    }
+    await this.configureWalMode();
+    this.startCheckpointTimer();
+    this.isRunning = true;
+    this.log("WAL Checkpoint Manager started");
+  }
+  /**
+   * Stop the checkpoint manager.
+   */
+  async stop() {
+    if (!this.isRunning) {
+      return;
+    }
+    this.stopCheckpointTimer();
+    try {
+      await this.checkpoint("FULL");
+    } catch (error) {
+      this.log(`Final checkpoint failed: ${error}`);
+    }
+    this.isRunning = false;
+    this.log("WAL Checkpoint Manager stopped");
+  }
+  // ============================================================================
+  // WAL Configuration
+  // ============================================================================
+  /**
+   * Configure WAL mode on the database.
+   */
+  async configureWalMode() {
+    const pragmas = [
+      "PRAGMA journal_mode = WAL",
+      `PRAGMA synchronous = ${this.config.synchronous}`,
+      `PRAGMA wal_autocheckpoint = ${this.config.autoCheckpointPages}`,
+      `PRAGMA page_size = ${this.config.pageSize}`
+    ];
+    for (const pragma of pragmas) {
+      await this.adapter.exec(pragma);
+    }
+    this.log("WAL mode configured");
+  }
+  /**
+   * Disable WAL mode and switch back to DELETE journal mode.
+   */
+  async disableWalMode() {
+    await this.checkpoint("TRUNCATE");
+    await this.adapter.exec("PRAGMA journal_mode = DELETE");
+    this.log("WAL mode disabled");
+  }
+  // ============================================================================
+  // Checkpoint Operations
+  // ============================================================================
+  /**
+   * Perform a WAL checkpoint.
+   *
+   * @param strategy - Checkpoint strategy (defaults to config strategy)
+   * @returns Checkpoint result
+   */
+  async checkpoint(strategy) {
+    const effectiveStrategy = strategy ?? this.config.strategy;
+    const startTime = Date.now();
+    try {
+      const walBefore = await this.getWalFrameCount();
+      const result = await this.adapter.get(`PRAGMA wal_checkpoint(${effectiveStrategy})`);
+      const walAfter = await this.getWalFrameCount();
+      const checkpointResult = {
+        success: true,
+        strategy: effectiveStrategy,
+        walFramesBefore: walBefore,
+        walFramesAfter: walAfter,
+        framesCheckpointed: result?.checkpointed ?? 0,
+        busyFrames: result?.busy ?? 0,
+        durationMs: Date.now() - startTime,
+        timestamp: Date.now()
+      };
+      this.lastCheckpoint = Date.now();
+      this.totalCheckpoints++;
+      this.log(`Checkpoint completed: ${checkpointResult.framesCheckpointed} frames (${effectiveStrategy}, ${checkpointResult.durationMs}ms)`);
+      return checkpointResult;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.log(`Checkpoint failed: ${errorMessage}`);
+      return {
+        success: false,
+        strategy: effectiveStrategy,
+        walFramesBefore: 0,
+        walFramesAfter: 0,
+        framesCheckpointed: 0,
+        busyFrames: 0,
+        durationMs: Date.now() - startTime,
+        timestamp: Date.now(),
+        error: errorMessage
+      };
+    }
+  }
+  /**
+   * Force a full checkpoint that clears the WAL.
+   */
+  async forceFullCheckpoint() {
+    return this.checkpoint("TRUNCATE");
+  }
+  // ============================================================================
+  // Timer Management
+  // ============================================================================
+  /**
+   * Start the automatic checkpoint timer.
+   */
+  startCheckpointTimer() {
+    if (this.checkpointTimer) {
+      clearInterval(this.checkpointTimer);
+    }
+    this.checkpointTimer = setInterval(async () => {
+      try {
+        const walSize = await this.getWalSize();
+        const strategy = walSize > this.config.maxWalSize ? "FULL" : this.config.strategy;
+        await this.checkpoint(strategy);
+      } catch (error) {
+        this.log(`Periodic checkpoint failed: ${error}`);
+      }
+    }, this.config.checkpointInterval);
+  }
+  /**
+   * Stop the automatic checkpoint timer.
+   */
+  stopCheckpointTimer() {
+    if (this.checkpointTimer) {
+      clearInterval(this.checkpointTimer);
+      this.checkpointTimer = null;
+    }
+  }
+  // ============================================================================
+  // Status & Monitoring
+  // ============================================================================
+  /**
+   * Get current WAL status.
+   */
+  async getStatus() {
+    const journalMode = await this.adapter.get("PRAGMA journal_mode");
+    const walFrames = await this.getWalFrameCount();
+    const autoCheckpoint = await this.adapter.get("PRAGMA wal_autocheckpoint");
+    return {
+      enabled: journalMode?.journal_mode?.toLowerCase() === "wal",
+      walSize: walFrames * this.config.pageSize,
+      walPages: walFrames,
+      lastCheckpoint: this.lastCheckpoint,
+      totalCheckpoints: this.totalCheckpoints,
+      autoCheckpointThreshold: autoCheckpoint?.wal_autocheckpoint ?? this.config.autoCheckpointPages
+    };
+  }
+  /**
+   * Get current WAL size in bytes.
+   */
+  async getWalSize() {
+    const frames = await this.getWalFrameCount();
+    return frames * this.config.pageSize;
+  }
+  /**
+   * Get current WAL frame count.
+   */
+  async getWalFrameCount() {
+    const result = await this.adapter.get("PRAGMA wal_checkpoint(PASSIVE)");
+    return result?.log ?? 0;
+  }
+  /**
+   * Check if WAL mode is currently enabled.
+   */
+  async isWalEnabled() {
+    const result = await this.adapter.get("PRAGMA journal_mode");
+    return result?.journal_mode?.toLowerCase() === "wal";
+  }
+  // ============================================================================
+  // Utilities
+  // ============================================================================
+  /**
+   * Get checkpoint statistics.
+   */
+  getStats() {
+    return {
+      totalCheckpoints: this.totalCheckpoints,
+      lastCheckpoint: this.lastCheckpoint,
+      isRunning: this.isRunning,
+      checkpointInterval: this.config.checkpointInterval,
+      strategy: this.config.strategy
+    };
+  }
+  /**
+   * Update checkpoint configuration at runtime.
+   */
+  updateConfig(newConfig) {
+    Object.assign(this.config, newConfig);
+    if (this.isRunning && newConfig.checkpointInterval !== void 0) {
+      this.startCheckpointTimer();
+    }
+  }
+  /**
+   * Log a message if verbose mode is enabled.
+   */
+  log(message) {
+    if (this.config.verbose) {
+      console.log(`[WalCheckpointManager] ${message}`);
+    }
+  }
+}
+function createWalCheckpointManager(adapter, config = {}) {
+  return new WalCheckpointManager(adapter, config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WalCheckpointManager,
+  createWalCheckpointManager
+});

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

@@ -0,0 +1,9 @@
+/**
+ * The renderer-process entry, `@framers/sql-storage-adapter/electron/renderer`: the adapter a window uses over IPC,
+ * and nothing from the main process (better-sqlite3, the window manager, recovery, migration).
+ *
+ * @module
+ */
+export { ElectronRendererAdapter, createElectronRendererAdapter, isElectronRenderer, isPreloadApiAvailable, type ElectronRendererAdapterOptions, } from './electronRendererAdapter.js';
+export type { DbChangeEvent, SyncStatus } from './ipc/types.js';
+//# sourceMappingURL=renderer.d.ts.map

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

@@ -0,0 +1,33 @@
+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 renderer_exports = {};
+__export(renderer_exports, {
+  ElectronRendererAdapter: () => import_electronRendererAdapter.ElectronRendererAdapter,
+  createElectronRendererAdapter: () => import_electronRendererAdapter.createElectronRendererAdapter,
+  isElectronRenderer: () => import_electronRendererAdapter.isElectronRenderer,
+  isPreloadApiAvailable: () => import_electronRendererAdapter.isPreloadApiAvailable
+});
+module.exports = __toCommonJS(renderer_exports);
+var import_electronRendererAdapter = require("./electronRendererAdapter.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ElectronRendererAdapter,
+  createElectronRendererAdapter,
+  isElectronRenderer,
+  isPreloadApiAvailable
+});

package/dist/cjs/adapters/electron/window/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Window Management Module for Electron SQL Storage Adapter.
+ *
+ * Provides multi-window coordination and change broadcasting.
+ *
+ * @packageDocumentation
+ */
+export { WindowManager, createWindowManager, type WindowManagerConfig, type WindowManagerCallbacks, type RegisteredWindow, } from './windowManager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/adapters/electron/window/index.js

@@ -0,0 +1,29 @@
+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 window_exports = {};
+__export(window_exports, {
+  WindowManager: () => import_windowManager.WindowManager,
+  createWindowManager: () => import_windowManager.createWindowManager
+});
+module.exports = __toCommonJS(window_exports);
+var import_windowManager = require("./windowManager.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WindowManager,
+  createWindowManager
+});

package/dist/cjs/adapters/electron/window/windowManager.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Multi-Window Manager for Electron SQL Storage Adapter.
+ *
+ * Coordinates database access across multiple Electron windows.
+ * Broadcasts database changes to all windows and manages
+ * window-specific state.
+ *
+ * ## Features
+ * - Change broadcasting to all windows
+ * - Window registration and tracking
+ * - Focused window optimization
+ * - Connection state synchronization
+ *
+ * @example
+ * ```typescript
+ * const manager = new WindowManager({
+ *   broadcastChanges: true,
+ *   trackFocusedWindow: true,
+ * });
+ *
+ * manager.initialize();
+ *
+ * // Register a window
+ * manager.registerWindow(mainWindow);
+ *
+ * // Broadcast a change
+ * manager.broadcastChange({
+ *   type: 'insert',
+ *   tables: ['users'],
+ *   changes: 1,
+ * });
+ * ```
+ */
+import { BrowserWindow } from 'electron';
+import type { DbChangeEvent } from '../ipc/types.js';
+/**
+ * Window registration info.
+ */
+export interface RegisteredWindow {
+    /** Window ID */
+    id: number;
+    /** Window name/label */
+    name?: string;
+    /** Whether the window is currently focused */
+    isFocused: boolean;
+    /** When the window was registered */
+    registeredAt: number;
+    /** Last activity timestamp */
+    lastActivityAt: number;
+    /** Whether the window is subscribed to changes */
+    subscribedToChanges: boolean;
+}
+/**
+ * Window manager configuration.
+ */
+export interface WindowManagerConfig {
+    /** Broadcast changes to all windows (default: true) */
+    broadcastChanges?: boolean;
+    /** Track focused window for optimizations (default: true) */
+    trackFocusedWindow?: boolean;
+    /** Enable verbose logging (default: false) */
+    verbose?: boolean;
+    /** Exclude windows by name from broadcasts */
+    excludeWindows?: string[];
+}
+/**
+ * Window manager event callbacks.
+ */
+export interface WindowManagerCallbacks {
+    /** Called when a window is registered */
+    onWindowRegistered?: (window: RegisteredWindow) => void;
+    /** Called when a window is unregistered */
+    onWindowUnregistered?: (windowId: number) => void;
+    /** Called when focus changes */
+    onFocusChanged?: (windowId: number | null) => void;
+}
+/**
+ * Multi-Window Manager.
+ *
+ * Manages database access coordination across multiple Electron windows.
+ */
+export declare class WindowManager {
+    private readonly config;
+    private readonly callbacks;
+    private windows;
+    private focusedWindowId;
+    private isInitialized;
+    constructor(config?: WindowManagerConfig, callbacks?: WindowManagerCallbacks);
+    /**
+     * Initialize the window manager.
+     */
+    initialize(): void;
+    /**
+     * Dispose the window manager.
+     */
+    dispose(): void;
+    /**
+     * Set up focus tracking for all windows.
+     */
+    private setupFocusTracking;
+    /**
+     * Register a window for management.
+     */
+    registerWindow(window: BrowserWindow, name?: string): void;
+    /**
+     * Unregister a window.
+     */
+    unregisterWindow(windowId: number): void;
+    /**
+     * Handle window focus event.
+     */
+    private handleWindowFocus;
+    /**
+     * Handle window blur event.
+     */
+    private handleWindowBlur;
+    /**
+     * Broadcast a database change to all windows.
+     */
+    broadcastChange(change: Omit<DbChangeEvent, 'timestamp'>, excludeWindowId?: number): void;
+    /**
+     * Broadcast connection state change to all windows.
+     */
+    broadcastConnectionState(state: 'open' | 'closed' | 'error', error?: Error): void;
+    /**
+     * Send a message to a specific window.
+     */
+    sendToWindow(windowId: number, channel: string, data: unknown): boolean;
+    /**
+     * Send a message to the focused window.
+     */
+    sendToFocusedWindow(channel: string, data: unknown): boolean;
+    /**
+     * Subscribe a window to database changes.
+     */
+    subscribeWindow(windowId: number): void;
+    /**
+     * Unsubscribe a window from database changes.
+     */
+    unsubscribeWindow(windowId: number): void;
+    /**
+     * Get all registered windows.
+     */
+    getWindows(): RegisteredWindow[];
+    /**
+     * Get a specific window registration.
+     */
+    getWindow(windowId: number): RegisteredWindow | undefined;
+    /**
+     * Get the focused window ID.
+     */
+    getFocusedWindowId(): number | null;
+    /**
+     * Get the focused window registration.
+     */
+    getFocusedWindow(): RegisteredWindow | undefined;
+    /**
+     * Get window count.
+     */
+    getWindowCount(): number;
+    /**
+     * Check if a window is registered.
+     */
+    hasWindow(windowId: number): boolean;
+    /**
+     * Update window activity timestamp.
+     */
+    updateActivity(windowId: number): void;
+    /**
+     * Get statistics about windows.
+     */
+    getStats(): {
+        totalWindows: number;
+        subscribedWindows: number;
+        focusedWindowId: number | null;
+    };
+    /**
+     * Log a message if verbose mode is enabled.
+     */
+    private log;
+}
+/**
+ * Create a Window Manager.
+ *
+ * @param config - Manager configuration
+ * @param callbacks - Event callbacks
+ * @returns WindowManager instance
+ */
+export declare function createWindowManager(config?: WindowManagerConfig, callbacks?: WindowManagerCallbacks): WindowManager;
+//# sourceMappingURL=windowManager.d.ts.map