@framers/sql-storage-adapter 0.7.2 → 0.7.4

package/README.md

@@ -78,6 +78,27 @@ npm install sql.js                    # WASM SQLite (auto-included for IndexedDB
 
 > `better-sqlite3` 13 needs Node-API 10: Node.js 22.14+ or 23.6+, or Electron 35+ (whose Node is 22.14). On an older runtime (Node.js 20, Node.js 22.13 and earlier, Electron 34 and earlier) install `better-sqlite3@12`; with 13 installed there, the adapter refuses to open, so the resolver falls back to `sql.js`, rather than letting the native binding crash the process. `better-sqlite3` 13 ships prebuilt binaries, but npm can still run `node-gyp rebuild` for it, which needs the build tools above (Python, and make and a C++ compiler, or the Visual Studio Build Tools on Windows): always when it installs from a lockfile (`npm ci`, or `npm install` with a `package-lock.json`), and on some platforms on a fresh install too ([WiseLibs/better-sqlite3#1516](https://github.com/WiseLibs/better-sqlite3/issues/1516)).
 
+### Entries
+
+The root entry exports everything and imports every adapter. A server takes its adapter from that adapter's own entry, with the rest from `./core`, so its bundle carries neither sql.js nor the S3 client:
+
+```typescript
+import { createPostgresAdapter } from '@framers/sql-storage-adapter/postgres';
+import { createStorageFeatures, runSchemaMigrations, isUniqueViolation } from '@framers/sql-storage-adapter/core';
+```
+
+| Entry | Holds |
+| --- | --- |
+| `@framers/sql-storage-adapter` | Everything, with `createDatabase` and the resolver |
+| `./core` | Contracts and errors, dialects, full-text search, codecs, exporters, `createStorageFeatures`, the schema-migration runner, `isUniqueViolation`, the logger. No adapter |
+| `./postgres`, `./better-sqlite3`, `./sqljs`, `./indexeddb`, `./capacitor` | One adapter each |
+| `./backup` | S3-compatible backups (`@aws-sdk/client-s3`) |
+| `./authjs` | The Auth.js database adapter (also in `./core`) |
+| `./electron`, `./electron/renderer`, `./electron/preload` | The Electron adapters. `./electron/renderer` holds only what a window uses; `require('./electron/preload')` gives one bundled CommonJS file for a sandboxed preload |
+| `./sync`, `./kv`, `./types` | Cross-platform sync, the key-value store, the types |
+
+Every entry has an `import` and a `require` condition. The CommonJS build under `dist/cjs` is made from the ES module build file by file, so a class has one identity whichever entry a caller takes it from. It carries its own declarations, so a CommonJS TypeScript consumer under `node16` resolution type-checks against them. CI packs the package, installs it in a new project and checks each of these: `require()` of every entry, what each server entry bundles, and the preload.
+
 ## Quick Start
 
 ```typescript
@@ -361,6 +382,26 @@ const status = await schemaMigrationStatus(db, migrations);            // { appl
 - **Outside a transaction.** A file whose first line is `-- outside transaction` (`outsideTransactionMarker`) runs outside a transaction, for `CREATE INDEX CONCURRENTLY` or `VACUUM`. On PostgreSQL it runs under the session lock on one held connection (`withConnection`).
 - **Unknown rows.** `unknown: 'ignore'` lets a run go on past ledger rows the list lacks.
 
+### Auth.js
+
+`createAuthJsAdapter(db)` is an Auth.js database adapter. It keeps users, accounts, sessions and verification tokens in the product's own database through this library, on PostgreSQL or SQLite. Pass it to NextAuth v5 or `@auth/core`; it has the shape of `Adapter` from `@auth/core/adapters`, which CI checks, and needs no dependency on it.
+
+```typescript
+import NextAuth from 'next-auth';
+import { createDatabase } from '@framers/sql-storage-adapter';
+import { createAuthJsAdapter, ensureAuthJsTables } from '@framers/sql-storage-adapter/authjs';
+
+const db = await createDatabase({ url: process.env.DATABASE_URL, strict: true });
+await ensureAuthJsTables(db); // or put authJsTablesSql(db) in a migration
+export const { handlers, auth, signIn, signOut } = NextAuth({ adapter: createAuthJsAdapter(db), providers: [/* ... */] });
+```
+
+- **Tables.** They are `auth_users`, `auth_accounts`, `auth_sessions` and `auth_verification_tokens`; `tablePrefix` changes the `auth_`. Ids are text, from `crypto.randomUUID()` unless Auth.js passes one or `generateId` is given. Times are `timestamptz` on PostgreSQL and ISO 8601 text on SQLite, and Dates either way in JavaScript.
+- **Deletes.** `deleteUser` deletes the user's sessions and accounts first, in one transaction, so it holds on engines that leave foreign keys off.
+- **Verification tokens.** `useVerificationToken` deletes and returns the token in one statement (`DELETE ... RETURNING`), so a token works once.
+- **Passkeys.** WebAuthn authenticators are not stored.
+- **Tests.** Auth.js's own adapter test suite runs against it on PostgreSQL, better-sqlite3 and sql.js.
+
 ### Values
 
 On SQLite, values convert as they bind, positional and named alike:

package/dist/adapters/electron/preload.cjs

@@ -0,0 +1,289 @@
+"use strict";
+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);
+
+// src/adapters/electron/preload.ts
+var preload_exports = {};
+__export(preload_exports, {
+  sqlStorageApi: () => sqlStorageApi
+});
+module.exports = __toCommonJS(preload_exports);
+var import_electron = require("electron");
+
+// src/adapters/electron/ipc/channels.ts
+var DB_CHANNELS = {
+  /** Execute a mutation (INSERT/UPDATE/DELETE) */
+  RUN: "sql-storage:db:run",
+  /** Get a single row */
+  GET: "sql-storage:db:get",
+  /** Get all matching rows */
+  ALL: "sql-storage:db:all",
+  /** Execute a SQL script */
+  EXEC: "sql-storage:db:exec",
+  /** Execute batch operations */
+  BATCH: "sql-storage:db:batch",
+  /** Open database connection */
+  OPEN: "sql-storage:db:open",
+  /** Close database connection */
+  CLOSE: "sql-storage:db:close",
+  /** Check if database is open */
+  IS_OPEN: "sql-storage:db:is-open",
+  /** Get adapter capabilities */
+  CAPABILITIES: "sql-storage:db:capabilities"
+};
+var TRANSACTION_CHANNELS = {
+  /** Begin a transaction */
+  BEGIN: "sql-storage:transaction:begin",
+  /** Commit current transaction */
+  COMMIT: "sql-storage:transaction:commit",
+  /** Rollback current transaction */
+  ROLLBACK: "sql-storage:transaction:rollback",
+  /** Execute operation within transaction context */
+  EXECUTE: "sql-storage:transaction:execute"
+};
+var SYNC_CHANNELS = {
+  /** Get sync status */
+  STATUS: "sql-storage:sync:status",
+  /** Trigger manual sync */
+  TRIGGER: "sql-storage:sync:trigger",
+  /** Sync progress updates (main -> renderer) */
+  PROGRESS: "sql-storage:sync:progress",
+  /** Sync completed (main -> renderer) */
+  COMPLETE: "sql-storage:sync:complete",
+  /** Sync error (main -> renderer) */
+  ERROR: "sql-storage:sync:error"
+};
+var BROADCAST_CHANNELS = {
+  /** Database change notification */
+  DB_CHANGE: "sql-storage:broadcast:db-change",
+  /** Connection state change */
+  CONNECTION_STATE: "sql-storage:broadcast:connection-state",
+  /** Error notification */
+  ERROR: "sql-storage:broadcast:error"
+};
+
+// src/adapters/electron/preload.ts
+function generateMessageId() {
+  return `msg_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+}
+function createRequest(payload) {
+  return {
+    messageId: generateMessageId(),
+    payload,
+    timestamp: Date.now()
+  };
+}
+async function invokeIpc(channel, payload) {
+  const request = createRequest(payload);
+  const response = await import_electron.ipcRenderer.invoke(channel, request);
+  if (!response.success) {
+    const error = new Error(response.error?.message ?? "Unknown IPC error");
+    error.name = response.error?.code ?? "IpcError";
+    throw error;
+  }
+  return response.data;
+}
+var sqlStorageApi = {
+  // ============================================================================
+  // Database Operations
+  // ============================================================================
+  /**
+   * Open the database connection.
+   */
+  async open(options) {
+    const payload = { options };
+    await invokeIpc(DB_CHANNELS.OPEN, payload);
+  },
+  /**
+   * Close the database connection.
+   */
+  async close() {
+    await invokeIpc(DB_CHANNELS.CLOSE, void 0);
+  },
+  /**
+   * Check if the database is open.
+   */
+  async isOpen() {
+    return invokeIpc(DB_CHANNELS.IS_OPEN, void 0);
+  },
+  /**
+   * Get adapter capabilities.
+   */
+  async getCapabilities() {
+    return invokeIpc(DB_CHANNELS.CAPABILITIES, void 0);
+  },
+  /**
+   * Execute a mutation statement (INSERT, UPDATE, DELETE).
+   */
+  async run(statement, parameters) {
+    const payload = { statement, parameters };
+    return invokeIpc(DB_CHANNELS.RUN, payload);
+  },
+  /**
+   * Get a single row.
+   */
+  async get(statement, parameters) {
+    const payload = { statement, parameters };
+    return invokeIpc(DB_CHANNELS.GET, payload);
+  },
+  /**
+   * Get all matching rows.
+   */
+  async all(statement, parameters) {
+    const payload = { statement, parameters };
+    return invokeIpc(DB_CHANNELS.ALL, payload);
+  },
+  /**
+   * Execute a SQL script.
+   */
+  async exec(script) {
+    const payload = { script };
+    await invokeIpc(DB_CHANNELS.EXEC, payload);
+  },
+  /**
+   * Execute batch operations.
+   */
+  async batch(operations) {
+    const payload = { operations };
+    return invokeIpc(DB_CHANNELS.BATCH, payload);
+  },
+  // ============================================================================
+  // Transaction Operations
+  // ============================================================================
+  /**
+   * Begin a transaction.
+   */
+  async beginTransaction() {
+    return invokeIpc(TRANSACTION_CHANNELS.BEGIN, void 0);
+  },
+  /**
+   * Commit a transaction.
+   */
+  async commitTransaction(transactionId) {
+    await invokeIpc(TRANSACTION_CHANNELS.COMMIT, { transactionId });
+  },
+  /**
+   * Rollback a transaction.
+   */
+  async rollbackTransaction(transactionId) {
+    await invokeIpc(TRANSACTION_CHANNELS.ROLLBACK, { transactionId });
+  },
+  /**
+   * Execute an operation within a transaction.
+   */
+  async executeInTransaction(transactionId, statement, parameters) {
+    const payload = {
+      transactionId,
+      operation: { statement, parameters }
+    };
+    return invokeIpc(TRANSACTION_CHANNELS.EXECUTE, payload);
+  },
+  /**
+   * Execute a callback within a transaction (convenience method).
+   * Automatically handles begin/commit/rollback.
+   */
+  async transaction(fn) {
+    const ctx = await this.beginTransaction();
+    const trx = {
+      run: async (statement, parameters) => {
+        const result = await this.executeInTransaction(ctx.transactionId, statement, parameters);
+        return result;
+      },
+      get: async (statement, parameters) => {
+        const result = await this.executeInTransaction(ctx.transactionId, statement, parameters);
+        return Array.isArray(result) ? result[0] ?? null : null;
+      },
+      all: async (statement, parameters) => {
+        const result = await this.executeInTransaction(ctx.transactionId, statement, parameters);
+        return Array.isArray(result) ? result : [];
+      }
+    };
+    try {
+      const result = await fn(trx);
+      await this.commitTransaction(ctx.transactionId);
+      return result;
+    } catch (error) {
+      await this.rollbackTransaction(ctx.transactionId).catch(() => {
+      });
+      throw error;
+    }
+  },
+  // ============================================================================
+  // Sync Operations
+  // ============================================================================
+  /**
+   * Get sync status.
+   */
+  async getSyncStatus() {
+    return invokeIpc(SYNC_CHANNELS.STATUS, void 0);
+  },
+  /**
+   * Trigger manual sync.
+   */
+  async triggerSync() {
+    await invokeIpc(SYNC_CHANNELS.TRIGGER, void 0);
+  },
+  // ============================================================================
+  // Event Subscriptions
+  // ============================================================================
+  /**
+   * Subscribe to database change events.
+   */
+  onDatabaseChange(callback) {
+    const handler = (_, event) => {
+      callback(event);
+    };
+    import_electron.ipcRenderer.on(BROADCAST_CHANNELS.DB_CHANGE, handler);
+    return () => import_electron.ipcRenderer.removeListener(BROADCAST_CHANNELS.DB_CHANGE, handler);
+  },
+  /**
+   * Subscribe to sync progress events.
+   */
+  onSyncProgress(callback) {
+    const handler = (_, progress) => {
+      callback(progress);
+    };
+    import_electron.ipcRenderer.on(SYNC_CHANNELS.PROGRESS, handler);
+    return () => import_electron.ipcRenderer.removeListener(SYNC_CHANNELS.PROGRESS, handler);
+  },
+  /**
+   * Subscribe to sync complete events.
+   */
+  onSyncComplete(callback) {
+    const handler = () => callback();
+    import_electron.ipcRenderer.on(SYNC_CHANNELS.COMPLETE, handler);
+    return () => import_electron.ipcRenderer.removeListener(SYNC_CHANNELS.COMPLETE, handler);
+  },
+  /**
+   * Subscribe to sync error events.
+   */
+  onSyncError(callback) {
+    const handler = (_, error) => {
+      callback(new Error(error.message));
+    };
+    import_electron.ipcRenderer.on(SYNC_CHANNELS.ERROR, handler);
+    return () => import_electron.ipcRenderer.removeListener(SYNC_CHANNELS.ERROR, handler);
+  }
+};
+if (import_electron.contextBridge) {
+  import_electron.contextBridge.exposeInMainWorld("sqlStorage", sqlStorageApi);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  sqlStorageApi
+});

