@statewalker/webrun-files-sqlite 0.10.3 → 0.11.0

package/README.md

@@ -3,8 +3,8 @@
 ## What it is
 
 Two implementations of `FilesApi` from `@statewalker/webrun-files` that store files in a SQLite
-database, behind one small SQL driver interface with drivers for `node:sqlite`, Cloudflare Durable
-Object storage and Cloudflare D1:
+database, through `@statewalker/db-api`'s `Db`: any `@statewalker/db-sqlite-*` driver — `node:sqlite`,
+the browser (sqlite-wasm), or a Durable Object's storage:
 
 - `SqliteFilesApi` streams content as fixed-size blocks (1 MiB by default, optionally deflated per
   block), shares identical content between paths, and makes every metadata change one transaction.
@@ -14,9 +14,9 @@ Object storage and Cloudflare D1:
 
 ## Why it exists
 
-Durable Objects and D1 offer SQLite and nothing like a file system, and a single SQLite file is a
+Durable Objects offer SQLite and nothing like a file system, and a single SQLite file is a
 convenient, transactional store elsewhere too. Storing a file as one blob breaks there: Durable
-Objects and D1 cap a row at 2 MB, and a blob is read and written whole. `SqliteFilesApi` cuts
+Objects cap a row at 2 MB, and a blob is read and written whole. `SqliteFilesApi` cuts
 content into blocks that stay under the cap and can be streamed and range-read. `SqlarFilesApi`
 exists for the opposite need: an archive other SQLAR tools can open, in runtimes without a row
 limit.
@@ -25,7 +25,7 @@ limit.
 | --- | --- | --- |
 | Storage | paths -> contents -> blocks of at most 1.5 MiB | one row per file, SQLite Archive format |
 | File size | unbounded; streamed block by block | one blob, read and written whole |
-| Durable Objects / D1 | yes, every row stays under the 2 MB limit | only files whose stored row is under 2 MB |
+| Durable Objects | yes, every row stays under the 2 MB limit | only files whose stored row is under 2 MB |
 | Readable by `sqlite3 -A` | no | yes |
 | Identical content | stored once, shared by every path | stored per path |
 
@@ -34,23 +34,28 @@ Use `SqliteFilesApi` by default.
 ## How to use
 
 ```bash
-pnpm add @statewalker/webrun-files-sqlite @statewalker/webrun-files
+pnpm add @statewalker/webrun-files-sqlite @statewalker/webrun-files @statewalker/db-sqlite-node
 ```
 
+Pick the driver for your runtime: `@statewalker/db-sqlite-node` on Node, `@statewalker/db-sqlite-do`
+in a Durable Object, `@statewalker/db-sqlite-browser` in the browser.
+
 `pako` is not a dependency: pass the module to `pakoCodec` / `pakoDeflateCodec` if you use them.
 
 One entry point, `@statewalker/webrun-files-sqlite`: ESM (`dist/esm/index.js`), CommonJS
 (`dist/cjs/index.cjs`), types (`dist/index.d.ts`); sources in `src/`. The package imports no
-database binding itself; you pass the handle in, so it bundles for any runtime.
+database driver itself; you pass a `Db` in, so it bundles for any runtime.
 
 ```typescript
-import { D1SqlDriver, DoSqlDriver, NodeSqlDriver, SqliteFilesApi } from '@statewalker/webrun-files-sqlite';
+import { newNodeSqliteDb } from '@statewalker/db-sqlite-node';
+import { SqliteFilesApi } from '@statewalker/webrun-files-sqlite';
 
-new NodeSqlDriver(new DatabaseSync('files.db')); // node:sqlite
-new DoSqlDriver(this.ctx.storage);               // in a Durable Object: ctx.storage, not ctx.storage.sql
-new D1SqlDriver(env.DB);                          // a D1 binding
+const db = await newNodeSqliteDb({ path: 'files.db' }); // node:sqlite
+// or, in a Durable Object (ctx.storage, not ctx.storage.sql):
+// import { newDoSqliteDb } from '@statewalker/db-sqlite-do';
+// const db = newDoSqliteDb(this.ctx.storage);
 
-const files = new SqliteFilesApi(driver, { blockSize: 1024 * 1024 });
+const files = new SqliteFilesApi(db, { blockSize: 1024 * 1024 });
 await files.init(); // creates tables and indexes if missing; await it before any other call
 ```
 
