@tanstack/node-db-sqlite-persistence 0.1.2

package/README.md

@@ -0,0 +1,49 @@
+# @tanstack/node-db-sqlite-persistence
+
+Thin Node SQLite persistence for TanStack DB.
+
+## Public API
+
+- `createNodeSQLitePersistence(...)`
+- `persistedCollectionOptions(...)` (re-exported from core)
+
+## Quick start
+
+```ts
+import { createCollection } from '@tanstack/db'
+import {
+  createNodeSQLitePersistence,
+  persistedCollectionOptions,
+} from '@tanstack/node-db-sqlite-persistence'
+import Database from 'better-sqlite3'
+
+type Todo = {
+  id: string
+  title: string
+  completed: boolean
+}
+
+// You own database lifecycle directly.
+const database = new Database(`./tanstack-db.sqlite`)
+
+// One shared persistence instance for the whole database.
+const persistence = createNodeSQLitePersistence({
+  database,
+})
+
+export const todosCollection = createCollection(
+  persistedCollectionOptions<Todo, string>({
+    id: `todos`,
+    getKey: (todo) => todo.id,
+    persistence,
+    schemaVersion: 1, // Per-collection schema version
+  }),
+)
+```
+
+## Notes
+
+- `createNodeSQLitePersistence` is shared across collections; it resolves
+  mode-specific behavior (`sync-present` vs `sync-absent`) automatically.
+- `schemaVersion` is specified per collection via `persistedCollectionOptions`.
+- Call `database.close()` when your app shuts down.

package/dist/cjs/index.cjs

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const nodePersistence = require("./node-persistence.cjs");
+const dbSqlitePersistenceCore = require("@tanstack/db-sqlite-persistence-core");
+exports.createNodeSQLitePersistence = nodePersistence.createNodeSQLitePersistence;
+Object.defineProperty(exports, "persistedCollectionOptions", {
+  enumerable: true,
+  get: () => dbSqlitePersistenceCore.persistedCollectionOptions
+});
+//# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;"}

package/dist/cjs/index.d.cts

@@ -0,0 +1,4 @@
+export { createNodeSQLitePersistence } from './node-persistence.cjs';
+export type { BetterSqlite3Database, NodeSQLitePersistenceOptions, NodeSQLiteSchemaMismatchPolicy, } from './node-persistence.cjs';
+export { persistedCollectionOptions } from '@tanstack/db-sqlite-persistence-core';
+export type { PersistedCollectionCoordinator, PersistedCollectionPersistence, } from '@tanstack/db-sqlite-persistence-core';

package/dist/cjs/node-driver.cjs

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const node_async_hooks = require("node:async_hooks");
+const BetterSqlite3 = require("better-sqlite3");
+const dbSqlitePersistenceCore = require("@tanstack/db-sqlite-persistence-core");
+const DEFAULT_PRAGMAS = [
+  `journal_mode = WAL`,
+  `synchronous = NORMAL`,
+  `foreign_keys = ON`
+];
+const INVALID_PRAGMA_PATTERN = /(;|--|\/\*)/;
+function assertTransactionCallbackHasDriverArg(fn) {
+  if (fn.length > 0) {
+    return;
+  }
+  throw new dbSqlitePersistenceCore.InvalidPersistedCollectionConfigError(
+    `SQLiteDriver.transaction callback must accept the transaction driver argument`
+  );
+}
+function hasExistingDatabase(options) {
+  return `database` in options;
+}
+class BetterSqlite3SQLiteDriver {
+  constructor(options) {
+    this.transactionContext = new node_async_hooks.AsyncLocalStorage();
+    this.queue = Promise.resolve();
+    this.nextSavepointId = 1;
+    if (hasExistingDatabase(options)) {
+      this.database = options.database;
+      this.ownsDatabase = false;
+      this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS);
+      return;
+    }
+    if (options.filename.trim().length === 0) {
+      throw new dbSqlitePersistenceCore.InvalidPersistedCollectionConfigError(
+        `Node SQLite driver filename cannot be empty`
+      );
+    }
+    this.database = new BetterSqlite3(options.filename, options.options);
+    this.ownsDatabase = true;
+    this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS);
+  }
+  async exec(sql) {
+    if (this.isInsideTransaction()) {
+      this.database.exec(sql);
+      return;
+    }
+    await this.enqueue(() => {
+      this.database.exec(sql);
+    });
+  }
+  async query(sql, params = []) {
+    if (this.isInsideTransaction()) {
+      return this.executeQuery(sql, params);
+    }
+    return this.enqueue(() => this.executeQuery(sql, params));
+  }
+  async run(sql, params = []) {
+    if (this.isInsideTransaction()) {
+      this.executeRun(sql, params);
+      return;
+    }
+    await this.enqueue(() => {
+      this.executeRun(sql, params);
+    });
+  }
+  async transaction(fn) {
+    assertTransactionCallbackHasDriverArg(fn);
+    if (this.isInsideTransaction()) {
+      return this.runNestedTransaction(fn);
+    }
+    return this.enqueue(async () => {
+      this.database.exec(`BEGIN IMMEDIATE`);
+      try {
+        const result = await this.transactionContext.run(
+          { depth: 1 },
+          async () => fn(this)
+        );
+        this.database.exec(`COMMIT`);
+        return result;
+      } catch (error) {
+        try {
+          this.database.exec(`ROLLBACK`);
+        } catch {
+        }
+        throw error;
+      }
+    });
+  }
+  async transactionWithDriver(fn) {
+    return this.transaction(fn);
+  }
+  close() {
+    if (!this.ownsDatabase) {
+      return;
+    }
+    this.database.close();
+  }
+  getDatabase() {
+    return this.database;
+  }
+  applyPragmas(pragmas) {
+    for (const pragma of pragmas) {
+      const trimmedPragma = pragma.trim();
+      if (trimmedPragma.length === 0) {
+        continue;
+      }
+      if (INVALID_PRAGMA_PATTERN.test(trimmedPragma)) {
+        throw new dbSqlitePersistenceCore.InvalidPersistedCollectionConfigError(
+          `Invalid SQLite PRAGMA: "${pragma}"`
+        );
+      }
+      this.database.exec(`PRAGMA ${trimmedPragma}`);
+    }
+  }
+  isInsideTransaction() {
+    return this.transactionContext.getStore() !== void 0;
+  }
+  executeQuery(sql, params) {
+    const statement = this.database.prepare(sql);
+    if (params.length === 0) {
+      return statement.all();
+    }
+    return statement.all(...params);
+  }
+  executeRun(sql, params) {
+    const statement = this.database.prepare(sql);
+    if (params.length === 0) {
+      statement.run();
+      return;
+    }
+    statement.run(...params);
+  }
+  enqueue(operation) {
+    const queuedOperation = this.queue.then(operation, operation);
+    this.queue = queuedOperation.then(
+      () => void 0,
+      () => void 0
+    );
+    return queuedOperation;
+  }
+  async runNestedTransaction(fn) {
+    const context = this.transactionContext.getStore();
+    if (!context) {
+      return fn(this);
+    }
+    const savepointName = `tsdb_sp_${this.nextSavepointId}`;
+    this.nextSavepointId++;
+    this.database.exec(`SAVEPOINT ${savepointName}`);
+    try {
+      const result = await this.transactionContext.run(
+        { depth: context.depth + 1 },
+        async () => fn(this)
+      );
+      this.database.exec(`RELEASE SAVEPOINT ${savepointName}`);
+      return result;
+    } catch (error) {
+      this.database.exec(`ROLLBACK TO SAVEPOINT ${savepointName}`);
+      this.database.exec(`RELEASE SAVEPOINT ${savepointName}`);
+      throw error;
+    }
+  }
+}
+exports.BetterSqlite3SQLiteDriver = BetterSqlite3SQLiteDriver;
+//# sourceMappingURL=node-driver.cjs.map

