@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.
@@ -0,0 +1,95 @@
1
+ import type { Db, DbEntry } from "@statewalker/db-api";
2
+
3
+ /**
4
+ * The calls of one `Db`, run one at a time in call order. Once `close()` has started, `run`
5
+ * rejects at once with `<name>: the database is closed`; `close()` itself queues behind every
6
+ * earlier call, closes the engine once, and returns the same promise to every later caller.
7
+ */
8
+ export type DbCallQueue = {
9
+ run<T>(fn: () => T | Promise<T>): Promise<T>;
10
+ close(): Promise<void>;
11
+ };
12
+
13
+ export function newDbCallQueue(name: string, closeEngine: () => void | Promise<void>): DbCallQueue {
14
+ let tail: Promise<unknown> = Promise.resolve();
15
+ let closing: Promise<void> | undefined;
16
+ const enqueue = <T>(fn: () => T | Promise<T>): Promise<T> => {
17
+ const result = tail.then(fn);
18
+ tail = result.catch(() => undefined);
19
+ return result;
20
+ };
21
+ return {
22
+ run: (fn) =>
23
+ closing ? Promise.reject(new Error(`${name}: the database is closed`)) : enqueue(fn),
24
+ close: () => {
25
+ closing ??= enqueue(closeEngine);
26
+ return closing;
27
+ },
28
+ };
29
+ }
30
+
31
+ const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
32
+ const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
33
+
34
+ const isPlainObject = (value: object): boolean => {
35
+ const proto = Object.getPrototypeOf(value);
36
+ return proto === Object.prototype || proto === null;
37
+ };
38
+
39
+ /** A bigint within ±(2^53 - 1) as a number; arrays and plain objects converted in place. */
40
+ function safeInteger(value: unknown): unknown {
41
+ if (typeof value === "bigint") {
42
+ return value >= MIN_SAFE && value <= MAX_SAFE ? Number(value) : value;
43
+ }
44
+ if (Array.isArray(value)) {
45
+ for (let i = 0; i < value.length; i++) value[i] = safeInteger(value[i]);
46
+ } else if (value !== null && typeof value === "object" && isPlainObject(value)) {
47
+ const record = value as Record<string, unknown>;
48
+ for (const key in record) record[key] = safeInteger(record[key]);
49
+ }
50
+ return value;
51
+ }
52
+
53
+ /**
54
+ * Integers within ±(2^53 - 1) become numbers, larger ones stay bigints (no precision loss), in
55
+ * every column and inside list, struct and map values. The rows are converted in place.
56
+ */
57
+ export function toSafeIntegers<T extends Record<string, unknown>>(rows: T[]): T[] {
58
+ for (const row of rows) {
59
+ const record = row as Record<string, unknown>;
60
+ for (const key in record) record[key] = safeInteger(record[key]);
61
+ }
62
+ return rows;
63
+ }
64
+
65
+ /**
66
+ * The asynchronous engine a driver wraps with {@link newSerialisedDb}. It is called one call at a
67
+ * time and never after `close`; `query` returns rows with integers as numbers or bigints (the
68
+ * wrapper turns safe bigints into numbers).
69
+ */
70
+ export type SerialisedDbEngine = {
71
+ query(sql: string, params: unknown[]): Promise<Record<string, unknown>[]>;
72
+ exec(sql: string): Promise<void>;
73
+ flush?(): Promise<void>;
74
+ close(): void | Promise<void>;
75
+ };
76
+
77
+ /**
78
+ * Wrap an engine as a `Db` that keeps the lifecycle every driver shares: calls run one at a time,
79
+ * in call order; `close()` waits for the calls made before it, then closes the engine; calls made
80
+ * once `close()` has started reject with `<name>: the database is closed`; closing twice is a
81
+ * no-op. Integers come back as numbers when safe and as bigints beyond (see
82
+ * {@link toSafeIntegers}). `name` prefixes the error, e.g. `"db-pglite"`.
83
+ */
84
+ export function newSerialisedDb(engine: SerialisedDbEngine, options: { name: string }): Db {
85
+ const queue = newDbCallQueue(options.name, () => engine.close());
86
+ const db: Db = {
87
+ query: <T = DbEntry>(sql: string, params: unknown[] = []) =>
88
+ queue.run(async () => toSafeIntegers(await engine.query(sql, params)) as T[]),
89
+ exec: (sql: string) => queue.run(() => engine.exec(sql)),
90
+ close: () => queue.close(),
91
+ };
92
+ const flush = engine.flush?.bind(engine);
93
+ if (flush) db.flush = () => queue.run(flush);
94
+ return db;
95
+ }
@@ -1,13 +1,24 @@
1
1
  import type { Db, DbEntry } from "@statewalker/db-api";
