@framers/sql-storage-adapter 0.7.2 → 0.7.3

package/dist/cjs/adapters/capacitorSqliteAdapter.js

@@ -0,0 +1,250 @@
+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 capacitorSqliteAdapter_exports = {};
+__export(capacitorSqliteAdapter_exports, {
+  CapacitorSqliteAdapter: () => CapacitorSqliteAdapter,
+  createCapacitorSqliteAdapter: () => createCapacitorSqliteAdapter
+});
+module.exports = __toCommonJS(capacitorSqliteAdapter_exports);
+var import_parameterUtils = require("../shared/parameterUtils.js");
+var import_sqlPlaceholders = require("../shared/sqlPlaceholders.js");
+var import_serializedTransaction = require("../shared/serializedTransaction.js");
+var import_connectionGate = require("../shared/connectionGate.js");
+var import_segment = require("../shared/segment.js");
+const LONG_WAIT_MS = 1e4;
+const isCapacitorPlugin = (value) => {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.createConnection === "function";
+};
+const loadCapacitorSqlite = async () => {
+  try {
+    const mod = await Promise.resolve().then(() => __toESM(require("@capacitor-community/sqlite")));
+    if (isCapacitorPlugin(mod)) {
+      return mod;
+    }
+    if (mod && typeof mod === "object") {
+      const { default: defaultExport, CapacitorSQLite } = mod;
+      if (isCapacitorPlugin(defaultExport)) {
+        return defaultExport;
+      }
+      if (isCapacitorPlugin(CapacitorSQLite)) {
+        return CapacitorSQLite;
+      }
+    }
+    return null;
+  } catch (error) {
+    console.warn("[StorageAdapter] @capacitor-community/sqlite module not available.", error);
+    return null;
+  }
+};
+const toRunResult = (answer) => {
+  const outer = answer ?? {};
+  const inner = typeof outer.changes === "object" && outer.changes !== null ? outer.changes : outer;
+  const changes = typeof inner.changes === "number" ? inner.changes : 0;
+  const lastId = inner.lastId;
+  return {
+    changes,
+    lastInsertRowid: typeof lastId === "number" || typeof lastId === "string" ? lastId : null
+  };
+};
+class CapacitorSqliteAdapter {
+  /** @throws {Error} When `options.segment` is not a name a segment can take. */
+  constructor(options = {}) {
+    this.options = options;
+    this.kind = "capacitor-sqlite";
+    this.capabilities = /* @__PURE__ */ new Set([
+      "transactions",
+      "wal",
+      "locks",
+      "persistence"
+    ]);
+    this.plugin = null;
+    this.connection = null;
+    this.runSerializedTransaction = (0, import_serializedTransaction.createSerializedTransactionRunner)();
+    this.gate = (0, import_connectionGate.createConnectionGate)(null, { withoutContext: "wait" });
+    this.inFlight = /* @__PURE__ */ new Set();
+    this.longWaitReported = false;
+    this.longWait = {
+      afterMs: LONG_WAIT_MS,
+      onLongWait: () => this.reportLongWait()
+    };
+    this.dbName = options.database ?? "app";
+    this.segment = options.segment === void 0 ? void 0 : (0, import_segment.validateSegment)(options.segment);
+  }
+  async open(options) {
+    if (this.connection) {
+      return;
+    }
+    this.plugin = await loadCapacitorSqlite();
+    if (!this.plugin) {
+      throw new Error("@capacitor-community/sqlite is unavailable. Install the plugin or choose a different adapter.");
+    }
+    const adapterOptions = options?.adapterOptions;
+    const requestedName = typeof adapterOptions?.database === "string" ? adapterOptions.database : void 0;
+    const configuredName = this.options.database;
+    const resolvedDbName = (0, import_segment.segmentName)(requestedName ?? configuredName ?? this.dbName, this.segment);
+    this.connection = await this.plugin.createConnection(resolvedDbName, false, "no-encryption", 1, false);
+    await this.connection.open();
+    if (this.options.enableWal ?? true) {
+      try {
+        await this.connection.execute("PRAGMA journal_mode = WAL;");
+      } catch (error) {
+        console.warn("[StorageAdapter] Failed to enable WAL on Capacitor SQLite.", error);
+      }
+    }
+    if (options?.foreignKeys !== void 0) {
+      await this.connection.execute(`PRAGMA foreign_keys = ${options.foreignKeys ? "ON" : "OFF"};`, false);
+    }
+  }
+  async run(statement, parameters) {
+    return (0, import_connectionGate.whenAdmitted)(this.gate, () => this.track(this.runNow(statement, parameters, true)), void 0, this.longWait);
+  }
+  async get(statement, parameters) {
+    const rows = await this.all(statement, parameters);
+    return rows.length > 0 ? rows[0] : null;
+  }
+  async all(statement, parameters) {
+    return (0, import_connectionGate.whenAdmitted)(this.gate, () => this.track(this.allNow(statement, parameters)), void 0, this.longWait);
+  }
+  async exec(script) {
+    return (0, import_connectionGate.whenAdmitted)(this.gate, () => this.track(this.execNow(script, true)), void 0, this.longWait);
+  }
+  /**
+   * Executes a callback within a database transaction.
+   *
+   * Callbacks run one at a time, since every transaction shares the one
+   * connection. The callback's statements go through the handle it receives;
+   * a statement issued through the adapter itself while the callback runs
+   * waits until the transaction ends, so a callback must not await one.
+   */
+  async transaction(fn) {
+    this.ensureConnection();
+    const queued = setTimeout(() => this.reportLongWait(), LONG_WAIT_MS);
+    return this.runSerializedTransaction(() => {
+      clearTimeout(queued);
+      return this.gate.hold(async (token) => {
+        await Promise.allSettled([...this.inFlight]);
+        const conn = this.ensureConnection();
+        await conn.beginTransaction();
+        const transactionAdapter = (0, import_serializedTransaction.createSharedConnectionTransactionAdapter)(this.handleStatements(token));
+        try {
+          const result = await fn(transactionAdapter);
+          await conn.commitTransaction();
+          return result;
+        } catch (error) {
+          try {
+            await conn.rollbackTransaction();
+          } catch {
+          }
+          throw error;
+        }
+      });
+    });
+  }
+  async close() {
+    if (this.connection) {
+      await this.connection.close();
+      this.connection = null;
+    }
+  }
+  /**
+   * The statements of one transaction's handle: they carry the transaction's
+   * token, so the gate admits them while the transaction is open, and run
+   * inside the plugin's open transaction.
+   */
+  handleStatements(token) {
+    return {
+      kind: this.kind,
+      capabilities: this.capabilities,
+      open: async () => {
+      },
+      close: async () => {
+      },
+      run: (statement, parameters) => (0, import_connectionGate.whenAdmitted)(this.gate, () => this.runNow(statement, parameters, false), token),
+      get: async (statement, parameters) => {
+        const rows = await (0, import_connectionGate.whenAdmitted)(this.gate, () => this.allNow(statement, parameters), token);
+        return rows.length > 0 ? rows[0] : null;
+      },
+      all: (statement, parameters) => (0, import_connectionGate.whenAdmitted)(this.gate, () => this.allNow(statement, parameters), token),
+      exec: (script) => (0, import_connectionGate.whenAdmitted)(this.gate, () => this.execNow(script, false), token),
+      // The handle answers a nested transaction() itself and never calls this.
+      transaction: (fn) => fn(this)
+    };
+  }
+  /**
+   * @param ownTransaction - true for a statement from outside a transaction:
+   *   the plugin runs it in a transaction of its own, as it always has.
+   */
+  async runNow(statement, parameters, ownTransaction) {
+    ({ statement, parameters } = (0, import_sqlPlaceholders.toSqliteStatement)(statement, parameters));
+    const conn = this.ensureConnection();
+    const { positional } = (0, import_parameterUtils.normaliseParameters)(parameters);
+    return toRunResult(await conn.run(statement, positional ?? [], ownTransaction));
+  }
+  async allNow(statement, parameters) {
+    ({ statement, parameters } = (0, import_sqlPlaceholders.toSqliteStatement)(statement, parameters));
+    const conn = this.ensureConnection();
+    const { positional } = (0, import_parameterUtils.normaliseParameters)(parameters);
+    const result = await conn.query(statement, positional ?? []);
+    return result.values ?? [];
+  }
+  async execNow(script, ownTransaction) {
+    const conn = this.ensureConnection();
+    await conn.execute(script, ownTransaction);
+  }
+  /** Keeps a statement sent from outside a transaction in `inFlight` until it answers. */
+  track(sent) {
+    this.inFlight.add(sent);
+    const forget = () => {
+      this.inFlight.delete(sent);
+    };
+    sent.then(forget, forget);
+    return sent;
+  }
+  reportLongWait() {
+    if (this.longWaitReported)
+      return;
+    this.longWaitReported = true;
+    console.warn(`[StorageAdapter] A Capacitor SQLite statement has waited ${LONG_WAIT_MS / 1e3} s for an open transaction to end. Inside a transaction() callback, run statements through the callback's handle: one run through the adapter itself waits for the transaction, and the transaction waits for it.`);
+  }
+  ensureConnection() {
+    if (!this.connection) {
+      throw new Error("Storage adapter not opened. Call open() before executing statements.");
+    }
+    return this.connection;
+  }
+}
+const createCapacitorSqliteAdapter = (options) => new CapacitorSqliteAdapter(options);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CapacitorSqliteAdapter,
+  createCapacitorSqliteAdapter
+});

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