@@ -76,10 +81,10 @@ await files.init(); // creates tables and indexes if missing; await it before an
 ### Stream a large file through `SqliteFilesApi`
 
 ```typescript
-import { DatabaseSync } from 'node:sqlite';
-import { NodeSqlDriver, SqliteFilesApi } from '@statewalker/webrun-files-sqlite';
+import { newNodeSqliteDb } from '@statewalker/db-sqlite-node';
+import { SqliteFilesApi } from '@statewalker/webrun-files-sqlite';
 
-const files = new SqliteFilesApi(new NodeSqlDriver(new DatabaseSync('files.db')));
+const files = new SqliteFilesApi(await newNodeSqliteDb({ path: 'files.db' }));
 await files.init();
 
 await files.write('/video.mp4', chunks); // any Iterable or AsyncIterable of Uint8Array
@@ -91,9 +96,10 @@ for await (const chunk of files.read('/video.mp4', { start: 10_000_000, length:
 ### Inside a Durable Object
 
 ```typescript
-import { DoSqlDriver, SqliteFilesApi } from '@statewalker/webrun-files-sqlite';
+import { newDoSqliteDb } from '@statewalker/db-sqlite-do';
+import { SqliteFilesApi } from '@statewalker/webrun-files-sqlite';
 
-const files = new SqliteFilesApi(new DoSqlDriver(this.ctx.storage));
+const files = new SqliteFilesApi(newDoSqliteDb(this.ctx.storage));
 await files.init();
 ```
 
@@ -106,12 +112,12 @@ const removed = await files.sweep({ olderThan: 60 * 60_000 }); // contents untou
 ### A portable archive with `SqlarFilesApi`
 
 ```typescript
-import { DatabaseSync } from 'node:sqlite';
+import { newNodeSqliteDb } from '@statewalker/db-sqlite-node';
 import * as pako from 'pako';
 import { readText, writeText } from '@statewalker/webrun-files';
-import { NodeSqlDriver, pakoCodec, SqlarFilesApi } from '@statewalker/webrun-files-sqlite';
+import { pakoCodec, SqlarFilesApi } from '@statewalker/webrun-files-sqlite';
 