package/dist/adapters/electron/renderer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The renderer-process entry, `@framers/sql-storage-adapter/electron/renderer`: the adapter a window uses over IPC,
+ * and nothing from the main process (better-sqlite3, the window manager, recovery, migration).
+ *
+ * @module
+ */
+export { ElectronRendererAdapter, createElectronRendererAdapter, isElectronRenderer, isPreloadApiAvailable, type ElectronRendererAdapterOptions, } from './electronRendererAdapter.js';
+export type { DbChangeEvent, SyncStatus } from './ipc/types.js';
+//# sourceMappingURL=renderer.d.ts.map

package/dist/adapters/electron/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../src/adapters/electron/renderer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,8BAA8B,GACpC,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/adapters/electron/renderer.js

@@ -0,0 +1,8 @@
+/**
+ * The renderer-process entry, `@framers/sql-storage-adapter/electron/renderer`: the adapter a window uses over IPC,
+ * and nothing from the main process (better-sqlite3, the window manager, recovery, migration).
+ *
+ * @module
+ */
+export { ElectronRendererAdapter, createElectronRendererAdapter, isElectronRenderer, isPreloadApiAvailable, } from './electronRendererAdapter.js';
+//# sourceMappingURL=renderer.js.map

package/dist/adapters/electron/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../../../src/adapters/electron/renderer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,kBAAkB,EAClB,qBAAqB,GAEtB,MAAM,2BAA2B,CAAC"}

