@framers/sql-storage-adapter 0.7.2 → 0.7.3

package/dist/cjs/adapters/electron/migration/autoMigrator.js

@@ -0,0 +1,441 @@
+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 autoMigrator_exports = {};
+__export(autoMigrator_exports, {
+  AutoMigrator: () => AutoMigrator,
+  createAutoMigrator: () => createAutoMigrator
+});
+module.exports = __toCommonJS(autoMigrator_exports);
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+const DEFAULT_CONFIG = {
+  runOnVersionChange: true,
+  tableName: "_migrations",
+  verbose: false
+};
+class AutoMigrator {
+  constructor(adapter, config) {
+    this.adapter = adapter;
+    this.migrations = [];
+    this.isInitialized = false;
+    this.lastMigrationResult = null;
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      getAppVersion: config.getAppVersion ?? this.defaultGetAppVersion.bind(this)
+    };
+  }
+  // ============================================================================
+  // Initialization
+  // ============================================================================
+  /**
+   * Initialize the migration system.
+   */
+  async initialize() {
+    if (this.isInitialized)
+      return;
+    await this.createMigrationsTable();
+    this.migrations = await this.loadMigrations();
+    if (this.config.runOnVersionChange) {
+      const shouldRun = await this.shouldRunMigrations();
+      if (shouldRun) {
+        this.log("App version changed, running migrations...");
+        await this.runPending();
+      }
+    }
+    this.isInitialized = true;
+    this.log(`AutoMigrator initialized with ${this.migrations.length} migrations`);
+  }
+  /**
+   * Create the migrations tracking table.
+   */
+  async createMigrationsTable() {
+    await this.adapter.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.config.tableName} (
+        version INTEGER PRIMARY KEY,
+        name TEXT NOT NULL,
+        applied_at INTEGER NOT NULL,
+        app_version TEXT NOT NULL,
+        checksum TEXT NOT NULL
+      )
+    `);
+  }
+  // ============================================================================
+  // Migration Discovery
+  // ============================================================================
+  /**
+   * Load all migration files from the migrations directory.
+   */
+  async loadMigrations() {
+    const migrationsPath = this.config.migrationsPath;
+    if (!import_fs.default.existsSync(migrationsPath)) {
+      this.log(`Migrations directory not found: ${migrationsPath}`);
+      return [];
+    }
+    const files = import_fs.default.readdirSync(migrationsPath).filter((f) => f.endsWith(".sql") || f.endsWith(".js") || f.endsWith(".ts")).sort();
+    const migrations = [];
+    for (const file of files) {
+      const filePath = import_path.default.join(migrationsPath, file);
+      const migration = await this.parseMigrationFile(filePath);
+      if (migration) {
+        migrations.push(migration);
+      }
+    }
+    migrations.sort((a, b) => a.version - b.version);
+    return migrations;
+  }
+  /**
+   * Parse a migration file.
+   */
+  async parseMigrationFile(filePath) {
+    const fileName = import_path.default.basename(filePath);
+    const ext = import_path.default.extname(filePath);
+    const match = fileName.match(/^(\d+)[_-](.+)\.(sql|js|ts)$/);
+    if (!match) {
+      this.log(`Skipping invalid migration filename: ${fileName}`);
+      return null;
+    }
+    const version = parseInt(match[1], 10);
+    const name = match[2];
+    if (ext === ".sql") {
+      return this.parseSqlMigration(filePath, version, name);
+    } else {
+      return this.parseJsMigration(filePath, version, name);
+    }
+  }
+  /**
+   * Parse a SQL migration file.
+   * Supports UP and DOWN sections separated by `-- DOWN`.
+   */
+  parseSqlMigration(filePath, version, name) {
+    const content = import_fs.default.readFileSync(filePath, "utf-8");
+    const parts = content.split(/^--\s*DOWN\s*$/im);
+    const up = parts[0].trim();
+    const down = parts[1]?.trim();
+    return { version, name, path: filePath, up, down };
+  }
+  /**
+   * Parse a JS/TS migration file.
+   * Expects exports: { up: string, down?: string }
+   */
+  async parseJsMigration(filePath, version, name) {
+    try {
+      const module2 = await Promise.resolve().then(() => __toESM(require(filePath)));
+      const exports2 = module2.default ?? module2;
+      if (!exports2.up) {
+        this.log(`Migration ${name} missing 'up' export`);
+        return null;
+      }
+      return {
+        version,
+        name,
+        path: filePath,
+        up: typeof exports2.up === "function" ? await exports2.up() : exports2.up,
+        down: typeof exports2.down === "function" ? await exports2.down() : exports2.down
+      };
+    } catch (error) {
+      this.log(`Failed to load migration ${name}: ${error}`);
+      return null;
+    }
+  }
+  // ============================================================================
+  // Migration Execution
+  // ============================================================================
+  /**
+   * Run all pending migrations.
+   */
+  async runPending() {
+    const startTime = Date.now();
+    const applied = await this.getAppliedMigrations();
+    const appliedVersions = new Set(applied.map((m) => m.version));
+    const pending = this.migrations.filter((m) => !appliedVersions.has(m.version));
+    if (pending.length === 0) {
+      this.log("No pending migrations");
+      return {
+        success: true,
+        migrationsRun: 0,
+        migrationsFailed: 0,
+        duration: Date.now() - startTime,
+        appliedMigrations: [],
+        errors: []
+      };
+    }
+    const result = {
+      success: true,
+      migrationsRun: 0,
+      migrationsFailed: 0,
+      duration: 0,
+      appliedMigrations: [],
+      errors: []
+    };
+    for (const migration of pending) {
+      try {
+        await this.applyMigration(migration);
+        result.migrationsRun++;
+        result.appliedMigrations.push(migration.name);
+        this.log(`Applied migration: ${migration.name}`);
+      } catch (error) {
+        result.migrationsFailed++;
+        result.success = false;
+        result.errors.push({
+          migration: migration.name,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        this.log(`Failed migration: ${migration.name} - ${error}`);
+        break;
+      }
+    }
+    result.duration = Date.now() - startTime;
+    this.lastMigrationResult = result;
+    return result;
+  }
+  /**
+   * Run a single migration.
+   */
+  async applyMigration(migration) {
+    const appVersion = this.config.getAppVersion();
+    const checksum = this.calculateChecksum(migration.up);
+    await this.adapter.transaction(async (trx) => {
+      await trx.exec(migration.up);
+      await trx.run(`INSERT INTO ${this.config.tableName} (version, name, applied_at, app_version, checksum) VALUES (?, ?, ?, ?, ?)`, [migration.version, migration.name, Date.now(), appVersion, checksum]);
+    });
+  }
+  /**
+   * Run a specific migration by version.
+   */
+  async runMigrationByVersion(version) {
+    const migration = this.migrations.find((m) => m.version === version);
+    if (!migration) {
+      throw new Error(`Migration version ${version} not found`);
+    }
+    await this.applyMigration(migration);
+  }
+  // ============================================================================
+  // Rollback
+  // ============================================================================
+  /**
+   * Rollback the last applied migration.
+   */
+  async rollbackLast() {
+    const startTime = Date.now();
+    const applied = await this.getAppliedMigrations();
+    if (applied.length === 0) {
+      return {
+        success: true,
+        migrationsRun: 0,
+        migrationsFailed: 0,
+        duration: Date.now() - startTime,
+        appliedMigrations: [],
+        errors: []
+      };
+    }
+    const lastApplied = applied[applied.length - 1];
+    const migration = this.migrations.find((m) => m.version === lastApplied.version);
+    if (!migration) {
+      throw new Error(`Migration ${lastApplied.version} not found in migration files`);
+    }
+    if (!migration.down) {
+      throw new Error(`Migration ${migration.name} does not have a rollback script`);
+    }
+    try {
+      await this.adapter.transaction(async (trx) => {
+        await trx.exec(migration.down);
+        await trx.run(`DELETE FROM ${this.config.tableName} WHERE version = ?`, [migration.version]);
+      });
+      this.log(`Rolled back migration: ${migration.name}`);
+      return {
+        success: true,
+        migrationsRun: 1,
+        migrationsFailed: 0,
+        duration: Date.now() - startTime,
+        appliedMigrations: [migration.name],
+        errors: []
+      };
+    } catch (error) {
+      return {
+        success: false,
+        migrationsRun: 0,
+        migrationsFailed: 1,
+        duration: Date.now() - startTime,
+        appliedMigrations: [],
+        errors: [{
+          migration: migration.name,
+          error: error instanceof Error ? error.message : String(error)
+        }]
+      };
+    }
+  }
+  /**
+   * Rollback to a specific version.
+   */
+  async rollbackTo(targetVersion) {
+    const startTime = Date.now();
+    const applied = await this.getAppliedMigrations();
+    const toRollback = applied.filter((m) => m.version > targetVersion).reverse();
+    const result = {
+      success: true,
+      migrationsRun: 0,
+      migrationsFailed: 0,
+      duration: 0,
+      appliedMigrations: [],
+      errors: []
+    };
+    for (const migration of toRollback) {
+      const migrationFile = this.migrations.find((m) => m.version === migration.version);
+      if (!migrationFile?.down) {
+        result.migrationsFailed++;
+        result.success = false;
+        result.errors.push({
+          migration: migration.name,
+          error: "No rollback script available"
+        });
+        break;
+      }
+      try {
+        await this.adapter.transaction(async (trx) => {
+          await trx.exec(migrationFile.down);
+          await trx.run(`DELETE FROM ${this.config.tableName} WHERE version = ?`, [migration.version]);
+        });
+        result.migrationsRun++;
+        result.appliedMigrations.push(migration.name);
+      } catch (error) {
+        result.migrationsFailed++;
+        result.success = false;
+        result.errors.push({
+          migration: migration.name,
+          error: error instanceof Error ? error.message : String(error)
+        });
+        break;
+      }
+    }
+    result.duration = Date.now() - startTime;
+    return result;
+  }
+  // ============================================================================
+  // Status & Query
+  // ============================================================================
+  /**
+   * Get all applied migrations.
+   */
+  async getAppliedMigrations() {
+    const rows = await this.adapter.all(`SELECT * FROM ${this.config.tableName} ORDER BY version ASC`);
+    return rows.map((row) => ({
+      version: row.version,
+      name: row.name,
+      appliedAt: row.applied_at,
+      appVersion: row.app_version,
+      checksum: row.checksum
+    }));
+  }
+  /**
+   * Get pending migrations.
+   */
+  async getPendingMigrations() {
+    const applied = await this.getAppliedMigrations();
+    const appliedVersions = new Set(applied.map((m) => m.version));
+    return this.migrations.filter((m) => !appliedVersions.has(m.version));
+  }
+  /**
+   * Get migration status.
+   */
+  async getStatus() {
+    const applied = await this.getAppliedMigrations();
+    const pending = await this.getPendingMigrations();
+    return {
+      currentVersion: applied.length > 0 ? applied[applied.length - 1].version : 0,
+      latestVersion: this.migrations.length > 0 ? this.migrations[this.migrations.length - 1].version : 0,
+      pending: pending.map((m) => m.name),
+      applied: applied.map((m) => m.name)
+    };
+  }
+  /**
+   * Check if migrations should run based on version change.
+   */
+  async shouldRunMigrations() {
+    const pending = await this.getPendingMigrations();
+    return pending.length > 0;
+  }
+  // ============================================================================
+  // Utilities
+  // ============================================================================
+  /**
+   * Default app version getter.
+   */
+  defaultGetAppVersion() {
+    try {
+      const { app } = require("electron");
+      if (app?.getVersion) {
+        return app.getVersion();
+      }
+    } catch {
+    }
+    try {
+      const packagePath = import_path.default.join(process.cwd(), "package.json");
+      if (import_fs.default.existsSync(packagePath)) {
+        const pkg = JSON.parse(import_fs.default.readFileSync(packagePath, "utf-8"));
+        return pkg.version ?? "0.0.0";
+      }
+    } catch {
+    }
+    return "0.0.0";
+  }
+  /**
+   * Calculate checksum of migration content.
+   */
+  calculateChecksum(content) {
+    let hash = 0;
+    for (let i = 0; i < content.length; i++) {
+      const char = content.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+    return hash.toString(16);
+  }
+  /**
+   * Log a message if verbose mode is enabled.
+   */
+  log(message) {
+    if (this.config.verbose) {
+      console.log(`[AutoMigrator] ${message}`);
+    }
+  }
+  /**
+   * Get the last migration result.
+   */
+  getLastResult() {
+    return this.lastMigrationResult;
+  }
+}
+function createAutoMigrator(adapter, config) {
+  return new AutoMigrator(adapter, config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AutoMigrator,
+  createAutoMigrator
+});

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

@@ -0,0 +1,9 @@
+/**
+ * Migration Module for Electron SQL Storage Adapter.
+ *
+ * Provides automatic database migration management for Electron applications.
+ *
+ * @packageDocumentation
+ */
+export { AutoMigrator, createAutoMigrator, type AutoMigratorConfig, type MigrationFile, type AppliedMigration, type MigrationResult, } from './autoMigrator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/adapters/electron/migration/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 migration_exports = {};
+__export(migration_exports, {
+  AutoMigrator: () => import_autoMigrator.AutoMigrator,
+  createAutoMigrator: () => import_autoMigrator.createAutoMigrator
+});
+module.exports = __toCommonJS(migration_exports);
+var import_autoMigrator = require("./autoMigrator.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AutoMigrator,
+  createAutoMigrator
+});

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

@@ -0,0 +1,126 @@
+/**
+ * Preload Script for Electron SQL Storage Adapter.
+ *
+ * Exposes a secure API to renderer processes via contextBridge.
+ * This script runs in an isolated context with access to Node.js APIs
+ * and Electron's IPC modules.
+ *
+ * ## Security
+ * - Only exposes necessary functions via contextBridge
+ * - All IPC calls are wrapped with proper error handling
+ * - No direct access to Node.js modules from renderer
+ *
+ * ## Usage in main.js
+ * ```javascript
+ * new BrowserWindow({
+ *   webPreferences: {
+ *     preload: path.join(__dirname, 'preload.js'),
+ *     contextIsolation: true,
+ *     nodeIntegration: false,
+ *   }
+ * });
+ * ```
+ */
+import type { TransactionContext, SyncStatus, DbChangeEvent } from './ipc/types.js';
+import type { StorageRunResult, StorageOpenOptions, StorageParameters, BatchOperation, BatchResult, StorageCapability } from '../../core/contracts/index.js';
+/**
+ * SQL Storage API exposed to renderer processes.
+ */
+declare const sqlStorageApi: {
+    /**
+     * Open the database connection.
+     */
+    open(options?: StorageOpenOptions): Promise<void>;
+    /**
+     * Close the database connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Check if the database is open.
+     */
+    isOpen(): Promise<boolean>;
+    /**
+     * Get adapter capabilities.
+     */
+    getCapabilities(): Promise<StorageCapability[]>;
+    /**
+     * 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 batch operations.
+     */
+    batch(operations: BatchOperation[]): Promise<BatchResult>;
+    /**
+     * Begin a transaction.
+     */
+    beginTransaction(): Promise<TransactionContext>;
+    /**
+     * Commit a transaction.
+     */
+    commitTransaction(transactionId: string): Promise<void>;
+    /**
+     * Rollback a transaction.
+     */
+    rollbackTransaction(transactionId: string): Promise<void>;
+    /**
+     * Execute an operation within a transaction.
+     */
+    executeInTransaction(transactionId: string, statement: string, parameters?: StorageParameters): Promise<StorageRunResult | unknown[]>;
+    /**
+     * Execute a callback within a transaction (convenience method).
+     * Automatically handles begin/commit/rollback.
+     */
+    transaction<T>(fn: (trx: {
+        run: (statement: string, parameters?: StorageParameters) => Promise<StorageRunResult>;
+        get: <R = unknown>(statement: string, parameters?: StorageParameters) => Promise<R | null>;
+        all: <R = unknown>(statement: string, parameters?: StorageParameters) => Promise<R[]>;
+    }) => Promise<T>): Promise<T>;
+    /**
+     * Get sync status.
+     */
+    getSyncStatus(): Promise<SyncStatus>;
+    /**
+     * Trigger manual sync.
+     */
+    triggerSync(): Promise<void>;
+    /**
+     * Subscribe to database change events.
+     */
+    onDatabaseChange(callback: (event: DbChangeEvent) => void): () => void;
+    /**
+     * Subscribe to sync progress events.
+     */
+    onSyncProgress(callback: (progress: number) => void): () => void;
+    /**
+     * Subscribe to sync complete events.
+     */
+    onSyncComplete(callback: () => void): () => void;
+    /**
+     * Subscribe to sync error events.
+     */
+    onSyncError(callback: (error: Error) => void): () => void;
+};
+/**
+ * Type declaration for window.sqlStorage.
+ */
+export type SqlStorageApi = typeof sqlStorageApi;
+export { sqlStorageApi };
+declare global {
+    interface Window {
+        sqlStorage: SqlStorageApi;
+    }
+}
+//# sourceMappingURL=preload.d.ts.map