package/dist/cjs/node-driver.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-driver.cjs","sources":["../../src/node-driver.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks'\nimport BetterSqlite3 from 'better-sqlite3'\nimport { InvalidPersistedCollectionConfigError } from '@tanstack/db-sqlite-persistence-core'\nimport type { SQLiteDriver } from '@tanstack/db-sqlite-persistence-core'\n\nconst DEFAULT_PRAGMAS = [\n  `journal_mode = WAL`,\n  `synchronous = NORMAL`,\n  `foreign_keys = ON`,\n] as const\n\nconst INVALID_PRAGMA_PATTERN = /(;|--|\\/\\*)/\n\nexport type BetterSqlite3Database = InstanceType<typeof BetterSqlite3>\nexport type BetterSqlite3OpenOptions = ConstructorParameters<\n  typeof BetterSqlite3\n>[1]\n\ntype BetterSqlite3ExistingDatabaseOptions = {\n  database: BetterSqlite3Database\n  pragmas?: ReadonlyArray<string>\n}\n\ntype BetterSqlite3OpenFileOptions = {\n  filename: string\n  options?: BetterSqlite3OpenOptions\n  pragmas?: ReadonlyArray<string>\n}\n\nexport type BetterSqlite3DriverOptions =\n  | BetterSqlite3ExistingDatabaseOptions\n  | BetterSqlite3OpenFileOptions\n\ntype TransactionContext = {\n  depth: number\n}\n\nfunction assertTransactionCallbackHasDriverArg(\n  fn: (transactionDriver: SQLiteDriver) => Promise<unknown>,\n): void {\n  if (fn.length > 0) {\n    return\n  }\n\n  throw new InvalidPersistedCollectionConfigError(\n    `SQLiteDriver.transaction callback must accept the transaction driver argument`,\n  )\n}\n\nfunction hasExistingDatabase(\n  options: BetterSqlite3DriverOptions,\n): options is BetterSqlite3ExistingDatabaseOptions {\n  return `database` in options\n}\n\nexport class BetterSqlite3SQLiteDriver implements SQLiteDriver {\n  private readonly database: BetterSqlite3Database\n  private readonly ownsDatabase: boolean\n  private readonly transactionContext =\n    new AsyncLocalStorage<TransactionContext>()\n  private queue: Promise<void> = Promise.resolve()\n  private nextSavepointId = 1\n\n  constructor(options: BetterSqlite3DriverOptions) {\n    if (hasExistingDatabase(options)) {\n      this.database = options.database\n      this.ownsDatabase = false\n      this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS)\n      return\n    }\n\n    if (options.filename.trim().length === 0) {\n      throw new InvalidPersistedCollectionConfigError(\n        `Node SQLite driver filename cannot be empty`,\n      )\n    }\n\n    this.database = new BetterSqlite3(options.filename, options.options)\n    this.ownsDatabase = true\n    this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS)\n  }\n\n  async exec(sql: string): Promise<void> {\n    if (this.isInsideTransaction()) {\n      this.database.exec(sql)\n      return\n    }\n\n    await this.enqueue(() => {\n      this.database.exec(sql)\n    })\n  }\n\n  async query<T>(\n    sql: string,\n    params: ReadonlyArray<unknown> = [],\n  ): Promise<ReadonlyArray<T>> {\n    if (this.isInsideTransaction()) {\n      return this.executeQuery<T>(sql, params)\n    }\n\n    return this.enqueue(() => this.executeQuery<T>(sql, params))\n  }\n\n  async run(sql: string, params: ReadonlyArray<unknown> = []): Promise<void> {\n    if (this.isInsideTransaction()) {\n      this.executeRun(sql, params)\n      return\n    }\n\n    await this.enqueue(() => {\n      this.executeRun(sql, params)\n    })\n  }\n\n  async transaction<T>(\n    fn: (transactionDriver: SQLiteDriver) => Promise<T>,\n  ): Promise<T> {\n    assertTransactionCallbackHasDriverArg(fn)\n\n    if (this.isInsideTransaction()) {\n      return this.runNestedTransaction(fn)\n    }\n\n    return this.enqueue(async () => {\n      this.database.exec(`BEGIN IMMEDIATE`)\n      try {\n        const result = await this.transactionContext.run(\n          { depth: 1 },\n          async () => fn(this),\n        )\n        this.database.exec(`COMMIT`)\n        return result\n      } catch (error) {\n        try {\n          this.database.exec(`ROLLBACK`)\n        } catch {\n          // Keep the original transaction error as the primary failure.\n        }\n        throw error\n      }\n    })\n  }\n\n  async transactionWithDriver<T>(\n    fn: (transactionDriver: SQLiteDriver) => Promise<T>,\n  ): Promise<T> {\n    return this.transaction(fn)\n  }\n\n  close(): void {\n    if (!this.ownsDatabase) {\n      return\n    }\n\n    this.database.close()\n  }\n\n  getDatabase(): BetterSqlite3Database {\n    return this.database\n  }\n\n  private applyPragmas(pragmas: ReadonlyArray<string>): void {\n    for (const pragma of pragmas) {\n      const trimmedPragma = pragma.trim()\n      if (trimmedPragma.length === 0) {\n        continue\n      }\n\n      if (INVALID_PRAGMA_PATTERN.test(trimmedPragma)) {\n        throw new InvalidPersistedCollectionConfigError(\n          `Invalid SQLite PRAGMA: \"${pragma}\"`,\n        )\n      }\n\n      this.database.exec(`PRAGMA ${trimmedPragma}`)\n    }\n  }\n\n  private isInsideTransaction(): boolean {\n    return this.transactionContext.getStore() !== undefined\n  }\n\n  private executeQuery<T>(\n    sql: string,\n    params: ReadonlyArray<unknown>,\n  ): ReadonlyArray<T> {\n    const statement = this.database.prepare(sql)\n    if (params.length === 0) {\n      return statement.all() as ReadonlyArray<T>\n    }\n\n    return statement.all(...params) as ReadonlyArray<T>\n  }\n\n  private executeRun(sql: string, params: ReadonlyArray<unknown>): void {\n    const statement = this.database.prepare(sql)\n    if (params.length === 0) {\n      statement.run()\n      return\n    }\n\n    statement.run(...params)\n  }\n\n  private enqueue<T>(operation: () => Promise<T> | T): Promise<T> {\n    const queuedOperation = this.queue.then(operation, operation)\n    this.queue = queuedOperation.then(\n      () => undefined,\n      () => undefined,\n    )\n    return queuedOperation\n  }\n\n  private async runNestedTransaction<T>(\n    fn: (transactionDriver: SQLiteDriver) => Promise<T>,\n  ): Promise<T> {\n    const context = this.transactionContext.getStore()\n    if (!context) {\n      return fn(this)\n    }\n\n    const savepointName = `tsdb_sp_${this.nextSavepointId}`\n    this.nextSavepointId++\n    this.database.exec(`SAVEPOINT ${savepointName}`)\n\n    try {\n      const result = await this.transactionContext.run(\n        { depth: context.depth + 1 },\n        async () => fn(this),\n      )\n      this.database.exec(`RELEASE SAVEPOINT ${savepointName}`)\n      return result\n    } catch (error) {\n      this.database.exec(`ROLLBACK TO SAVEPOINT ${savepointName}`)\n      this.database.exec(`RELEASE SAVEPOINT ${savepointName}`)\n      throw error\n    }\n  }\n}\n\nexport function createBetterSqlite3Driver(\n  options: BetterSqlite3DriverOptions,\n): BetterSqlite3SQLiteDriver {\n  return new BetterSqlite3SQLiteDriver(options)\n}\n"],"names":["InvalidPersistedCollectionConfigError","AsyncLocalStorage"],"mappings":";;;;;AAKA,MAAM,kBAAkB;AAAA,EACtB;AAAA,EACA;AAAA,EACA;AACF;AAEA,MAAM,yBAAyB;AA0B/B,SAAS,sCACP,IACM;AACN,MAAI,GAAG,SAAS,GAAG;AACjB;AAAA,EACF;AAEA,QAAM,IAAIA,wBAAAA;AAAAA,IACR;AAAA,EAAA;AAEJ;AAEA,SAAS,oBACP,SACiD;AACjD,SAAO,cAAc;AACvB;AAEO,MAAM,0BAAkD;AAAA,EAQ7D,YAAY,SAAqC;AALjD,SAAiB,qBACf,IAAIC,mCAAA;AACN,SAAQ,QAAuB,QAAQ,QAAA;AACvC,SAAQ,kBAAkB;AAGxB,QAAI,oBAAoB,OAAO,GAAG;AAChC,WAAK,WAAW,QAAQ;AACxB,WAAK,eAAe;AACpB,WAAK,aAAa,QAAQ,WAAW,eAAe;AACpD;AAAA,IACF;AAEA,QAAI,QAAQ,SAAS,KAAA,EAAO,WAAW,GAAG;AACxC,YAAM,IAAID,wBAAAA;AAAAA,QACR;AAAA,MAAA;AAAA,IAEJ;AAEA,SAAK,WAAW,IAAI,cAAc,QAAQ,UAAU,QAAQ,OAAO;AACnE,SAAK,eAAe;AACpB,SAAK,aAAa,QAAQ,WAAW,eAAe;AAAA,EACtD;AAAA,EAEA,MAAM,KAAK,KAA4B;AACrC,QAAI,KAAK,uBAAuB;AAC9B,WAAK,SAAS,KAAK,GAAG;AACtB;AAAA,IACF;AAEA,UAAM,KAAK,QAAQ,MAAM;AACvB,WAAK,SAAS,KAAK,GAAG;AAAA,IACxB,CAAC;AAAA,EACH;AAAA,EAEA,MAAM,MACJ,KACA,SAAiC,IACN;AAC3B,QAAI,KAAK,uBAAuB;AAC9B,aAAO,KAAK,aAAgB,KAAK,MAAM;AAAA,IACzC;AAEA,WAAO,KAAK,QAAQ,MAAM,KAAK,aAAgB,KAAK,MAAM,CAAC;AAAA,EAC7D;AAAA,EAEA,MAAM,IAAI,KAAa,SAAiC,IAAmB;AACzE,QAAI,KAAK,uBAAuB;AAC9B,WAAK,WAAW,KAAK,MAAM;AAC3B;AAAA,IACF;AAEA,UAAM,KAAK,QAAQ,MAAM;AACvB,WAAK,WAAW,KAAK,MAAM;AAAA,IAC7B,CAAC;AAAA,EACH;AAAA,EAEA,MAAM,YACJ,IACY;AACZ,0CAAsC,EAAE;AAExC,QAAI,KAAK,uBAAuB;AAC9B,aAAO,KAAK,qBAAqB,EAAE;AAAA,IACrC;AAEA,WAAO,KAAK,QAAQ,YAAY;AAC9B,WAAK,SAAS,KAAK,iBAAiB;AACpC,UAAI;AACF,cAAM,SAAS,MAAM,KAAK,mBAAmB;AAAA,UAC3C,EAAE,OAAO,EAAA;AAAA,UACT,YAAY,GAAG,IAAI;AAAA,QAAA;AAErB,aAAK,SAAS,KAAK,QAAQ;AAC3B,eAAO;AAAA,MACT,SAAS,OAAO;AACd,YAAI;AACF,eAAK,SAAS,KAAK,UAAU;AAAA,QAC/B,QAAQ;AAAA,QAER;AACA,cAAM;AAAA,MACR;AAAA,IACF,CAAC;AAAA,EACH;AAAA,EAEA,MAAM,sBACJ,IACY;AACZ,WAAO,KAAK,YAAY,EAAE;AAAA,EAC5B;AAAA,EAEA,QAAc;AACZ,QAAI,CAAC,KAAK,cAAc;AACtB;AAAA,IACF;AAEA,SAAK,SAAS,MAAA;AAAA,EAChB;AAAA,EAEA,cAAqC;AACnC,WAAO,KAAK;AAAA,EACd;AAAA,EAEQ,aAAa,SAAsC;AACzD,eAAW,UAAU,SAAS;AAC5B,YAAM,gBAAgB,OAAO,KAAA;AAC7B,UAAI,cAAc,WAAW,GAAG;AAC9B;AAAA,MACF;AAEA,UAAI,uBAAuB,KAAK,aAAa,GAAG;AAC9C,cAAM,IAAIA,wBAAAA;AAAAA,UACR,2BAA2B,MAAM;AAAA,QAAA;AAAA,MAErC;AAEA,WAAK,SAAS,KAAK,UAAU,aAAa,EAAE;AAAA,IAC9C;AAAA,EACF;AAAA,EAEQ,sBAA+B;AACrC,WAAO,KAAK,mBAAmB,SAAA,MAAe;AAAA,EAChD;AAAA,EAEQ,aACN,KACA,QACkB;AAClB,UAAM,YAAY,KAAK,SAAS,QAAQ,GAAG;AAC3C,QAAI,OAAO,WAAW,GAAG;AACvB,aAAO,UAAU,IAAA;AAAA,IACnB;AAEA,WAAO,UAAU,IAAI,GAAG,MAAM;AAAA,EAChC;AAAA,EAEQ,WAAW,KAAa,QAAsC;AACpE,UAAM,YAAY,KAAK,SAAS,QAAQ,GAAG;AAC3C,QAAI,OAAO,WAAW,GAAG;AACvB,gBAAU,IAAA;AACV;AAAA,IACF;AAEA,cAAU,IAAI,GAAG,MAAM;AAAA,EACzB;AAAA,EAEQ,QAAW,WAA6C;AAC9D,UAAM,kBAAkB,KAAK,MAAM,KAAK,WAAW,SAAS;AAC5D,SAAK,QAAQ,gBAAgB;AAAA,MAC3B,MAAM;AAAA,MACN,MAAM;AAAA,IAAA;AAER,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,qBACZ,IACY;AACZ,UAAM,UAAU,KAAK,mBAAmB,SAAA;AACxC,QAAI,CAAC,SAAS;AACZ,aAAO,GAAG,IAAI;AAAA,IAChB;AAEA,UAAM,gBAAgB,WAAW,KAAK,eAAe;AACrD,SAAK;AACL,SAAK,SAAS,KAAK,aAAa,aAAa,EAAE;AAE/C,QAAI;AACF,YAAM,SAAS,MAAM,KAAK,mBAAmB;AAAA,QAC3C,EAAE,OAAO,QAAQ,QAAQ,EAAA;AAAA,QACzB,YAAY,GAAG,IAAI;AAAA,MAAA;AAErB,WAAK,SAAS,KAAK,qBAAqB,aAAa,EAAE;AACvD,aAAO;AAAA,IACT,SAAS,OAAO;AACd,WAAK,SAAS,KAAK,yBAAyB,aAAa,EAAE;AAC3D,WAAK,SAAS,KAAK,qBAAqB,aAAa,EAAE;AACvD,YAAM;AAAA,IACR;AAAA,EACF;AACF;;"}