2
- import { countSqlStatements, firstSqlStatement } from "./sql-statements.js";
3
- import { SQLITE_TRANSACTION, type SqliteTransactionHook } from "./sqlite-transaction.js";
2
+ import { newDbCallQueue, toSafeIntegers } from "./serialised-db.js";
3
+ import {
4
+ countSqlStatements,
5
+ firstSqlStatement,
6
+ splitSqlStatements,
7
+ sqlStatementHeads,
8
+ } from "./sql-statements.js";
9
+ import {
10
+ SQLITE_READ_ONLY_TRANSACTION,
11
+ SQLITE_TRANSACTION,
12
+ type SqliteTransactionHook,
13
+ } from "./sqlite-transaction.js";
4
14
 
5
15
  /**
6
16
  * The synchronous engine a SQLite driver wraps. `all` returns rows (BLOBs as Uint8Array; integers
7
17
  * as numbers or bigints, which the wrapper turns into numbers when they are safe) and is given
8
- * exactly one non-empty statement and parameters already normalised (no boolean, undefined or
9
- * Date); `exec` runs every statement of a non-empty string. `transaction`, when present, replaces
10
- * `BEGIN IMMEDIATE`/`COMMIT`/`ROLLBACK` (Durable Objects forbid them in SQL).
18
+ * exactly one non-empty statement and parameters already normalised and checked (only null,
19
+ * number, bigint, string and Uint8Array); `exec` runs every statement of a non-empty string.
20
+ * `transaction`, when present, replaces `BEGIN IMMEDIATE`/`COMMIT`/`ROLLBACK` (Durable Objects
21
+ * forbid them in SQL).
11
22
  */
