@framers/sql-storage-adapter 0.7.1 → 0.7.3

package/dist/cjs/adapters/betterSqliteAdapter.d.ts

@@ -0,0 +1,124 @@
+import type { StorageAdapter, StorageOpenOptions, StorageParameters, StorageRunResult, StorageCapability, BatchOperation, BatchResult } from '../core/contracts/index.js';
+/** Options of the better-sqlite3 adapter. */
+export interface BetterSqliteAdapterOptions {
+    /**
+     * A database file of its own: the segment goes into the file's name, before
+     * its extension (`app.sqlite3` becomes `app-agentos.sqlite3`), for the
+     * default path and for a path given to `open()`. `:memory:` stays as it is.
+     */
+    segment?: string;
+}
+/**
+ * Native SQLite adapter using better-sqlite3.
+ *
+ * ## Performance Characteristics
+ * - Synchronous operations (unique among adapters)
+ * - ~100,000 simple queries/second on modern hardware
+ * - Efficient for single-writer, multiple-reader scenarios
+ *
+ * ## Limitations
+ * - Single writer at a time (readers don't block)
+ * - No network access (local files only)
+ * - Platform-specific native binaries required
+ *
+ * ## When to Use
+ * - Desktop applications (Electron, Node.js)
+ * - Development and testing
+ * - Single-user applications
+ * - When synchronous operations are needed
+ *
+ * ## Graceful Degradation
+ * - Falls back to sql.js if native module unavailable
+ * - Automatically enables WAL mode for better concurrency
+ * - Handles database corruption with automatic recovery
+ */
+/**
+ * Native SQLite adapter backed by the `better-sqlite3` module.
+ *
+ * Features:
+ * - Synchronous & high-performance local storage
+ * - WAL support, prepared statements, batched writes
+ * - Graceful degradation when the native module is absent
+ *
+ * Browser Safety:
+ * This class can be imported in browser bundles without immediate failure.
+ * A runtime error is only thrown if `open()` is invoked in a browser context.
+ */
+export declare class BetterSqliteAdapter implements StorageAdapter {
+    private readonly defaultFilePath;
+    readonly kind = "better-sqlite3";
+    readonly capabilities: ReadonlySet<StorageCapability>;
+    private module;
+    private db;
+    private preparedStatements;
+    private readonly runSerializedTransaction;
+    /**
+     * Holds statements from outside an open transaction until it ends, so they
+     * neither join it nor read what it has not committed. open() gives it Node's
+     * AsyncLocalStorage, which tells the transaction's own statements apart.
+     */
+    private gate;
+    private readonly segment;
+    /**
+     * Creates a new better-sqlite3 adapter instance.
+     *
+     * @param defaultFilePath - Absolute path to the SQLite database file.
+     *                         Will be created if it doesn't exist.
+     * @param options - The adapter's segment.
+     * @throws {Error} When `options.segment` is not a name a segment can take.
+     */
+    constructor(defaultFilePath: string, options?: BetterSqliteAdapterOptions);
+    /**
+     * Open (or no-op if already open) the underlying native database.
+     *
+     * Throws a descriptive error if called in a browser environment.
+     */
+    open(options?: StorageOpenOptions): Promise<void>;
+    run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
+    get<T = unknown>(statement: string, parameters?: StorageParameters): Promise<T | null>;
+    all<T>(statement: string, parameters?: StorageParameters): Promise<T[]>;
+    exec(script: string): Promise<void>;
+    private runNow;
+    private getNow;
+    private allNow;
+    private execNow;
+    /**
+     * The statements of one transaction's handle: they carry the transaction's
+     * token, so the gate admits them whatever async context runs them (a callback
+     * may reach its handle through an AsyncResource made before the transaction).
+     */
+    private handleStatements;
+    transaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+    /**
+     * Execute multiple operations efficiently in a single transaction.
+     *
+     * Much faster than executing operations individually, especially
+     * for bulk inserts. Automatically wraps in a transaction.
+     *
+     * @param operations - Array of SQL operations to execute
+     * @returns Results of the batch operation
+     */
+    batch(operations: BatchOperation[]): Promise<BatchResult>;
+    private batchNow;
+    private prepareInternal;
+    private ensureOpen;
+}
+/**
+ * Factory helper.
+ */
+/**
+ * Factory helper for creating a BetterSqliteAdapter.
+ *
+ * Path Resolution:
+ * - Absolute paths are used as-is.
+ * - Relative paths are resolved against the current working directory instead
+ *   of the adapter file location (simpler & bundler neutral).
+ * - Special values like ':memory:' and 'file:' URIs are passed through.
+ * - With `options.segment`, the file's name carries the segment
+ *   (`app.sqlite3` becomes `app-agentos.sqlite3`).
+ *
+ * @throws {Error} When `options.segment` is not a name a segment can take.
+ */
+export declare const createBetterSqliteAdapter: (filePath: string, options?: BetterSqliteAdapterOptions) => StorageAdapter;
+//# sourceMappingURL=betterSqliteAdapter.d.ts.map