package/dist/cjs/node-driver.d.cts

@@ -0,0 +1,37 @@
+import { default as BetterSqlite3 } from 'better-sqlite3';
+import { SQLiteDriver } from '@tanstack/db-sqlite-persistence-core';
+export type BetterSqlite3Database = InstanceType<typeof BetterSqlite3>;
+export type BetterSqlite3OpenOptions = ConstructorParameters<typeof BetterSqlite3>[1];
+type BetterSqlite3ExistingDatabaseOptions = {
+    database: BetterSqlite3Database;
+    pragmas?: ReadonlyArray<string>;
+};
+type BetterSqlite3OpenFileOptions = {
+    filename: string;
+    options?: BetterSqlite3OpenOptions;
+    pragmas?: ReadonlyArray<string>;
+};
+export type BetterSqlite3DriverOptions = BetterSqlite3ExistingDatabaseOptions | BetterSqlite3OpenFileOptions;
+export declare class BetterSqlite3SQLiteDriver implements SQLiteDriver {
+    private readonly database;
+    private readonly ownsDatabase;
+    private readonly transactionContext;
+    private queue;
+    private nextSavepointId;
+    constructor(options: BetterSqlite3DriverOptions);
+    exec(sql: string): Promise<void>;
+    query<T>(sql: string, params?: ReadonlyArray<unknown>): Promise<ReadonlyArray<T>>;
+    run(sql: string, params?: ReadonlyArray<unknown>): Promise<void>;
+    transaction<T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>): Promise<T>;
+    transactionWithDriver<T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>): Promise<T>;
+    close(): void;
+    getDatabase(): BetterSqlite3Database;
+    private applyPragmas;
+    private isInsideTransaction;
+    private executeQuery;
+    private executeRun;
+    private enqueue;
+    private runNestedTransaction;
+}
+export declare function createBetterSqlite3Driver(options: BetterSqlite3DriverOptions): BetterSqlite3SQLiteDriver;
+export {};

package/dist/cjs/node-persistence.cjs

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const dbSqlitePersistenceCore = require("@tanstack/db-sqlite-persistence-core");
+const nodeDriver = require("./node-driver.cjs");
+function normalizeSchemaMismatchPolicy(policy) {
+  if (policy === `throw`) {
+    return `sync-absent-error`;
+  }
+  return policy;
+}
+function resolveSchemaMismatchPolicy(explicitPolicy, mode) {
+  if (explicitPolicy) {
+    return normalizeSchemaMismatchPolicy(explicitPolicy);
+  }
+  return mode === `sync-present` ? `sync-present-reset` : `sync-absent-error`;
+}
+function createAdapterCacheKey(schemaMismatchPolicy, schemaVersion) {
+  const schemaVersionKey = schemaVersion === void 0 ? `schema:default` : `schema:${schemaVersion}`;
+  return `${schemaMismatchPolicy}|${schemaVersionKey}`;
+}
+function createInternalSQLiteDriver(options) {
+  return new nodeDriver.BetterSqlite3SQLiteDriver({
+    database: options.database,
+    ...options.pragmas ? { pragmas: options.pragmas } : {}
+  });
+}
+function resolveAdapterBaseOptions(options) {
+  return {
+    appliedTxPruneMaxRows: options.appliedTxPruneMaxRows,
+    appliedTxPruneMaxAgeSeconds: options.appliedTxPruneMaxAgeSeconds,
+    pullSinceReloadThreshold: options.pullSinceReloadThreshold
+  };
+}
+function createNodeSQLitePersistence(options) {
+  const { coordinator, schemaMismatchPolicy } = options;
+  const driver = createInternalSQLiteDriver(options);
+  const adapterBaseOptions = resolveAdapterBaseOptions(options);
+  const resolvedCoordinator = coordinator ?? new dbSqlitePersistenceCore.SingleProcessCoordinator();
+  const adapterCache = /* @__PURE__ */ new Map();
+  const getAdapterForCollection = (mode, schemaVersion) => {
+    const resolvedSchemaMismatchPolicy = resolveSchemaMismatchPolicy(
+      schemaMismatchPolicy,
+      mode
+    );
+    const cacheKey = createAdapterCacheKey(
+      resolvedSchemaMismatchPolicy,
+      schemaVersion
+    );
+    const cachedAdapter = adapterCache.get(cacheKey);
+    if (cachedAdapter) {
+      return cachedAdapter;
+    }
+    const adapter = dbSqlitePersistenceCore.createSQLiteCorePersistenceAdapter({
+      ...adapterBaseOptions,
+      driver,
+      schemaMismatchPolicy: resolvedSchemaMismatchPolicy,
+      ...schemaVersion === void 0 ? {} : { schemaVersion }
+    });
+    adapterCache.set(cacheKey, adapter);
+    return adapter;
+  };
+  const createCollectionPersistence = (mode, schemaVersion) => ({
+    adapter: getAdapterForCollection(
+      mode,
+      schemaVersion
+    ),
+    coordinator: resolvedCoordinator
+  });
+  const defaultPersistence = createCollectionPersistence(
+    `sync-absent`,
+    void 0
+  );
+  return {
+    ...defaultPersistence,
+    resolvePersistenceForCollection: ({ mode, schemaVersion }) => createCollectionPersistence(mode, schemaVersion),
+    // Backward compatible fallback for older callers.
+    resolvePersistenceForMode: (mode) => createCollectionPersistence(mode, void 0)
+  };
+}
+exports.createNodeSQLitePersistence = createNodeSQLitePersistence;
+//# sourceMappingURL=node-persistence.cjs.map

