@statewalker/db-sqlite-do 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mikhail Kotelnikov
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,104 @@
1
- # Temporary Holding Version
1
+ # @statewalker/db-sqlite-do
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ ## What it is
4
+
5
+ A driver that implements `Db` from `@statewalker/db-api` on a Durable Object's SQLite storage
6
+ (`ctx.storage`), on Cloudflare or on celld. Its Db works with `inTransaction` from
7
+ `@statewalker/db-sqlite`. The `./fake` subpath gives a Node.js stand-in for `ctx.storage` with
8
+ the same limits, for unit tests.
9
+
10
+ ## Why it exists
11
+
12
+ Code written against `Db` (search indexes, file stores) must run inside a Durable Object as it
13
+ does on Node.js and in the browser. DO SQLite differs in ways that break such code silently: SQL
14
+ `BEGIN` is rejected, `transactionSync` commits at the first `await`, BLOBs come back as
15
+ `ArrayBuffer`. This driver hides those differences behind the same `Db` and transaction call.
16
+
17
+ ## How to use
18
+
19
+ ```sh
20
+ pnpm add @statewalker/db-sqlite-do
21
+ ```
22
+
23
+ | Import | Gives | Environment |
24
+ | --- | --- | --- |
25
+ | `@statewalker/db-sqlite-do` | `newDoSqliteDb`; types `DoSqlStorage`, `DoSqlCursor`, `Db`, `DbEntry` | Durable Object (Cloudflare, celld) |
26
+ | `@statewalker/db-sqlite-do/fake` | `newFakeDoStorage`; type `FakeDoStorage` | Node.js 22.13 or later (tests) |
27
+
28
+ `newDoSqliteDb(storage)` returns a `Db` synchronously, so it can be created in the DO
29
+ constructor. Use `?` placeholders.
30
+
31
+ ## Examples
32
+
33
+ ```ts
34
+ import { DurableObject } from "cloudflare:workers";
35
+ import { inTransaction } from "@statewalker/db-sqlite";
36
+ import { newDoSqliteDb } from "@statewalker/db-sqlite-do";
37
+
38
+ export class Notes extends DurableObject {
39
+ db = newDoSqliteDb(this.ctx.storage);
40
+
41
+ async add(body: string) {
42
+ await this.db.exec("CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT)");
43
+ return inTransaction(this.db, (tx) =>
44
+ tx.query<{ id: number }>("INSERT INTO notes (body) VALUES (?) RETURNING id", [body]),
45
+ );
46
+ }
47
+ }
48
+ ```
49
+
50
+ In a Node.js test:
51
+
52
+ ```ts
53
+ import { newDoSqliteDb } from "@statewalker/db-sqlite-do";
54
+ import { newFakeDoStorage } from "@statewalker/db-sqlite-do/fake";
55
+
56
+ const db = newDoSqliteDb(newFakeDoStorage());
57
+ ```
58
+
59
+ ## How it is tested against a real Durable Object
60
+
61
+ `pnpm test:do` (from the repository root) builds the workspace, starts `celld dev` on
62
+ `packages/db-sqlite-do/test-do/` with a clean state on a free port, and runs, inside a real
63
+ Durable Object, the shared `Db` conformance suite (through a small HTTP bridge), every scenario
64
+ listed in `test-do/scenarios.ts` (the SQLite transaction scenarios a DO can meet, plus the
65
+ vector and n-gram smoke scenarios of `@statewalker/db-sqlite-index`), and a platform probe whose expectations the `./fake` must also meet. It
66
+ needs celld 0.6.x on `PATH`; with another version it stops at once with
67
+ `test:do needs celld 0.6.x on PATH, found "<version>"`. A celld that prints no `ready` line within 60 seconds fails
68
+ the run with `celld dev was not ready within 60 s`. It stops only the celld process it started. It is not part of `pnpm test`: run it before a release.
69
+
70
+ ## Internals
71
+
72
+ - **Transactions use `storage.transaction(async fn)`.** It rolls back on a throw even after
73
+ `await`s on timers or `fetch`. `transactionSync` is not used: given an async function it commits
74
+ at the first `await`, so a later throw rolls nothing back. The platform can run the callback
75
+ again, so it must be idempotent and do no external I/O.
76
+ - **Limits of DO SQLite, and what they look like:** more than 100 bound parameters rejects with
77
+ `too many SQL variables` (pass id lists as one JSON string to `json_each(?)`); a BLOB or string
78
+ over about 2 MB rejects with `string or blob too big` (celld 0.6.2 accepts 1,900,000 bytes and
79
+ rejects 2,500,000; the fake rejects above 2,000,000 bytes, measuring a string in UTF-8);
80
+ `BEGIN`, `SAVEPOINT` and `PRAGMA` reject with `not authorized`.
81
+ - **`ON CONFLICT ROLLBACK` and `RAISE(ROLLBACK)` fail the whole DO call.** Inside `inTransaction`
82
+ on a Durable Object, a statement that makes SQLite itself end the transaction rolls the data
83
+ back, but the call in flight rejects with `a transaction rollback failed: … cannot rollback - no
84
+ transaction is active` instead of the constraint error, and the DO instance is reset (observed
85
+ on celld 0.6.2; Cloudflare unverified). Use the default `ABORT` conflict resolution inside
86
+ transactions. The fake rejects with the same message, so `inTransaction` callers see it in unit
87
+ tests too. An operation that runs past the platform deadline (15 s on celld) is
88
+ retried rather than failed, so keep each write step small.
89
+ - **BLOBs are converted both ways.** Typed-array parameters are bound as `ArrayBuffer`;
90
+ `ArrayBuffer` values read back become `Uint8Array`, as on every other SQLite driver.
91
+ - **`close()` releases nothing.** The storage belongs to the DO. It only makes later calls on this
92
+ Db reject with `db-sqlite: the database is closed`.
93
+ - **Use one Db per DO.** Calls are queued inside one Db; direct `ctx.storage.sql` calls made
94
+ elsewhere in the DO bypass that queue.
95
+ - **The fake is strict where the platform is unknown.** It rejects every `PRAGMA` (the platform
96
+ allows a few) and typed-array BLOB parameters, so code that passes on the fake does not depend
97
+ on them. Its limits are checked against real DO SQLite by `pnpm test:do`, which runs the same
98
+ probe in a `celld dev` Durable Object.
99
+ - **Dependencies:** `@statewalker/db-sqlite` (queue and transactions), `@statewalker/db-api`
100
+ (types). `./fake` uses Node.js's `node:sqlite`.
101
+
102
+ ## License
103
+
104
+ MIT
@@ -0,0 +1,21 @@
1
+ import { Db } from "@statewalker/db-api";
2
+ //#region src/do-sqlite-db.d.ts
3
+ /** The rows of one `ctx.storage.sql.exec` call. */
4
+ interface DoSqlCursor {
5
+ toArray(): Record<string, unknown>[];
6
+ }
7
+ /** The part of a Durable Object's `ctx.storage` this driver uses; `ctx.storage` fits it as is. */
8
+ interface DoSqlStorage {
9
+ sql: {
10
+ exec(query: string, ...bindings: unknown[]): DoSqlCursor;
11
+ };
12
+ transaction<T>(closure: () => Promise<T>): Promise<T>;
13
+ }
14
+ /**
15
+ * A {@link Db} over a Durable Object's SQLite storage (`ctx.storage`). Transactions go through
16
+ * `storage.transaction`, since DO SQLite rejects `BEGIN`. Create one per DO, in its constructor.
17
+ */
18
+ declare function newDoSqliteDb(storage: DoSqlStorage): Db;
19
+ //#endregion
20
+ export { DoSqlStorage as n, newDoSqliteDb as r, DoSqlCursor as t };
21
+ //# sourceMappingURL=do-sqlite-db-nKIypUic.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"do-sqlite-db-nKIypUic.d.mts","names":[],"sources":["../src/do-sqlite-db.ts"],"mappings":";;;UAIiB;EACf,WAAW;;;UAII;EACf;IAAO,KAAK,kBAAkB,sBAAsB;;EACpD,YAAY,GAAG,eAAe,QAAQ,KAAK,QAAQ;;;;;;iBAsBrC,cAAc,SAAS,eAAe"}
@@ -0,0 +1,15 @@
1
+ import { n as DoSqlStorage } from "./do-sqlite-db-nKIypUic.mjs";
2
+ //#region src/fake-do-storage.d.ts
3
+ type FakeDoStorage = DoSqlStorage & {
4
+ close(): void;
5
+ };
6
+ /**
7
+ * An in-memory stand-in for a Durable Object's `ctx.storage` on Node.js's `node:sqlite`, with the
8
+ * DO limits: no SQL-level transactions or PRAGMA, at most 100 bound parameters, BLOBs bound and
9
+ * read as ArrayBuffer, and bound strings (UTF-8 bytes) and BLOBs at most ~2 MB. `transaction` runs the closure between BEGIN and
10
+ * COMMIT/ROLLBACK and, like the platform, does not queue concurrent calls.
11
+ */
12
+ export declare function newFakeDoStorage(): FakeDoStorage;
13
+ //#endregion
14
+ export type { FakeDoStorage };
15
+ //# sourceMappingURL=fake.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fake.d.mts","names":[],"sources":["../src/fake-do-storage.ts"],"mappings":";;KAGY,gBAAgB;EAAiB;;;;;;;;wBAmB7B,oBAAoB"}
package/dist/fake.mjs ADDED
@@ -0,0 +1,59 @@
1
+ import { DatabaseSync } from "node:sqlite";
2
+ //#region src/fake-do-storage.ts
3
+ /**
4
+ * An empty view over a real buffer. node:sqlite (Node 22) binds a view whose buffer has no backing
5
+ * store, such as `new Uint8Array(new ArrayBuffer(0))`, as NULL; the platform stores an empty BLOB.
6
+ */
7
+ const EMPTY_BLOB = (/* @__PURE__ */ new Uint8Array(1)).subarray(0, 0);
8
+ /** Limits probed on celld's DO SQLite (see test-do/platform-probe.ts). */
9
+ const MAX_BOUND_PARAMETERS = 100;
10
+ const MAX_VALUE_BYTES = 2e6;
11
+ const NOT_AUTHORIZED = /^\s*(BEGIN|COMMIT|END|ROLLBACK|SAVEPOINT|RELEASE|PRAGMA)\b/i;
12
+ /**
13
+ * An in-memory stand-in for a Durable Object's `ctx.storage` on Node.js's `node:sqlite`, with the
14
+ * DO limits: no SQL-level transactions or PRAGMA, at most 100 bound parameters, BLOBs bound and
15
+ * read as ArrayBuffer, and bound strings (UTF-8 bytes) and BLOBs at most ~2 MB. `transaction` runs the closure between BEGIN and
16
+ * COMMIT/ROLLBACK and, like the platform, does not queue concurrent calls.
17
+ */
18
+ function newFakeDoStorage() {
19
+ const db = new DatabaseSync(":memory:");
20
+ const bind = (value) => {
21
+ if (ArrayBuffer.isView(value)) throw new TypeError("fake DO storage: bind a BLOB as an ArrayBuffer, not a typed array");
22
+ const tooBig = () => /* @__PURE__ */ new Error("SQL error: bind sync KV cursor: string or blob too big");
23
+ if (typeof value === "string" && Buffer.byteLength(value) > MAX_VALUE_BYTES) throw tooBig();
24
+ if (value instanceof ArrayBuffer) {
25
+ if (value.byteLength > MAX_VALUE_BYTES) throw tooBig();
26
+ return value.byteLength === 0 ? EMPTY_BLOB : new Uint8Array(value);
27
+ }
28
+ return value;
29
+ };
30
+ return {
31
+ sql: { exec(query, ...bindings) {
32
+ if (NOT_AUTHORIZED.test(query)) throw new Error("SQL error: prepare SQL cursor: not authorized");
33
+ if (bindings.length > MAX_BOUND_PARAMETERS) throw new Error("SQL error: prepare SQL cursor: too many SQL variables");
34
+ const statement = db.prepare(query);
35
+ let rows = [];
36
+ if (bindings.length === 0 && statement.columns().length === 0) db.exec(query);
37
+ else rows = statement.all(...bindings.map(bind));
38
+ const out = rows.map((row) => Object.fromEntries(Object.entries(row).map(([key, value]) => [key, value instanceof Uint8Array ? value.slice().buffer : value])));
39
+ return { toArray: () => out };
40
+ } },
41
+ async transaction(closure) {
42
+ db.exec("BEGIN");
43
+ try {
44
+ const result = await closure();
45
+ db.exec("COMMIT");
46
+ return result;
47
+ } catch (error) {
48
+ if (!db.isTransaction) throw new Error("a transaction rollback failed: cannot rollback - no transaction is active");
49
+ db.exec("ROLLBACK");
50
+ throw error;
51
+ }
52
+ },
53
+ close: () => db.close()
54
+ };
55
+ }
56
+ //#endregion
57
+ export { newFakeDoStorage };
58
+
59
+ //# sourceMappingURL=fake.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fake.mjs","names":[],"sources":["../src/fake-do-storage.ts"],"sourcesContent":["import { DatabaseSync, type SQLInputValue } from \"node:sqlite\";\nimport type { DoSqlStorage } from \"./do-sqlite-db.js\";\n\nexport type FakeDoStorage = DoSqlStorage & { close(): void };\n\n/**\n * An empty view over a real buffer. node:sqlite (Node 22) binds a view whose buffer has no backing\n * store, such as `new Uint8Array(new ArrayBuffer(0))`, as NULL; the platform stores an empty BLOB.\n */\nconst EMPTY_BLOB = new Uint8Array(1).subarray(0, 0);\n\n/** Limits probed on celld's DO SQLite (see test-do/platform-probe.ts). */\nconst MAX_BOUND_PARAMETERS = 100;\nconst MAX_VALUE_BYTES = 2_000_000;\nconst NOT_AUTHORIZED = /^\\s*(BEGIN|COMMIT|END|ROLLBACK|SAVEPOINT|RELEASE|PRAGMA)\\b/i;\n\n/**\n * An in-memory stand-in for a Durable Object's `ctx.storage` on Node.js's `node:sqlite`, with the\n * DO limits: no SQL-level transactions or PRAGMA, at most 100 bound parameters, BLOBs bound and\n * read as ArrayBuffer, and bound strings (UTF-8 bytes) and BLOBs at most ~2 MB. `transaction` runs the closure between BEGIN and\n * COMMIT/ROLLBACK and, like the platform, does not queue concurrent calls.\n */\nexport function newFakeDoStorage(): FakeDoStorage {\n const db = new DatabaseSync(\":memory:\");\n const bind = (value: unknown): SQLInputValue => {\n if (ArrayBuffer.isView(value)) {\n throw new TypeError(\"fake DO storage: bind a BLOB as an ArrayBuffer, not a typed array\");\n }\n const tooBig = () => new Error(\"SQL error: bind sync KV cursor: string or blob too big\");\n if (typeof value === \"string\" && Buffer.byteLength(value) > MAX_VALUE_BYTES) throw tooBig();\n if (value instanceof ArrayBuffer) {\n if (value.byteLength > MAX_VALUE_BYTES) throw tooBig();\n return value.byteLength === 0 ? EMPTY_BLOB : new Uint8Array(value);\n }\n return value as SQLInputValue;\n };\n return {\n sql: {\n exec(query: string, ...bindings: unknown[]) {\n if (NOT_AUTHORIZED.test(query))\n throw new Error(\"SQL error: prepare SQL cursor: not authorized\");\n if (bindings.length > MAX_BOUND_PARAMETERS) {\n throw new Error(\"SQL error: prepare SQL cursor: too many SQL variables\");\n }\n const statement = db.prepare(query);\n let rows: Record<string, unknown>[] = [];\n // prepare() compiles only the first statement: run row-less, parameter-less text with exec().\n if (bindings.length === 0 && statement.columns().length === 0) db.exec(query);\n else rows = statement.all(...bindings.map(bind)) as Record<string, unknown>[];\n const out = rows.map((row) =>\n Object.fromEntries(\n Object.entries(row).map(([key, value]) => [\n key,\n value instanceof Uint8Array ? value.slice().buffer : value,\n ]),\n ),\n );\n return { toArray: () => out };\n },\n },\n async transaction<T>(closure: () => Promise<T>): Promise<T> {\n db.exec(\"BEGIN\");\n try {\n const result = await closure();\n db.exec(\"COMMIT\");\n return result;\n } catch (error) {\n // Like the platform: when SQLite already ended the transaction (ON CONFLICT ROLLBACK), the\n // rollback fails and its error replaces the callback's.\n if (!db.isTransaction) {\n throw new Error(\n \"a transaction rollback failed: cannot rollback - no transaction is active\",\n );\n }\n db.exec(\"ROLLBACK\");\n throw error;\n }\n },\n close: () => db.close(),\n };\n}\n"],"mappings":";;;;;;AASA,MAAM,8BAAa,IAAI,WAAW,CAAC,EAAA,CAAE,SAAS,GAAG,CAAC;;AAGlD,MAAM,uBAAuB;AAC7B,MAAM,kBAAkB;AACxB,MAAM,iBAAiB;;;;;;;AAQvB,SAAgB,mBAAkC;CAChD,MAAM,KAAK,IAAI,aAAa,UAAU;CACtC,MAAM,QAAQ,UAAkC;EAC9C,IAAI,YAAY,OAAO,KAAK,GAC1B,MAAM,IAAI,UAAU,mEAAmE;EAEzF,MAAM,+BAAe,IAAI,MAAM,wDAAwD;EACvF,IAAI,OAAO,UAAU,YAAY,OAAO,WAAW,KAAK,IAAI,iBAAiB,MAAM,OAAO;EAC1F,IAAI,iBAAiB,aAAa;GAChC,IAAI,MAAM,aAAa,iBAAiB,MAAM,OAAO;GACrD,OAAO,MAAM,eAAe,IAAI,aAAa,IAAI,WAAW,KAAK;EACnE;EACA,OAAO;CACT;CACA,OAAO;EACL,KAAK,EACH,KAAK,OAAe,GAAG,UAAqB;GAC1C,IAAI,eAAe,KAAK,KAAK,GAC3B,MAAM,IAAI,MAAM,+CAA+C;GACjE,IAAI,SAAS,SAAS,sBACpB,MAAM,IAAI,MAAM,uDAAuD;GAEzE,MAAM,YAAY,GAAG,QAAQ,KAAK;GAClC,IAAI,OAAkC,CAAC;GAEvC,IAAI,SAAS,WAAW,KAAK,UAAU,QAAQ,CAAC,CAAC,WAAW,GAAG,GAAG,KAAK,KAAK;QACvE,OAAO,UAAU,IAAI,GAAG,SAAS,IAAI,IAAI,CAAC;GAC/C,MAAM,MAAM,KAAK,KAAK,QACpB,OAAO,YACL,OAAO,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CACxC,KACA,iBAAiB,aAAa,MAAM,MAAM,CAAC,CAAC,SAAS,KACvD,CAAC,CACH,CACF;GACA,OAAO,EAAE,eAAe,IAAI;EAC9B,EACF;EACA,MAAM,YAAe,SAAuC;GAC1D,GAAG,KAAK,OAAO;GACf,IAAI;IACF,MAAM,SAAS,MAAM,QAAQ;IAC7B,GAAG,KAAK,QAAQ;IAChB,OAAO;GACT,SAAS,OAAO;IAGd,IAAI,CAAC,GAAG,eACN,MAAM,IAAI,MACR,2EACF;IAEF,GAAG,KAAK,UAAU;IAClB,MAAM;GACR;EACF;EACA,aAAa,GAAG,MAAM;CACxB;AACF"}
@@ -0,0 +1,3 @@
1
+ import { n as DoSqlStorage, r as newDoSqliteDb, t as DoSqlCursor } from "./do-sqlite-db-nKIypUic.mjs";
2
+ import { Db, DbEntry } from "@statewalker/db-api";
3
+ export { type Db, type DbEntry, type DoSqlCursor, type DoSqlStorage, newDoSqliteDb };
package/dist/index.mjs ADDED
@@ -0,0 +1,24 @@
1
+ import { newSerialisedSqliteDb } from "@statewalker/db-sqlite";
2
+ //#region src/do-sqlite-db.ts
3
+ /** DO SQLite binds BLOBs from ArrayBuffer; copy exactly the view's bytes. */
4
+ const toDoValue = (value) => ArrayBuffer.isView(value) ? value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength) : value;
5
+ /** DO SQLite reads BLOBs back as ArrayBuffer; every SQLite Db returns Uint8Array. */
6
+ const fromDoRow = (row) => Object.fromEntries(Object.entries(row).map(([key, value]) => [key, value instanceof ArrayBuffer ? new Uint8Array(value) : value]));
7
+ /**
8
+ * A {@link Db} over a Durable Object's SQLite storage (`ctx.storage`). Transactions go through
9
+ * `storage.transaction`, since DO SQLite rejects `BEGIN`. Create one per DO, in its constructor.
10
+ */
11
+ function newDoSqliteDb(storage) {
12
+ return newSerialisedSqliteDb({
13
+ all: (sql, params) => storage.sql.exec(sql, ...params.map(toDoValue)).toArray().map(fromDoRow),
14
+ exec: (sql) => {
15
+ storage.sql.exec(sql).toArray();
16
+ },
17
+ close: () => {},
18
+ transaction: (fn) => storage.transaction(fn)
19
+ });
20
+ }
21
+ //#endregion
22
+ export { newDoSqliteDb };
23
+
24
+ //# sourceMappingURL=index.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.mjs","names":[],"sources":["../src/do-sqlite-db.ts"],"sourcesContent":["import type { Db } from \"@statewalker/db-api\";\nimport { newSerialisedSqliteDb } from \"@statewalker/db-sqlite\";\n\n/** The rows of one `ctx.storage.sql.exec` call. */\nexport interface DoSqlCursor {\n toArray(): Record<string, unknown>[];\n}\n\n/** The part of a Durable Object's `ctx.storage` this driver uses; `ctx.storage` fits it as is. */\nexport interface DoSqlStorage {\n sql: { exec(query: string, ...bindings: unknown[]): DoSqlCursor };\n transaction<T>(closure: () => Promise<T>): Promise<T>;\n}\n\n/** DO SQLite binds BLOBs from ArrayBuffer; copy exactly the view's bytes. */\nconst toDoValue = (value: unknown): unknown =>\n ArrayBuffer.isView(value)\n ? value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength)\n : value;\n\n/** DO SQLite reads BLOBs back as ArrayBuffer; every SQLite Db returns Uint8Array. */\nconst fromDoRow = (row: Record<string, unknown>): Record<string, unknown> =>\n Object.fromEntries(\n Object.entries(row).map(([key, value]) => [\n key,\n value instanceof ArrayBuffer ? new Uint8Array(value) : value,\n ]),\n );\n\n/**\n * A {@link Db} over a Durable Object's SQLite storage (`ctx.storage`). Transactions go through\n * `storage.transaction`, since DO SQLite rejects `BEGIN`. Create one per DO, in its constructor.\n */\nexport function newDoSqliteDb(storage: DoSqlStorage): Db {\n return newSerialisedSqliteDb({\n all: (sql, params) =>\n storage.sql\n .exec(sql, ...params.map(toDoValue))\n .toArray()\n .map(fromDoRow),\n exec: (sql) => {\n storage.sql.exec(sql).toArray();\n },\n close: () => {},\n transaction: (fn) => storage.transaction(fn),\n });\n}\n"],"mappings":";;;AAeA,MAAM,aAAa,UACjB,YAAY,OAAO,KAAK,IACpB,MAAM,OAAO,MAAM,MAAM,YAAY,MAAM,aAAa,MAAM,UAAU,IACxE;;AAGN,MAAM,aAAa,QACjB,OAAO,YACL,OAAO,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,KAAK,WAAW,CACxC,KACA,iBAAiB,cAAc,IAAI,WAAW,KAAK,IAAI,KACzD,CAAC,CACH;;;;;AAMF,SAAgB,cAAc,SAA2B;CACvD,OAAO,sBAAsB;EAC3B,MAAM,KAAK,WACT,QAAQ,IACL,KAAK,KAAK,GAAG,OAAO,IAAI,SAAS,CAAC,CAAC,CACnC,QAAQ,CAAC,CACT,IAAI,SAAS;EAClB,OAAO,QAAQ;GACb,QAAQ,IAAI,KAAK,GAAG,CAAC,CAAC,QAAQ;EAChC;EACA,aAAa,CAAC;EACd,cAAc,OAAO,QAAQ,YAAY,EAAE;CAC7C,CAAC;AACH"}
package/package.json CHANGED
@@ -1,6 +1,66 @@
1
1
  {
2
2
  "name": "@statewalker/db-sqlite-do",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.1",
4
+ "private": false,
5
+ "type": "module",
6
+ "description": "Durable Object SQLite (ctx.storage) driver for @statewalker/db-api, with transactions through @statewalker/db-sqlite and a node:sqlite fake for tests.",
7
+ "bugs": {
8
+ "url": "https://github.com/statewalker/statewalker-db/issues"
9
+ },
10
+ "homepage": "https://github.com/statewalker/statewalker-db/tree/main/packages/db-sqlite-do#readme",
11
+ "author": {
12
+ "name": "Mikhail Kotelnikov",
13
+ "email": "mikhail.kotelnikov@gmail.com"
14
+ },
15
+ "license": "MIT",
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/statewalker/statewalker-db.git",
19
+ "directory": "packages/db-sqlite-do"
20
+ },
21
+ "exports": {
22
+ ".": {
23
+ "source": "./src/index.ts",
24
+ "types": "./dist/index.d.mts",
25
+ "import": "./dist/index.mjs"
26
+ },
27
+ "./fake": {
28
+ "source": "./src/fake.ts",
29
+ "types": "./dist/fake.d.mts",
30
+ "import": "./dist/fake.mjs"
31
+ }
32
+ },
33
+ "files": [
34
+ "dist",
35
+ "src"
36
+ ],
37
+ "dependencies": {
38
+ "@statewalker/db-api": "^0.1.5",
39
+ "@statewalker/db-sqlite": "^0.1.1"
40
+ },
41
+ "devDependencies": {
42
+ "@types/node": "^26.6.4",
43
+ "rimraf": "^6.1.3",
44
+ "tsdown": "^0.23.0",
45
+ "typescript": "^7.0.2",
46
+ "vitest": "^4.1.10 || ^5.0.3",
47
+ "@statewalker/db-tests": "^0.1.1"
48
+ },
49
+ "engines": {
50
+ "node": ">=22.13"
51
+ },
52
+ "sideEffects": false,
53
+ "publishConfig": {
54
+ "access": "public"
55
+ },
56
+ "scripts": {
57
+ "build": "tsdown",
58
+ "dev": "tsdown --watch",
59
+ "test": "vitest run",
60
+ "test:do": "vitest run --config vitest.do.config.ts",
61
+ "typecheck": "tsc --noEmit",
62
+ "clean": "rimraf dist",
63
+ "lint": "biome check --write .",
64
+ "format": "biome format --write ."
65
+ }
6
66
  }