@@ -0,0 +1,251 @@
+/**
+ * Electron Main Process Storage Adapter.
+ *
+ * Wraps BetterSqliteAdapter for use in Electron's main process.
+ * Handles IPC communication, WAL management, crash recovery,
+ * and multi-window coordination.
+ *
+ * ## Architecture
+ * This adapter runs in the main process and owns the actual database connection.
+ * Renderer processes communicate with it via IPC using ElectronRendererAdapter.
+ *
+ * ## Features
+ * - WAL mode with configurable checkpointing
+ * - Integrity checking and auto-repair
+ * - Multi-window change broadcasting
+ * - Cloud backup scheduling
+ * - Auto-migration on app updates
+ *
+ * @example
+ * ```typescript
+ * import { createElectronMainAdapter } from '@framers/sql-storage-adapter/electron';
+ * import { app } from 'electron';
+ * import path from 'path';
+ *
+ * const db = await createElectronMainAdapter({
+ *   filePath: path.join(app.getPath('userData'), 'app.db'),
+ *   wal: { enabled: true, checkpointInterval: 300000 },
+ *   recovery: { enabled: true, checkOnOpen: true },
+ * });
+ *
+ * await db.open();
+ * ```
+ */
+import type { StorageAdapter, StorageCapability, StorageOpenOptions, StorageParameters, StorageRunResult, BatchOperation, BatchResult, PreparedStatement } from '../../core/contracts/index.js';
+/**
+ * WAL (Write-Ahead Logging) configuration.
+ */
+export interface WalConfig {
+    /** Enable WAL mode (default: true) */
+    enabled?: boolean;
+    /** Checkpoint interval in milliseconds (default: 300000 = 5 minutes) */
+    checkpointInterval?: number;
+    /** Auto-checkpoint threshold in pages (default: 1000) */
+    autoCheckpointPages?: number;
+    /** Synchronous mode: OFF, NORMAL, FULL, EXTRA (default: NORMAL) */
+    synchronous?: 'OFF' | 'NORMAL' | 'FULL' | 'EXTRA';
+}
+/**
+ * Recovery and integrity check configuration.
+ */
+export interface RecoveryConfig {
+    /** Enable recovery features (default: true) */
+    enabled?: boolean;
+    /** Run integrity check on open (default: true) */
+    checkOnOpen?: boolean;
+    /** Attempt auto-repair on corruption (default: true) */
+    autoRepair?: boolean;
+    /** Maximum time for integrity check in ms (default: 30000) */
+    integrityCheckTimeout?: number;
+}
+/**
+ * Auto-migration configuration.
+ */
+export interface MigrationConfig {
+    /** Enable auto-migration (default: false) */
+    enabled?: boolean;
+    /** Path to migrations directory */
+    migrationsPath?: string;
+    /** Run migrations on app version change (default: true) */
+    runOnVersionChange?: boolean;
+}
+/**
+ * Cloud backup configuration.
+ */
+export interface BackupConfig {
+    /** Enable cloud backups (default: false) */
+    enabled?: boolean;
+    /** Backup interval in milliseconds (default: 3600000 = 1 hour) */
+    interval?: number;
+    /** Maximum backups to keep (default: 7) */
+    maxBackups?: number;
+    /** Backup provider (implement your own) */
+    provider?: CloudBackupProvider;
+}
+/**
+ * Cloud backup provider interface.
+ */
+export interface CloudBackupProvider {
+    upload(localPath: string, remotePath: string): Promise<void>;
+    download(remotePath: string, localPath: string): Promise<void>;
+    list(): Promise<{
+        path: string;
+        createdAt: Date;
+        size: number;
+    }[]>;
+    delete(remotePath: string): Promise<void>;
+}
+/**
+ * Multi-window coordination configuration.
+ */
+export interface MultiWindowConfig {
+    /** Enable multi-window support (default: true) */
+    enabled?: boolean;
+    /** Broadcast changes to other windows (default: true) */
+    broadcastChanges?: boolean;
+}
+/**
+ * Full configuration for ElectronMainAdapter.
+ */
+export interface ElectronMainAdapterOptions {
+    /** Path to SQLite database file */
+    filePath: string;
+    /** WAL configuration */
+    wal?: WalConfig;
+    /** Recovery configuration */
+    recovery?: RecoveryConfig;
+    /** Migration configuration */
+    migration?: MigrationConfig;
+    /** Backup configuration */
+    backup?: BackupConfig;
+    /** Multi-window configuration */
+    multiWindow?: MultiWindowConfig;
+    /** Enable verbose logging (default: false) */
+    verbose?: boolean;
+    /**
+     * A database file of its own: the segment goes into the file's name, before
+     * its extension (`app.db` becomes `app-agentos.db`), and `getFilePath()`
+     * and the backups name that file. The renderer's IPC channels are one set
+     * per process, so a segmented adapter leaves them to the app's adapter
+     * without a segment: it serves the main process alone.
+     */
+    segment?: string;
+}
+/**
+ * Electron Main Process Storage Adapter.
+ *
+ * This adapter is designed to run exclusively in Electron's main process.
+ * It wraps BetterSqliteAdapter and adds Electron-specific features like
+ * IPC handling, multi-window coordination, and crash recovery.
+ */
+export declare class ElectronMainAdapter implements StorageAdapter {
+    readonly kind = "electron-main";
+    readonly capabilities: ReadonlySet<StorageCapability>;
+    private innerAdapter;
+    private isInitialized;
+    private walCheckpointTimer;
+    private backupTimer;
+    private readonly options;
+    /** The database file: `options.filePath` with the segment in its name. */
+    private readonly filePath;
+    private readonly walConfig;
+    private readonly recoveryConfig;
+    private readonly multiWindowConfig;
+    constructor(options: ElectronMainAdapterOptions);
+    /**
+     * Open the database and initialize all subsystems.
+     */
+    open(openOptions?: StorageOpenOptions): Promise<void>;
+    /**
+     * Close the database and cleanup all subsystems.
+     */
+    close(): Promise<void>;
+    run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
+    get<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T | null>;
+    all<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T[]>;
+    exec(script: string): Promise<void>;
+    transaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
+    batch(operations: BatchOperation[]): Promise<BatchResult>;
+    prepare?<T = unknown>(statement: string): PreparedStatement<T>;
+    /**
+     * Configure WAL mode on the database.
+     */
+    private configureWalMode;
+    /**
+     * Start the WAL checkpoint timer.
+     */
+    private startWalCheckpointTimer;
+    /**
+     * Run a WAL checkpoint.
+     */
+    runWalCheckpoint(): Promise<{
+        framesCheckpointed: number;
+        totalFrames: number;
+    }>;
+    /**
+     * Run an integrity check on the database.
+     */
+    runIntegrityCheck(): Promise<{
+        ok: boolean;
+        issues: string[];
+    }>;
+    /**
+     * Attempt to repair the database.
+     */
+    private attemptRepair;
+    /**
+     * Start the backup scheduler.
+     */
+    private startBackupScheduler;
+    /**
+     * Run a backup.
+     */
+    runBackup(): Promise<void>;
+    /**
+     * Cleanup old backups beyond the retention limit.
+     */
+    private cleanupOldBackups;
+    /**
+     * Broadcast a database change to all windows.
+     */
+    private broadcastChange;
+    /**
+     * Detect mutation type from SQL statement.
+     */
+    private detectMutationType;
+    /**
+     * Extract table names from SQL statement.
+     */
+    private extractTables;
+    /**
+     * Log a message if verbose mode is enabled.
+     */
+    private log;
+    /**
+     * Check if the adapter is initialized.
+     */
+    isOpen(): boolean;
+    /**
+     * Get the database file path.
+     */
+    getFilePath(): string;
+}
+/**
+ * Create an Electron Main Process Storage Adapter.
+ *
+ * @param options - Adapter configuration
+ * @returns ElectronMainAdapter instance
+ *
+ * @example
+ * ```typescript
+ * const db = createElectronMainAdapter({
+ *   filePath: path.join(app.getPath('userData'), 'app.db'),
+ *   wal: { enabled: true },
+ *   recovery: { checkOnOpen: true },
+ * });
+ *
+ * await db.open();
+ * ```
+ */
+export declare function createElectronMainAdapter(options: ElectronMainAdapterOptions): ElectronMainAdapter;
+//# sourceMappingURL=electronMainAdapter.d.ts.map