-const files = new SqlarFilesApi(new NodeSqlDriver(new DatabaseSync('site.sqlar')), {
+const files = new SqlarFilesApi(await newNodeSqliteDb({ path: 'site.sqlar' }), {
   codec: pakoCodec(pako, { level: 9 }),
 });
 await files.init(); // creates the sqlar table if missing
@@ -123,38 +129,23 @@ await files.symlink('/latest.md', './docs/index.md');
 await files.readlink('/latest.md'); // "./docs/index.md"
 ```
 
-### Your own SQLite binding
-
-Implement the driver interface:
-
-```typescript
-import type { SqlDriver, SqlStatement } from '@statewalker/webrun-files-sqlite';
-
-interface SqlStatement {
-  sql: string;
-  params?: unknown[];
-}
-
-interface SqlDriver {
-  /** Rows as objects keyed by column name. */
-  all<T>(sql: string, ...params: unknown[]): T[] | Promise<T[]>;
-  /** One statement, for its effect. */
-  run(sql: string, ...params: unknown[]): void | Promise<void>;
-  /** The statements in order, as one transaction: all apply or none do. Returns rows changed per
-   *  statement. No statement may depend on another's result. */
-  transaction(statements: SqlStatement[]): number[] | Promise<number[]>;
-}
-```
-
 ## Internals
 
-### The drivers and their transactions
+### Why every step runs through `inTransaction`, and what breaks it
 
-The built-in drivers implement `transaction` with `BEGIN IMMEDIATE ... COMMIT` (node:sqlite),
-`ctx.storage.transactionSync` (Durable Objects, where `sql.exec` rejects `BEGIN`) and `batch()` (D1).
-Blobs come back as `Uint8Array`, `ArrayBuffer` or `number[]` depending on the runtime; both
-implementations accept all three. The handle types are exported as `NodeSqliteDatabase`,
-`DoStorage` and `D1Database`.
+Each step that changes what a path shows runs as one SQLite transaction through `inTransaction`
+from `@statewalker/db-sqlite`. It runs as `BEGIN IMMEDIATE … COMMIT` behind a mutex on Node and in
+the browser, and through `ctx.storage.transaction()` in a Durable Object, where `sql.exec` rejects
+`BEGIN`. The rows a statement changed come from `SELECT changes()` inside that transaction. Steps
+never depend on reading another statement's result: conditions live in SQL (`WHERE EXISTS …`).
+
+`inTransaction` finds the driver's transaction support through a hook on the `Db` it was given.
+**A `Db` wrapped in your own proxy (logging, metrics) loses the hook.** The first `write`,
+`remove`, `copy`, `move` or `sweep` then rejects with: `inTransaction: this Db has no SQLite
+transaction hook. It is not a @statewalker/db-sqlite* Db, or it wraps one (a wrapper object loses
+the hook - pass the driver's Db itself), or it is the handle of a running transaction (nesting is
+not supported).` Pass the driver's `Db` itself, or forward `db[SQLITE_TRANSACTION]` (exported by
+`@statewalker/db-sqlite`) in your wrapper.
 
 ### How `SqliteFilesApi` stores content
 
@@ -178,9 +169,9 @@ it too. A content and its blocks are deleted when the last path pointing at it g
 ### Why the block size is capped at 1.5 MiB
 
 A deflated block can be slightly larger than its input. 1.5 MiB keeps even incompressible input
-under the 2 MB row limit of Durable Objects and D1. Larger blocks mean fewer rows, which matters
-where every statement costs (D1); smaller blocks make small range reads cheaper. Each content
-records its own block size, so changing `blockSize` never affects existing files.
+under the 2 MB row limit of Durable Objects. Larger blocks mean fewer rows; smaller blocks make
+small range reads cheaper. Each content records its own block size, so changing `blockSize` never
+affects existing files.
 
 ### Streaming and memory
 
@@ -236,14 +227,27 @@ does. A dangling link, or a chain longer than 8, behaves as a missing path. `rem
 ### `SqlarFilesApi` limits
 
 - A file is one blob: `write` buffers it, `read` inflates it whole and yields one chunk.
-- On Durable Objects and D1 the stored (possibly compressed) size of one file must stay under 2 MB.
-- Multi-row mutations (`copy`, `move`, `remove` of a tree) are not wrapped in a transaction.
+- On Durable Objects the stored (possibly compressed) size of one file must stay under 2 MB, since
+  SQLAR keeps each file in one row. A larger file fails the `write` with `string or blob too big`
+  — a value limit, not corruption. Store big files with `SqliteFilesApi`, whose blocks stay under
+  the limit.
+- Multi-row mutations (`copy`, `move`, `remove` of a tree) are not wrapped in a transaction: a
+  failure part-way leaves the rows already changed in place, and a `move` can leave the entry under
+  both paths.
 - `list` loads every row under the directory, then sorts the entries into path order before
   applying `after`.
 
 ### Dependencies
 
-`@statewalker/webrun-files` only. SQLite handles and `pako` are passed in by the caller.
+- `@statewalker/db-api` — the `Db` contract both implementations run on.
+- `@statewalker/db-sqlite` — `inTransaction`, for `SqliteFilesApi`'s atomic steps.
+- `@statewalker/webrun-files` — the `FilesApi` contract and path helpers.
+
+The browser driver (`@statewalker/db-sqlite-browser`) is supported through the same `Db` contract, but
+this package's tests run on `node:sqlite` and the Durable Object fake only.
+
+The drivers (`@statewalker/db-sqlite-node`, `@statewalker/db-sqlite-do`, …) are the caller's
+choice and are not dependencies; neither is `pako`, which is passed in.
 
 ## License
 

package/dist/blocks/sqlite-files-api.d.ts

@@ -1,5 +1,5 @@
+import type { Db } from "@statewalker/db-api";
 import type { FileInfo, FileStats, FilesApi, ListOptions, ReadOptions } from "@statewalker/webrun-files";
-import type { SqlDriver } from "../sql.types.js";
 import { type StreamCodec } from "./stream-codec.js";
 export interface SqliteFilesApiOptions {
     /** Prefix of the three table names. Defaults to "fs_". */
@@ -20,7 +20,7 @@ export interface SqliteFilesApiOptions {
  * A FilesApi over three SQLite tables: paths point at immutable contents, and
  * a content is a sequence of bounded, optionally compressed blocks. Reads and
  * writes stream one block at a time, so no file is ever held whole and no row
- * outgrows the 2 MB limit of Durable Objects and D1.
+ * outgrows the 2 MB row limit of Durable Objects.
  *
  * Streaming happens outside transactions; every step that changes what a path
  * shows is one transaction, so an interruption leaves at most an unreferenced
@@ -28,7 +28,7 @@ export interface SqliteFilesApiOptions {
  */
 export declare class SqliteFilesApi implements FilesApi {
     #private;
-    constructor(sql: SqlDriver, opts?: SqliteFilesApiOptions);
+    constructor(db: Db, opts?: SqliteFilesApiOptions);
     /** Creates the tables and indexes if missing. Await it before any other call. */
     init(): Promise<void>;
     read(path: string, options?: ReadOptions): AsyncIterable<Uint8Array>;

package/dist/blocks/sqlite-files-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-files-api.d.ts","sourceRoot":"","sources":["../../src/blocks/sqlite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAGnC,OAAO,KAAK,EAAE,SAAS,EAAgB,MAAM,iBAAiB,CAAC;AAG/D,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,mBAAmB,CAAC;AAOtE,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAcD;;;;;;;;;GASG;AACH,qBAAa,cAAe,YAAW,QAAQ;;IAS7C,YAAY,GAAG,EAAE,SAAS,EAAE,IAAI,GAAE,qBAA0B,EAqB3D;IAED,iFAAiF;IAC3E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA0B1B;IAIM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,UAAU,CAAC,CA8C9E;IAID;;;;OAIG;IACG,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAmEf;IA8CK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASvC;IAIK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAKxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC,CA4B5E;IAIK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAgCK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3D;IA6CD;;;;;;;;OAQG;IACG,KAAK,CAAC,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB3D;CAiEF"}
+{"version":3,"file":"sqlite-files-api.d.ts","sourceRoot":"","sources":["../../src/blocks/sqlite-files-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,qBAAqB,CAAC;AAE9C,OAAO,KAAK,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACZ,MAAM,2BAA2B,CAAC;AAMnC,OAAO,EAAE,KAAK,WAAW,EAAmB,MAAM,mBAAmB,CAAC;AAOtE,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAcD;;;;;;;;;GASG;AACH,qBAAa,cAAe,YAAW,QAAQ;;IAS7C,YAAY,EAAE,EAAE,EAAE,EAAE,IAAI,GAAE,qBAA0B,EAqBnD;IAED,iFAAiF;IAC3E,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CA0B1B;IAIM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,UAAU,CAAC,CA8C9E;IAID;;;;OAIG;IACG,KAAK,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,GACxD,OAAO,CAAC,IAAI,CAAC,CAuEf;IA8CK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvC;IAIK,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAKxD;IAEK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3C;IAEM,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,aAAa,CAAC,QAAQ,CAAC,CA4B5E;IAIK,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3C;IAgCK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3D;IAEK,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAE3D;IA6CD;;;;;;;;OAQG;IACG,KAAK,CAAC,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAqB3D;CAqEF"}

package/dist/bytes.d.ts

@@ -1,3 +1,3 @@
-/** Blobs arrive as Uint8Array (node:sqlite), ArrayBuffer (Durable Objects) or number[] (D1). */
+/** BLOBs arrive as Uint8Array from every @statewalker/db-sqlite driver; SQLAR may hold TEXT. */
 export declare function toBytes(value: unknown): Uint8Array;
 //# sourceMappingURL=bytes.d.ts.map

package/dist/bytes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAMlD"}
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAIlD"}

package/dist/cjs/index.cjs

@@ -1,4 +1,19 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region ../../node_modules/.pnpm/@statewalker+db-sqlite@0.1.0/node_modules/@statewalker/db-sqlite/dist/index.mjs
+/** Key under which a SQLite Db carries its transaction hook. Shared across bundles via Symbol.for. */
+const SQLITE_TRANSACTION = Symbol.for("@statewalker/db-sqlite:transaction");
+const NO_HOOK = "inTransaction: this Db has no SQLite transaction hook. It is not a @statewalker/db-sqlite* Db, or it wraps one (a wrapper object loses the hook - pass the driver's Db itself), or it is the handle of a running transaction (nesting is not supported).";
+/**
+* Run `cb` in one SQLite transaction: every statement issued through `tx` commits together, or
+* none does if `cb` throws. Other calls on `db` wait until the transaction ends. `cb` must not do
+* external I/O and must be idempotent: a Durable Object may run it more than once.
+*/
+function inTransaction(db, cb) {
+	const hook = db[SQLITE_TRANSACTION];
+	if (typeof hook !== "function") return Promise.reject(/* @__PURE__ */ new Error(NO_HOOK));
+	return hook(cb);
+}
+//#endregion
 //#region ../webrun-files/dist/esm/index.js
 /**
 * The order every `FilesApi.list()` yields: paths compared by Unicode code
@@ -38,15 +53,31 @@ function normalizePath(filePath) {
 }
 //#endregion
 //#region src/bytes.ts
-/** Blobs arrive as Uint8Array (node:sqlite), ArrayBuffer (Durable Objects) or number[] (D1). */
+/** BLOBs arrive as Uint8Array from every @statewalker/db-sqlite driver; SQLAR may hold TEXT. */
 function toBytes(value) {
 	if (value instanceof Uint8Array) return value;
-	if (value instanceof ArrayBuffer) return new Uint8Array(value);
-	if (Array.isArray(value)) return Uint8Array.from(value);
 	if (typeof value === "string") return new TextEncoder().encode(value);
 	return /* @__PURE__ */ new Uint8Array(0);
 }
 //#endregion
+//#region src/run-statements.ts
+/**
+* Runs the statements in order on a transaction's Db and returns, per
+* statement, the rows it changed — zero exactly when it changed nothing. The
+* count is SQLite's `changes()` on the same connection, so index writes are
+* not counted. Call it only inside `inTransaction`; it does nothing but SQL,
+* so a retried transaction callback is safe.
+*/
+async function runStatements(tx, statements) {
+	const counts = [];
+	for (const { sql, params = [] } of statements) {
+		await tx.query(sql, params);
+		const [row] = await tx.query("SELECT changes() AS n");
+		counts.push(Number(row.n));
+	}
+	return counts;
+}
+//#endregion
 //#region src/blocks/byte-reader.ts
 /**
 * Pull bytes from a chunk source in bounded pieces.
@@ -353,33 +384,33 @@ async function* iterate(stream) {
 //#endregion
 //#region src/blocks/sqlite-files-api.ts
 const MiB = 1048576;
-/** Rows on Durable Objects and D1 are capped at 2 MB; leave room for deflate's worst case. */
+/** Rows on Durable Objects are capped at 2 MB; leave room for deflate's worst case. */
 const MAX_BLOCK_SIZE_LIMIT = 1.5 * MiB;
 const LIST_PAGE = 256;
 /**
 * A FilesApi over three SQLite tables: paths point at immutable contents, and
 * a content is a sequence of bounded, optionally compressed blocks. Reads and
 * writes stream one block at a time, so no file is ever held whole and no row
-* outgrows the 2 MB limit of Durable Objects and D1.
+* outgrows the 2 MB row limit of Durable Objects.
 *
 * Streaming happens outside transactions; every step that changes what a path
 * shows is one transaction, so an interruption leaves at most an unreferenced
 * content, which {@link sweep} removes.
 */
 var SqliteFilesApi = class {
-	#sql;
+	#db;
 	#codec;
 	#blockSize;
 	#paths;
 	#files;
 	#blocks;
 	#prefix;
-	constructor(sql, opts = {}) {
+	constructor(db, opts = {}) {
 		const prefix = opts.tablePrefix ?? "fs_";
 		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix)) throw new Error(`SqliteFilesApi: tablePrefix must be a plain SQL identifier, got ${prefix}`);
 		this.#blockSize = opts.blockSize ?? MiB;
 		if (!Number.isInteger(this.#blockSize) || this.#blockSize < 1 || this.#blockSize > MAX_BLOCK_SIZE_LIMIT) throw new Error(`SqliteFilesApi: blockSize must be an integer from 1 to ${MAX_BLOCK_SIZE_LIMIT}, got ${this.#blockSize}`);
-		this.#sql = sql;
+		this.#db = db;
 		this.#codec = opts.compression === void 0 ? availableWebCodec() : opts.compression;
 		this.#prefix = prefix;
 		this.#paths = `${prefix}paths`;
@@ -412,7 +443,7 @@ var SqliteFilesApi = class {
 			`CREATE INDEX IF NOT EXISTS ${this.#prefix}paths_fid ON ${this.#paths}(fid)`,
 			`CREATE INDEX IF NOT EXISTS ${this.#prefix}files_hash ON ${this.#files}(hash, size)`
 		];
-		for (const statement of statements) await this.#sql.run(statement);
+		for (const statement of statements) await this.#db.query(statement);
 	}
 	async *read(path, options = {}) {
 		options.signal?.throwIfAborted();
@@ -456,8 +487,12 @@ var SqliteFilesApi = class {
 	async write(path, content) {
 		const name = normalizePath(path);
 		const compression = this.#codec?.name ?? "none";
-		const fid = (await this.#sql.all(`INSERT INTO ${this.#files}(size, compression, block_size, hash, updated)
-       VALUES (NULL, ?, ?, NULL, ?) RETURNING fid`, compression, this.#blockSize, Date.now()))[0].fid;
+		const fid = await inTransaction(this.#db, async (tx) => (await tx.query(`INSERT INTO ${this.#files}(size, compression, block_size, hash, updated)
+             VALUES (NULL, ?, ?, NULL, ?) RETURNING fid`, [
+			compression,
+			this.#blockSize,
+			Date.now()
+		]))[0].fid);
 		const limit = this.#blockSize;
 		const reader = new ByteReader(content);
 		const hash = new Sha256();
@@ -478,7 +513,7 @@ var SqliteFilesApi = class {
 					}
 				};
 				const block = await collectBlock(this.#codec ? this.#codec.compress(pieces()) : pieces());
-				const [alive] = await this.#sql.transaction([{
+				const [alive] = await this.#transaction([{
 					sql: `UPDATE ${this.#files} SET updated = ? WHERE fid = ? AND size IS NULL`,
 					params: [Date.now(), fid]
 				}, {
@@ -495,14 +530,14 @@ var SqliteFilesApi = class {
 				size += raw;
 			}
 			const previous = await this.#entry(name);
-			const [finished] = await this.#sql.transaction(this.#finishWrite(name, fid, size, hash.digestHex(), compression, previous?.fid ?? null));
+			const [finished] = await this.#transaction(this.#finishWrite(name, fid, size, hash.digestHex(), compression, previous?.fid ?? null));
 			if (finished === 0) throw sweptDuringWrite(name);
 		} catch (error) {
 			try {
 				await reader.close();
 			} catch {}
 			try {
-				await this.#sql.transaction([{
+				await this.#transaction([{
 					sql: `DELETE FROM ${this.#files} WHERE fid = ? AND size IS NULL`,
 					params: [fid]
 				}, ...this.#deleteBlocksOfMissing(fid)]);
@@ -567,7 +602,7 @@ var SqliteFilesApi = class {
 	}
 	async mkdir(path) {
 		const now = Date.now();
-		for (const dir of ancestorsAndSelf$1(normalizePath(path))) await this.#sql.run(`INSERT INTO ${this.#paths}(path, fid, mtime) VALUES (?, NULL, ?) ON CONFLICT(path) DO NOTHING`, dir, now);
+		for (const dir of ancestorsAndSelf$1(normalizePath(path))) await this.#db.query(`INSERT INTO ${this.#paths}(path, fid, mtime) VALUES (?, NULL, ?) ON CONFLICT(path) DO NOTHING`, [dir, now]);
 	}
 	async stats(path) {
 		const name = normalizePath(path);
@@ -588,10 +623,10 @@ var SqliteFilesApi = class {
 		for (;;) {
 			const params = [...range.params, cursor];
 			if (!options.recursive) params.push(prefixLength + 1);
-			const rows = await this.#sql.all(`SELECT p.path, p.fid, p.mtime, f.size, f.compression, f.block_size
+			const rows = await this.#db.query(`SELECT p.path, p.fid, p.mtime, f.size, f.compression, f.block_size
          FROM ${this.#paths} p LEFT JOIN ${this.#files} f ON f.fid = p.fid
          WHERE ${range.where} AND p.path > ? ${directOnly}
-         ORDER BY p.path LIMIT ${LIST_PAGE}`, ...params);
+         ORDER BY p.path LIMIT ${LIST_PAGE}`, params);
 			for (const row of rows) {
 				const stats = toStats$1(row);
 				if (stats) yield {
@@ -605,7 +640,7 @@ var SqliteFilesApi = class {
 		}
 	}
 	async remove(path) {
-		const counts = await this.#sql.transaction(this.#removeTree(normalizePath(path)));
+		const counts = await this.#transaction(this.#removeTree(normalizePath(path)));
 		return counts[counts.length - 1] > 0;
 	}
 	/**
@@ -695,7 +730,7 @@ var SqliteFilesApi = class {
 				]
 			}
 		];
-		const counts = await this.#sql.transaction(statements);
+		const counts = await this.#transaction(statements);
 		return counts[counts.length - 1] > 0;
 	}
 	/**
@@ -714,7 +749,7 @@ var SqliteFilesApi = class {
 		const eligible = `f.updated < ? AND NOT EXISTS (
       SELECT 1 FROM ${this.#paths} p WHERE p.fid = f.fid
     )`;
-		const [, contents] = await this.#sql.transaction([{
+		const [, contents] = await this.#transaction([{
 			sql: `DELETE FROM ${this.#blocks} WHERE fid IN (SELECT f.fid FROM ${this.#files} f WHERE ${eligible})`,
 			params: [cutoff]
 		}, {
@@ -723,10 +758,14 @@ var SqliteFilesApi = class {
 		}]);
 		return contents;
 	}
+	/** The statements as one transaction; per statement, the rows it changed. */
+	#transaction(statements) {
+		return inTransaction(this.#db, (tx) => runStatements(tx, statements));
+	}
 	async #entry(name) {
-		return (await this.#sql.all(`SELECT p.fid, p.mtime, f.size, f.compression, f.block_size
+		return (await this.#db.query(`SELECT p.fid, p.mtime, f.size, f.compression, f.block_size
        FROM ${this.#paths} p LEFT JOIN ${this.#files} f ON f.fid = p.fid
-       WHERE p.path = ?`, name))[0];
+       WHERE p.path = ?`, [name]))[0];
 	}
 	#decoder(name, compression) {
 		if (compression === "none") return null;
@@ -738,7 +777,7 @@ var SqliteFilesApi = class {
 		throw new Error(`sqlite-files: ${name} is compressed with ${compression}, and no codec reads it`);
 	}
 	async #block(fid, shift) {
-		return (await this.#sql.all(`SELECT shift, block FROM ${this.#blocks} WHERE fid = ? AND shift = ?`, fid, shift))[0];
+		return (await this.#db.query(`SELECT shift, block FROM ${this.#blocks} WHERE fid = ? AND shift = ?`, [fid, shift]))[0];
 	}
 	/** A subquery selecting the content `fid` while it is still pending. */
 	#pending(fid) {
@@ -872,79 +911,6 @@ async function pipe(bytes, transform) {
 	return new Uint8Array(await new Response(stream).arrayBuffer());
 }
 //#endregion
-//#region src/drivers.ts
-/** node:sqlite — local development, tests and any Node deployment. */
-var NodeSqlDriver = class {
-	#db;
-	constructor(db) {
-		this.#db = db;
-	}
-	all(sql, ...params) {
-		return this.#db.prepare(sql).all(...params);
-	}
-	run(sql, ...params) {
-		this.#db.prepare(sql).run(...params);
-	}
-	/** Synchronous from BEGIN to COMMIT, so no other call can interleave on the connection. */
-	transaction(statements) {
-		this.#db.exec("BEGIN IMMEDIATE");
-		try {
-			const counts = statements.map(({ sql, params = [] }) => Number(this.#db.prepare(sql).run(...params).changes));
-			this.#db.exec("COMMIT");
-			return counts;
-		} catch (error) {
-			this.#db.exec("ROLLBACK");
-			throw error;
-		}
-	}
-};
-/**
-* Durable Object SQLite storage: pass `ctx.storage`. Synchronous; BLOBs come
-* back as ArrayBuffer. Transactions use `transactionSync`, since `sql.exec`
-* rejects `BEGIN`.
-*/
-var DoSqlDriver = class {
-	#storage;
-	constructor(storage) {
-		this.#storage = storage;
-	}
-	all(sql, ...params) {
-		return this.#storage.sql.exec(sql, ...params).toArray();
-	}
-	run(sql, ...params) {
-		this.#storage.sql.exec(sql, ...params).toArray();
-	}
-	/**
-	* Counts come from SQLite's `changes()` on the same connection, not from the
-	* cursor's `rowsWritten`, which also counts every index row a write touches.
-	*/
-	transaction(statements) {
-		return this.#storage.transactionSync(() => statements.map(({ sql, params = [] }) => {
-			this.#storage.sql.exec(sql, ...params).toArray();
-			const [row] = this.#storage.sql.exec("SELECT changes() AS n").toArray();
-			return row.n;
-		}));
-	}
-};
-/** Cloudflare D1. Asynchronous; BLOBs come back as number[]; transactions are `batch()`. */
-var D1SqlDriver = class {
-	#db;
-	constructor(db) {
-		this.#db = db;
-	}
-	async all(sql, ...params) {
-		const { results } = await this.#db.prepare(sql).bind(...params).all();
-		return results;
-	}
-	async run(sql, ...params) {
-		await this.#db.prepare(sql).bind(...params).run();
-	}
-	async transaction(statements) {
-		if (statements.length === 0) return [];
-		return (await this.#db.batch(statements.map(({ sql, params = [] }) => this.#db.prepare(sql).bind(...params)))).map((result) => result.meta.changes);
-	}
-};
-//#endregion
 //#region src/sqlar-files-api.ts
 /**
 * The table, verbatim from the SQLite Archive specification. Five columns,
@@ -971,22 +937,22 @@ const MAX_SYMLINK_HOPS = 8;
 * missing path — and {@link symlink} / {@link readlink} expose the link itself.
 */
 var SqlarFilesApi = class {
-	#sql;
+	#db;
 	#codec;
-	constructor(sql, opts = {}) {
-		this.#sql = sql;
+	constructor(db, opts = {}) {
+		this.#db = db;
 		this.#codec = opts.codec ?? defaultCodec();
 	}
 	/** Creates the table if it is missing. Await it before any other call. */
 	async init() {
-		await this.#sql.run(SCHEMA);
+		await this.#db.query(SCHEMA);
 	}
 	/** A missing path or a directory yields nothing; a file yields one chunk. */
 	async *read(path, options = {}) {
 		options.signal?.throwIfAborted();
 		const resolved = await this.#resolve(toName(path));
 		if (resolved?.stats.kind !== "file") return;
-		const rows = await this.#sql.all("SELECT data FROM sqlar WHERE name = ?", resolved.name);
+		const rows = await this.#db.query("SELECT data FROM sqlar WHERE name = ?", [resolved.name]);
 		const content = await this.#content(resolved.name, resolved.stats.size, toBytes(rows[0]?.data));
 		options.signal?.throwIfAborted();
 		const start = options.start ?? 0;
@@ -1051,7 +1017,7 @@ var SqlarFilesApi = class {
 		if (resolved?.stats.kind !== "directory") return;
 		const base = resolved.name;
 		const range = descendants(base);
-		const rows = await this.#sql.all(`SELECT ${ROW_COLUMNS} FROM sqlar WHERE ${range.where} ORDER BY name`, ...range.params);
+		const rows = await this.#db.query(`SELECT ${ROW_COLUMNS} FROM sqlar WHERE ${range.where} ORDER BY name`, range.params);
 		const prefixLength = base === "" ? 0 : base.length + 1;
 		const seen = /* @__PURE__ */ new Set();
 		for (const row of rows) {
@@ -1081,8 +1047,8 @@ var SqlarFilesApi = class {
 	}
 	async remove(path) {
 		const range = selfAndDescendants(toName(path));
-		if ((await this.#sql.all(`SELECT 1 FROM sqlar WHERE ${range.where} LIMIT 1`, ...range.params)).length === 0) return false;
-		await this.#sql.run(`DELETE FROM sqlar WHERE ${range.where}`, ...range.params);
+		if ((await this.#db.query(`SELECT 1 FROM sqlar WHERE ${range.where} LIMIT 1`, range.params)).length === 0) return false;
+		await this.#db.query(`DELETE FROM sqlar WHERE ${range.where}`, range.params);
 		return true;
 	}
 	/**
@@ -1093,7 +1059,7 @@ var SqlarFilesApi = class {
 		const from = toName(source);
 		const to = toName(target);
 		const range = selfAndDescendants(from);
-		const rows = await this.#sql.all(`SELECT name, mode, sz, typeof(data) AS dtype, data FROM sqlar WHERE ${range.where}`, ...range.params);
+		const rows = await this.#db.query(`SELECT name, mode, sz, typeof(data) AS dtype, data FROM sqlar WHERE ${range.where}`, range.params);
 		if (rows.length === 0) return false;
 		await this.mkdir(parentName(to));
 		for (const row of rows) {
@@ -1147,16 +1113,22 @@ var SqlarFilesApi = class {
 		}
 	}
 	async #row(name) {
-		return (await this.#sql.all(`SELECT ${ROW_COLUMNS} FROM sqlar WHERE name = ?`, name))[0];
+		return (await this.#db.query(`SELECT ${ROW_COLUMNS} FROM sqlar WHERE name = ?`, [name]))[0];
 	}
 	async #hasDescendants(name) {
 		const range = descendants(name);
-		return (await this.#sql.all(`SELECT 1 FROM sqlar WHERE ${range.where} LIMIT 1`, ...range.params)).length > 0;
+		return (await this.#db.query(`SELECT 1 FROM sqlar WHERE ${range.where} LIMIT 1`, range.params)).length > 0;
 	}
 	async #put(name, mode, sz, data) {
-		await this.#sql.run(`INSERT INTO sqlar (name, mode, mtime, sz, data) VALUES (?, ?, ?, ?, ?)
+		await this.#db.query(`INSERT INTO sqlar (name, mode, mtime, sz, data) VALUES (?, ?, ?, ?, ?)
        ON CONFLICT(name) DO UPDATE SET
-         mode = excluded.mode, mtime = excluded.mtime, sz = excluded.sz, data = excluded.data`, name, mode, Math.floor(Date.now() / 1e3), sz, data);
+         mode = excluded.mode, mtime = excluded.mtime, sz = excluded.sz, data = excluded.data`, [
+			name,
+			mode,
+			Math.floor(Date.now() / 1e3),
+			sz,
+			data
+		]);
 	}
 };
 const ROW_COLUMNS = "name, mode, mtime, sz, typeof(data) AS dtype, CASE WHEN sz = -1 THEN data END AS target";
@@ -1251,9 +1223,6 @@ async function concat(content) {
 	return out;
 }
 //#endregion
-exports.D1SqlDriver = D1SqlDriver;
-exports.DoSqlDriver = DoSqlDriver;
-exports.NodeSqlDriver = NodeSqlDriver;
 exports.SqlarFilesApi = SqlarFilesApi;
 exports.SqliteFilesApi = SqliteFilesApi;
 exports.defaultCodec = defaultCodec;