@framers/sql-storage-adapter 0.7.1 → 0.7.3

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

@@ -0,0 +1,64 @@
+import type { SqlJsConfig } from 'sql.js';
+import type { StorageAdapter, StorageCapability, StorageOpenOptions, StorageParameters, StorageRunResult } from '../core/contracts/index.js';
+/** sql.js's own configuration (`locateFile` and the rest), and the adapter's segment. */
+export type SqlJsAdapterOptions = SqlJsConfig & {
+    /**
+     * A database file of its own: the segment goes into the name of the file
+     * `open({ filePath })` names, before its extension (`app.sqlite3` becomes
+     * `app-agentos.sqlite3`). An in-memory database is its own already.
+     */
+    segment?: string;
+};
+/**
+ * Storage adapter backed by sql.js (WebAssembly) for environments without native SQLite bindings.
+ */
+export declare class SqlJsAdapter implements StorageAdapter {
+    readonly kind = "sqljs";
+    readonly capabilities: ReadonlySet<StorageCapability>;
+    private SQL;
+    private db;
+    private filePath?;
+    /** Foreign-key enforcement as open() was asked for it (undefined: the engine default); sql.js forgets the PRAGMA when export() reopens the connection. */
+    private foreignKeys;
+    private readonly runSerializedTransaction;
+    /**
+     * Open transaction depth. > 0 means a SQLite-level transaction is in
+     * flight on this connection and {@link persistIfNeeded} MUST be
+     * skipped until the outermost commit / rollback returns.
+     *
+     * Why this exists: sql.js's `db.export()` (called by persistIfNeeded
+     * to flush state to disk) ends any open transaction as a side
+     * effect. Persisting mid-transaction therefore SILENTLY closes the
+     * tx, making subsequent COMMIT / ROLLBACK throw "no transaction is
+     * active" and — worse — leaking partial writes onto disk that the
+     * matching rollback can no longer undo. Counter is bumped on
+     * BEGIN/SAVEPOINT and decremented on COMMIT/RELEASE/ROLLBACK
+     * regardless of whether the statement is issued via {@link run}
+     * (caller-managed transactions) or {@link transaction} (helper-
+     * managed). One source of truth for the in-tx flag.
+     */
+    private transactionDepth;
+    private readonly sqlJsConfig;
+    private readonly segment;
+    constructor(adapterOptions?: SqlJsAdapterOptions);
+    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>;
+    transaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+    private prepareInternal;
+    private ensureOpen;
+    /** Applies the connection settings open() was asked for: sql.js loses them whenever export() reopens the connection. */
+    private applyConnectionSettings;
+    private persistIfNeeded;
+}
+/**
+ * Creates a sql.js adapter. `open({ filePath })` loads the database from that
+ * file and saves it there; with `segment`, from a file of the segment's own.
+ *
+ * @throws {Error} When `segment` is not a name a segment can take.
+ */
+export declare const createSqlJsAdapter: (options?: SqlJsAdapterOptions) => StorageAdapter;
+//# sourceMappingURL=sqlJsAdapter.d.ts.map

package/dist/cjs/adapters/sqlJsAdapter.js