package/dist/cjs/node-persistence.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-persistence.cjs","sources":["../../src/node-persistence.ts"],"sourcesContent":["import {\n  SingleProcessCoordinator,\n  createSQLiteCorePersistenceAdapter,\n} from '@tanstack/db-sqlite-persistence-core'\nimport { BetterSqlite3SQLiteDriver } from './node-driver'\nimport type {\n  PersistedCollectionCoordinator,\n  PersistedCollectionMode,\n  PersistedCollectionPersistence,\n  SQLiteCoreAdapterOptions,\n  SQLiteDriver,\n} from '@tanstack/db-sqlite-persistence-core'\nimport type { BetterSqlite3Database } from './node-driver'\n\nexport type { BetterSqlite3Database } from './node-driver'\n\ntype NodeSQLiteCoreSchemaMismatchPolicy =\n  | `sync-present-reset`\n  | `sync-absent-error`\n  | `reset`\n\nexport type NodeSQLiteSchemaMismatchPolicy =\n  | NodeSQLiteCoreSchemaMismatchPolicy\n  | `throw`\n\ntype NodeSQLitePersistenceBaseOptions = Omit<\n  SQLiteCoreAdapterOptions,\n  `driver` | `schemaVersion` | `schemaMismatchPolicy`\n> & {\n  database: BetterSqlite3Database\n  pragmas?: ReadonlyArray<string>\n  coordinator?: PersistedCollectionCoordinator\n  schemaMismatchPolicy?: NodeSQLiteSchemaMismatchPolicy\n}\n\nexport type NodeSQLitePersistenceOptions = NodeSQLitePersistenceBaseOptions\n\nfunction normalizeSchemaMismatchPolicy(\n  policy: NodeSQLiteSchemaMismatchPolicy,\n): NodeSQLiteCoreSchemaMismatchPolicy {\n  if (policy === `throw`) {\n    return `sync-absent-error`\n  }\n\n  return policy\n}\n\nfunction resolveSchemaMismatchPolicy(\n  explicitPolicy: NodeSQLiteSchemaMismatchPolicy | undefined,\n  mode: PersistedCollectionMode,\n): NodeSQLiteCoreSchemaMismatchPolicy {\n  if (explicitPolicy) {\n    return normalizeSchemaMismatchPolicy(explicitPolicy)\n  }\n\n  return mode === `sync-present` ? `sync-present-reset` : `sync-absent-error`\n}\n\nfunction createAdapterCacheKey(\n  schemaMismatchPolicy: NodeSQLiteCoreSchemaMismatchPolicy,\n  schemaVersion: number | undefined,\n): string {\n  const schemaVersionKey =\n    schemaVersion === undefined ? `schema:default` : `schema:${schemaVersion}`\n  return `${schemaMismatchPolicy}|${schemaVersionKey}`\n}\n\nfunction createInternalSQLiteDriver(\n  options: NodeSQLitePersistenceOptions,\n): SQLiteDriver {\n  return new BetterSqlite3SQLiteDriver({\n    database: options.database,\n    ...(options.pragmas ? { pragmas: options.pragmas } : {}),\n  })\n}\n\nfunction resolveAdapterBaseOptions(\n  options: NodeSQLitePersistenceOptions,\n): Omit<\n  SQLiteCoreAdapterOptions,\n  `driver` | `schemaVersion` | `schemaMismatchPolicy`\n> {\n  return {\n    appliedTxPruneMaxRows: options.appliedTxPruneMaxRows,\n    appliedTxPruneMaxAgeSeconds: options.appliedTxPruneMaxAgeSeconds,\n    pullSinceReloadThreshold: options.pullSinceReloadThreshold,\n  }\n}\n\n/**\n * Creates a shared SQLite persistence instance that can be reused by many\n * collections on the same database. Collection-specific schema versions are\n * resolved by `persistedCollectionOptions` via `resolvePersistenceForCollection`.\n */\nexport function createNodeSQLitePersistence<\n  T extends object,\n  TKey extends string | number = string | number,\n>(\n  options: NodeSQLitePersistenceOptions,\n): PersistedCollectionPersistence<T, TKey> {\n  const { coordinator, schemaMismatchPolicy } = options\n  const driver = createInternalSQLiteDriver(options)\n  const adapterBaseOptions = resolveAdapterBaseOptions(options)\n  const resolvedCoordinator = coordinator ?? new SingleProcessCoordinator()\n  const adapterCache = new Map<\n    string,\n    ReturnType<\n      typeof createSQLiteCorePersistenceAdapter<\n        Record<string, unknown>,\n        string | number\n      >\n    >\n  >()\n\n  const getAdapterForCollection = (\n    mode: PersistedCollectionMode,\n    schemaVersion: number | undefined,\n  ) => {\n    const resolvedSchemaMismatchPolicy = resolveSchemaMismatchPolicy(\n      schemaMismatchPolicy,\n      mode,\n    )\n    const cacheKey = createAdapterCacheKey(\n      resolvedSchemaMismatchPolicy,\n      schemaVersion,\n    )\n    const cachedAdapter = adapterCache.get(cacheKey)\n    if (cachedAdapter) {\n      return cachedAdapter\n    }\n\n    const adapter = createSQLiteCorePersistenceAdapter<\n      Record<string, unknown>,\n      string | number\n    >({\n      ...adapterBaseOptions,\n      driver,\n      schemaMismatchPolicy: resolvedSchemaMismatchPolicy,\n      ...(schemaVersion === undefined ? {} : { schemaVersion }),\n    })\n    adapterCache.set(cacheKey, adapter)\n    return adapter\n  }\n\n  const createCollectionPersistence = (\n    mode: PersistedCollectionMode,\n    schemaVersion: number | undefined,\n  ): PersistedCollectionPersistence<T, TKey> => ({\n    adapter: getAdapterForCollection(\n      mode,\n      schemaVersion,\n    ) as unknown as PersistedCollectionPersistence<T, TKey>[`adapter`],\n    coordinator: resolvedCoordinator,\n  })\n\n  const defaultPersistence = createCollectionPersistence(\n    `sync-absent`,\n    undefined,\n  )\n\n  return {\n    ...defaultPersistence,\n    resolvePersistenceForCollection: ({ mode, schemaVersion }) =>\n      createCollectionPersistence(mode, schemaVersion),\n    // Backward compatible fallback for older callers.\n    resolvePersistenceForMode: (mode) =>\n      createCollectionPersistence(mode, undefined),\n  }\n}\n"],"names":["BetterSqlite3SQLiteDriver","SingleProcessCoordinator","createSQLiteCorePersistenceAdapter"],"mappings":";;;;AAqCA,SAAS,8BACP,QACoC;AACpC,MAAI,WAAW,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAEA,SAAS,4BACP,gBACA,MACoC;AACpC,MAAI,gBAAgB;AAClB,WAAO,8BAA8B,cAAc;AAAA,EACrD;AAEA,SAAO,SAAS,iBAAiB,uBAAuB;AAC1D;AAEA,SAAS,sBACP,sBACA,eACQ;AACR,QAAM,mBACJ,kBAAkB,SAAY,mBAAmB,UAAU,aAAa;AAC1E,SAAO,GAAG,oBAAoB,IAAI,gBAAgB;AACpD;AAEA,SAAS,2BACP,SACc;AACd,SAAO,IAAIA,WAAAA,0BAA0B;AAAA,IACnC,UAAU,QAAQ;AAAA,IAClB,GAAI,QAAQ,UAAU,EAAE,SAAS,QAAQ,QAAA,IAAY,CAAA;AAAA,EAAC,CACvD;AACH;AAEA,SAAS,0BACP,SAIA;AACA,SAAO;AAAA,IACL,uBAAuB,QAAQ;AAAA,IAC/B,6BAA6B,QAAQ;AAAA,IACrC,0BAA0B,QAAQ;AAAA,EAAA;AAEtC;AAOO,SAAS,4BAId,SACyC;AACzC,QAAM,EAAE,aAAa,qBAAA,IAAyB;AAC9C,QAAM,SAAS,2BAA2B,OAAO;AACjD,QAAM,qBAAqB,0BAA0B,OAAO;AAC5D,QAAM,sBAAsB,eAAe,IAAIC,iDAAA;AAC/C,QAAM,mCAAmB,IAAA;AAUzB,QAAM,0BAA0B,CAC9B,MACA,kBACG;AACH,UAAM,+BAA+B;AAAA,MACnC;AAAA,MACA;AAAA,IAAA;AAEF,UAAM,WAAW;AAAA,MACf;AAAA,MACA;AAAA,IAAA;AAEF,UAAM,gBAAgB,aAAa,IAAI,QAAQ;AAC/C,QAAI,eAAe;AACjB,aAAO;AAAA,IACT;AAEA,UAAM,UAAUC,wBAAAA,mCAGd;AAAA,MACA,GAAG;AAAA,MACH;AAAA,MACA,sBAAsB;AAAA,MACtB,GAAI,kBAAkB,SAAY,CAAA,IAAK,EAAE,cAAA;AAAA,IAAc,CACxD;AACD,iBAAa,IAAI,UAAU,OAAO;AAClC,WAAO;AAAA,EACT;AAEA,QAAM,8BAA8B,CAClC,MACA,mBAC6C;AAAA,IAC7C,SAAS;AAAA,MACP;AAAA,MACA;AAAA,IAAA;AAAA,IAEF,aAAa;AAAA,EAAA;AAGf,QAAM,qBAAqB;AAAA,IACzB;AAAA,IACA;AAAA,EAAA;AAGF,SAAO;AAAA,IACL,GAAG;AAAA,IACH,iCAAiC,CAAC,EAAE,MAAM,oBACxC,4BAA4B,MAAM,aAAa;AAAA;AAAA,IAEjD,2BAA2B,CAAC,SAC1B,4BAA4B,MAAM,MAAS;AAAA,EAAA;AAEjD;;"}

package/dist/cjs/node-persistence.d.cts

@@ -0,0 +1,18 @@
+import { PersistedCollectionCoordinator, PersistedCollectionPersistence, SQLiteCoreAdapterOptions } from '@tanstack/db-sqlite-persistence-core';
+import { BetterSqlite3Database } from './node-driver.cjs';
+export type { BetterSqlite3Database } from './node-driver.cjs';
+type NodeSQLiteCoreSchemaMismatchPolicy = `sync-present-reset` | `sync-absent-error` | `reset`;
+export type NodeSQLiteSchemaMismatchPolicy = NodeSQLiteCoreSchemaMismatchPolicy | `throw`;
+type NodeSQLitePersistenceBaseOptions = Omit<SQLiteCoreAdapterOptions, `driver` | `schemaVersion` | `schemaMismatchPolicy`> & {
+    database: BetterSqlite3Database;
+    pragmas?: ReadonlyArray<string>;
+    coordinator?: PersistedCollectionCoordinator;
+    schemaMismatchPolicy?: NodeSQLiteSchemaMismatchPolicy;
+};
+export type NodeSQLitePersistenceOptions = NodeSQLitePersistenceBaseOptions;
+/**
+ * Creates a shared SQLite persistence instance that can be reused by many
+ * collections on the same database. Collection-specific schema versions are
+ * resolved by `persistedCollectionOptions` via `resolvePersistenceForCollection`.
+ */
+export declare function createNodeSQLitePersistence<T extends object, TKey extends string | number = string | number>(options: NodeSQLitePersistenceOptions): PersistedCollectionPersistence<T, TKey>;

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+export { createNodeSQLitePersistence } from './node-persistence.js';
+export type { BetterSqlite3Database, NodeSQLitePersistenceOptions, NodeSQLiteSchemaMismatchPolicy, } from './node-persistence.js';
+export { persistedCollectionOptions } from '@tanstack/db-sqlite-persistence-core';
+export type { PersistedCollectionCoordinator, PersistedCollectionPersistence, } from '@tanstack/db-sqlite-persistence-core';

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+import { createNodeSQLitePersistence } from "./node-persistence.js";
+import { persistedCollectionOptions } from "@tanstack/db-sqlite-persistence-core";
+export {
+  createNodeSQLitePersistence,
+  persistedCollectionOptions
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/dist/esm/node-driver.d.ts

@@ -0,0 +1,37 @@
+import { default as BetterSqlite3 } from 'better-sqlite3';
+import { SQLiteDriver } from '@tanstack/db-sqlite-persistence-core';
+export type BetterSqlite3Database = InstanceType<typeof BetterSqlite3>;
+export type BetterSqlite3OpenOptions = ConstructorParameters<typeof BetterSqlite3>[1];
+type BetterSqlite3ExistingDatabaseOptions = {
+    database: BetterSqlite3Database;
+    pragmas?: ReadonlyArray<string>;
+};
+type BetterSqlite3OpenFileOptions = {
+    filename: string;
+    options?: BetterSqlite3OpenOptions;
+    pragmas?: ReadonlyArray<string>;
+};
+export type BetterSqlite3DriverOptions = BetterSqlite3ExistingDatabaseOptions | BetterSqlite3OpenFileOptions;
+export declare class BetterSqlite3SQLiteDriver implements SQLiteDriver {
+    private readonly database;
+    private readonly ownsDatabase;
+    private readonly transactionContext;
+    private queue;
+    private nextSavepointId;
+    constructor(options: BetterSqlite3DriverOptions);
+    exec(sql: string): Promise<void>;
+    query<T>(sql: string, params?: ReadonlyArray<unknown>): Promise<ReadonlyArray<T>>;
+    run(sql: string, params?: ReadonlyArray<unknown>): Promise<void>;
+    transaction<T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>): Promise<T>;
+    transactionWithDriver<T>(fn: (transactionDriver: SQLiteDriver) => Promise<T>): Promise<T>;
+    close(): void;
+    getDatabase(): BetterSqlite3Database;
+    private applyPragmas;
+    private isInsideTransaction;
+    private executeQuery;
+    private executeRun;
+    private enqueue;
+    private runNestedTransaction;
+}
+export declare function createBetterSqlite3Driver(options: BetterSqlite3DriverOptions): BetterSqlite3SQLiteDriver;
+export {};

package/dist/esm/node-driver.js

@@ -0,0 +1,165 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import BetterSqlite3 from "better-sqlite3";
+import { InvalidPersistedCollectionConfigError } from "@tanstack/db-sqlite-persistence-core";
+const DEFAULT_PRAGMAS = [
+  `journal_mode = WAL`,
+  `synchronous = NORMAL`,
+  `foreign_keys = ON`
+];
+const INVALID_PRAGMA_PATTERN = /(;|--|\/\*)/;
+function assertTransactionCallbackHasDriverArg(fn) {
+  if (fn.length > 0) {
+    return;
+  }
+  throw new InvalidPersistedCollectionConfigError(
+    `SQLiteDriver.transaction callback must accept the transaction driver argument`
+  );
+}
+function hasExistingDatabase(options) {
+  return `database` in options;
+}
+class BetterSqlite3SQLiteDriver {
+  constructor(options) {
+    this.transactionContext = new AsyncLocalStorage();
+    this.queue = Promise.resolve();
+    this.nextSavepointId = 1;
+    if (hasExistingDatabase(options)) {
+      this.database = options.database;
+      this.ownsDatabase = false;
+      this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS);
+      return;
+    }
+    if (options.filename.trim().length === 0) {
+      throw new InvalidPersistedCollectionConfigError(
+        `Node SQLite driver filename cannot be empty`
+      );
+    }
+    this.database = new BetterSqlite3(options.filename, options.options);
+    this.ownsDatabase = true;
+    this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS);
+  }
+  async exec(sql) {
+    if (this.isInsideTransaction()) {
+      this.database.exec(sql);
+      return;
+    }
+    await this.enqueue(() => {
+      this.database.exec(sql);
+    });
+  }
+  async query(sql, params = []) {
+    if (this.isInsideTransaction()) {
+      return this.executeQuery(sql, params);
+    }
+    return this.enqueue(() => this.executeQuery(sql, params));
+  }
+  async run(sql, params = []) {
+    if (this.isInsideTransaction()) {
+      this.executeRun(sql, params);
+      return;
+    }
+    await this.enqueue(() => {
+      this.executeRun(sql, params);
+    });
+  }
+  async transaction(fn) {
+    assertTransactionCallbackHasDriverArg(fn);
+    if (this.isInsideTransaction()) {
+      return this.runNestedTransaction(fn);
+    }
+    return this.enqueue(async () => {
+      this.database.exec(`BEGIN IMMEDIATE`);
+      try {
+        const result = await this.transactionContext.run(
+          { depth: 1 },
+          async () => fn(this)
+        );
+        this.database.exec(`COMMIT`);
+        return result;
+      } catch (error) {
+        try {
+          this.database.exec(`ROLLBACK`);
+        } catch {
+        }
+        throw error;
+      }
+    });
+  }
+  async transactionWithDriver(fn) {
+    return this.transaction(fn);
+  }
+  close() {
+    if (!this.ownsDatabase) {
+      return;
+    }
+    this.database.close();
+  }
+  getDatabase() {
+    return this.database;
+  }
+  applyPragmas(pragmas) {
+    for (const pragma of pragmas) {
+      const trimmedPragma = pragma.trim();
+      if (trimmedPragma.length === 0) {
+        continue;
+      }
+      if (INVALID_PRAGMA_PATTERN.test(trimmedPragma)) {
+        throw new InvalidPersistedCollectionConfigError(
+          `Invalid SQLite PRAGMA: "${pragma}"`
+        );
+      }
+      this.database.exec(`PRAGMA ${trimmedPragma}`);
+    }
+  }
+  isInsideTransaction() {
+    return this.transactionContext.getStore() !== void 0;
+  }
+  executeQuery(sql, params) {
+    const statement = this.database.prepare(sql);
+    if (params.length === 0) {
+      return statement.all();
+    }
+    return statement.all(...params);
+  }
+  executeRun(sql, params) {
+    const statement = this.database.prepare(sql);
+    if (params.length === 0) {
+      statement.run();
+      return;
+    }
+    statement.run(...params);
+  }
+  enqueue(operation) {
+    const queuedOperation = this.queue.then(operation, operation);
+    this.queue = queuedOperation.then(
+      () => void 0,
+      () => void 0
+    );
+    return queuedOperation;
+  }
+  async runNestedTransaction(fn) {
+    const context = this.transactionContext.getStore();
+    if (!context) {
+      return fn(this);
+    }
+    const savepointName = `tsdb_sp_${this.nextSavepointId}`;
+    this.nextSavepointId++;
+    this.database.exec(`SAVEPOINT ${savepointName}`);
+    try {
+      const result = await this.transactionContext.run(
+        { depth: context.depth + 1 },
+        async () => fn(this)
+      );
+      this.database.exec(`RELEASE SAVEPOINT ${savepointName}`);
+      return result;
+    } catch (error) {
+      this.database.exec(`ROLLBACK TO SAVEPOINT ${savepointName}`);
+      this.database.exec(`RELEASE SAVEPOINT ${savepointName}`);
+      throw error;
+    }
+  }
+}
+export {
+  BetterSqlite3SQLiteDriver
+};
+//# sourceMappingURL=node-driver.js.map