package/dist/cjs/adapters/betterSqliteAdapter.js

@@ -0,0 +1,334 @@
+const __importMetaUrl = require('url').pathToFileURL(__filename).href;
+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 betterSqliteAdapter_exports = {};
+__export(betterSqliteAdapter_exports, {
+  BetterSqliteAdapter: () => BetterSqliteAdapter,
+  createBetterSqliteAdapter: () => createBetterSqliteAdapter
+});
+module.exports = __toCommonJS(betterSqliteAdapter_exports);
+var import_path = __toESM(require("path"));
+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 isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
+const versionOf = (require2) => {
+  try {
+    const pkg = require2("better-sqlite3/package.json");
+    return typeof pkg.version === "string" ? pkg.version : void 0;
+  } catch {
+    return void 0;
+  }
+};
+const loadBetterSqlite = async () => {
+  const { createRequire } = await Promise.resolve().then(() => __toESM(require("module")));
+  try {
+    const imported = await Promise.resolve().then(() => __toESM(require("better-sqlite3")));
+    return { module: imported, version: versionOf(createRequire(__importMetaUrl)) };
+  } catch {
+    try {
+      const require2 = createRequire(import_path.default.join(process.cwd(), "noop.js"));
+      return { module: require2("better-sqlite3"), version: versionOf(require2) };
+    } catch (error) {
+      return null;
+    }
+  }
+};
+const betterSqliteRuntimeRefusal = (version, nodeApi) => {
+  const major = Number(version?.split(".")[0]);
+  if (!(major >= 13)) {
+    return null;
+  }
+  const api = Number(nodeApi);
+  if (api >= 10) {
+    return null;
+  }
+  const has = Number.isFinite(api) && api > 0 ? `Node-API ${api}` : "no Node-API version";
+  return `better-sqlite3 ${version} needs Node-API 10 (Node.js 22.14+ or 23.6+, Electron 35+), and this runtime has ${has}. Install better-sqlite3 12 for this runtime, or choose another adapter.`;
+};
+const loadTransactionContext = async () => {
+  try {
+    const { AsyncLocalStorage } = await Promise.resolve().then(() => __toESM(require("async_hooks")));
+    return new AsyncLocalStorage();
+  } catch {
+    return null;
+  }
+};
+const normaliseRowId = (rowId) => {
+  if (rowId === null || rowId === void 0) {
+    return null;
+  }
+  return typeof rowId === "bigint" ? rowId.toString() : rowId;
+};
+class BetterSqliteAdapter {
+  /**
+   * Creates a new better-sqlite3 adapter instance.
+   *
+   * @param defaultFilePath - Absolute path to the SQLite database file.
+   *                         Will be created if it doesn't exist.
+   * @param options - The adapter's segment.
+   * @throws {Error} When `options.segment` is not a name a segment can take.
+   */
+  constructor(defaultFilePath, options = {}) {
+    this.defaultFilePath = defaultFilePath;
+    this.kind = "better-sqlite3";
+    this.capabilities = /* @__PURE__ */ new Set([
+      "sync",
+      // Unique: supports synchronous operations
+      "transactions",
+      // Full ACID transaction support
+      "wal",
+      // Write-Ahead Logging for better concurrency
+      "locks",
+      // OS-level file locking prevents corruption
+      "persistence",
+      // File-based storage survives restarts
+      "prepared",
+      // Prepared statements for performance
+      "batch"
+      // Efficient batch operations
+    ]);
+    this.module = null;
+    this.db = null;
+    this.preparedStatements = /* @__PURE__ */ new Map();
+    this.runSerializedTransaction = (0, import_serializedTransaction.createSerializedTransactionRunner)();
+    this.gate = (0, import_connectionGate.createConnectionGate)(null);
+    this.segment = options.segment === void 0 ? void 0 : (0, import_segment.validateSegment)(options.segment);
+  }
+  /**
+   * Open (or no-op if already open) the underlying native database.
+   *
+   * Throws a descriptive error if called in a browser environment.
+   */
+  async open(options) {
+    if (this.db) {
+      return;
+    }
+    if (isBrowser) {
+      throw new Error("[StorageAdapter] better-sqlite3 adapter cannot be opened in a browser environment.");
+    }
+    const loaded = await loadBetterSqlite();
+    if (!loaded) {
+      throw new Error("better-sqlite3 module is not available. Install it or choose another adapter.");
+    }
+    const refusal = betterSqliteRuntimeRefusal(loaded.version, process.versions?.napi);
+    if (refusal) {
+      throw new Error(refusal);
+    }
+    this.module = loaded.module;
+    const moduleReference = this.module;
+    const DatabaseCtor = moduleReference.default ?? moduleReference;
+    const resolvedPath = (0, import_segment.segmentFilePath)(options?.filePath ?? this.defaultFilePath, this.segment);
+    if (resolvedPath !== ":memory:" && !resolvedPath.startsWith("file:")) {
+      const fs = await Promise.resolve().then(() => __toESM(require("fs")));
+      const parentDir = import_path.default.dirname(resolvedPath);
+      if (!fs.existsSync(parentDir)) {
+        fs.mkdirSync(parentDir, { recursive: true });
+      }
+    }
+    const databaseOptions = options?.readOnly ? { readonly: true } : void 0;
+    this.gate = (0, import_connectionGate.createConnectionGate)(await loadTransactionContext());
+    this.db = new DatabaseCtor(resolvedPath, databaseOptions);
+    if (options?.foreignKeys !== void 0) {
+      this.db.exec(`PRAGMA foreign_keys = ${options.foreignKeys ? "ON" : "OFF"}`);
+    }
+  }
+  async run(statement, parameters) {
+    return (0, import_connectionGate.whenAdmitted)(this.gate, () => this.runNow(statement, parameters));
+  }
+  async get(statement, parameters) {
+    return (0, import_connectionGate.whenAdmitted)(this.gate, () => this.getNow(statement, parameters));
+  }
+  async all(statement, parameters) {
+    return (0, import_connectionGate.whenAdmitted)(this.gate, () => this.allNow(statement, parameters));
+  }
+  async exec(script) {
+    return (0, import_connectionGate.whenAdmitted)(this.gate, () => this.execNow(script));
+  }
+  runNow(statement, parameters) {
+    ({ statement, parameters } = (0, import_sqlPlaceholders.toSqliteStatement)(statement, parameters));
+    parameters = (0, import_sqlPlaceholders.integersAsBigInt)(parameters);
+    const stmt = this.prepareInternal(statement);
+    const { named, positional } = (0, import_parameterUtils.normaliseParameters)(parameters);
+    const result = named ? stmt.run(named) : stmt.run(positional ?? []);
+    return { changes: result.changes, lastInsertRowid: normaliseRowId(result.lastInsertRowid) };
+  }
+  getNow(statement, parameters) {
+    ({ statement, parameters } = (0, import_sqlPlaceholders.toSqliteStatement)(statement, parameters));
+    parameters = (0, import_sqlPlaceholders.integersAsBigInt)(parameters);
+    const stmt = this.prepareInternal(statement);
+    const { named, positional } = (0, import_parameterUtils.normaliseParameters)(parameters);
+    const row = named ? stmt.get(named) : stmt.get(positional ?? []);
+    return row ?? null;
+  }
+  allNow(statement, parameters) {
+    ({ statement, parameters } = (0, import_sqlPlaceholders.toSqliteStatement)(statement, parameters));
+    parameters = (0, import_sqlPlaceholders.integersAsBigInt)(parameters);
+    const stmt = this.prepareInternal(statement);
+    const { named, positional } = (0, import_parameterUtils.normaliseParameters)(parameters);
+    const rows = named ? stmt.all(named) : stmt.all(positional ?? []);
+    return rows;
+  }
+  execNow(script) {
+    this.ensureOpen();
+    this.db.exec(script);
+  }
+  /**
+   * The statements of one transaction's handle: they carry the transaction's
+   * token, so the gate admits them whatever async context runs them (a callback
+   * may reach its handle through an AsyncResource made before the 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), token),
+      get: (statement, parameters) => (0, import_connectionGate.whenAdmitted)(this.gate, () => this.getNow(statement, parameters), token),
+      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), token),
+      batch: (operations) => (0, import_connectionGate.whenAdmitted)(this.gate, () => this.batchNow(operations), token),
+      // The handle answers a nested transaction() itself and never calls this.
+      transaction: (fn) => fn(this)
+    };
+  }
+  async transaction(fn) {
+    this.ensureOpen();
+    const openToken = this.gate.inside() ? this.gate.openToken() : null;
+    if (openToken) {
+      return fn((0, import_serializedTransaction.createSharedConnectionTransactionAdapter)(this.handleStatements(openToken)));
+    }
+    return this.runSerializedTransaction(() => this.gate.hold(async (token) => {
+      this.ensureOpen();
+      this.db.exec("BEGIN");
+      const transactionAdapter = (0, import_serializedTransaction.createSharedConnectionTransactionAdapter)(this.handleStatements(token));
+      try {
+        const result = await fn(transactionAdapter);
+        this.db.exec("COMMIT");
+        return result;
+      } catch (error) {
+        try {
+          this.db.exec("ROLLBACK");
+        } catch {
+        }
+        throw error;
+      }
+    }));
+  }
+  async close() {
+    this.gate.dispose();
+    this.gate = (0, import_connectionGate.createConnectionGate)(null);
+    if (this.db) {
+      this.preparedStatements.clear();
+      this.db.close();
+      this.db = null;
+    }
+  }
+  /**
+   * Execute multiple operations efficiently in a single transaction.
+   *
+   * Much faster than executing operations individually, especially
+   * for bulk inserts. Automatically wraps in a transaction.
+   *
+   * @param operations - Array of SQL operations to execute
+   * @returns Results of the batch operation
+   */
+  async batch(operations) {
+    return (0, import_connectionGate.whenAdmitted)(this.gate, () => this.batchNow(operations));
+  }
+  batchNow(operations) {
+    this.ensureOpen();
+    const results = [];
+    const errors = [];
+    let successful = 0;
+    let failed = 0;
+    const transaction = this.db.transaction(() => {
+      operations.forEach((op, index) => {
+        try {
+          const prepared = (0, import_sqlPlaceholders.toSqliteStatement)(op.statement, op.parameters);
+          const stmt = this.prepareInternal(prepared.statement);
+          const { named, positional } = (0, import_parameterUtils.normaliseParameters)((0, import_sqlPlaceholders.integersAsBigInt)(prepared.parameters));
+          const result = named ? stmt.run(named) : stmt.run(positional ?? []);
+          results.push({
+            changes: result.changes,
+            lastInsertRowid: normaliseRowId(result.lastInsertRowid)
+          });
+          successful++;
+        } catch (error) {
+          failed++;
+          errors.push({
+            index,
+            error: error instanceof Error ? error : new Error(String(error))
+          });
+        }
+      });
+    });
+    try {
+      transaction();
+    } catch (error) {
+      return {
+        successful: 0,
+        failed: operations.length,
+        errors: [{
+          index: -1,
+          error: error instanceof Error ? error : new Error(String(error))
+        }]
+      };
+    }
+    return { successful, failed, results, errors };
+  }
+  prepareInternal(statement) {
+    this.ensureOpen();
+    if (!this.preparedStatements.has(statement)) {
+      this.preparedStatements.set(statement, this.db.prepare(statement));
+    }
+    return this.preparedStatements.get(statement);
+  }
+  ensureOpen() {
+    if (!this.db) {
+      throw new Error("Storage adapter not opened. Call open() before executing statements.");
+    }
+  }
+}
+const createBetterSqliteAdapter = (filePath, options) => {
+  if (filePath === ":memory:" || filePath.startsWith("file:")) {
+    return new BetterSqliteAdapter(filePath, options);
+  }
+  const resolved = import_path.default.isAbsolute(filePath) ? filePath : import_path.default.resolve(process.cwd(), filePath);
+  return new BetterSqliteAdapter(resolved, options);
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BetterSqliteAdapter,
+  createBetterSqliteAdapter
+});