@@ -0,0 +1,268 @@
+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 sqlJsAdapter_exports = {};
+__export(sqlJsAdapter_exports, {
+  SqlJsAdapter: () => SqlJsAdapter,
+  createSqlJsAdapter: () => createSqlJsAdapter
+});
+module.exports = __toCommonJS(sqlJsAdapter_exports);
+var import_sql = __toESM(require("sql.js"));
+var import_fs = __toESM(require("fs"));
+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_segment = require("../shared/segment.js");
+const normaliseRowId = (value) => {
+  if (typeof value === "number" || typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  return null;
+};
+const hasFsAccess = () => {
+  try {
+    return typeof import_fs.default.accessSync === "function";
+  } catch {
+    return false;
+  }
+};
+class SqlJsAdapter {
+  constructor(adapterOptions = {}) {
+    this.kind = "sqljs";
+    this.SQL = null;
+    this.db = null;
+    this.runSerializedTransaction = (0, import_serializedTransaction.createSerializedTransactionRunner)();
+    this.transactionDepth = 0;
+    const { segment, ...sqlJsConfig } = adapterOptions;
+    this.segment = segment === void 0 ? void 0 : (0, import_segment.validateSegment)(segment);
+    this.sqlJsConfig = sqlJsConfig;
+    const caps = ["transactions", "json", "prepared"];
+    if (hasFsAccess()) {
+      caps.push("persistence");
+    }
+    this.capabilities = new Set(caps);
+  }
+  async open(options) {
+    if (this.db) {
+      return;
+    }
+    this.SQL = await (0, import_sql.default)(this.sqlJsConfig);
+    const requested = options?.filePath;
+    this.filePath = requested === void 0 || (0, import_segment.namesInMemoryDatabase)(requested) ? void 0 : (0, import_segment.segmentFilePath)(requested, this.segment);
+    this.foreignKeys = options?.foreignKeys;
+    if (this.filePath && hasFsAccess() && import_fs.default.existsSync(this.filePath)) {
+      const buffer = import_fs.default.readFileSync(this.filePath);
+      this.db = new this.SQL.Database(buffer);
+    } else {
+      this.db = new this.SQL.Database();
+    }
+    this.applyConnectionSettings();
+  }
+  async run(statement, parameters) {
+    ({ statement, parameters } = (0, import_sqlPlaceholders.toSqliteStatement)(statement, parameters));
+    const txKind = classifyTransactionControl(statement);
+    if (txKind === "begin") {
+      this.transactionDepth += 1;
+    }
+    const stmt = this.prepareInternal(statement);
+    try {
+      const { named, positional } = (0, import_parameterUtils.normaliseParameters)(parameters);
+      if (named) {
+        stmt.bind((0, import_parameterUtils.expandNamedParameters)(named));
+      } else if (positional) {
+        stmt.bind(positional);
+      }
+      stmt.step();
+      const rowIdResult = this.db.exec("SELECT last_insert_rowid() AS id");
+      const rawRowId = rowIdResult[0]?.values?.[0]?.[0];
+      return {
+        changes: this.db.getRowsModified(),
+        lastInsertRowid: normaliseRowId(rawRowId)
+      };
+    } catch (err) {
+      if (txKind === "begin") {
+        this.transactionDepth = Math.max(0, this.transactionDepth - 1);
+      }
+      throw err;
+    } finally {
+      stmt.free();
+      if (txKind === "end" && this.transactionDepth > 0) {
+        this.transactionDepth -= 1;
+      }
+      if (this.transactionDepth === 0) {
+        await this.persistIfNeeded();
+      }
+    }
+  }
+  async get(statement, parameters) {
+    const rows = await this.all(statement, parameters);
+    return rows.length > 0 ? rows[0] : null;
+  }
+  async all(statement, parameters) {
+    ({ statement, parameters } = (0, import_sqlPlaceholders.toSqliteStatement)(statement, parameters));
+    const stmt = this.prepareInternal(statement);
+    try {
+      const { named, positional } = (0, import_parameterUtils.normaliseParameters)(parameters);
+      if (named) {
+        stmt.bind((0, import_parameterUtils.expandNamedParameters)(named));
+      } else if (positional) {
+        stmt.bind(positional);
+      }
+      const results = [];
+      while (stmt.step()) {
+        const row = {};
+        stmt.getColumnNames().forEach((column, index) => {
+          row[column] = stmt.get()[index];
+        });
+        results.push(row);
+      }
+      return results;
+    } finally {
+      stmt.free();
+    }
+  }
+  async exec(script) {
+    this.ensureOpen();
+    const isControl = isTransactionControlStatement(script);
+    const txKind = isControl ? classifyTransactionControl(script) : "none";
+    if (txKind === "begin") {
+      this.transactionDepth += 1;
+    }
+    try {
+      this.db.exec(script);
+    } catch (err) {
+      if (txKind === "begin") {
+        this.transactionDepth = Math.max(0, this.transactionDepth - 1);
+      }
+      throw err;
+    }
+    if (txKind === "end" && this.transactionDepth > 0) {
+      this.transactionDepth -= 1;
+    }
+    if (!isControl && this.transactionDepth === 0) {
+      await this.persistIfNeeded();
+    } else if (txKind === "end" && this.transactionDepth === 0) {
+      await this.persistIfNeeded();
+    }
+  }
+  async transaction(fn) {
+    this.ensureOpen();
+    return this.runSerializedTransaction(async () => {
+      this.ensureOpen();
+      this.db.run("BEGIN TRANSACTION;");
+      this.transactionDepth += 1;
+      const transactionAdapter = (0, import_serializedTransaction.createSharedConnectionTransactionAdapter)(this);
+      let committed = false;
+      try {
+        const result = await fn(transactionAdapter);
+        this.db.run("COMMIT;");
+        committed = true;
+        return result;
+      } catch (error) {
+        if (!committed) {
+          try {
+            this.db.run("ROLLBACK;");
+          } catch (rollbackError) {
+            const message = rollbackError instanceof Error ? rollbackError.message : String(rollbackError);
+            if (!message.includes("no transaction is active")) {
+              throw rollbackError;
+            }
+          }
+        }
+        throw error;
+      } finally {
+        this.transactionDepth = Math.max(0, this.transactionDepth - 1);
+        if (this.transactionDepth === 0) {
+          await this.persistIfNeeded();
+        }
+      }
+    });
+  }
+  async close() {
+    if (this.db) {
+      await this.persistIfNeeded();
+      this.db.close();
+      this.db = null;
+    }
+  }
+  prepareInternal(statement) {
+    this.ensureOpen();
+    return this.db.prepare(statement);
+  }
+  ensureOpen() {
+    if (!this.db) {
+      throw new Error("Storage adapter not opened. Call open() first.");
+    }
+  }
+  /** Applies the connection settings open() was asked for: sql.js loses them whenever export() reopens the connection. */
+  applyConnectionSettings() {
+    if (this.foreignKeys !== void 0) {
+      this.db.run(`PRAGMA foreign_keys = ${this.foreignKeys ? "ON" : "OFF"};`);
+    }
+  }
+  async persistIfNeeded() {
+    if (!this.filePath || !hasFsAccess()) {
+      return;
+    }
+    const dir = import_path.default.dirname(this.filePath);
+    if (!import_fs.default.existsSync(dir)) {
+      import_fs.default.mkdirSync(dir, { recursive: true });
+    }
+    const data = this.db.export();
+    this.applyConnectionSettings();
+    import_fs.default.writeFileSync(this.filePath, Buffer.from(data));
+  }
+}
+const createSqlJsAdapter = (options) => new SqlJsAdapter(options);
+function isTransactionControlStatement(script) {
+  return classifyTransactionControl(script) !== "none";
+}
+function classifyTransactionControl(script) {
+  const trimmed = script.trim().replace(/;\s*$/, "").toUpperCase();
+  if (trimmed === "BEGIN")
+    return "begin";
+  if (trimmed === "COMMIT" || trimmed === "ROLLBACK")
+    return "end";
+  if (/^BEGIN\s+(DEFERRED|IMMEDIATE|EXCLUSIVE|TRANSACTION)$/.test(trimmed))
+    return "begin";
+  if (/^SAVEPOINT\s+\S+$/.test(trimmed))
+    return "begin";
+  if (/^RELEASE(\s+SAVEPOINT)?\s+\S+$/.test(trimmed))
+    return "end";
+  if (/^ROLLBACK(\s+TO(\s+SAVEPOINT)?)?\s+\S+$/.test(trimmed))
+    return "end";
+  return "none";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SqlJsAdapter,
+  createSqlJsAdapter
+});

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