package/dist/esm/node-driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-driver.js","sources":["../../src/node-driver.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks'\nimport BetterSqlite3 from 'better-sqlite3'\nimport { InvalidPersistedCollectionConfigError } from '@tanstack/db-sqlite-persistence-core'\nimport type { SQLiteDriver } from '@tanstack/db-sqlite-persistence-core'\n\nconst DEFAULT_PRAGMAS = [\n  `journal_mode = WAL`,\n  `synchronous = NORMAL`,\n  `foreign_keys = ON`,\n] as const\n\nconst INVALID_PRAGMA_PATTERN = /(;|--|\\/\\*)/\n\nexport type BetterSqlite3Database = InstanceType<typeof BetterSqlite3>\nexport type BetterSqlite3OpenOptions = ConstructorParameters<\n  typeof BetterSqlite3\n>[1]\n\ntype BetterSqlite3ExistingDatabaseOptions = {\n  database: BetterSqlite3Database\n  pragmas?: ReadonlyArray<string>\n}\n\ntype BetterSqlite3OpenFileOptions = {\n  filename: string\n  options?: BetterSqlite3OpenOptions\n  pragmas?: ReadonlyArray<string>\n}\n\nexport type BetterSqlite3DriverOptions =\n  | BetterSqlite3ExistingDatabaseOptions\n  | BetterSqlite3OpenFileOptions\n\ntype TransactionContext = {\n  depth: number\n}\n\nfunction assertTransactionCallbackHasDriverArg(\n  fn: (transactionDriver: SQLiteDriver) => Promise<unknown>,\n): void {\n  if (fn.length > 0) {\n    return\n  }\n\n  throw new InvalidPersistedCollectionConfigError(\n    `SQLiteDriver.transaction callback must accept the transaction driver argument`,\n  )\n}\n\nfunction hasExistingDatabase(\n  options: BetterSqlite3DriverOptions,\n): options is BetterSqlite3ExistingDatabaseOptions {\n  return `database` in options\n}\n\nexport class BetterSqlite3SQLiteDriver implements SQLiteDriver {\n  private readonly database: BetterSqlite3Database\n  private readonly ownsDatabase: boolean\n  private readonly transactionContext =\n    new AsyncLocalStorage<TransactionContext>()\n  private queue: Promise<void> = Promise.resolve()\n  private nextSavepointId = 1\n\n  constructor(options: BetterSqlite3DriverOptions) {\n    if (hasExistingDatabase(options)) {\n      this.database = options.database\n      this.ownsDatabase = false\n      this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS)\n      return\n    }\n\n    if (options.filename.trim().length === 0) {\n      throw new InvalidPersistedCollectionConfigError(\n        `Node SQLite driver filename cannot be empty`,\n      )\n    }\n\n    this.database = new BetterSqlite3(options.filename, options.options)\n    this.ownsDatabase = true\n    this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS)\n  }\n\n  async exec(sql: string): Promise<void> {\n    if (this.isInsideTransaction()) {\n      this.database.exec(sql)\n      return\n    }\n\n    await this.enqueue(() => {\n      this.database.exec(sql)\n    })\n  }\n\n  async query<T>(\n    sql: string,\n    params: ReadonlyArray<unknown> = [],\n  ): Promise<ReadonlyArray<T>> {\n    if (this.isInsideTransaction()) {\n      return this.executeQuery<T>(sql, params)\n    }\n\n    return this.enqueue(() => this.executeQuery<T>(sql, params))\n  }\n\n  async run(sql: string, params: ReadonlyArray<unknown> = []): Promise<void> {\n    if (this.isInsideTransaction()) {\n      this.executeRun(sql, params)\n      return\n    }\n\n    await this.enqueue(() => {\n      this.executeRun(sql, params)\n    })\n  }\n\n  async transaction<T>(\n    fn: (transactionDriver: SQLiteDriver) => Promise<T>,\n  ): Promise<T> {\n    assertTransactionCallbackHasDriverArg(fn)\n\n    if (this.isInsideTransaction()) {\n      return this.runNestedTransaction(fn)\n    }\n\n    return this.enqueue(async () => {\n      this.database.exec(`BEGIN IMMEDIATE`)\n      try {\n        const result = await this.transactionContext.run(\n          { depth: 1 },\n          async () => fn(this),\n        )\n        this.database.exec(`COMMIT`)\n        return result\n      } catch (error) {\n        try {\n          this.database.exec(`ROLLBACK`)\n        } catch {\n          // Keep the original transaction error as the primary failure.\n        }\n        throw error\n      }\n    })\n  }\n\n  async transactionWithDriver<T>(\n    fn: (transactionDriver: SQLiteDriver) => Promise<T>,\n  ): Promise<T> {\n    return this.transaction(fn)\n  }\n\n  close(): void {\n    if (!this.ownsDatabase) {\n      return\n    }\n\n    this.database.close()\n  }\n\n  getDatabase(): BetterSqlite3Database {\n    return this.database\n  }\n\n  private applyPragmas(pragmas: ReadonlyArray<string>): void {\n    for (const pragma of pragmas) {\n      const trimmedPragma = pragma.trim()\n      if (trimmedPragma.length === 0) {\n        continue\n      }\n\n      if (INVALID_PRAGMA_PATTERN.test(trimmedPragma)) {\n        throw new InvalidPersistedCollectionConfigError(\n          `Invalid SQLite PRAGMA: \"${pragma}\"`,\n        )\n      }\n\n      this.database.exec(`PRAGMA ${trimmedPragma}`)\n    }\n  }\n\n  private isInsideTransaction(): boolean {\n    return this.transactionContext.getStore() !== undefined\n  }\n\n  private executeQuery<T>(\n    sql: string,\n    params: ReadonlyArray<unknown>,\n  ): ReadonlyArray<T> {\n    const statement = this.database.prepare(sql)\n    if (params.length === 0) {\n      return statement.all() as ReadonlyArray<T>\n    }\n\n    return statement.all(...params) as ReadonlyArray<T>\n  }\n\n  private executeRun(sql: string, params: ReadonlyArray<unknown>): void {\n    const statement = this.database.prepare(sql)\n    if (params.length === 0) {\n      statement.run()\n      return\n    }\n\n    statement.run(...params)\n  }\n\n  private enqueue<T>(operation: () => Promise<T> | T): Promise<T> {\n    const queuedOperation = this.queue.then(operation, operation)\n    this.queue = queuedOperation.then(\n      () => undefined,\n      () => undefined,\n    )\n    return queuedOperation\n  }\n\n  private async runNestedTransaction<T>(\n    fn: (transactionDriver: SQLiteDriver) => Promise<T>,\n  ): Promise<T> {\n    const context = this.transactionContext.getStore()\n    if (!context) {\n      return fn(this)\n    }\n\n    const savepointName = `tsdb_sp_${this.nextSavepointId}`\n    this.nextSavepointId++\n    this.database.exec(`SAVEPOINT ${savepointName}`)\n\n    try {\n      const result = await this.transactionContext.run(\n        { depth: context.depth + 1 },\n        async () => fn(this),\n      )\n      this.database.exec(`RELEASE SAVEPOINT ${savepointName}`)\n      return result\n    } catch (error) {\n      this.database.exec(`ROLLBACK TO SAVEPOINT ${savepointName}`)\n      this.database.exec(`RELEASE SAVEPOINT ${savepointName}`)\n      throw error\n    }\n  }\n}\n\nexport function createBetterSqlite3Driver(\n  options: BetterSqlite3DriverOptions,\n): BetterSqlite3SQLiteDriver {\n  return new BetterSqlite3SQLiteDriver(options)\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/node-persistence.d.ts

