@syncular/client 0.15.46 → 0.15.47

package/README.md

@@ -4,8 +4,9 @@ The TypeScript client protocol core (SPEC.md §§3–8, client side) plus its
 browser platform bindings.
 
 The normal `SyncClient` also runs in a CLI or background service.
-Use `openBunDatabase(path)` or `openNodeDatabase(path)` for a persistent local
-replica. See the [server-side sync client guide](https://syncular.dev/guide-server-clients/).
+Use `openSqliteDatabase(path)` from `@syncular/client/sqlite` for a persistent
+local replica on Node or Bun. See the
+[server-side sync client guide](https://syncular.dev/guide-server-clients/).
 
 `SyncRemoteClient` is the database-less server client. It sends ordinary
 push-only commits through `/sync` and can call registered typed queries,
@@ -470,10 +471,10 @@ directory or IndexedDB store. This is the pinned decision (SPEC §5.9.7 B1):
   that pin them — a refcount adjust and a body insert/delete commit atomically,
   so a crash never strands a body against a stale count.
 - **Survives restarts for free.** The client DB already rides OPFS via the
-  sahpool VFS in the browser (and a plain file under `rusqlite`/better-sqlite3
-  on native/Node), so there is no second persistence surface and no second
-  eviction policy to keep coherent. Close the app, reopen it: `fetchBlob` serves
-  the cached body with no network.
+  sahpool VFS in the browser (and a plain file under `rusqlite`, `bun:sqlite`,
+  or `node:sqlite` on native runtimes), so there is no second persistence
+  surface and no second eviction policy to keep coherent. Close the app, reopen
+  it: `fetchBlob` serves the cached body with no network.
 - **SQLite handles multi-MB images fine.** A page-cached `BLOB` read is a memory
   copy, well within the image/document envelope this targets.
 
@@ -507,57 +508,38 @@ straight to a media element instead of pulling bytes through the cache — the
 image-app default (refcounted `BLOB` cache) and the large-media path (presigned
 URL, no byte cache) coexist per attachment.
 
-## Node / Electron-main backend (`./node`)
+## Node and Bun SQLite backend (`./sqlite`)
 
-Hosts that run outside a browser — an **Electron main process**, a plain
-**Node** service, a CLI — get a native SQLite backend through
-`openNodeDatabase`, a `ClientDatabase` over
-[better-sqlite3](https://github.com/WiseLibs/better-sqlite3):
+CLIs, background workers, Electron main processes, and services can use one
+runtime-selected import:
 
 ```ts
-import { openNodeDatabase } from '@syncular/client/node';
+import { openSqliteDatabase } from '@syncular/client/sqlite';
 import { SyncClient } from '@syncular/client';
 
-const database = openNodeDatabase('app.db'); // or ':memory:' (default)
+const database = openSqliteDatabase('app.db'); // or ':memory:' (default)
 const client = new SyncClient({ database, schema, /* … */ });
 ```
 
-It mirrors the bun:sqlite adapter exactly: synchronous `exec` / `query` /
-`transaction` (nested calls are savepoints — an inner failure rolls back only
-the inner scope), the same boolean→0/1 bind coercion, `null` round-trips, and
-BLOB columns handed back as plain `Uint8Array`s. The §5.3 `withSqliteImage`
-attach path is supported too, so a Node host can accept sqlite-image segments.
+The export selects `bun:sqlite` on Bun and the built-in `node:sqlite` module on
+Node 22.13 or newer. No SQLite package or native addon is required. Both
+adapters support synchronous `exec`, `query`, nested transactions, boolean
+bindings, `null`, `Uint8Array` BLOB values, and §5.3 SQLite-image attachment.
 
-**better-sqlite3 is an OPTIONAL peer dependency, not a hard one.** The package
-installs cleanly without it (browser-only apps never pay for a native build);
-`openNodeDatabase()` loads it lazily on first call and throws a clear,
-actionable error if the peer is missing. Add it in your app:
+Runtime-specific imports remain available:
 
-```sh
-npm install better-sqlite3     # or: bun add better-sqlite3
+```ts
+import { openBunDatabase } from '@syncular/client/bun';
+import { openNodeDatabase } from '@syncular/client/node';
 ```
 
-**Verifying the Node adapter — and why not under bun.** bun **cannot** dlopen
-better-sqlite3 (`ERR_DLOPEN_FAILED`,
-[oven-sh/bun#4290](https://github.com/oven-sh/bun/issues/4290)); calling
-`openNodeDatabase()` under bun deliberately raises the same helpful error and
-points you at `./bun` instead. So the bun test suite
-(`test/node-database.test.ts`) proves what it can under bun — type/subpath
-conformance, the missing-peer error, and that the shared behavioral contract
-(`test/node-database/adapter-contract.ts`) passes on the reference bun:sqlite
-backend — while the better-sqlite3 adapter's real behavior is proven under
-**Node** against the actual native module by running that same contract:
+The source and packed-package runtime contracts run under actual Node and Bun:
 
 ```sh
-cd packages/web-client
-bun run verify:node
+bun run verify:runtimes
+bun run build:packages && bun run verify:packages
 ```
 
-That bundles the verifier with bun (transpile + resolve only — bun never
-executes the native module) and runs the plain-JS bundle under Node, which
-exercises `openNodeDatabase` against real better-sqlite3 and exits non-zero on
-any divergence from the contract.
-
 ## RPC protocol (6 message types)
 
 `init`, `call`, `ready`, `result`, `error`, `event` — every API method
@@ -573,8 +555,9 @@ they own their buffer.
 | `.` | protocol core, transports, handle + RPC protocol (browser-safe, no SQLite) |
 | `./worker` | `startSyncWorker` — worker-side bootstrap (pulls sqlite-wasm) |
 | `./wasm` | sqlite-wasm bindings: `openPersistentWasmDatabase`, `openWasmDatabase` |
-| `./bun` | bun:sqlite binding for tests |
-| `./node` | better-sqlite3 binding: `openNodeDatabase` (Electron-main / plain Node) |
+| `./sqlite` | Runtime-selected SQLite: `openSqliteDatabase` on Node or Bun |
+| `./bun` | Explicit `bun:sqlite` binding: `openBunDatabase` |
+| `./node` | Explicit built-in `node:sqlite` binding: `openNodeDatabase` |
 
 Tests drive the real worker entry in a bun `Worker` with bun:sqlite
 injected through the bootstrap's database-factory override

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  * SPEC.md is normative.
  *
  * Browser-safe root: database backends live behind subpath exports
- * (`./bun` for bun:sqlite tests, `./wasm` for sqlite-wasm + OPFS); the
+ * (`./sqlite` for Node or Bun, `./wasm` for sqlite-wasm + OPFS); the
  * worker-side bootstrap lives behind `./worker`. The main-thread handle
  * (`worker-host`) and the RPC protocol types are root exports — they
  * import no SQLite.

package/dist/index.js

@@ -3,7 +3,7 @@
  * SPEC.md is normative.
  *
  * Browser-safe root: database backends live behind subpath exports
- * (`./bun` for bun:sqlite tests, `./wasm` for sqlite-wasm + OPFS); the
+ * (`./sqlite` for Node or Bun, `./wasm` for sqlite-wasm + OPFS); the
  * worker-side bootstrap lives behind `./worker`. The main-thread handle
  * (`worker-host`) and the RPC protocol types are root exports — they
  * import no SQLite.

package/dist/node-database.d.ts

@@ -1,41 +1,18 @@
-import { type ClientDatabase, type SqlRow, type SqlValue } from './database.js';
 /**
- * Structural view of the tiny better-sqlite3 surface this binding uses. We
- * type it locally (rather than importing `better-sqlite3`'s types) so the
- * package typechecks without the optional peer installed.
+ * `ClientDatabase` on Node's built-in `node:sqlite`. Semantics mirror the Bun
+ * adapter: synchronous queries, nested transactions, and SQLite image attach.
  */
-interface BetterSqliteStatement {
-    run(...params: NodeParam[]): unknown;
-    all(...params: NodeParam[]): unknown[];
-}
-interface BetterSqliteDatabase {
-    readonly inTransaction: boolean;
-    prepare(sql: string): BetterSqliteStatement;
-    exec(sql: string): unknown;
-    close(): void;
-}
-/**
- * better-sqlite3 accepts string / number / bigint / null / Buffer|Uint8Array
- * bind values, but NOT booleans (it throws "TypeError: can only bind …"). We
- * coerce booleans to 0/1 exactly like the bun adapter so callers see one
- * uniform bind contract across every backend.
- */
-type NodeParam = string | number | bigint | Uint8Array | null;
+import { DatabaseSync } from 'node:sqlite';
+import { type ClientDatabase, type SqlRow, type SqlValue } from './database.js';
 export declare class NodeClientDatabase implements ClientDatabase {
     #private;
-    readonly db: BetterSqliteDatabase;
+    readonly db: DatabaseSync;
     constructor(path?: string);
     exec(sql: string, params?: readonly SqlValue[]): void;
     query(sql: string, params?: readonly SqlValue[]): SqlRow[];
     transaction<T>(fn: () => T): T;
-    /**
-     * §5.3 image import: better-sqlite3 (like bun:sqlite) attaches files, not
-     * buffers, so the image lands in a private temp file for the duration of
-     * the ATTACH. Must be called outside any open transaction (SQLite cannot
-     * ATTACH inside one).
-     */
+    /** §5.3 image import through a private file attached for one callback. */
     withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T): T;
     close(): void;
 }
 export declare function openNodeDatabase(path?: string): ClientDatabase;
-export {};

package/dist/node-database.js

@@ -1,23 +1,9 @@
 /**
- * `ClientDatabase` on better-sqlite3 — the Electron-main / plain-Node
- * backend. Semantics mirror `./bun-database`
- * exactly (synchronous exec/query/transaction with the shared savepoint
- * helper, and the same §5.3 sqlite-image ATTACH path), so the core behaves
- * identically whether it runs on bun:sqlite (tests), sqlite-wasm (browser)
- * or better-sqlite3 (Node/Electron-main).
- *
- * better-sqlite3 is an OPTIONAL peer dependency, not a hard one: the package
- * installs cleanly without it and this module errors helpfully only when a
- * host actually calls `openNodeDatabase()` without having installed the peer.
- * Not exported from the package root, so browser/bun entries never resolve
- * the native module. Subpath export: `@syncular/client/node`.
- *
- * bun CANNOT dlopen better-sqlite3 (ERR_DLOPEN_FAILED, oven-sh/bun#4290), so
- * this adapter is verified under real Node — see the README "Electron-main /
- * plain-Node" section for the one-command recipe and `test/node-database`.
+ * `ClientDatabase` on Node's built-in `node:sqlite`. Semantics mirror the Bun
+ * adapter: synchronous queries, nested transactions, and SQLite image attach.
  */
+import { DatabaseSync } from 'node:sqlite';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { assertImageAlias, runTransaction, } from './database.js';
@@ -28,19 +14,12 @@ function coerceParams(params) {
         return value;
     });
 }
-/**
- * better-sqlite3 returns BLOB columns as Node `Buffer`s. A Buffer IS a
- * Uint8Array subclass, but it can be a view onto a shared pool buffer, so we
- * normalize to a standalone Uint8Array — matching what bun:sqlite hands back
- * and keeping the buffer-ownership assumptions elsewhere (worker transfer,
- * structured clone) honest.
- */
 function normalizeRow(row) {
     const out = {};
     for (const key in row) {
         const value = row[key];
-        if (Buffer.isBuffer(value)) {
-            out[key] = new Uint8Array(value); // copies out of the pool
+        if (value instanceof Uint8Array) {
+            out[key] = new Uint8Array(value);
         }
         else {
             out[key] = value;
@@ -48,47 +27,11 @@ function normalizeRow(row) {
     }
     return out;
 }
-/**
- * Load the optional peer AND open the database in one guarded step, so BOTH
- * failure modes are turned into a clear, actionable error rather than a raw
- * one:
- *
- *  - `require('better-sqlite3')` throwing MODULE_NOT_FOUND — the peer is not
- *    installed (the common browser-only-host case), and
- *  - `new Database()` throwing ERR_DLOPEN_FAILED — the module resolves but the
- *    native addon cannot load, which is exactly what bun does for
- *    better-sqlite3 (oven-sh/bun#4290); the addon only dlopens at construction.
- */
-function openBetterSqlite(path) {
-    const require = createRequire(import.meta.url);
-    try {
-        const mod = require('better-sqlite3');
-        const Database = mod.default ??
-            mod;
-        return new Database(path);
-    }
-    catch (error) {
-        const code = error?.code;
-        if (code === 'ERR_DLOPEN_FAILED') {
-            throw new Error("openNodeDatabase() requires the 'better-sqlite3' native module, but " +
-                'it failed to load. This most commonly means you are running under ' +
-                'bun, which cannot dlopen better-sqlite3 (oven-sh/bun#4290) — use ' +
-                "the bun:sqlite backend ('@syncular/client/bun') under bun, " +
-                "and reserve '@syncular/client/node' for Node/Electron-main. " +
-                `Underlying error: ${String(error)}`);
-        }
-        throw new Error('openNodeDatabase() requires the optional peer dependency ' +
-            "'better-sqlite3', which is not installed. Add it to your app " +
-            '(`npm install better-sqlite3` / `bun add better-sqlite3`) — it is ' +
-            'kept optional so @syncular/client installs without a native ' +
-            `build for browser-only hosts. Underlying error: ${String(error)}`);
-    }
-}
 export class NodeClientDatabase {
     db;
     #tx = { depth: 0 };
     constructor(path = ':memory:') {
-        this.db = openBetterSqlite(path);
+        this.db = new DatabaseSync(path);
     }
     exec(sql, params = []) {
         this.db.prepare(sql).run(...coerceParams(params));
@@ -100,12 +43,7 @@ export class NodeClientDatabase {
     transaction(fn) {
         return runTransaction(this.#tx, (sql) => this.db.exec(sql), fn);
     }
-    /**
-     * §5.3 image import: better-sqlite3 (like bun:sqlite) attaches files, not
-     * buffers, so the image lands in a private temp file for the duration of
-     * the ATTACH. Must be called outside any open transaction (SQLite cannot
-     * ATTACH inside one).
-     */
+    /** §5.3 image import through a private file attached for one callback. */
     withSqliteImage(bytes, alias, fn) {
         assertImageAlias(alias);
         const dir = mkdtempSync(join(tmpdir(), 'syncular-image-'));

package/dist/query-guard.d.ts

@@ -10,8 +10,8 @@
  *      bypasses the outbox (SPEC §7.1) and silently diverges from the
  *      server — writes MUST go through `client.mutate([...])`.
  *   2. ONE STATEMENT. `sqlite-wasm`'s `exec` runs every statement in a
- *      multi-statement string (`SELECT 1; DROP TABLE t`), while bun:sqlite /
- *      better-sqlite3 prepare only the first. We unify on the strict
+ *      multi-statement string (`SELECT 1; DROP TABLE t`), while the native
+ *      SQLite adapters prepare only the first. We unify on the strict
  *      behaviour: exactly one statement per `query()`.
  *
  * The guard only fronts the PUBLIC `client.query()` — engine-internal reads

package/dist/query-guard.js

@@ -10,8 +10,8 @@
  *      bypasses the outbox (SPEC §7.1) and silently diverges from the
  *      server — writes MUST go through `client.mutate([...])`.
  *   2. ONE STATEMENT. `sqlite-wasm`'s `exec` runs every statement in a
- *      multi-statement string (`SELECT 1; DROP TABLE t`), while bun:sqlite /
- *      better-sqlite3 prepare only the first. We unify on the strict
+ *      multi-statement string (`SELECT 1; DROP TABLE t`), while the native
+ *      SQLite adapters prepare only the first. We unify on the strict
  *      behaviour: exactly one statement per `query()`.
  *
  * The guard only fronts the PUBLIC `client.query()` — engine-internal reads

package/dist/sqlite-bun.d.ts

@@ -0,0 +1,2 @@
+import type { ClientDatabase } from './database.js';
+export declare function openSqliteDatabase(path?: string): ClientDatabase;

package/dist/sqlite-bun.js

@@ -0,0 +1,4 @@
+import { openBunDatabase } from './bun-database.js';
+export function openSqliteDatabase(path = ':memory:') {
+    return openBunDatabase(path);
+}

package/dist/sqlite-node.d.ts

@@ -0,0 +1,2 @@
+import type { ClientDatabase } from './database.js';
+export declare function openSqliteDatabase(path?: string): ClientDatabase;

package/dist/sqlite-node.js

@@ -0,0 +1,4 @@
+import { openNodeDatabase } from './node-database.js';
+export function openSqliteDatabase(path = ':memory:') {
+    return openNodeDatabase(path);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.15.46",
+  "version": "0.15.47",
   "description": "Syncular TypeScript client core — offline-first sync over SQLite (WASM/OPFS, Bun, Node)",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -58,6 +58,14 @@
         "default": "./dist/node-database.js"
       }
     },
+    "./sqlite": {
+      "bun": "./src/sqlite-bun.ts",
+      "node": {
+        "types": "./dist/sqlite-node.d.ts",
+        "default": "./dist/sqlite-node.js"
+      },
+      "types": "./dist/sqlite-node.d.ts"
+    },
     "./wasm": {
       "bun": "./src/wasm-database.ts",
       "browser": "./dist/wasm-database.js",
@@ -85,23 +93,13 @@
     "!dist/**/*.test.d.ts"
   ],
   "scripts": {
-    "verify:node": "bun build ./test/node-database/verify-node.mjs --target=node --external better-sqlite3 --outfile=./.verify-node.built.mjs && node ./.verify-node.built.mjs"
+    "verify:node": "bun build ./test/node-database/verify-node.mjs --target=node --outfile=./.verify-node.built.mjs && node ./.verify-node.built.mjs"
   },
   "dependencies": {
     "@sqlite.org/sqlite-wasm": "^3.53.0-build1",
-    "@syncular/core": "0.15.46"
-  },
-  "peerDependencies": {
-    "better-sqlite3": ">=11"
-  },
-  "peerDependenciesMeta": {
-    "better-sqlite3": {
-      "optional": true
-    }
+    "@syncular/core": "0.15.47"
   },
   "devDependencies": {
-    "@syncular/server": "0.15.46",
-    "@types/better-sqlite3": "^7.6.13",
-    "better-sqlite3": "^12.11.1"
+    "@syncular/server": "0.15.47"
   }
 }

package/src/index.ts

@@ -3,7 +3,7 @@
  * SPEC.md is normative.
  *
  * Browser-safe root: database backends live behind subpath exports
- * (`./bun` for bun:sqlite tests, `./wasm` for sqlite-wasm + OPFS); the
+ * (`./sqlite` for Node or Bun, `./wasm` for sqlite-wasm + OPFS); the
  * worker-side bootstrap lives behind `./worker`. The main-thread handle
  * (`worker-host`) and the RPC protocol types are root exports — they
  * import no SQLite.

package/src/node-database.ts

@@ -1,23 +1,9 @@
 /**
- * `ClientDatabase` on better-sqlite3 — the Electron-main / plain-Node
- * backend. Semantics mirror `./bun-database`
- * exactly (synchronous exec/query/transaction with the shared savepoint
- * helper, and the same §5.3 sqlite-image ATTACH path), so the core behaves
- * identically whether it runs on bun:sqlite (tests), sqlite-wasm (browser)
- * or better-sqlite3 (Node/Electron-main).
- *
- * better-sqlite3 is an OPTIONAL peer dependency, not a hard one: the package
- * installs cleanly without it and this module errors helpfully only when a
- * host actually calls `openNodeDatabase()` without having installed the peer.
- * Not exported from the package root, so browser/bun entries never resolve
- * the native module. Subpath export: `@syncular/client/node`.
- *
- * bun CANNOT dlopen better-sqlite3 (ERR_DLOPEN_FAILED, oven-sh/bun#4290), so
- * this adapter is verified under real Node — see the README "Electron-main /
- * plain-Node" section for the one-command recipe and `test/node-database`.
+ * `ClientDatabase` on Node's built-in `node:sqlite`. Semantics mirror the Bun
+ * adapter: synchronous queries, nested transactions, and SQLite image attach.
  */
+import { DatabaseSync, type SQLInputValue } from 'node:sqlite';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
@@ -28,54 +14,19 @@ import {
   type SqlValue,
 } from './database';
 
-/**
- * Structural view of the tiny better-sqlite3 surface this binding uses. We
- * type it locally (rather than importing `better-sqlite3`'s types) so the
- * package typechecks without the optional peer installed.
- */
-interface BetterSqliteStatement {
-  run(...params: NodeParam[]): unknown;
-  all(...params: NodeParam[]): unknown[];
-}
-interface BetterSqliteDatabase {
-  readonly inTransaction: boolean;
-  prepare(sql: string): BetterSqliteStatement;
-  exec(sql: string): unknown;
-  close(): void;
-}
-type BetterSqliteConstructor = new (
-  path: string,
-  options?: { readonly?: boolean; fileMustExist?: boolean },
-) => BetterSqliteDatabase;
-
-/**
- * better-sqlite3 accepts string / number / bigint / null / Buffer|Uint8Array
- * bind values, but NOT booleans (it throws "TypeError: can only bind …"). We
- * coerce booleans to 0/1 exactly like the bun adapter so callers see one
- * uniform bind contract across every backend.
- */
-type NodeParam = string | number | bigint | Uint8Array | null;
-
-function coerceParams(params: readonly SqlValue[]): NodeParam[] {
-  return params.map((value): NodeParam => {
+function coerceParams(params: readonly SqlValue[]): SQLInputValue[] {
+  return params.map((value): SQLInputValue => {
     if (typeof value === 'boolean') return value ? 1 : 0;
     return value;
   });
 }
 
-/**
- * better-sqlite3 returns BLOB columns as Node `Buffer`s. A Buffer IS a
- * Uint8Array subclass, but it can be a view onto a shared pool buffer, so we
- * normalize to a standalone Uint8Array — matching what bun:sqlite hands back
- * and keeping the buffer-ownership assumptions elsewhere (worker transfer,
- * structured clone) honest.
- */
 function normalizeRow(row: Record<string, unknown>): SqlRow {
   const out: SqlRow = {};
   for (const key in row) {
     const value = row[key];
-    if (Buffer.isBuffer(value)) {
-      out[key] = new Uint8Array(value); // copies out of the pool
+    if (value instanceof Uint8Array) {
+      out[key] = new Uint8Array(value);
     } else {
       out[key] = value as SqlValue;
     }
@@ -83,55 +34,12 @@ function normalizeRow(row: Record<string, unknown>): SqlRow {
   return out;
 }
 
-/**
- * Load the optional peer AND open the database in one guarded step, so BOTH
- * failure modes are turned into a clear, actionable error rather than a raw
- * one:
- *
- *  - `require('better-sqlite3')` throwing MODULE_NOT_FOUND — the peer is not
- *    installed (the common browser-only-host case), and
- *  - `new Database()` throwing ERR_DLOPEN_FAILED — the module resolves but the
- *    native addon cannot load, which is exactly what bun does for
- *    better-sqlite3 (oven-sh/bun#4290); the addon only dlopens at construction.
- */
-function openBetterSqlite(path: string): BetterSqliteDatabase {
-  const require = createRequire(import.meta.url);
-  try {
-    const mod = require('better-sqlite3') as
-      | BetterSqliteConstructor
-      | { default: BetterSqliteConstructor };
-    const Database =
-      (mod as { default?: BetterSqliteConstructor }).default ??
-      (mod as BetterSqliteConstructor);
-    return new Database(path);
-  } catch (error) {
-    const code = (error as { code?: string })?.code;
-    if (code === 'ERR_DLOPEN_FAILED') {
-      throw new Error(
-        "openNodeDatabase() requires the 'better-sqlite3' native module, but " +
-          'it failed to load. This most commonly means you are running under ' +
-          'bun, which cannot dlopen better-sqlite3 (oven-sh/bun#4290) — use ' +
-          "the bun:sqlite backend ('@syncular/client/bun') under bun, " +
-          "and reserve '@syncular/client/node' for Node/Electron-main. " +
-          `Underlying error: ${String(error)}`,
-      );
-    }
-    throw new Error(
-      'openNodeDatabase() requires the optional peer dependency ' +
-        "'better-sqlite3', which is not installed. Add it to your app " +
-        '(`npm install better-sqlite3` / `bun add better-sqlite3`) — it is ' +
-        'kept optional so @syncular/client installs without a native ' +
-        `build for browser-only hosts. Underlying error: ${String(error)}`,
-    );
-  }
-}
-
 export class NodeClientDatabase implements ClientDatabase {
-  readonly db: BetterSqliteDatabase;
+  readonly db: DatabaseSync;
   #tx = { depth: 0 };
 
   constructor(path = ':memory:') {
-    this.db = openBetterSqlite(path);
+    this.db = new DatabaseSync(path);
   }
 
   exec(sql: string, params: readonly SqlValue[] = []): void {
@@ -140,19 +48,14 @@ export class NodeClientDatabase implements ClientDatabase {
 
   query(sql: string, params: readonly SqlValue[] = []): SqlRow[] {
     const rows = this.db.prepare(sql).all(...coerceParams(params));
-    return (rows as Record<string, unknown>[]).map(normalizeRow);
+    return rows.map(normalizeRow);
   }
 
   transaction<T>(fn: () => T): T {
     return runTransaction(this.#tx, (sql) => this.db.exec(sql), fn);
   }
 
-  /**
-   * §5.3 image import: better-sqlite3 (like bun:sqlite) attaches files, not
-   * buffers, so the image lands in a private temp file for the duration of
-   * the ATTACH. Must be called outside any open transaction (SQLite cannot
-   * ATTACH inside one).
-   */
+  /** §5.3 image import through a private file attached for one callback. */
   withSqliteImage<T>(bytes: Uint8Array, alias: string, fn: () => T): T {
     assertImageAlias(alias);
     const dir = mkdtempSync(join(tmpdir(), 'syncular-image-'));

package/src/query-guard.ts

@@ -10,8 +10,8 @@
  *      bypasses the outbox (SPEC §7.1) and silently diverges from the
  *      server — writes MUST go through `client.mutate([...])`.
  *   2. ONE STATEMENT. `sqlite-wasm`'s `exec` runs every statement in a
- *      multi-statement string (`SELECT 1; DROP TABLE t`), while bun:sqlite /
- *      better-sqlite3 prepare only the first. We unify on the strict
+ *      multi-statement string (`SELECT 1; DROP TABLE t`), while the native
+ *      SQLite adapters prepare only the first. We unify on the strict
  *      behaviour: exactly one statement per `query()`.
  *
  * The guard only fronts the PUBLIC `client.query()` — engine-internal reads

package/src/sqlite-bun.ts

@@ -0,0 +1,6 @@
+import { openBunDatabase } from './bun-database';
+import type { ClientDatabase } from './database';
+
+export function openSqliteDatabase(path = ':memory:'): ClientDatabase {
+  return openBunDatabase(path);
+}

package/src/sqlite-node.ts

@@ -0,0 +1,6 @@
+import type { ClientDatabase } from './database';
+import { openNodeDatabase } from './node-database';
+
+export function openSqliteDatabase(path = ':memory:'): ClientDatabase {
+  return openNodeDatabase(path);
+}