12
23
  export type SqliteEngine = {
13
24
  all(sql: string, params: unknown[]): Record<string, unknown>[];
@@ -16,15 +27,6 @@ export type SqliteEngine = {
16
27
  transaction?<T>(fn: () => Promise<T>): Promise<T>;
17
28
  };
18
29
 
19
- function newLock() {
20
- let tail: Promise<unknown> = Promise.resolve();
21
- return <T>(fn: () => Promise<T>): Promise<T> => {
22
- const run = tail.then(fn);
23
- tail = run.catch(() => undefined);
24
- return run;
25
- };
26
- }
27
-
28
30
  const EMPTY_SQL = "db-sqlite: the SQL is empty (only whitespace, comments or semicolons)";
29
31
  const MANY_STATEMENTS =
30
32
  "db-sqlite: query runs one statement, and this SQL has more after the first; " +
@@ -37,8 +39,23 @@ function checkSql(sql: string, one: boolean): void {
37
39
  if (one && count === "many") throw new Error(MANY_STATEMENTS);
38
40
  }
39
41
 
40
- /** boolean → 1/0, undefined → NULL, Date → ISO 8601 UTC text; anything else is left as given. */
42
+ /** The type a rejected parameter is named by: `symbol`, `function`, or the object's class. */
43
+ function typeName(value: unknown): string {
44
+ if (typeof value !== "object" || value === null) return typeof value;
45
+ const name = (value as { constructor?: { name?: unknown } }).constructor?.name;
46
+ return typeof name === "string" && name ? name : "Object";
47
+ }
48
+
49
+ /**
50
+ * boolean → 1/0, undefined → NULL, Date → ISO 8601 UTC text, ArrayBuffer or any ArrayBuffer view →
51
+ * a Uint8Array over exactly its bytes; null, number, bigint and string are left as given. Anything
52
+ * else (a plain object, Map, array, function, symbol, boxed primitive) rejects: node:sqlite would
53
+ * take a leading object as named parameters and bind the rest one place to the left, and SQLite
54
+ * has no array type (bind a list as JSON text and read it with `json_each`).
55
+ */
41
56
  function toSqliteParam(value: unknown, index: number): unknown {
57
+ if (value === null || typeof value === "string" || typeof value === "number") return value;
58
+ if (typeof value === "bigint") return value;
42
59
  if (typeof value === "boolean") return value ? 1 : 0;
43
60
  if (value === undefined) return null;
44
61
  if (value instanceof Date) {
@@ -47,29 +64,28 @@ function toSqliteParam(value: unknown, index: number): unknown {
47
64
  }
48
65
  return value.toISOString();
49
66
  }
50
- return value;
51
- }
52
-
53
- const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
54
- const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
55
-
56
- /** Integers within ±(2^53 - 1) become numbers; larger ones stay bigints (no precision loss). */
57
- function fromSqliteRows(rows: Record<string, unknown>[]): Record<string, unknown>[] {
58
- for (const row of rows) {
59
- for (const key in row) {
60
- const value = row[key];
61
- if (typeof value === "bigint" && value >= MIN_SAFE && value <= MAX_SAFE) {
62
- row[key] = Number(value);
63
- }
64
- }
67
+ // node:sqlite (Node 22) binds a view over a buffer with no backing store (any zero-length
68
+ // ArrayBuffer) as NULL: give an empty value a fresh empty Uint8Array, which binds as a BLOB.
69
+ if ((ArrayBuffer.isView(value) || value instanceof ArrayBuffer) && value.byteLength === 0) {
70
+ return new Uint8Array(1).subarray(0, 0);
71
+ }
72
+ if (value instanceof Uint8Array && value.constructor === Uint8Array) return value;
73
+ if (ArrayBuffer.isView(value)) {
74
+ return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
65
75
  }
66
- return rows;
76
+ if (value instanceof ArrayBuffer) return new Uint8Array(value);
77
+ const hint = Array.isArray(value) ? "; bind a list as JSON text and read it with json_each" : "";
78
+ throw new TypeError(
79
+ `db-sqlite: parameter ${index + 1} has type ${typeName(value)}, which SQLite cannot bind; ` +
80
+ "pass null, undefined, a boolean, number, bigint, string, Date, ArrayBuffer or " +
81
+ `ArrayBuffer view${hint}`,
82
+ );
67
83
  }
68
84
 
69
85
  function runAll(engine: SqliteEngine, sql: string, params: unknown[]): Record<string, unknown>[] {
70
86
  checkSql(sql, true);
71
87
  // Only the statement itself reaches the engine: DO SQLite rejects an empty tail ("; -- c ;").
72
- return fromSqliteRows(engine.all(firstSqlStatement(sql), params.map(toSqliteParam)));
88
+ return toSafeIntegers(engine.all(firstSqlStatement(sql), params.map(toSqliteParam)));
73
89
  }
74
90
 
75
91
  function runExec(engine: SqliteEngine, sql: string): void {
@@ -77,19 +93,55 @@ function runExec(engine: SqliteEngine, sql: string): void {
77
93
  engine.exec(sql);
78
94
  }
79
95
 
96
+ /** Statements a read-only transaction refuses: they end it, or reach outside it. */
97
+ const READ_ONLY_REFUSED = new Set([
98
+ "begin",
99
+ "commit",
100
+ "end",
101
+ "rollback",
102
+ "savepoint",
103
+ "release",
104
+ "attach",
105
+ "detach",
106
+ "pragma",
107
+ "vacuum",
108
+ ]);
109
+
110
+ function checkReadOnly(sql: string): void {
111
+ if (typeof sql !== "string") return; // checkSql reports it
112
+ for (const head of sqlStatementHeads(sql)) {
113
+ // A statement that does not start with a word is refused too: where this scanner and SQLite
114
+ // could disagree on where a statement starts, the word SQLite sees is never checked.
115
+ if (head === "") {
116
+ throw new Error(
117
+ "db-sqlite: a read-only transaction refuses a statement that does not start with a keyword",
118
+ );
119
+ }
120
+ if (READ_ONLY_REFUSED.has(head)) {
121
+ throw new Error(
122
+ `db-sqlite: a read-only transaction refuses ${head.toUpperCase()} ` +
123
+ "(it would end the transaction or reach outside it)",
124
+ );
125
+ }
126
+ }
127
+ }
128
+
129
+ const READ_ONLY_FAILED =
130
+ "db-sqlite: a statement of this read-only transaction failed, so it refuses later calls " +
131
+ "(SQLite may have ended the transaction)";
132
+ const ROLLBACK_ON_PURPOSE = "db-sqlite: the read-only transaction is rolled back";
133
+
80
134
  /**
81
- * Wrap an engine as a `Db` whose calls run one at a time, in call order, and which carries the
82
- * `inTransaction` hook. Every SQLite driver gets the same input handling here: empty SQL rejects,
83
- * `query` rejects a second statement, parameters are normalised and safe integers come back as
84
- * numbers. The `tx` handed to a transaction callback bypasses the queue, has no hook
85
- * (so nesting is rejected) and rejects once its transaction has finished.
135
+ * Wrap an engine as a `Db` with the lifecycle of `newSerialisedDb` (calls run one at a time, in
136
+ * call order; `close()` waits for earlier calls; later calls reject with
137
+ * `db-sqlite: the database is closed`; closing twice is a no-op) and the `inTransaction` hook.
138
+ * Every SQLite driver gets the same input handling here: empty SQL rejects, `query` rejects a
139
+ * second statement, parameters are normalised (one SQLite cannot bind rejects) and safe integers come back as numbers. The `tx`
140
+ * handed to a transaction callback bypasses the queue, has no hook (so nesting is rejected) and
141
+ * rejects once its transaction has finished.
86
142
  */
87
143
  export function newSerialisedSqliteDb(engine: SqliteEngine): Db {
88
- const lock = newLock();
89
- let closed = false;
90
- const live = () => {
91
- if (closed) throw new Error("db-sqlite: the database is closed");
92
- };
144
+ const queue = newDbCallQueue("db-sqlite", () => engine.close());
93
145
  const runTransaction =
94
146
  engine.transaction?.bind(engine) ??
95
147
  (async <T>(fn: () => Promise<T>): Promise<T> => {
@@ -108,50 +160,101 @@ export function newSerialisedSqliteDb(engine: SqliteEngine): Db {
108
160
  }
109
161
  });
110
162
 
111
- const transaction: SqliteTransactionHook = (cb) =>
112
- lock(async () => {
113
- live();
114
- let finished = false;
115
- const open = () => {
116
- if (finished) throw new Error("db-sqlite: the transaction is finished; use the outer Db");
117
- };
118
- const tx: Db = {
119
- async query<T = DbEntry>(sql: string, params: unknown[] = []): Promise<T[]> {
120
- open();
121
- return runAll(engine, sql, params) as T[];
122
- },
123
- async exec(sql: string): Promise<void> {
124
- open();
125
- runExec(engine, sql);
126
- },
127
- async close(): Promise<void> {
128
- throw new Error("db-sqlite: close the outer Db, not the transaction handle");
129
- },
130
- };
131
- try {
132
- return await runTransaction(() => cb(tx));
133
- } finally {
134
- finished = true;
163
+ const platformTransaction = engine.transaction?.bind(engine);
164
+ const runReadOnlyTransaction = platformTransaction
165
+ ? async <T>(fn: () => Promise<T>): Promise<T> => {
166
+ // The platform commits when the closure returns: throw to make it roll back.
167
+ let result: T | undefined;
168
+ let returned = false;
169
+ try {
170
+ await platformTransaction(async () => {
171
+ returned = false;
172
+ result = await fn();
173
+ returned = true;
174
+ throw new Error(ROLLBACK_ON_PURPOSE);
175
+ });
176
+ } catch (error) {
177
+ if (returned && error instanceof Error && error.message === ROLLBACK_ON_PURPOSE) {
178
+ return result as T;
179
+ }
180
+ throw error;
181
+ }
182
+ throw new Error("db-sqlite: the platform did not roll back the read-only transaction");
135
183
  }
136
- });
184
+ : async <T>(fn: () => Promise<T>): Promise<T> => {
185
+ // A ROLLBACK that fails for any reason but "no transaction" (SQLite ended it itself, as
186
+ // INSERT OR ROLLBACK does: nothing to undo) leaves the transaction open: report it.
187
+ const rollback = () => {
188
+ try {
189
+ engine.exec("ROLLBACK");
190
+ } catch (error) {
191
+ if (!/no transaction is active/i.test(String((error as Error)?.message))) throw error;
192
+ }
193
+ };
194
+ engine.exec("BEGIN");
195
+ let result: T;
196
+ try {
197
+ result = await fn();
198
+ } catch (error) {
199
+ rollback();
200
+ throw error;
201
+ }
202
+ rollback();
203
+ return result;
204
+ };
205
+
206
+ const newTransactionHook =
207
+ (readOnly: boolean): SqliteTransactionHook =>
208
+ (cb) =>
209
+ queue.run(async () => {
210
+ let finished = false;
211
+ let failed = false;
212
+ const run = <R>(fn: () => R): R => {
213
+ if (finished) throw new Error("db-sqlite: the transaction is finished; use the outer Db");
214
+ if (!readOnly) return fn();
215
+ if (failed) throw new Error(READ_ONLY_FAILED);
216
+ try {
217
+ return fn();
218
+ } catch (error) {
219
+ failed = true;
220
+ throw error;
221
+ }
222
+ };
223
+ const tx: Db = {
224
+ async query<T = DbEntry>(sql: string, params: unknown[] = []): Promise<T[]> {
225
+ return run(() => {
226
+ if (readOnly) checkReadOnly(sql);
227
+ return runAll(engine, sql, params) as T[];
228
+ });
229
+ },
230
+ async exec(sql: string): Promise<void> {
231
+ run(() => {
232
+ if (!readOnly) return runExec(engine, sql);
233
+ checkReadOnly(sql);
234
+ checkSql(sql, false);
235
+ // One statement per engine call, through `all`, which runs exactly one (node:sqlite
236
+ // compiles only the first): text the splitter might misread as part of a statement
237
+ // never runs as a statement of its own, whatever it says.
238
+ for (const statement of splitSqlStatements(sql)) runAll(engine, statement, []);
239
+ });
240
+ },
241
+ async close(): Promise<void> {
242
+ throw new Error("db-sqlite: close the outer Db, not the transaction handle");
243
+ },
244
+ };
245
+ try {
246
+ return await (readOnly ? runReadOnlyTransaction : runTransaction)(() => cb(tx));
247
+ } finally {
248
+ finished = true;
249
+ }
250
+ });
137
251
 
138
252
  return {
139
253
  query: <T = DbEntry>(sql: string, params: unknown[] = []) =>
140
- lock(async () => {
141
- live();
142
- return runAll(engine, sql, params) as T[];
143
- }),
144
- exec: (sql: string) =>
145
- lock(async () => {
146
- live();
147
- runExec(engine, sql);
148
- }),
149
- close: () =>
150
- lock(async () => {
151
- if (closed) return;
152
- closed = true;
153
- engine.close();
154
- }),
155
- [SQLITE_TRANSACTION]: transaction,
254
+ queue.run(() => runAll(engine, sql, params) as T[]),
255
+ exec: (sql: string) => queue.run(() => runExec(engine, sql)),
256
+ close: () => queue.close(),
257
+ [SQLITE_TRANSACTION]: newTransactionHook(false),
258
+ [SQLITE_READ_ONLY_TRANSACTION]: newTransactionHook(true),
156
259
  } as Db;
157
260
  }
@@ -42,6 +42,37 @@ const KEYWORDS: Record<string, number> = {
42
42
 
43
43
  const isIdChar = (c: string) => /[A-Za-z0-9_$]/.test(c) || c.charCodeAt(0) >= 0x80;
44
44
 
45
+ /** SQLite's whitespace (sqlite3Isspace): space, \t, \n, \v, \f, \r. */
46
+ const isSpace = (c: string | undefined) =>
47
+ c === " " || c === "\t" || c === "\n" || c === "\v" || c === "\f" || c === "\r";
48
+
49
+ /**
50
+ * The end (exclusive) of a variable token starting at `i` (`$`, `:`, `@` or `#`), as SQLite's
51
+ * tokenizer reads it: identifier characters and `::`, and the Tcl form `$name(…)`, which runs to
52
+ * the first `)` (included) or whitespace, quotes and semicolons included.
53
+ */
54
+ function variableEnd(sql: string, i: number): number {
55
+ let j = i + 1;
56
+ let n = 0;
57
+ while (j < sql.length) {
58
+ const c = sql[j] as string;
59
+ if (isIdChar(c)) {
60
+ n++;
61
+ j++;
62
+ } else if (c === "(" && n > 0) {
63
+ j++;
64
+ while (j < sql.length && !isSpace(sql[j]) && sql[j] !== ")") j++;
65
+ if (sql[j] === ")") j++;
66
+ break;
67
+ } else if (c === ":" && sql[j + 1] === ":") {
68
+ j += 2;
69
+ } else {
70
+ break;
71
+ }
72
+ }
73
+ return j;
74
+ }
75
+
45
76
  export function countSqlStatements(sql: string): SqlStatementCount {
46
77
  return scanSqlStatements(sql).count;
47
78
  }
@@ -57,19 +88,56 @@ export function firstSqlStatement(sql: string): string {
57
88
  return firstEnd < 0 ? sql : sql.slice(0, firstEnd);
58
89
  }
59
90
 
60
- function scanSqlStatements(sql: string): { count: SqlStatementCount; firstEnd: number } {
91
+ /**
92
+ * The first word of every statement of `sql`, lowercased, in order ("" for a statement that does
93
+ * not start with a word, such as `(SELECT 1)`). Statements are split as SQLite splits them, so a
94
+ * keyword inside a literal, a comment or a trigger body is not a head. Empty statements are
95
+ * skipped.
96
+ */
97
+ export function sqlStatementHeads(sql: string): string[] {
98
+ return scanSqlStatements(sql).heads;
99
+ }
100
+
101
+ /**
102
+ * The statements of `sql`, split as {@link sqlStatementHeads} splits them: each from its first
103
+ * token to just before the semicolon that ends it (the last to the end of the text).
104
+ */
105
+ export function splitSqlStatements(sql: string): string[] {
106
+ return scanSqlStatements(sql).statements;
107
+ }
108
+
109
+ function scanSqlStatements(sql: string): {
110
+ count: SqlStatementCount;
111
+ firstEnd: number;
112
+ heads: string[];
113
+ statements: string[];
114
+ } {
115
+ const heads: string[] = [];
116
+ const statements: string[] = [];
117
+ let start = 0; // where the current statement's first token starts
61
118
  let firstEnd = -1; // index of the ";" that ends the first statement
62
119
  let state = 0;
63
- let content = false; // a token other than whitespace or ";" was seen
64
- let firstEnded = false; // the first statement with content has reached its ";"
120
+ let inStatement = false; // a token other than whitespace or ";" was seen since the last end
65
121
  let i = 0;
66
122
  const n = sql.length;
123
+ const result = () => ({
124
+ count: (heads.length === 0
125
+ ? "empty"
126
+ : heads.length === 1
127
+ ? "one"
128
+ : "many") as SqlStatementCount,
129
+ firstEnd,
130
+ heads,
131
+ statements: inStatement ? [...statements, sql.slice(start)] : statements,
132
+ });
67
133
  while (i < n) {
68
134
  const c = sql[i] as string;
135
+ const tokenStart = i;
69
136
  let token: number;
137
+ let word = "";
70
138
  if (c === ";") {
71
139
  token = SEMI;
72
- } else if (c === " " || c === "\t" || c === "\n" || c === "\r" || c === "\f") {
140
+ } else if (isSpace(c)) {
73
141
  token = WS;
74
142
  } else if (c === "/" && sql[i + 1] === "*") {
75
143
  const close = sql.indexOf("*/", i + 2);
@@ -83,27 +151,42 @@ function scanSqlStatements(sql: string): { count: SqlStatementCount; firstEnd: n
83
151
  token = WS;
84
152
  } else if (c === "[" || c === "`" || c === '"' || c === "'") {
85
153
  const close = sql.indexOf(c === "[" ? "]" : c, i + 1);
86
- if (close < 0) return { count: firstEnded ? "many" : "one", firstEnd };
154
+ if (close < 0) {
155
+ // An unterminated literal runs to the end: content, which SQLite reports as an error.
156
+ if (!inStatement) {
157
+ heads.push("");
158
+ start = tokenStart;
159
+ inStatement = true;
160
+ }
161
+ return result();
162
+ }
87
163
  i = close;
88
164
  token = OTHER;
165
+ } else if (c === "$" || c === ":" || c === "@" || c === "#") {
166
+ // A variable, not a word: SQLite reads `$a(';x')` as one token, quotes and all.
167
+ i = variableEnd(sql, i) - 1;
168
+ token = OTHER;
89
169
  } else if (isIdChar(c)) {
90
170
  let j = i + 1;
91
171
  while (j < n && isIdChar(sql[j] as string)) j++;
92
- token = KEYWORDS[sql.slice(i, j).toLowerCase()] ?? OTHER;
172
+ word = sql.slice(i, j).toLowerCase();
173
+ token = KEYWORDS[word] ?? OTHER;
93
174
  i = j - 1;
94
175
  } else {
95
176
  token = OTHER;
96
177
  }
97
- if (token !== SEMI && token !== WS) {
98
- if (firstEnded) return { count: "many", firstEnd };
99
- content = true;
178
+ if (token !== SEMI && token !== WS && !inStatement) {
179
+ inStatement = true;
180
+ heads.push(word);
181
+ start = tokenStart;
100
182
  }
101
183
  state = TRANS[state]?.[token] ?? 2;
102
- if (token === SEMI && state === 1 && content && !firstEnded) {
103
- firstEnded = true;
104
- firstEnd = i;
184
+ if (token === SEMI && state === 1 && inStatement) {
185
+ inStatement = false;
186
+ statements.push(sql.slice(start, i));
187
+ if (firstEnd < 0) firstEnd = i;
105
188
  }
106
189
  i++;
107
190
  }
108
- return { count: content ? "one" : "empty", firstEnd };
191
+ return result();
109
192
  }
@@ -3,6 +3,14 @@ import type { Db } from "@statewalker/db-api";
3
3
  /** Key under which a SQLite Db carries its transaction hook. Shared across bundles via Symbol.for. */
4
4
  export const SQLITE_TRANSACTION: unique symbol = Symbol.for("@statewalker/db-sqlite:transaction");
5
5
 
6
+ /**
7
+ * Key under which a SQLite Db carries its read-only transaction hook (a separate key, so that a Db
8
+ * from an older db-sqlite, which has only the committing hook, is refused rather than committed).
9
+ */
10
+ export const SQLITE_READ_ONLY_TRANSACTION: unique symbol = Symbol.for(
11
+ "@statewalker/db-sqlite:read-only-transaction",
12
+ );
13
+
6
14
  /** Runs `cb` inside one transaction of the Db that carries it. */
7
15
  export type SqliteTransactionHook = <T>(cb: (tx: Db) => Promise<T>) => Promise<T>;
8
16
 
@@ -21,3 +29,34 @@ export function inTransaction<T>(db: Db, cb: (tx: Db) => Promise<T>): Promise<T>
21
29
  if (typeof hook !== "function") return Promise.reject(new Error(NO_HOOK));
22
30
  return hook(cb);
23
31
  }
32
+
33
+ const NO_READ_ONLY_HOOK =
34
+ "inReadOnlyTransaction: this Db has no SQLite read-only transaction hook. It is not a " +
35
+ "@statewalker/db-sqlite* Db (or one from a db-sqlite older than 0.1.4), " +
36
+ "or it wraps one (a wrapper object loses the hook - pass the driver's Db itself), " +
37
+ "or it is the handle of a running transaction (nesting is not supported).";
38
+
39
+ /**
40
+ * Run `cb` in one SQLite transaction that is always rolled back: `tx` sees the committed data and
41
+ * its own writes, and nothing it writes persists, whether `cb` returns (its value is returned) or
42
+ * throws (its error is rethrown). Statements that would end the transaction or reach outside it
43
+ * (BEGIN, COMMIT, END, ROLLBACK, SAVEPOINT, RELEASE, ATTACH, DETACH, PRAGMA, VACUUM) are refused,
44
+ * and once a statement fails, `tx` refuses every later call (SQLite may have ended the transaction
45
+ * itself, as `INSERT OR ROLLBACK` does). Other calls on `db` wait until it ends. `cb` must not do
46
+ * external I/O and must be idempotent: a Durable Object may run it more than once.
47
+ */
48
+ export function inReadOnlyTransaction<T>(db: Db, cb: (tx: Db) => Promise<T>): Promise<T> {
49
+ const hook = (db as { [SQLITE_READ_ONLY_TRANSACTION]?: SqliteTransactionHook })[
50
+ SQLITE_READ_ONLY_TRANSACTION
51
+ ];
52
+ if (typeof hook !== "function") return Promise.reject(new Error(NO_READ_ONLY_HOOK));
53
+ return hook(cb);
54
+ }
55
+
56
+ /** Whether `db` carries the hook {@link inReadOnlyTransaction} needs. */
57
+ export function hasReadOnlyTransaction(db: Db): boolean {
58
+ return (
59
+ typeof (db as { [SQLITE_READ_ONLY_TRANSACTION]?: unknown })[SQLITE_READ_ONLY_TRANSACTION] ===
60
+ "function"
61
+ );
62
+ }