@@ -0,0 +1,18 @@
+import { PersistedCollectionCoordinator, PersistedCollectionPersistence, SQLiteCoreAdapterOptions } from '@tanstack/db-sqlite-persistence-core';
+import { BetterSqlite3Database } from './node-driver.js';
+export type { BetterSqlite3Database } from './node-driver.js';
+type NodeSQLiteCoreSchemaMismatchPolicy = `sync-present-reset` | `sync-absent-error` | `reset`;
+export type NodeSQLiteSchemaMismatchPolicy = NodeSQLiteCoreSchemaMismatchPolicy | `throw`;
+type NodeSQLitePersistenceBaseOptions = Omit<SQLiteCoreAdapterOptions, `driver` | `schemaVersion` | `schemaMismatchPolicy`> & {
+    database: BetterSqlite3Database;
+    pragmas?: ReadonlyArray<string>;
+    coordinator?: PersistedCollectionCoordinator;
+    schemaMismatchPolicy?: NodeSQLiteSchemaMismatchPolicy;
+};
+export type NodeSQLitePersistenceOptions = NodeSQLitePersistenceBaseOptions;
+/**
+ * Creates a shared SQLite persistence instance that can be reused by many
+ * collections on the same database. Collection-specific schema versions are
+ * resolved by `persistedCollectionOptions` via `resolvePersistenceForCollection`.
+ */
+export declare function createNodeSQLitePersistence<T extends object, TKey extends string | number = string | number>(options: NodeSQLitePersistenceOptions): PersistedCollectionPersistence<T, TKey>;

package/dist/esm/node-persistence.js

@@ -0,0 +1,81 @@
+import { SingleProcessCoordinator, createSQLiteCorePersistenceAdapter } from "@tanstack/db-sqlite-persistence-core";
+import { BetterSqlite3SQLiteDriver } from "./node-driver.js";
+function normalizeSchemaMismatchPolicy(policy) {
+  if (policy === `throw`) {
+    return `sync-absent-error`;
+  }
+  return policy;
+}
+function resolveSchemaMismatchPolicy(explicitPolicy, mode) {
+  if (explicitPolicy) {
+    return normalizeSchemaMismatchPolicy(explicitPolicy);
+  }
+  return mode === `sync-present` ? `sync-present-reset` : `sync-absent-error`;
+}
+function createAdapterCacheKey(schemaMismatchPolicy, schemaVersion) {
+  const schemaVersionKey = schemaVersion === void 0 ? `schema:default` : `schema:${schemaVersion}`;
+  return `${schemaMismatchPolicy}|${schemaVersionKey}`;
+}
+function createInternalSQLiteDriver(options) {
+  return new BetterSqlite3SQLiteDriver({
+    database: options.database,
+    ...options.pragmas ? { pragmas: options.pragmas } : {}
+  });
+}
+function resolveAdapterBaseOptions(options) {
+  return {
+    appliedTxPruneMaxRows: options.appliedTxPruneMaxRows,
+    appliedTxPruneMaxAgeSeconds: options.appliedTxPruneMaxAgeSeconds,
+    pullSinceReloadThreshold: options.pullSinceReloadThreshold
+  };
+}
+function createNodeSQLitePersistence(options) {
+  const { coordinator, schemaMismatchPolicy } = options;
+  const driver = createInternalSQLiteDriver(options);
+  const adapterBaseOptions = resolveAdapterBaseOptions(options);
+  const resolvedCoordinator = coordinator ?? new SingleProcessCoordinator();
+  const adapterCache = /* @__PURE__ */ new Map();
+  const getAdapterForCollection = (mode, schemaVersion) => {
+    const resolvedSchemaMismatchPolicy = resolveSchemaMismatchPolicy(
+      schemaMismatchPolicy,
+      mode
+    );
+    const cacheKey = createAdapterCacheKey(
+      resolvedSchemaMismatchPolicy,
+      schemaVersion
+    );
+    const cachedAdapter = adapterCache.get(cacheKey);
+    if (cachedAdapter) {
+      return cachedAdapter;
+    }
+    const adapter = createSQLiteCorePersistenceAdapter({
+      ...adapterBaseOptions,
+      driver,
+      schemaMismatchPolicy: resolvedSchemaMismatchPolicy,
+      ...schemaVersion === void 0 ? {} : { schemaVersion }
+    });
+    adapterCache.set(cacheKey, adapter);
+    return adapter;
+  };
+  const createCollectionPersistence = (mode, schemaVersion) => ({
+    adapter: getAdapterForCollection(
+      mode,
+      schemaVersion
+    ),
+    coordinator: resolvedCoordinator
+  });
+  const defaultPersistence = createCollectionPersistence(
+    `sync-absent`,
+    void 0
+  );
+  return {
+    ...defaultPersistence,
+    resolvePersistenceForCollection: ({ mode, schemaVersion }) => createCollectionPersistence(mode, schemaVersion),
+    // Backward compatible fallback for older callers.
+    resolvePersistenceForMode: (mode) => createCollectionPersistence(mode, void 0)
+  };
+}
+export {
+  createNodeSQLitePersistence
+};
+//# sourceMappingURL=node-persistence.js.map