package/dist/cjs/adapters/capacitorSqliteAdapter.d.ts

@@ -0,0 +1,83 @@
+import type { StorageAdapter, StorageCapability, StorageOpenOptions, StorageParameters, StorageRunResult } from '../core/contracts/index.js';
+export interface CapacitorAdapterOptions {
+    /**
+     * Database name. Defaults to `app`.
+     */
+    database?: string;
+    /**
+     * Whether to enable WAL when platform supports it.
+     */
+    enableWal?: boolean;
+    /**
+     * A database of its own: the segment is appended to the database name
+     * (`app` becomes `app-agentos`), whether the name comes from `database` or
+     * from `open()`'s `adapterOptions.database`.
+     */
+    segment?: string;
+}
+/**
+ * Adapter using @capacitor-community/sqlite for native mobile targets.
+ *
+ * Transactions use the plugin's beginTransaction, commitTransaction and
+ * rollbackTransaction (plugin 5.0.7 and later). The plugin runs every other
+ * execute and run call in a transaction of its own, which cannot nest in an
+ * open one, so the statements of a transaction's callback go to the plugin
+ * with `transaction` false.
+ */
+export declare class CapacitorSqliteAdapter implements StorageAdapter {
+    private readonly options;
+    readonly kind = "capacitor-sqlite";
+    readonly capabilities: ReadonlySet<StorageCapability>;
+    private plugin;
+    private connection;
+    private dbName;
+    /** The connection is shared, so transaction() runs one callback at a time. */
+    private readonly runSerializedTransaction;
+    /**
+     * Holds statements from outside an open transaction until it ends. A WebView
+     * has no async context to tell the callback's own statements apart, so the
+     * callback's handle is the only way into an open transaction.
+     */
+    private readonly gate;
+    /** Statements sent to the plugin from outside a transaction and not yet answered. */
+    private readonly inFlight;
+    private longWaitReported;
+    private readonly longWait;
+    private readonly segment;
+    /** @throws {Error} When `options.segment` is not a name a segment can take. */
+    constructor(options?: CapacitorAdapterOptions);
+    open(options?: StorageOpenOptions): Promise<void>;
+    run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
+    get<T>(statement: string, parameters?: StorageParameters): Promise<T | null>;
+    all<T>(statement: string, parameters?: StorageParameters): Promise<T[]>;
+    exec(script: string): Promise<void>;
+    /**
+     * 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.
+     */
+    transaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+    /**
+     * 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.
+     */
+    private handleStatements;
+    /**
+     * @param ownTransaction - true for a statement from outside a transaction:
+     *   the plugin runs it in a transaction of its own, as it always has.
+     */
+    private runNow;
+    private allNow;
+    private execNow;
+    /** Keeps a statement sent from outside a transaction in `inFlight` until it answers. */
+    private track;
+    private reportLongWait;
+    private ensureConnection;
+}
+export declare const createCapacitorSqliteAdapter: (options?: CapacitorAdapterOptions) => StorageAdapter;
+//# sourceMappingURL=capacitorSqliteAdapter.d.ts.map