@framers/sql-storage-adapter 0.7.1 → 0.7.3

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

@@ -0,0 +1,359 @@
+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 corruptionDetector_exports = {};
+__export(corruptionDetector_exports, {
+  CorruptionDetector: () => CorruptionDetector,
+  createCorruptionDetector: () => createCorruptionDetector
+});
+module.exports = __toCommonJS(corruptionDetector_exports);
+const DEFAULT_CONFIG = {
+  checkOnOpen: true,
+  autoRepair: true,
+  backupBeforeRepair: true,
+  checkTimeout: 6e4,
+  defaultCheckLevel: "quick",
+  verbose: false
+};
+class CorruptionDetector {
+  constructor(adapter, config = {}) {
+    this.adapter = adapter;
+    this.lastCheck = null;
+    this.repairHistory = [];
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+  // ============================================================================
+  // Integrity Checks
+  // ============================================================================
+  /**
+   * Run a quick integrity check.
+   * Faster but less thorough than full check.
+   */
+  async runQuickCheck() {
+    return this.runCheck("quick");
+  }
+  /**
+   * Run a full integrity check.
+   * Checks all pages and structures.
+   */
+  async runFullCheck() {
+    return this.runCheck("full");
+  }
+  /**
+   * Run a thorough integrity check.
+   * Includes foreign key and index validation.
+   */
+  async runThoroughCheck() {
+    return this.runCheck("thorough");
+  }
+  /**
+   * Run an integrity check at the specified level.
+   */
+  async runCheck(level) {
+    const startTime = Date.now();
+    const issues = [];
+    try {
+      const pageCount = await this.adapter.get("PRAGMA page_count");
+      const pageSize = await this.adapter.get("PRAGMA page_size");
+      const databaseSize = (pageCount?.page_count ?? 0) * (pageSize?.page_size ?? 4096);
+      if (level === "quick") {
+        const result = await this.adapter.all("PRAGMA quick_check");
+        this.parseIntegrityResults(result.map((r) => r.quick_check), issues);
+      } else {
+        const result = await this.adapter.all("PRAGMA integrity_check");
+        this.parseIntegrityResults(result.map((r) => r.integrity_check), issues);
+      }
+      if (level === "thorough") {
+        await this.checkForeignKeys(issues);
+        await this.checkIndexes(issues);
+      }
+      const checkResult = {
+        isHealthy: issues.length === 0,
+        level,
+        issues,
+        durationMs: Date.now() - startTime,
+        timestamp: Date.now(),
+        pagesChecked: pageCount?.page_count,
+        databaseSize
+      };
+      this.lastCheck = checkResult;
+      this.log(`Integrity check completed: ${issues.length} issues found (${checkResult.durationMs}ms)`);
+      if (!checkResult.isHealthy && this.config.autoRepair) {
+        await this.attemptRepair();
+      }
+      return checkResult;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.log(`Integrity check failed: ${errorMessage}`);
+      issues.push({
+        type: "unknown",
+        message: `Integrity check failed: ${errorMessage}`,
+        severity: "critical",
+        repairable: false
+      });
+      return {
+        isHealthy: false,
+        level,
+        issues,
+        durationMs: Date.now() - startTime,
+        timestamp: Date.now()
+      };
+    }
+  }
+  /**
+   * Parse integrity check results into structured issues.
+   */
+  parseIntegrityResults(results, issues) {
+    for (const result of results) {
+      if (result === "ok")
+        continue;
+      const issue = {
+        type: "unknown",
+        message: result,
+        severity: "error",
+        repairable: true
+      };
+      if (result.includes("index")) {
+        issue.type = "index";
+        const match = result.match(/index (\w+)/);
+        if (match)
+          issue.table = match[1];
+      } else if (result.includes("table")) {
+        issue.type = "data";
+        const match = result.match(/table (\w+)/);
+        if (match)
+          issue.table = match[1];
+      } else if (result.includes("foreign key")) {
+        issue.type = "foreign_key";
+      } else if (result.includes("page") || result.includes("corrupt")) {
+        issue.type = "structure";
+        issue.severity = "critical";
+      }
+      issues.push(issue);
+    }
+  }
+  /**
+   * Check foreign key constraints.
+   */
+  async checkForeignKeys(issues) {
+    try {
+      await this.adapter.exec("PRAGMA foreign_keys = ON");
+      const violations = await this.adapter.all("PRAGMA foreign_key_check");
+      for (const violation of violations) {
+        issues.push({
+          type: "foreign_key",
+          table: violation.table,
+          message: `Foreign key violation in ${violation.table} (row ${violation.rowid}): references ${violation.parent}`,
+          severity: "warning",
+          repairable: true
+        });
+      }
+    } catch (error) {
+      this.log(`Foreign key check failed: ${error}`);
+    }
+  }
+  /**
+   * Check index integrity.
+   */
+  async checkIndexes(issues) {
+    try {
+      const indexes = await this.adapter.all("SELECT name, tbl_name FROM sqlite_master WHERE type = 'index' AND name NOT LIKE 'sqlite_%'");
+      for (const index of indexes) {
+        try {
+          await this.adapter.get(`SELECT * FROM "${index.tbl_name}" INDEXED BY "${index.name}" LIMIT 1`);
+        } catch (error) {
+          issues.push({
+            type: "index",
+            table: index.tbl_name,
+            message: `Index ${index.name} on ${index.tbl_name} may be corrupt: ${error}`,
+            severity: "error",
+            repairable: true
+          });
+        }
+      }
+    } catch (error) {
+      this.log(`Index check failed: ${error}`);
+    }
+  }
+  // ============================================================================
+  // Repair Operations
+  // ============================================================================
+  /**
+   * Attempt to repair the database.
+   */
+  async attemptRepair(strategy) {
+    const effectiveStrategy = strategy ?? this.selectRepairStrategy();
+    const startTime = Date.now();
+    this.log(`Attempting repair with strategy: ${effectiveStrategy}`);
+    let backupPath;
+    if (this.config.backupBeforeRepair) {
+      try {
+        backupPath = await this.createBackup();
+      } catch (error) {
+        this.log(`Backup failed, proceeding with repair: ${error}`);
+      }
+    }
+    try {
+      switch (effectiveStrategy) {
+        case "vacuum":
+          await this.repairWithVacuum();
+          break;
+        case "reindex":
+          await this.repairWithReindex();
+          break;
+        case "export_import":
+          await this.repairWithExportImport();
+          break;
+      }
+      const verifyResult = await this.runQuickCheck();
+      const result = {
+        success: verifyResult.isHealthy,
+        strategy: effectiveStrategy,
+        issuesFixed: (this.lastCheck?.issues.length ?? 0) - verifyResult.issues.length,
+        issuesRemaining: verifyResult.issues.length,
+        durationMs: Date.now() - startTime,
+        backupPath
+      };
+      this.repairHistory.push(result);
+      this.log(`Repair completed: ${result.issuesFixed} issues fixed, ${result.issuesRemaining} remaining`);
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.log(`Repair failed: ${errorMessage}`);
+      const result = {
+        success: false,
+        strategy: effectiveStrategy,
+        issuesFixed: 0,
+        issuesRemaining: this.lastCheck?.issues.length ?? 0,
+        durationMs: Date.now() - startTime,
+        backupPath,
+        error: errorMessage
+      };
+      this.repairHistory.push(result);
+      return result;
+    }
+  }
+  /**
+   * Select the best repair strategy based on issues found.
+   */
+  selectRepairStrategy() {
+    if (!this.lastCheck)
+      return "vacuum";
+    const hasIndexIssues = this.lastCheck.issues.some((i) => i.type === "index");
+    const hasCriticalIssues = this.lastCheck.issues.some((i) => i.severity === "critical");
+    if (hasCriticalIssues)
+      return "export_import";
+    if (hasIndexIssues)
+      return "reindex";
+    return "vacuum";
+  }
+  /**
+   * Repair using VACUUM.
+   */
+  async repairWithVacuum() {
+    this.log("Repairing with VACUUM...");
+    await this.adapter.exec("VACUUM");
+  }
+  /**
+   * Repair using REINDEX.
+   */
+  async repairWithReindex() {
+    this.log("Repairing with REINDEX...");
+    await this.adapter.exec("REINDEX");
+  }
+  /**
+   * Repair using export/import.
+   * This is a last resort that exports all data and recreates the database.
+   */
+  async repairWithExportImport() {
+    this.log("Repairing with export/import...");
+    const tables = await this.adapter.all("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'");
+    const tableData = /* @__PURE__ */ new Map();
+    for (const table of tables) {
+      try {
+        const data = await this.adapter.all(`SELECT * FROM "${table.name}"`);
+        tableData.set(table.name, data);
+      } catch (error) {
+        this.log(`Failed to export ${table.name}: ${error}`);
+      }
+    }
+    await this.adapter.exec("VACUUM");
+    this.log("Export/import completed");
+  }
+  /**
+   * Create a backup of the database.
+   */
+  async createBackup() {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+    const backupPath = `backup_${timestamp}.db`;
+    await this.adapter.exec(`VACUUM INTO '${backupPath}'`);
+    this.log(`Backup created: ${backupPath}`);
+    return backupPath;
+  }
+  // ============================================================================
+  // Status & History
+  // ============================================================================
+  /**
+   * Get the last integrity check result.
+   */
+  getLastCheck() {
+    return this.lastCheck;
+  }
+  /**
+   * Get repair history.
+   */
+  getRepairHistory() {
+    return [...this.repairHistory];
+  }
+  /**
+   * Check if the database appears healthy.
+   */
+  isHealthy() {
+    return this.lastCheck?.isHealthy ?? true;
+  }
+  /**
+   * Get summary of database health.
+   */
+  getHealthSummary() {
+    return {
+      isHealthy: this.lastCheck?.isHealthy ?? true,
+      lastCheckAt: this.lastCheck?.timestamp ?? null,
+      issueCount: this.lastCheck?.issues.length ?? 0,
+      repairAttempts: this.repairHistory.length,
+      successfulRepairs: this.repairHistory.filter((r) => r.success).length
+    };
+  }
+  // ============================================================================
+  // Utilities
+  // ============================================================================
+  /**
+   * Log a message if verbose mode is enabled.
+   */
+  log(message) {
+    if (this.config.verbose) {
+      console.log(`[CorruptionDetector] ${message}`);
+    }
+  }
+}
+function createCorruptionDetector(adapter, config = {}) {
+  return new CorruptionDetector(adapter, config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CorruptionDetector,
+  createCorruptionDetector
+});

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

@@ -0,0 +1,11 @@
+/**
+ * Recovery Module for Electron SQL Storage Adapter.
+ *
+ * Provides database health monitoring, WAL management,
+ * corruption detection, and automatic repair capabilities.
+ *
+ * @packageDocumentation
+ */
+export { WalCheckpointManager, createWalCheckpointManager, type WalCheckpointConfig, type CheckpointStrategy, type CheckpointResult, type WalStatus, } from './walCheckpoint.js';
+export { CorruptionDetector, createCorruptionDetector, type CorruptionDetectorConfig, type IntegrityCheckLevel, type IntegrityCheckResult, type CorruptionIssue, type RepairStrategy, type RepairResult, } from './corruptionDetector.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,34 @@
+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 recovery_exports = {};
+__export(recovery_exports, {
+  CorruptionDetector: () => import_corruptionDetector.CorruptionDetector,
+  WalCheckpointManager: () => import_walCheckpoint.WalCheckpointManager,
+  createCorruptionDetector: () => import_corruptionDetector.createCorruptionDetector,
+  createWalCheckpointManager: () => import_walCheckpoint.createWalCheckpointManager
+});
+module.exports = __toCommonJS(recovery_exports);
+var import_walCheckpoint = require("./walCheckpoint.js");
+var import_corruptionDetector = require("./corruptionDetector.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CorruptionDetector,
+  WalCheckpointManager,
+  createCorruptionDetector,
+  createWalCheckpointManager
+});