package/dist/esm/node-persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-persistence.js","sources":["../../src/node-persistence.ts"],"sourcesContent":["import {\n  SingleProcessCoordinator,\n  createSQLiteCorePersistenceAdapter,\n} from '@tanstack/db-sqlite-persistence-core'\nimport { BetterSqlite3SQLiteDriver } from './node-driver'\nimport type {\n  PersistedCollectionCoordinator,\n  PersistedCollectionMode,\n  PersistedCollectionPersistence,\n  SQLiteCoreAdapterOptions,\n  SQLiteDriver,\n} from '@tanstack/db-sqlite-persistence-core'\nimport type { BetterSqlite3Database } from './node-driver'\n\nexport type { BetterSqlite3Database } from './node-driver'\n\ntype NodeSQLiteCoreSchemaMismatchPolicy =\n  | `sync-present-reset`\n  | `sync-absent-error`\n  | `reset`\n\nexport type NodeSQLiteSchemaMismatchPolicy =\n  | NodeSQLiteCoreSchemaMismatchPolicy\n  | `throw`\n\ntype NodeSQLitePersistenceBaseOptions = Omit<\n  SQLiteCoreAdapterOptions,\n  `driver` | `schemaVersion` | `schemaMismatchPolicy`\n> & {\n  database: BetterSqlite3Database\n  pragmas?: ReadonlyArray<string>\n  coordinator?: PersistedCollectionCoordinator\n  schemaMismatchPolicy?: NodeSQLiteSchemaMismatchPolicy\n}\n\nexport type NodeSQLitePersistenceOptions = NodeSQLitePersistenceBaseOptions\n\nfunction normalizeSchemaMismatchPolicy(\n  policy: NodeSQLiteSchemaMismatchPolicy,\n): NodeSQLiteCoreSchemaMismatchPolicy {\n  if (policy === `throw`) {\n    return `sync-absent-error`\n  }\n\n  return policy\n}\n\nfunction resolveSchemaMismatchPolicy(\n  explicitPolicy: NodeSQLiteSchemaMismatchPolicy | undefined,\n  mode: PersistedCollectionMode,\n): NodeSQLiteCoreSchemaMismatchPolicy {\n  if (explicitPolicy) {\n    return normalizeSchemaMismatchPolicy(explicitPolicy)\n  }\n\n  return mode === `sync-present` ? `sync-present-reset` : `sync-absent-error`\n}\n\nfunction createAdapterCacheKey(\n  schemaMismatchPolicy: NodeSQLiteCoreSchemaMismatchPolicy,\n  schemaVersion: number | undefined,\n): string {\n  const schemaVersionKey =\n    schemaVersion === undefined ? `schema:default` : `schema:${schemaVersion}`\n  return `${schemaMismatchPolicy}|${schemaVersionKey}`\n}\n\nfunction createInternalSQLiteDriver(\n  options: NodeSQLitePersistenceOptions,\n): SQLiteDriver {\n  return new BetterSqlite3SQLiteDriver({\n    database: options.database,\n    ...(options.pragmas ? { pragmas: options.pragmas } : {}),\n  })\n}\n\nfunction resolveAdapterBaseOptions(\n  options: NodeSQLitePersistenceOptions,\n): Omit<\n  SQLiteCoreAdapterOptions,\n  `driver` | `schemaVersion` | `schemaMismatchPolicy`\n> {\n  return {\n    appliedTxPruneMaxRows: options.appliedTxPruneMaxRows,\n    appliedTxPruneMaxAgeSeconds: options.appliedTxPruneMaxAgeSeconds,\n    pullSinceReloadThreshold: options.pullSinceReloadThreshold,\n  }\n}\n\n/**\n * Creates a shared SQLite persistence instance that can be reused by many\n * collections on the same database. Collection-specific schema versions are\n * resolved by `persistedCollectionOptions` via `resolvePersistenceForCollection`.\n */\nexport function createNodeSQLitePersistence<\n  T extends object,\n  TKey extends string | number = string | number,\n>(\n  options: NodeSQLitePersistenceOptions,\n): PersistedCollectionPersistence<T, TKey> {\n  const { coordinator, schemaMismatchPolicy } = options\n  const driver = createInternalSQLiteDriver(options)\n  const adapterBaseOptions = resolveAdapterBaseOptions(options)\n  const resolvedCoordinator = coordinator ?? new SingleProcessCoordinator()\n  const adapterCache = new Map<\n    string,\n    ReturnType<\n      typeof createSQLiteCorePersistenceAdapter<\n        Record<string, unknown>,\n        string | number\n      >\n    >\n  >()\n\n  const getAdapterForCollection = (\n    mode: PersistedCollectionMode,\n    schemaVersion: number | undefined,\n  ) => {\n    const resolvedSchemaMismatchPolicy = resolveSchemaMismatchPolicy(\n      schemaMismatchPolicy,\n      mode,\n    )\n    const cacheKey = createAdapterCacheKey(\n      resolvedSchemaMismatchPolicy,\n      schemaVersion,\n    )\n    const cachedAdapter = adapterCache.get(cacheKey)\n    if (cachedAdapter) {\n      return cachedAdapter\n    }\n\n    const adapter = createSQLiteCorePersistenceAdapter<\n      Record<string, unknown>,\n      string | number\n    >({\n      ...adapterBaseOptions,\n      driver,\n      schemaMismatchPolicy: resolvedSchemaMismatchPolicy,\n      ...(schemaVersion === undefined ? {} : { schemaVersion }),\n    })\n    adapterCache.set(cacheKey, adapter)\n    return adapter\n  }\n\n  const createCollectionPersistence = (\n    mode: PersistedCollectionMode,\n    schemaVersion: number | undefined,\n  ): PersistedCollectionPersistence<T, TKey> => ({\n    adapter: getAdapterForCollection(\n      mode,\n      schemaVersion,\n    ) as unknown as PersistedCollectionPersistence<T, TKey>[`adapter`],\n    coordinator: resolvedCoordinator,\n  })\n\n  const defaultPersistence = createCollectionPersistence(\n    `sync-absent`,\n    undefined,\n  )\n\n  return {\n    ...defaultPersistence,\n    resolvePersistenceForCollection: ({ mode, schemaVersion }) =>\n      createCollectionPersistence(mode, schemaVersion),\n    // Backward compatible fallback for older callers.\n    resolvePersistenceForMode: (mode) =>\n      createCollectionPersistence(mode, undefined),\n  }\n}\n"],"names":[],"mappings":";;AAqCA,SAAS,8BACP,QACoC;AACpC,MAAI,WAAW,SAAS;AACtB,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAEA,SAAS,4BACP,gBACA,MACoC;AACpC,MAAI,gBAAgB;AAClB,WAAO,8BAA8B,cAAc;AAAA,EACrD;AAEA,SAAO,SAAS,iBAAiB,uBAAuB;AAC1D;AAEA,SAAS,sBACP,sBACA,eACQ;AACR,QAAM,mBACJ,kBAAkB,SAAY,mBAAmB,UAAU,aAAa;AAC1E,SAAO,GAAG,oBAAoB,IAAI,gBAAgB;AACpD;AAEA,SAAS,2BACP,SACc;AACd,SAAO,IAAI,0BAA0B;AAAA,IACnC,UAAU,QAAQ;AAAA,IAClB,GAAI,QAAQ,UAAU,EAAE,SAAS,QAAQ,QAAA,IAAY,CAAA;AAAA,EAAC,CACvD;AACH;AAEA,SAAS,0BACP,SAIA;AACA,SAAO;AAAA,IACL,uBAAuB,QAAQ;AAAA,IAC/B,6BAA6B,QAAQ;AAAA,IACrC,0BAA0B,QAAQ;AAAA,EAAA;AAEtC;AAOO,SAAS,4BAId,SACyC;AACzC,QAAM,EAAE,aAAa,qBAAA,IAAyB;AAC9C,QAAM,SAAS,2BAA2B,OAAO;AACjD,QAAM,qBAAqB,0BAA0B,OAAO;AAC5D,QAAM,sBAAsB,eAAe,IAAI,yBAAA;AAC/C,QAAM,mCAAmB,IAAA;AAUzB,QAAM,0BAA0B,CAC9B,MACA,kBACG;AACH,UAAM,+BAA+B;AAAA,MACnC;AAAA,MACA;AAAA,IAAA;AAEF,UAAM,WAAW;AAAA,MACf;AAAA,MACA;AAAA,IAAA;AAEF,UAAM,gBAAgB,aAAa,IAAI,QAAQ;AAC/C,QAAI,eAAe;AACjB,aAAO;AAAA,IACT;AAEA,UAAM,UAAU,mCAGd;AAAA,MACA,GAAG;AAAA,MACH;AAAA,MACA,sBAAsB;AAAA,MACtB,GAAI,kBAAkB,SAAY,CAAA,IAAK,EAAE,cAAA;AAAA,IAAc,CACxD;AACD,iBAAa,IAAI,UAAU,OAAO;AAClC,WAAO;AAAA,EACT;AAEA,QAAM,8BAA8B,CAClC,MACA,mBAC6C;AAAA,IAC7C,SAAS;AAAA,MACP;AAAA,MACA;AAAA,IAAA;AAAA,IAEF,aAAa;AAAA,EAAA;AAGf,QAAM,qBAAqB;AAAA,IACzB;AAAA,IACA;AAAA,EAAA;AAGF,SAAO;AAAA,IACL,GAAG;AAAA,IACH,iCAAiC,CAAC,EAAE,MAAM,oBACxC,4BAA4B,MAAM,aAAa;AAAA;AAAA,IAEjD,2BAA2B,CAAC,SAC1B,4BAA4B,MAAM,MAAS;AAAA,EAAA;AAEjD;"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@tanstack/node-db-sqlite-persistence",
+  "version": "0.1.2",
+  "description": "Node SQLite persisted collection adapter for TanStack DB",
+  "author": "TanStack Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/db.git",
+    "directory": "packages/node-db-sqlite-persistence"
+  },
+  "homepage": "https://tanstack.com/db",
+  "keywords": [
+    "sqlite",
+    "node",
+    "persistence",
+    "optimistic",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "lint": "eslint . --fix",
+    "test": "vitest --run",
+    "test:e2e": "pnpm --filter @tanstack/db-ivm build && pnpm --filter @tanstack/db build && pnpm --filter @tanstack/db-sqlite-persistence-core build && pnpm --filter @tanstack/node-db-sqlite-persistence build && vitest --config vitest.e2e.config.ts --run"
+  },
+  "type": "module",
+  "main": "dist/cjs/index.cjs",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@tanstack/db-sqlite-persistence-core": "workspace:*",
+    "better-sqlite3": "^12.6.2"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.7"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@vitest/coverage-istanbul": "^3.2.4"
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { createNodeSQLitePersistence } from './node-persistence'
+export type {
+  BetterSqlite3Database,
+  NodeSQLitePersistenceOptions,
+  NodeSQLiteSchemaMismatchPolicy,
+} from './node-persistence'
+export { persistedCollectionOptions } from '@tanstack/db-sqlite-persistence-core'
+export type {
+  PersistedCollectionCoordinator,
+  PersistedCollectionPersistence,
+} from '@tanstack/db-sqlite-persistence-core'

package/src/node-driver.ts

@@ -0,0 +1,246 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+import BetterSqlite3 from 'better-sqlite3'
+import { InvalidPersistedCollectionConfigError } from '@tanstack/db-sqlite-persistence-core'
+import type { SQLiteDriver } from '@tanstack/db-sqlite-persistence-core'
+
+const DEFAULT_PRAGMAS = [
+  `journal_mode = WAL`,
+  `synchronous = NORMAL`,
+  `foreign_keys = ON`,
+] as const
+
+const INVALID_PRAGMA_PATTERN = /(;|--|\/\*)/
+
+export type BetterSqlite3Database = InstanceType<typeof BetterSqlite3>
+export type BetterSqlite3OpenOptions = ConstructorParameters<
+  typeof BetterSqlite3
+>[1]
+
+type BetterSqlite3ExistingDatabaseOptions = {
+  database: BetterSqlite3Database
+  pragmas?: ReadonlyArray<string>
+}
+
+type BetterSqlite3OpenFileOptions = {
+  filename: string
+  options?: BetterSqlite3OpenOptions
+  pragmas?: ReadonlyArray<string>
+}
+
+export type BetterSqlite3DriverOptions =
+  | BetterSqlite3ExistingDatabaseOptions
+  | BetterSqlite3OpenFileOptions
+
+type TransactionContext = {
+  depth: number
+}
+
+function assertTransactionCallbackHasDriverArg(
+  fn: (transactionDriver: SQLiteDriver) => Promise<unknown>,
+): void {
+  if (fn.length > 0) {
+    return
+  }
+
+  throw new InvalidPersistedCollectionConfigError(
+    `SQLiteDriver.transaction callback must accept the transaction driver argument`,
+  )
+}
+
+function hasExistingDatabase(
+  options: BetterSqlite3DriverOptions,
+): options is BetterSqlite3ExistingDatabaseOptions {
+  return `database` in options
+}
+
+export class BetterSqlite3SQLiteDriver implements SQLiteDriver {
+  private readonly database: BetterSqlite3Database
+  private readonly ownsDatabase: boolean
+  private readonly transactionContext =
+    new AsyncLocalStorage<TransactionContext>()
+  private queue: Promise<void> = Promise.resolve()
+  private nextSavepointId = 1
+
+  constructor(options: BetterSqlite3DriverOptions) {
+    if (hasExistingDatabase(options)) {
+      this.database = options.database
+      this.ownsDatabase = false
+      this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS)
+      return
+    }
+
+    if (options.filename.trim().length === 0) {
+      throw new InvalidPersistedCollectionConfigError(
+        `Node SQLite driver filename cannot be empty`,
+      )
+    }
+
+    this.database = new BetterSqlite3(options.filename, options.options)
+    this.ownsDatabase = true
+    this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS)
+  }
+
+  async exec(sql: string): Promise<void> {
+    if (this.isInsideTransaction()) {
+      this.database.exec(sql)
+      return
+    }
+
+    await this.enqueue(() => {
+      this.database.exec(sql)
+    })
+  }
+
+  async query<T>(
+    sql: string,
+    params: ReadonlyArray<unknown> = [],
+  ): Promise<ReadonlyArray<T>> {
+    if (this.isInsideTransaction()) {
+      return this.executeQuery<T>(sql, params)
+    }
+
+    return this.enqueue(() => this.executeQuery<T>(sql, params))
+  }
+
+  async run(sql: string, params: ReadonlyArray<unknown> = []): Promise<void> {
+    if (this.isInsideTransaction()) {
+      this.executeRun(sql, params)
+      return
+    }
+
+    await this.enqueue(() => {
+      this.executeRun(sql, params)
+    })
+  }
+
+  async transaction<T>(
+    fn: (transactionDriver: SQLiteDriver) => Promise<T>,
+  ): Promise<T> {
+    assertTransactionCallbackHasDriverArg(fn)
+
+    if (this.isInsideTransaction()) {
+      return this.runNestedTransaction(fn)
+    }
+
+    return this.enqueue(async () => {
+      this.database.exec(`BEGIN IMMEDIATE`)
+      try {
+        const result = await this.transactionContext.run(
+          { depth: 1 },
+          async () => fn(this),
+        )
+        this.database.exec(`COMMIT`)
+        return result
+      } catch (error) {
+        try {
+          this.database.exec(`ROLLBACK`)
+        } catch {
+          // Keep the original transaction error as the primary failure.
+        }
+        throw error
+      }
+    })
+  }
+
+  async transactionWithDriver<T>(
+    fn: (transactionDriver: SQLiteDriver) => Promise<T>,
+  ): Promise<T> {
+    return this.transaction(fn)
+  }
+
+  close(): void {
+    if (!this.ownsDatabase) {
+      return
+    }
+
+    this.database.close()
+  }
+
+  getDatabase(): BetterSqlite3Database {
+    return this.database
+  }
+
+  private applyPragmas(pragmas: ReadonlyArray<string>): void {
+    for (const pragma of pragmas) {
+      const trimmedPragma = pragma.trim()
+      if (trimmedPragma.length === 0) {
+        continue
+      }
+
+      if (INVALID_PRAGMA_PATTERN.test(trimmedPragma)) {
+        throw new InvalidPersistedCollectionConfigError(
+          `Invalid SQLite PRAGMA: "${pragma}"`,
+        )
+      }
+
+      this.database.exec(`PRAGMA ${trimmedPragma}`)
+    }
+  }
+
+  private isInsideTransaction(): boolean {
+    return this.transactionContext.getStore() !== undefined
+  }
+
+  private executeQuery<T>(
+    sql: string,
+    params: ReadonlyArray<unknown>,
+  ): ReadonlyArray<T> {
+    const statement = this.database.prepare(sql)
+    if (params.length === 0) {
+      return statement.all() as ReadonlyArray<T>
+    }
+
+    return statement.all(...params) as ReadonlyArray<T>
+  }
+
+  private executeRun(sql: string, params: ReadonlyArray<unknown>): void {
+    const statement = this.database.prepare(sql)
+    if (params.length === 0) {
+      statement.run()
+      return
+    }
+
+    statement.run(...params)
+  }
+
+  private enqueue<T>(operation: () => Promise<T> | T): Promise<T> {
+    const queuedOperation = this.queue.then(operation, operation)
+    this.queue = queuedOperation.then(
+      () => undefined,
+      () => undefined,
+    )
+    return queuedOperation
+  }
+
+  private async runNestedTransaction<T>(
+    fn: (transactionDriver: SQLiteDriver) => Promise<T>,
+  ): Promise<T> {
+    const context = this.transactionContext.getStore()
+    if (!context) {
+      return fn(this)
+    }
+
+    const savepointName = `tsdb_sp_${this.nextSavepointId}`
+    this.nextSavepointId++
+    this.database.exec(`SAVEPOINT ${savepointName}`)
+
+    try {
+      const result = await this.transactionContext.run(
+        { depth: context.depth + 1 },
+        async () => fn(this),
+      )
+      this.database.exec(`RELEASE SAVEPOINT ${savepointName}`)
+      return result
+    } catch (error) {
+      this.database.exec(`ROLLBACK TO SAVEPOINT ${savepointName}`)
+      this.database.exec(`RELEASE SAVEPOINT ${savepointName}`)
+      throw error
+    }
+  }
+}
+
+export function createBetterSqlite3Driver(
+  options: BetterSqlite3DriverOptions,
+): BetterSqlite3SQLiteDriver {
+  return new BetterSqlite3SQLiteDriver(options)
+}