@@ -0,0 +1,79 @@
1
+ import { inTransaction } from "@statewalker/db-sqlite";
2
+ import { runDbConformance, runSqliteTransactionConformance } from "@statewalker/db-tests";
3
+ import { describe, expect, it } from "vitest";
4
+ import { PROBE_EXPECTATIONS, probeDoSqlite } from "../test-do/platform-probe.js";
5
+ import { DO_UNSUPPORTED_SCENARIOS } from "../test-do/unsupported-scenarios.js";
6
+ import { newDoSqliteDb } from "./do-sqlite-db.js";
7
+ import { newFakeDoStorage } from "./fake-do-storage.js";
8
+
9
+ // Same suites as every other SQLite driver, on the node:sqlite fake of ctx.storage.
10
+ runDbConformance(async () => newDoSqliteDb(newFakeDoStorage()), {
11
+ placeholder: "?",
12
+ skipFilePersistence: true,
13
+ });
14
+ runSqliteTransactionConformance(async () => newDoSqliteDb(newFakeDoStorage()), {
15
+ skip: DO_UNSUPPORTED_SCENARIOS,
16
+ });
17
+
18
+ describe("newDoSqliteDb", () => {
19
+ it("fails the transaction with the platform's rollback error when SQLite already rolled back", async () => {
20
+ const db = newDoSqliteDb(newFakeDoStorage());
21
+ await db.exec("CREATE TABLE u (k TEXT UNIQUE ON CONFLICT ROLLBACK)");
22
+ await db.exec("INSERT INTO u VALUES ('a')");
23
+ await expect(
24
+ inTransaction(db, async (tx) => {
25
+ await tx.query("INSERT INTO u VALUES ('b')");
26
+ await tx.query("INSERT INTO u VALUES ('a')");
27
+ }),
28
+ ).rejects.toThrow(/no transaction is active/);
29
+ expect(await db.query("SELECT k FROM u")).toEqual([{ k: "a" }]);
30
+ await db.close();
31
+ });
32
+ });
33
+
34
+ describe("newFakeDoStorage", () => {
35
+ // The same probe runs on real DO SQLite in `test:do`; both must meet the same expectations.
36
+ it("matches the probed Durable Object SQLite behaviour", () => {
37
+ const storage = newFakeDoStorage();
38
+ try {
39
+ const result = probeDoSqlite(storage);
40
+ for (const [name, want] of Object.entries(PROBE_EXPECTATIONS)) {
41
+ if (want === "ok") expect(result[name], name).toBe("ok");
42
+ else expect(result[name], name).toMatch(want);
43
+ }
44
+ } finally {
45
+ storage.close();
46
+ }
47
+ });
48
+
49
+ it("stores an empty BLOB as a BLOB through the driver (not NULL, on any Node)", async () => {
50
+ const db = newDoSqliteDb(newFakeDoStorage());
51
+ await db.exec("CREATE TABLE e (k INTEGER PRIMARY KEY, d BLOB)");
52
+ await db.query("INSERT INTO e VALUES (1, ?), (2, ?)", [
53
+ new Uint8Array(0),
54
+ new Uint8Array(new ArrayBuffer(0)),
55
+ ]);
56
+ expect(await db.query("SELECT typeof(d) AS t, length(d) AS n FROM e ORDER BY k")).toEqual([
57
+ { t: "blob", n: 0 },
58
+ { t: "blob", n: 0 },
59
+ ]);
60
+ const back = await db.query<{ d: unknown }>("SELECT d FROM e ORDER BY k");
61
+ for (const { d } of back) {
62
+ expect(d).toBeInstanceOf(Uint8Array);
63
+ expect((d as Uint8Array).byteLength).toBe(0);
64
+ }
65
+ await db.close();
66
+ });
67
+
68
+ it("rejects a typed array bound as a BLOB, as the driver must pass an ArrayBuffer", () => {
69
+ const storage = newFakeDoStorage();
70
+ try {
71
+ storage.sql.exec("CREATE TABLE b (d BLOB)");
72
+ expect(() => storage.sql.exec("INSERT INTO b VALUES (?)", new Uint8Array([1]))).toThrow(
73
+ /ArrayBuffer/,
74
+ );
75
+ } finally {
76
+ storage.close();
77
+ }
78
+ });
79
+ });
@@ -0,0 +1,47 @@
1
+ import type { Db } from "@statewalker/db-api";
2
+ import { newSerialisedSqliteDb } from "@statewalker/db-sqlite";
3
+
4
+ /** The rows of one `ctx.storage.sql.exec` call. */
5
+ export interface DoSqlCursor {
6
+ toArray(): Record<string, unknown>[];
7
+ }
8
+
9
+ /** The part of a Durable Object's `ctx.storage` this driver uses; `ctx.storage` fits it as is. */
10
+ export interface DoSqlStorage {
11
+ sql: { exec(query: string, ...bindings: unknown[]): DoSqlCursor };
12
+ transaction<T>(closure: () => Promise<T>): Promise<T>;
13
+ }
14
+
15
+ /** DO SQLite binds BLOBs from ArrayBuffer; copy exactly the view's bytes. */
16
+ const toDoValue = (value: unknown): unknown =>
17
+ ArrayBuffer.isView(value)
18
+ ? value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength)
19
+ : value;
20
+
21
+ /** DO SQLite reads BLOBs back as ArrayBuffer; every SQLite Db returns Uint8Array. */
22
+ const fromDoRow = (row: Record<string, unknown>): Record<string, unknown> =>
23
+ Object.fromEntries(
24
+ Object.entries(row).map(([key, value]) => [
25
+ key,
26
+ value instanceof ArrayBuffer ? new Uint8Array(value) : value,
27
+ ]),
28
+ );
29
+
30
+ /**
31
+ * A {@link Db} over a Durable Object's SQLite storage (`ctx.storage`). Transactions go through
32
+ * `storage.transaction`, since DO SQLite rejects `BEGIN`. Create one per DO, in its constructor.
33
+ */
34
+ export function newDoSqliteDb(storage: DoSqlStorage): Db {
35
+ return newSerialisedSqliteDb({
36
+ all: (sql, params) =>
37
+ storage.sql
38
+ .exec(sql, ...params.map(toDoValue))
39
+ .toArray()
40
+ .map(fromDoRow),
41
+ exec: (sql) => {
42
+ storage.sql.exec(sql).toArray();
43
+ },
44
+ close: () => {},
45
+ transaction: (fn) => storage.transaction(fn),
46
+ });
47
+ }
@@ -0,0 +1,81 @@
1
+ import { DatabaseSync, type SQLInputValue } from "node:sqlite";
2
+ import type { DoSqlStorage } from "./do-sqlite-db.js";
3
+
4
+ export type FakeDoStorage = DoSqlStorage & { close(): void };
5
+
6
+ /**
7
+ * An empty view over a real buffer. node:sqlite (Node 22) binds a view whose buffer has no backing
8
+ * store, such as `new Uint8Array(new ArrayBuffer(0))`, as NULL; the platform stores an empty BLOB.
9
+ */
10
+ const EMPTY_BLOB = new Uint8Array(1).subarray(0, 0);
11
+
12
+ /** Limits probed on celld's DO SQLite (see test-do/platform-probe.ts). */
13
+ const MAX_BOUND_PARAMETERS = 100;
14
+ const MAX_VALUE_BYTES = 2_000_000;
15
+ const NOT_AUTHORIZED = /^\s*(BEGIN|COMMIT|END|ROLLBACK|SAVEPOINT|RELEASE|PRAGMA)\b/i;
16
+
17
+ /**
18
+ * An in-memory stand-in for a Durable Object's `ctx.storage` on Node.js's `node:sqlite`, with the
19
+ * DO limits: no SQL-level transactions or PRAGMA, at most 100 bound parameters, BLOBs bound and
20
+ * read as ArrayBuffer, and bound strings (UTF-8 bytes) and BLOBs at most ~2 MB. `transaction` runs the closure between BEGIN and
21
+ * COMMIT/ROLLBACK and, like the platform, does not queue concurrent calls.
22
+ */
23
+ export function newFakeDoStorage(): FakeDoStorage {
24
+ const db = new DatabaseSync(":memory:");
25
+ const bind = (value: unknown): SQLInputValue => {
26
+ if (ArrayBuffer.isView(value)) {
27
+ throw new TypeError("fake DO storage: bind a BLOB as an ArrayBuffer, not a typed array");
28
+ }
29
+ const tooBig = () => new Error("SQL error: bind sync KV cursor: string or blob too big");
30
+ if (typeof value === "string" && Buffer.byteLength(value) > MAX_VALUE_BYTES) throw tooBig();
31
+ if (value instanceof ArrayBuffer) {
32
+ if (value.byteLength > MAX_VALUE_BYTES) throw tooBig();
33
+ return value.byteLength === 0 ? EMPTY_BLOB : new Uint8Array(value);
34
+ }
35
+ return value as SQLInputValue;
36
+ };
37
+ return {
38
+ sql: {
39
+ exec(query: string, ...bindings: unknown[]) {
40
+ if (NOT_AUTHORIZED.test(query))
41
+ throw new Error("SQL error: prepare SQL cursor: not authorized");
42
+ if (bindings.length > MAX_BOUND_PARAMETERS) {
43
+ throw new Error("SQL error: prepare SQL cursor: too many SQL variables");
44
+ }
45
+ const statement = db.prepare(query);
46
+ let rows: Record<string, unknown>[] = [];
47
+ // prepare() compiles only the first statement: run row-less, parameter-less text with exec().
48
+ if (bindings.length === 0 && statement.columns().length === 0) db.exec(query);
49
+ else rows = statement.all(...bindings.map(bind)) as Record<string, unknown>[];
50
+ const out = rows.map((row) =>
51
+ Object.fromEntries(
52
+ Object.entries(row).map(([key, value]) => [
53
+ key,
54
+ value instanceof Uint8Array ? value.slice().buffer : value,
55
+ ]),
56
+ ),
57
+ );
58
+ return { toArray: () => out };
59
+ },
60
+ },
61
+ async transaction<T>(closure: () => Promise<T>): Promise<T> {
62
+ db.exec("BEGIN");
63
+ try {
64
+ const result = await closure();
65
+ db.exec("COMMIT");
66
+ return result;
67
+ } catch (error) {
68
+ // Like the platform: when SQLite already ended the transaction (ON CONFLICT ROLLBACK), the
69
+ // rollback fails and its error replaces the callback's.
70
+ if (!db.isTransaction) {
71
+ throw new Error(
72
+ "a transaction rollback failed: cannot rollback - no transaction is active",
73
+ );
74
+ }
75
+ db.exec("ROLLBACK");
76
+ throw error;
77
+ }
78
+ },
79
+ close: () => db.close(),
80
+ };
81
+ }
package/src/fake.ts ADDED
@@ -0,0 +1 @@
1
+ export { type FakeDoStorage, newFakeDoStorage } from "./fake-do-storage.js";
package/src/index.ts ADDED
@@ -0,0 +1,2 @@
1
+ export type { Db, DbEntry } from "@statewalker/db-api";
2
+ export { type DoSqlCursor, type DoSqlStorage, newDoSqliteDb } from "./do-sqlite-db.js";