@statewalker/db-sqlite 0.1.2 → 0.1.4
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/README.md +58 -6
- package/dist/index.d.mts +52 -9
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +278 -75
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -3
- package/src/index.ts +7 -0
- package/src/serialised-db.ts +95 -0
- package/src/serialised-sqlite-db.ts +186 -83
- package/src/sql-statements.ts +96 -13
- package/src/sqlite-transaction.ts +39 -0
package/README.md
CHANGED
|
@@ -4,8 +4,11 @@
|
|
|
4
4
|
|
|
5
5
|
Transactions for SQLite databases behind `Db` from `@statewalker/db-api`:
|
|
6
6
|
`inTransaction(db, cb)` runs `cb` so that every statement issued through its `tx` handle commits
|
|
7
|
-
together or not at all
|
|
8
|
-
|
|
7
|
+
together or not at all; `inReadOnlyTransaction(db, cb)` runs it in a transaction that is always
|
|
8
|
+
rolled back, so nothing it writes persists. It also holds `newSerialisedSqliteDb`, the wrapper every SQLite driver
|
|
9
|
+
(`db-sqlite-node`, `db-sqlite-browser`, `db-sqlite-do`) builds its `Db` with, and
|
|
10
|
+
`newSerialisedDb`, the engine-neutral lifecycle wrapper the DuckDB and PGlite drivers use. Both
|
|
11
|
+
keep the lifecycle that the `Db` JSDoc in `@statewalker/db-api` promises.
|
|
9
12
|
|
|
10
13
|
## Why it exists
|
|
11
14
|
|
|
@@ -22,12 +25,48 @@ pnpm add @statewalker/db-sqlite
|
|
|
22
25
|
|
|
23
26
|
| Import | Gives | Environment |
|
|
24
27
|
| --- | --- | --- |
|
|
25
|
-
| `@statewalker/db-sqlite` | `inTransaction`, `newSerialisedSqliteDb`, `SQLITE_TRANSACTION`; types `SqliteEngine`, `SqliteTransactionHook` | any |
|
|
28
|
+
| `@statewalker/db-sqlite` | `inTransaction`, `inReadOnlyTransaction`, `hasReadOnlyTransaction`, `newSerialisedDb`, `newSerialisedSqliteDb`, `SQLITE_TRANSACTION`, `SQLITE_READ_ONLY_TRANSACTION`; types `SerialisedDbEngine`, `SqliteEngine`, `SqliteTransactionHook` | any |
|
|
29
|
+
|
|
30
|
+
`newSerialisedDb(engine, { name })` wraps an asynchronous `SerialisedDbEngine` (`query(sql,
|
|
31
|
+
params)`, `exec(sql)`, optional `flush()`, `close()`) as a `Db`: calls run one at a time in call
|
|
32
|
+
order; `close()` waits for the calls made before it, then closes the engine once; a call made once
|
|
33
|
+
`close()` has started rejects with `<name>: the database is closed`; a second `close()` is a
|
|
34
|
+
no-op; integers in rows come back as numbers within ±(2^53 - 1) and as bigints beyond, also
|
|
35
|
+
inside arrays and plain objects. It lives here, not in `@statewalker/db-api`, because that
|
|
36
|
+
package is types-only; it has no SQLite code in it, so a DuckDB or PGlite driver depends on this
|
|
37
|
+
package without pulling in any engine.
|
|
26
38
|
|
|
27
39
|
`inTransaction(db, cb)` returns what `cb` returns. If `cb` throws, everything it wrote is rolled
|
|
28
40
|
back and the same error is rethrown; so is a failing `COMMIT` (a deferred foreign key, for
|
|
29
41
|
example), which rejects with SQLite's error. While it runs, other calls on `db` wait for it.
|
|
30
42
|
|
|
43
|
+
`inReadOnlyTransaction(db, cb)` returns what `cb` returns, or rethrows its error, and in both
|
|
44
|
+
cases rolls back everything it wrote: `tx` sees the committed data and its own writes, and none
|
|
45
|
+
of them persist. It is what a reader gets the full SQL surface through without the risk
|
|
46
|
+
(`@statewalker/db-rpc`'s read-only server uses it for every call). Two rules keep a statement from
|
|
47
|
+
slipping out of the transaction:
|
|
48
|
+
- SQL that would end the transaction or reach outside it is refused before it runs, on `query`
|
|
49
|
+
and `exec` alike: a statement starting with BEGIN, COMMIT, END, ROLLBACK, SAVEPOINT, RELEASE,
|
|
50
|
+
ATTACH, DETACH, PRAGMA or VACUUM rejects with
|
|
51
|
+
`db-sqlite: a read-only transaction refuses COMMIT (it would end the transaction or reach outside it)`.
|
|
52
|
+
Statements are split as SQLite splits them, so the words inside literals, comments and trigger
|
|
53
|
+
bodies do not count. A statement that does not start with a word (such as `(SELECT 1)`) is
|
|
54
|
+
refused too, so that a separator SQLite skips and the splitter might not can never hide the
|
|
55
|
+
word that starts it. The splitter follows SQLite's tokenizer where it matters: whitespace
|
|
56
|
+
includes `\v`, and a Tcl-style variable (`$a(…)`, `:a(…)`, `@a(…)`, `#a(…)`) runs to the first
|
|
57
|
+
`)` or whitespace, quotes included.
|
|
58
|
+
- `exec` inside it runs one statement per engine call, each through the engine's `all`. On
|
|
59
|
+
Node.js, `all` compiles only the first statement of what it is given, so even text the splitter
|
|
60
|
+
misreads as part of a statement never runs as a statement of its own. The browser engine's
|
|
61
|
+
`all` runs every statement of its text, so there the splitter is the only guard; on a Durable
|
|
62
|
+
Object the platform itself refuses transaction control in SQL.
|
|
63
|
+
- Once a statement fails, `tx` refuses every later call, with
|
|
64
|
+
`db-sqlite: a statement of this read-only transaction failed, so it refuses later calls (SQLite may have ended the transaction)`:
|
|
65
|
+
SQLite ends a transaction itself on some errors (`INSERT OR ROLLBACK`, `RAISE(ROLLBACK)`), and
|
|
66
|
+
what ran after that would run, and persist, outside it.
|
|
67
|
+
|
|
68
|
+
`hasReadOnlyTransaction(db)` tells whether `db` carries the hook it needs.
|
|
69
|
+
|
|
31
70
|
Every SQLite driver handles input the same way, because the wrapper does it before the engine
|
|
32
71
|
sees the call (on the Db and on the `tx` handle alike):
|
|
33
72
|
|
|
@@ -39,10 +78,13 @@ sees the call (on the Db and on the `tx` handle alike):
|
|
|
39
78
|
| `undefined` parameter | binds `NULL` |
|
|
40
79
|
| `Date` parameter | binds its ISO 8601 UTC text, `date.toISOString()` (`"2026-01-02T03:04:05.006Z"`), which SQLite date functions read; an invalid Date rejects with `db-sqlite: parameter N is an invalid Date` |
|
|
41
80
|
| `bigint` parameter | binds as an integer |
|
|
81
|
+
| `null`, `number`, `string` parameter | binds as given (an integer-valued number as an integer, any other as a real) |
|
|
82
|
+
| `ArrayBuffer`, or any ArrayBuffer view (`Uint8Array`, `DataView`, `Float32Array`, …) parameter | binds a BLOB of exactly the view's bytes (`byteOffset` to `byteOffset + byteLength`) |
|
|
83
|
+
| any other parameter: a plain object, `Map`, array, function, symbol, boxed primitive (`new String(…)`) | rejects with a `TypeError`, `db-sqlite: parameter N has type <type>, which SQLite cannot bind; …`, and nothing runs. node:sqlite would otherwise read a leading object as named parameters and bind the rest one place to the left. SQLite has no array type: bind a list as JSON text, `JSON.stringify(ids)`, and read it with `json_each(?)` |
|
|
42
84
|
| integer in a result | a `number` within ±(2^53 - 1), a `bigint` beyond, so no value loses precision |
|
|
43
85
|
|
|
44
86
|
A trailing `;`, comments, and semicolons inside literals or a `CREATE TRIGGER … BEGIN … END` body
|
|
45
|
-
do not count as a second statement.
|
|
87
|
+
do not count as a second statement. Parameter indexes in messages count from 1.
|
|
46
88
|
|
|
47
89
|
## Examples
|
|
48
90
|
|
|
@@ -65,6 +107,14 @@ await db.close();
|
|
|
65
107
|
|
|
66
108
|
## Internals
|
|
67
109
|
|
|
110
|
+
- **Read-only rollback.** On Node.js and in the browser the transaction is `BEGIN` (deferred)
|
|
111
|
+
… `ROLLBACK`; a `ROLLBACK` failing with `no transaction is active` (SQLite already ended it) is
|
|
112
|
+
ignored, any other failure rejects. On a Durable Object, whose `storage.transaction` commits
|
|
113
|
+
when the closure returns, the closure throws a marker error after `cb` returns, so the platform
|
|
114
|
+
rolls back, and the marker is turned back into `cb`'s value. The read-only hook has its own key,
|
|
115
|
+
`Symbol.for("@statewalker/db-sqlite:read-only-transaction")`, so a Db built by an older
|
|
116
|
+
db-sqlite (which has only the committing hook) is refused, never committed:
|
|
117
|
+
`inReadOnlyTransaction: this Db has no SQLite read-only transaction hook. ...`.
|
|
68
118
|
- **The hook travels on the Db object.** `newSerialisedSqliteDb` stores the transaction function
|
|
69
119
|
under `Symbol.for("@statewalker/db-sqlite:transaction")`; `inTransaction` looks it up. A Db
|
|
70
120
|
without it rejects with
|
|
@@ -72,8 +122,10 @@ await db.close();
|
|
|
72
122
|
Db, for **an object that wraps a SQLite Db** (copying `query`/`exec`/`close` drops the hook —
|
|
73
123
|
pass the driver's Db, or a spread copy `{ ...db }`, which keeps symbol keys), and for the `tx`
|
|
74
124
|
handle itself: **nested transactions are not supported**.
|
|
75
|
-
- **One call at a time.** Every `query`, `exec`, `close` and transaction goes through one queue
|
|
76
|
-
in call order. A
|
|
125
|
+
- **One call at a time.** Every `query`, `exec`, `close` and transaction goes through one queue
|
|
126
|
+
(the one `newSerialisedDb` uses), in call order. A call made once `close()` has started rejects
|
|
127
|
+
at once with `db-sqlite: the database is closed`; `close()` itself waits for earlier calls,
|
|
128
|
+
and a second `close()` is a no-op. A plain `db.exec` issued while another flow's transaction is open waits; it never
|
|
77
129
|
joins that transaction, so a rollback cannot take it down. `close` waits for a running
|
|
78
130
|
transaction.
|
|
79
131
|
- **The `tx` handle expires.** After the callback settles, `tx.query` rejects with
|
package/dist/index.d.mts
CHANGED
|
@@ -1,11 +1,35 @@
|
|
|
1
1
|
import { Db } from "@statewalker/db-api";
|
|
2
|
+
//#region src/serialised-db.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* The asynchronous engine a driver wraps with {@link newSerialisedDb}. It is called one call at a
|
|
5
|
+
* time and never after `close`; `query` returns rows with integers as numbers or bigints (the
|
|
6
|
+
* wrapper turns safe bigints into numbers).
|
|
7
|
+
*/
|
|
8
|
+
type SerialisedDbEngine = {
|
|
9
|
+
query(sql: string, params: unknown[]): Promise<Record<string, unknown>[]>;
|
|
10
|
+
exec(sql: string): Promise<void>;
|
|
11
|
+
flush?(): Promise<void>;
|
|
12
|
+
close(): void | Promise<void>;
|
|
13
|
+
};
|
|
14
|
+
/**
|
|
15
|
+
* Wrap an engine as a `Db` that keeps the lifecycle every driver shares: calls run one at a time,
|
|
16
|
+
* in call order; `close()` waits for the calls made before it, then closes the engine; calls made
|
|
17
|
+
* once `close()` has started reject with `<name>: the database is closed`; closing twice is a
|
|
18
|
+
* no-op. Integers come back as numbers when safe and as bigints beyond (see
|
|
19
|
+
* {@link toSafeIntegers}). `name` prefixes the error, e.g. `"db-pglite"`.
|
|
20
|
+
*/
|
|
21
|
+
export declare function newSerialisedDb(engine: SerialisedDbEngine, options: {
|
|
22
|
+
name: string;
|
|
23
|
+
}): Db;
|
|
24
|
+
//#endregion
|
|
2
25
|
//#region src/serialised-sqlite-db.d.ts
|
|
3
26
|
/**
|
|
4
27
|
* The synchronous engine a SQLite driver wraps. `all` returns rows (BLOBs as Uint8Array; integers
|
|
5
28
|
* as numbers or bigints, which the wrapper turns into numbers when they are safe) and is given
|
|
6
|
-
* exactly one non-empty statement and parameters already normalised (
|
|
7
|
-
*
|
|
8
|
-
* `BEGIN IMMEDIATE`/`COMMIT`/`ROLLBACK` (Durable Objects
|
|
29
|
+
* exactly one non-empty statement and parameters already normalised and checked (only null,
|
|
30
|
+
* number, bigint, string and Uint8Array); `exec` runs every statement of a non-empty string.
|
|
31
|
+
* `transaction`, when present, replaces `BEGIN IMMEDIATE`/`COMMIT`/`ROLLBACK` (Durable Objects
|
|
32
|
+
* forbid them in SQL).
|
|
9
33
|
*/
|
|
10
34
|
type SqliteEngine = {
|
|
11
35
|
all(sql: string, params: unknown[]): Record<string, unknown>[];
|
|
@@ -14,17 +38,24 @@ type SqliteEngine = {
|
|
|
14
38
|
transaction?<T>(fn: () => Promise<T>): Promise<T>;
|
|
15
39
|
};
|
|
16
40
|
/**
|
|
17
|
-
* Wrap an engine as a `Db`
|
|
18
|
-
* `
|
|
19
|
-
* `
|
|
20
|
-
*
|
|
21
|
-
* (
|
|
41
|
+
* Wrap an engine as a `Db` with the lifecycle of `newSerialisedDb` (calls run one at a time, in
|
|
42
|
+
* call order; `close()` waits for earlier calls; later calls reject with
|
|
43
|
+
* `db-sqlite: the database is closed`; closing twice is a no-op) and the `inTransaction` hook.
|
|
44
|
+
* Every SQLite driver gets the same input handling here: empty SQL rejects, `query` rejects a
|
|
45
|
+
* second statement, parameters are normalised (one SQLite cannot bind rejects) and safe integers come back as numbers. The `tx`
|
|
46
|
+
* handed to a transaction callback bypasses the queue, has no hook (so nesting is rejected) and
|
|
47
|
+
* rejects once its transaction has finished.
|
|
22
48
|
*/
|
|
23
49
|
export declare function newSerialisedSqliteDb(engine: SqliteEngine): Db;
|
|
24
50
|
//#endregion
|
|
25
51
|
//#region src/sqlite-transaction.d.ts
|
|
26
52
|
/** Key under which a SQLite Db carries its transaction hook. Shared across bundles via Symbol.for. */
|
|
27
53
|
export declare const SQLITE_TRANSACTION: unique symbol;
|
|
54
|
+
/**
|
|
55
|
+
* Key under which a SQLite Db carries its read-only transaction hook (a separate key, so that a Db
|
|
56
|
+
* from an older db-sqlite, which has only the committing hook, is refused rather than committed).
|
|
57
|
+
*/
|
|
58
|
+
export declare const SQLITE_READ_ONLY_TRANSACTION: unique symbol;
|
|
28
59
|
/** Runs `cb` inside one transaction of the Db that carries it. */
|
|
29
60
|
type SqliteTransactionHook = <T>(cb: (tx: Db) => Promise<T>) => Promise<T>;
|
|
30
61
|
/**
|
|
@@ -33,6 +64,18 @@ type SqliteTransactionHook = <T>(cb: (tx: Db) => Promise<T>) => Promise<T>;
|
|
|
33
64
|
* external I/O and must be idempotent: a Durable Object may run it more than once.
|
|
34
65
|
*/
|
|
35
66
|
export declare function inTransaction<T>(db: Db, cb: (tx: Db) => Promise<T>): Promise<T>;
|
|
67
|
+
/**
|
|
68
|
+
* Run `cb` in one SQLite transaction that is always rolled back: `tx` sees the committed data and
|
|
69
|
+
* its own writes, and nothing it writes persists, whether `cb` returns (its value is returned) or
|
|
70
|
+
* throws (its error is rethrown). Statements that would end the transaction or reach outside it
|
|
71
|
+
* (BEGIN, COMMIT, END, ROLLBACK, SAVEPOINT, RELEASE, ATTACH, DETACH, PRAGMA, VACUUM) are refused,
|
|
72
|
+
* and once a statement fails, `tx` refuses every later call (SQLite may have ended the transaction
|
|
73
|
+
* itself, as `INSERT OR ROLLBACK` does). Other calls on `db` wait until it ends. `cb` must not do
|
|
74
|
+
* external I/O and must be idempotent: a Durable Object may run it more than once.
|
|
75
|
+
*/
|
|
76
|
+
export declare function inReadOnlyTransaction<T>(db: Db, cb: (tx: Db) => Promise<T>): Promise<T>;
|
|
77
|
+
/** Whether `db` carries the hook {@link inReadOnlyTransaction} needs. */
|
|
78
|
+
export declare function hasReadOnlyTransaction(db: Db): boolean;
|
|
36
79
|
//#endregion
|
|
37
|
-
export type { SqliteEngine, SqliteTransactionHook };
|
|
80
|
+
export type { SerialisedDbEngine, SqliteEngine, SqliteTransactionHook };
|
|
38
81
|
//# sourceMappingURL=index.d.mts.map
|
package/dist/index.d.mts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/serialised-sqlite-db.ts","../src/sqlite-transaction.ts"],"mappings":";;;;;;;;;
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/serialised-db.ts","../src/serialised-sqlite-db.ts","../src/sqlite-transaction.ts"],"mappings":";;;;;;;KAqEY;EACV,MAAM,aAAa,oBAAoB,QAAQ;EAC/C,KAAK,cAAc;EACnB,UAAU;EACV,gBAAgB;;;;;;;;;wBAUF,gBAAgB,QAAQ,oBAAoB;EAAW;IAAiB;;;;;;;;;;;KC7D5E;EACV,IAAI,aAAa,oBAAoB;EACrC,KAAK;EACL;EACA,aAAa,GAAG,UAAU,QAAQ,KAAK,QAAQ;;;;;;;;;;;wBAoHjC,sBAAsB,QAAQ,eAAe;;;;qBC3IhD;;;;;qBAMA;;KAKD,yBAAyB,GAAG,KAAK,IAAI,OAAO,QAAQ,OAAO,QAAQ;;;;;;wBAY/D,cAAc,GAAG,IAAI,IAAI,KAAK,IAAI,OAAO,QAAQ,KAAK,QAAQ;;;;;;;;;;wBAqB9D,sBAAsB,GAAG,IAAI,IAAI,KAAK,IAAI,OAAO,QAAQ,KAAK,QAAQ;;wBAStE,uBAAuB,IAAI"}
|