package/dist/cjs/adapters/__tests__/indexedDbAdapter.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=indexedDbAdapter.spec.d.ts.map

package/dist/cjs/adapters/__tests__/indexedDbAdapter.spec.js

@@ -0,0 +1,133 @@
+var import_vitest = require("vitest");
+var import_indexedDbAdapter = require("../indexedDbAdapter.js");
+const setupIndexedDbMock = () => {
+  const stores = /* @__PURE__ */ new Map();
+  global.indexedDB = {
+    open: (_name, _version) => {
+      const req = {
+        result: {
+          objectStoreNames: { contains: () => false },
+          createObjectStore: (_storeName) => {
+            stores.set(_storeName, /* @__PURE__ */ new Map());
+          },
+          transaction: (_storeName, _mode) => ({
+            objectStore: (name) => {
+              const store = stores.get(name) || /* @__PURE__ */ new Map();
+              return {
+                get: (key) => ({
+                  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                  onsuccess: null,
+                  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                  onerror: null,
+                  result: store.get(key)
+                }),
+                put: (value, key) => {
+                  store.set(key, value);
+                  return {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    onsuccess: null,
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    onerror: null
+                  };
+                }
+              };
+            }
+          }),
+          close: () => {
+          }
+        }
+      };
+      setTimeout(() => {
+        if (req.onupgradeneeded)
+          req.onupgradeneeded();
+        if (req.onsuccess)
+          req.onsuccess();
+      }, 0);
+      return req;
+    }
+  };
+};
+(0, import_vitest.describe)("IndexedDbAdapter", () => {
+  let adapter;
+  (0, import_vitest.beforeEach)(async () => {
+    setupIndexedDbMock();
+    adapter = new import_indexedDbAdapter.IndexedDbAdapter({
+      dbName: "test-db",
+      autoSave: false
+      // Disable for tests
+    });
+  });
+  (0, import_vitest.afterEach)(async () => {
+    if (adapter) {
+      await adapter.close();
+    }
+  });
+  (0, import_vitest.it)("should initialize with correct capabilities", () => {
+    (0, import_vitest.expect)(adapter.kind).toBe("indexeddb");
+    (0, import_vitest.expect)(adapter.capabilities.has("transactions")).toBe(true);
+    (0, import_vitest.expect)(adapter.capabilities.has("persistence")).toBe(true);
+  });
+  (0, import_vitest.it)("should open database successfully", async () => {
+    await adapter.open();
+    (0, import_vitest.expect)(true).toBe(true);
+  });
+  (0, import_vitest.it)("should create table and insert data", async () => {
+    await adapter.open();
+    await adapter.run("CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)");
+    const result = await adapter.run("INSERT INTO test (name) VALUES (?)", ["Alice"]);
+    (0, import_vitest.expect)(result.changes).toBe(1);
+    (0, import_vitest.expect)(result.lastInsertRowid).toBeDefined();
+  });
+  (0, import_vitest.it)("should retrieve inserted data", async () => {
+    await adapter.open();
+    await adapter.run("CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)");
+    await adapter.run("INSERT INTO test (name) VALUES (?)", ["Bob"]);
+    const row = await adapter.get("SELECT * FROM test WHERE name = ?", ["Bob"]);
+    (0, import_vitest.expect)(row).toBeDefined();
+    (0, import_vitest.expect)(row?.name).toBe("Bob");
+  });
+  (0, import_vitest.it)("should return all rows", async () => {
+    await adapter.open();
+    await adapter.run("CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)");
+    await adapter.run("INSERT INTO test (name) VALUES (?)", ["Alice"]);
+    await adapter.run("INSERT INTO test (name) VALUES (?)", ["Bob"]);
+    const rows = await adapter.all("SELECT * FROM test");
+    (0, import_vitest.expect)(rows.length).toBe(2);
+    (0, import_vitest.expect)(rows.map((r) => r.name)).toContain("Alice");
+    (0, import_vitest.expect)(rows.map((r) => r.name)).toContain("Bob");
+  });
+  (0, import_vitest.it)("should support transactions", async () => {
+    await adapter.open();
+    await adapter.run("CREATE TABLE test (id INTEGER PRIMARY KEY, value INTEGER)");
+    await adapter.beginTransaction();
+    await adapter.run("INSERT INTO test (value) VALUES (?)", [100]);
+    await adapter.run("INSERT INTO test (value) VALUES (?)", [200]);
+    await adapter.commit();
+    const rows = await adapter.all("SELECT value FROM test");
+    (0, import_vitest.expect)(rows.length).toBe(2);
+    (0, import_vitest.expect)(rows.map((r) => r.value)).toEqual([100, 200]);
+  });
+  (0, import_vitest.it)("should rollback transactions", async () => {
+    await adapter.open();
+    await adapter.run("CREATE TABLE test (id INTEGER PRIMARY KEY, value INTEGER)");
+    await adapter.beginTransaction();
+    await adapter.run("INSERT INTO test (value) VALUES (?)", [100]);
+    await adapter.rollback();
+    const rows = await adapter.all("SELECT * FROM test");
+    (0, import_vitest.expect)(rows.length).toBe(0);
+  });
+  (0, import_vitest.it)("should export and import database", async () => {
+    await adapter.open();
+    await adapter.run("CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)");
+    await adapter.run("INSERT INTO test (name) VALUES (?)", ["Export Test"]);
+    const exported = adapter.exportDatabase();
+    (0, import_vitest.expect)(exported).toBeInstanceOf(Uint8Array);
+    (0, import_vitest.expect)(exported.length).toBeGreaterThan(0);
+    const adapter2 = new import_indexedDbAdapter.IndexedDbAdapter({ dbName: "test-db-2", autoSave: false });
+    await adapter2.open();
+    await adapter2.importDatabase(exported);
+    const row = await adapter2.get("SELECT * FROM test WHERE name = ?", ["Export Test"]);
+    (0, import_vitest.expect)(row?.name).toBe("Export Test");
+    await adapter2.close();
+  });
+});