@@ -0,0 +1,58 @@
+/**
+ * Supabase Postgres Storage Adapter
+ * Provides full Postgres capabilities with Supabase's managed infrastructure
+ */
+import type { StorageAdapter, StorageCapability, StorageOpenOptions, StorageParameters, StorageRunResult, BatchResult } from '../core/contracts/index.js';
+import type { StorageAdapterExtensions, ExtendedBatchOperation, Migration, PerformanceMetrics, StreamOptions } from '../core/contracts/extensions.js';
+export interface SupabaseAdapterOptions extends StorageOpenOptions {
+    connectionString?: string;
+    poolConfig?: {
+        max?: number;
+        min?: number;
+        idleTimeoutMillis?: number;
+        connectionTimeoutMillis?: number;
+    };
+    ssl?: boolean | {
+        rejectUnauthorized: boolean;
+    };
+}
+export declare class SupabaseAdapter implements StorageAdapter, StorageAdapterExtensions {
+    readonly kind = "supabase-postgres";
+    readonly capabilities: ReadonlySet<StorageCapability>;
+    private pool?;
+    private options?;
+    private metrics;
+    private profilingEnabled;
+    private queryCache;
+    private cacheEnabled;
+    private maxCacheSize;
+    open(options?: SupabaseAdapterOptions): Promise<void>;
+    close(): Promise<void>;
+    private trackQuery;
+    private getCacheKey;
+    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>;
+    stream<T = unknown>(query: string, parameters?: unknown, options?: StreamOptions): AsyncIterableIterator<T>;
+    batchWrite(operations: ExtendedBatchOperation[]): Promise<BatchResult>;
+    migrate(migrations: Migration[]): Promise<void>;
+    getMigrationStatus(): Promise<Migration[]>;
+    backup(_destination: string): Promise<void>;
+    restore(_source: string): Promise<void>;
+    enableProfiling(): void;
+    disableProfiling(): void;
+    getMetrics(): PerformanceMetrics;
+    clearMetrics(): void;
+    enableCache(maxSize?: number): void;
+    disableCache(): void;
+    clearCache(): void;
+    getPoolStatus(): {
+        active: number;
+        idle: number;
+        waiting: number;
+        max: number;
+    };
+}
+//# sourceMappingURL=supabase.d.ts.map