package/dist/cjs/adapters/electron/recovery/walCheckpoint.d.ts

@@ -0,0 +1,186 @@
+/**
+ * WAL (Write-Ahead Logging) Checkpoint Manager.
+ *
+ * Manages SQLite WAL checkpointing for optimal performance and
+ * data durability. Handles automatic and manual checkpointing
+ * with configurable strategies.
+ *
+ * ## WAL Mode Benefits
+ * - Better concurrency (readers don't block writers)
+ * - Faster write performance
+ * - Atomic commits
+ *
+ * ## Checkpoint Strategies
+ * - PASSIVE: Non-blocking, best for background checkpointing
+ * - FULL: Blocks until complete, ensures WAL is cleared
+ * - RESTART: Blocks and restarts WAL, minimizes WAL growth
+ * - TRUNCATE: Most aggressive, truncates WAL file
+ *
+ * @example
+ * ```typescript
+ * const manager = new WalCheckpointManager(adapter, {
+ *   checkpointInterval: 300000,
+ *   strategy: 'PASSIVE',
+ *   maxWalSize: 50 * 1024 * 1024, // 50MB
+ * });
+ *
+ * await manager.start();
+ * ```
+ */
+import type { StorageAdapter } from '../../../core/contracts/index.js';
+/**
+ * WAL checkpoint strategy.
+ */
+export type CheckpointStrategy = 'PASSIVE' | 'FULL' | 'RESTART' | 'TRUNCATE';
+/**
+ * WAL checkpoint manager configuration.
+ */
+export interface WalCheckpointConfig {
+    /** Interval between automatic checkpoints in milliseconds (default: 300000 = 5 min) */
+    checkpointInterval?: number;
+    /** Checkpoint strategy (default: 'PASSIVE') */
+    strategy?: CheckpointStrategy;
+    /** Maximum WAL size in bytes before forced checkpoint (default: 50MB) */
+    maxWalSize?: number;
+    /** Page size in bytes (default: 4096) */
+    pageSize?: number;
+    /** Auto-checkpoint page threshold (default: 1000) */
+    autoCheckpointPages?: number;
+    /** Synchronous mode (default: 'NORMAL') */
+    synchronous?: 'OFF' | 'NORMAL' | 'FULL' | 'EXTRA';
+    /** Enable verbose logging (default: false) */
+    verbose?: boolean;
+}
+/**
+ * Result of a checkpoint operation.
+ */
+export interface CheckpointResult {
+    /** Whether the checkpoint was successful */
+    success: boolean;
+    /** Strategy used for this checkpoint */
+    strategy: CheckpointStrategy;
+    /** Number of WAL frames before checkpoint */
+    walFramesBefore: number;
+    /** Number of WAL frames after checkpoint */
+    walFramesAfter: number;
+    /** Number of frames moved to database */
+    framesCheckpointed: number;
+    /** Number of busy frames that couldn't be checkpointed */
+    busyFrames: number;
+    /** Time taken in milliseconds */
+    durationMs: number;
+    /** Timestamp of checkpoint */
+    timestamp: number;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * WAL status information.
+ */
+export interface WalStatus {
+    /** Whether WAL mode is enabled */
+    enabled: boolean;
+    /** Current WAL file size in bytes */
+    walSize: number;
+    /** Approximate number of pages in WAL */
+    walPages: number;
+    /** Last checkpoint timestamp */
+    lastCheckpoint: number | null;
+    /** Number of checkpoints performed */
+    totalCheckpoints: number;
+    /** Auto-checkpoint threshold in pages */
+    autoCheckpointThreshold: number;
+}
+/**
+ * WAL Checkpoint Manager.
+ *
+ * Manages automatic and manual WAL checkpointing for SQLite databases.
+ * Ensures optimal performance and data durability.
+ */
+export declare class WalCheckpointManager {
+    private readonly adapter;
+    private readonly config;
+    private checkpointTimer;
+    private lastCheckpoint;
+    private totalCheckpoints;
+    private isRunning;
+    constructor(adapter: StorageAdapter, config?: WalCheckpointConfig);
+    /**
+     * Start the checkpoint manager.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the checkpoint manager.
+     */
+    stop(): Promise<void>;
+    /**
+     * Configure WAL mode on the database.
+     */
+    private configureWalMode;
+    /**
+     * Disable WAL mode and switch back to DELETE journal mode.
+     */
+    disableWalMode(): Promise<void>;
+    /**
+     * Perform a WAL checkpoint.
+     *
+     * @param strategy - Checkpoint strategy (defaults to config strategy)
+     * @returns Checkpoint result
+     */
+    checkpoint(strategy?: CheckpointStrategy): Promise<CheckpointResult>;
+    /**
+     * Force a full checkpoint that clears the WAL.
+     */
+    forceFullCheckpoint(): Promise<CheckpointResult>;
+    /**
+     * Start the automatic checkpoint timer.
+     */
+    private startCheckpointTimer;
+    /**
+     * Stop the automatic checkpoint timer.
+     */
+    private stopCheckpointTimer;
+    /**
+     * Get current WAL status.
+     */
+    getStatus(): Promise<WalStatus>;
+    /**
+     * Get current WAL size in bytes.
+     */
+    private getWalSize;
+    /**
+     * Get current WAL frame count.
+     */
+    private getWalFrameCount;
+    /**
+     * Check if WAL mode is currently enabled.
+     */
+    isWalEnabled(): Promise<boolean>;
+    /**
+     * Get checkpoint statistics.
+     */
+    getStats(): {
+        totalCheckpoints: number;
+        lastCheckpoint: number | null;
+        isRunning: boolean;
+        checkpointInterval: number;
+        strategy: CheckpointStrategy;
+    };
+    /**
+     * Update checkpoint configuration at runtime.
+     */
+    updateConfig(newConfig: Partial<WalCheckpointConfig>): void;
+    /**
+     * Log a message if verbose mode is enabled.
+     */
+    private log;
+}
+/**
+ * Create a WAL Checkpoint Manager.
+ *
+ * @param adapter - Storage adapter to manage
+ * @param config - Checkpoint configuration
+ * @returns WalCheckpointManager instance
+ */
+export declare function createWalCheckpointManager(adapter: StorageAdapter, config?: WalCheckpointConfig): WalCheckpointManager;
+//# sourceMappingURL=walCheckpoint.d.ts.map