package/src/node-persistence.ts

@@ -0,0 +1,169 @@
+import {
+  SingleProcessCoordinator,
+  createSQLiteCorePersistenceAdapter,
+} from '@tanstack/db-sqlite-persistence-core'
+import { BetterSqlite3SQLiteDriver } from './node-driver'
+import type {
+  PersistedCollectionCoordinator,
+  PersistedCollectionMode,
+  PersistedCollectionPersistence,
+  SQLiteCoreAdapterOptions,
+  SQLiteDriver,
+} from '@tanstack/db-sqlite-persistence-core'
+import type { BetterSqlite3Database } from './node-driver'
+
+export type { BetterSqlite3Database } from './node-driver'
+
+type NodeSQLiteCoreSchemaMismatchPolicy =
+  | `sync-present-reset`
+  | `sync-absent-error`
+  | `reset`
+
+export type NodeSQLiteSchemaMismatchPolicy =
+  | NodeSQLiteCoreSchemaMismatchPolicy
+  | `throw`
+
+type NodeSQLitePersistenceBaseOptions = Omit<
+  SQLiteCoreAdapterOptions,
+  `driver` | `schemaVersion` | `schemaMismatchPolicy`
+> & {
+  database: BetterSqlite3Database
+  pragmas?: ReadonlyArray<string>
+  coordinator?: PersistedCollectionCoordinator
+  schemaMismatchPolicy?: NodeSQLiteSchemaMismatchPolicy
+}
+
+export type NodeSQLitePersistenceOptions = NodeSQLitePersistenceBaseOptions
+
+function normalizeSchemaMismatchPolicy(
+  policy: NodeSQLiteSchemaMismatchPolicy,
+): NodeSQLiteCoreSchemaMismatchPolicy {
+  if (policy === `throw`) {
+    return `sync-absent-error`
+  }
+
+  return policy
+}
+
+function resolveSchemaMismatchPolicy(
+  explicitPolicy: NodeSQLiteSchemaMismatchPolicy | undefined,
+  mode: PersistedCollectionMode,
+): NodeSQLiteCoreSchemaMismatchPolicy {
+  if (explicitPolicy) {
+    return normalizeSchemaMismatchPolicy(explicitPolicy)
+  }
+
+  return mode === `sync-present` ? `sync-present-reset` : `sync-absent-error`
+}
+
+function createAdapterCacheKey(
+  schemaMismatchPolicy: NodeSQLiteCoreSchemaMismatchPolicy,
+  schemaVersion: number | undefined,
+): string {
+  const schemaVersionKey =
+    schemaVersion === undefined ? `schema:default` : `schema:${schemaVersion}`
+  return `${schemaMismatchPolicy}|${schemaVersionKey}`
+}
+
+function createInternalSQLiteDriver(
+  options: NodeSQLitePersistenceOptions,
+): SQLiteDriver {
+  return new BetterSqlite3SQLiteDriver({
+    database: options.database,
+    ...(options.pragmas ? { pragmas: options.pragmas } : {}),
+  })
+}
+
+function resolveAdapterBaseOptions(
+  options: NodeSQLitePersistenceOptions,
+): Omit<
+  SQLiteCoreAdapterOptions,
+  `driver` | `schemaVersion` | `schemaMismatchPolicy`
+> {
+  return {
+    appliedTxPruneMaxRows: options.appliedTxPruneMaxRows,
+    appliedTxPruneMaxAgeSeconds: options.appliedTxPruneMaxAgeSeconds,
+    pullSinceReloadThreshold: options.pullSinceReloadThreshold,
+  }
+}
+
+/**
+ * Creates a shared SQLite persistence instance that can be reused by many
+ * collections on the same database. Collection-specific schema versions are
+ * resolved by `persistedCollectionOptions` via `resolvePersistenceForCollection`.
+ */
+export function createNodeSQLitePersistence<
+  T extends object,
+  TKey extends string | number = string | number,
+>(
+  options: NodeSQLitePersistenceOptions,
+): PersistedCollectionPersistence<T, TKey> {
+  const { coordinator, schemaMismatchPolicy } = options
+  const driver = createInternalSQLiteDriver(options)
+  const adapterBaseOptions = resolveAdapterBaseOptions(options)
+  const resolvedCoordinator = coordinator ?? new SingleProcessCoordinator()
+  const adapterCache = new Map<
+    string,
+    ReturnType<
+      typeof createSQLiteCorePersistenceAdapter<
+        Record<string, unknown>,
+        string | number
+      >
+    >
+  >()
+
+  const getAdapterForCollection = (
+    mode: PersistedCollectionMode,
+    schemaVersion: number | undefined,
+  ) => {
+    const resolvedSchemaMismatchPolicy = resolveSchemaMismatchPolicy(
+      schemaMismatchPolicy,
+      mode,
+    )
+    const cacheKey = createAdapterCacheKey(
+      resolvedSchemaMismatchPolicy,
+      schemaVersion,
+    )
+    const cachedAdapter = adapterCache.get(cacheKey)
+    if (cachedAdapter) {
+      return cachedAdapter
+    }
+
+    const adapter = createSQLiteCorePersistenceAdapter<
+      Record<string, unknown>,
+      string | number
+    >({
+      ...adapterBaseOptions,
+      driver,
+      schemaMismatchPolicy: resolvedSchemaMismatchPolicy,
+      ...(schemaVersion === undefined ? {} : { schemaVersion }),
+    })
+    adapterCache.set(cacheKey, adapter)
+    return adapter
+  }
+
+  const createCollectionPersistence = (
+    mode: PersistedCollectionMode,
+    schemaVersion: number | undefined,
+  ): PersistedCollectionPersistence<T, TKey> => ({
+    adapter: getAdapterForCollection(
+      mode,
+      schemaVersion,
+    ) as unknown as PersistedCollectionPersistence<T, TKey>[`adapter`],
+    coordinator: resolvedCoordinator,
+  })
+
+  const defaultPersistence = createCollectionPersistence(
+    `sync-absent`,
+    undefined,
+  )
+
+  return {
+    ...defaultPersistence,
+    resolvePersistenceForCollection: ({ mode, schemaVersion }) =>
+      createCollectionPersistence(mode, schemaVersion),
+    // Backward compatible fallback for older callers.
+    resolvePersistenceForMode: (mode) =>
+      createCollectionPersistence(mode, undefined),
+  }
+}