|
| 1 | +/** |
| 2 | + * SQLite adapter wrapping node:sqlite's DatabaseSync with a convenient API. |
| 3 | + * |
| 4 | + * This module is the single import point for all SQLite access in the |
| 5 | + * codebase. It provides a `.query(sql).get()` / `.all()` / `.run()` |
| 6 | + * interface and a manual `transaction()` wrapper. |
| 7 | + * |
| 8 | + * Uses `node:sqlite` (Node 22+) as the backing implementation. Falls back |
| 9 | + * to `bun:sqlite` when `node:sqlite` is unavailable (Bun runtime) — this |
| 10 | + * fallback will be removed once the test runner migrates off Bun. |
| 11 | + */ |
| 12 | + |
| 13 | +import { logger } from "../logger.js"; |
| 14 | + |
| 15 | +const log = logger.withTag("sqlite"); |
| 16 | + |
| 17 | +/** Valid SQLite binding value. */ |
| 18 | +export type SQLQueryBindings = |
| 19 | + | string |
| 20 | + | number |
| 21 | + | bigint |
| 22 | + | boolean |
| 23 | + | null |
| 24 | + | Uint8Array |
| 25 | + | undefined; |
| 26 | + |
| 27 | +/** |
| 28 | + * Prepared statement wrapper exposing `.get()`, `.all()`, `.run()`. |
| 29 | + * |
| 30 | + * Uses a Proxy to pass through any additional driver-specific methods |
| 31 | + * (e.g. bun:sqlite's `.values()`) while normalising `.get()` to return |
| 32 | + * `null` (not `undefined`) for no-row results. |
| 33 | + */ |
| 34 | +type StatementWrapper = { |
| 35 | + get(...params: SQLQueryBindings[]): Record<string, SQLQueryBindings> | null; |
| 36 | + all(...params: SQLQueryBindings[]): Record<string, SQLQueryBindings>[]; |
| 37 | + run(...params: SQLQueryBindings[]): void; |
| 38 | + /** Allow driver-specific methods (e.g. bun:sqlite `.values()`) to pass through. */ |
| 39 | + [method: string]: unknown; |
| 40 | +}; |
| 41 | + |
| 42 | +// biome-ignore lint/suspicious/noExplicitAny: backing driver types vary |
| 43 | +function wrapStatement(stmt: any): StatementWrapper { |
| 44 | + return new Proxy(stmt, { |
| 45 | + get(target, prop) { |
| 46 | + if (prop === "get") { |
| 47 | + return (...params: SQLQueryBindings[]) => |
| 48 | + // node:sqlite returns undefined for no rows; bun:sqlite returns null. |
| 49 | + // Normalise to null so callers can rely on a single sentinel. |
| 50 | + (target.get(...params) as Record<string, SQLQueryBindings>) ?? null; |
| 51 | + } |
| 52 | + const value = Reflect.get(target, prop); |
| 53 | + if (typeof value === "function") { |
| 54 | + return value.bind(target); |
| 55 | + } |
| 56 | + return value; |
| 57 | + }, |
| 58 | + }) as StatementWrapper; |
| 59 | +} |
| 60 | + |
| 61 | +/** |
| 62 | + * Resolve the underlying SQLite database constructor. |
| 63 | + * |
| 64 | + * Prefers `node:sqlite` (Node 22+). Falls back to `bun:sqlite` when |
| 65 | + * `node:sqlite` is unavailable (Bun runtime). The fallback will be |
| 66 | + * removed once the test runner migrates off Bun. |
| 67 | + */ |
| 68 | +function getSqliteConstructor(): new ( |
| 69 | + path: string |
| 70 | +) => { |
| 71 | + exec(sql: string): void; |
| 72 | + close(): void; |
| 73 | +} { |
| 74 | + try { |
| 75 | + return require("node:sqlite").DatabaseSync; |
| 76 | + } catch (error) { |
| 77 | + log.debug("node:sqlite unavailable, falling back to bun:sqlite", error); |
| 78 | + return require("bun:sqlite").Database; |
| 79 | + } |
| 80 | +} |
| 81 | + |
| 82 | +// biome-ignore lint/suspicious/noExplicitAny: resolved dynamically |
| 83 | +const SqliteImpl: any = getSqliteConstructor(); |
| 84 | + |
| 85 | +/** |
| 86 | + * SQLite database wrapper. |
| 87 | + * |
| 88 | + * - `exec(sql)` — execute raw SQL (DDL, multi-statement) |
| 89 | + * - `query(sql)` — prepare a statement → `.get()` / `.all()` / `.run()` |
| 90 | + * - `close()` — close the connection |
| 91 | + * - `transaction(fn)` — wrap a function in BEGIN/COMMIT/ROLLBACK |
| 92 | + */ |
| 93 | +export class Database { |
| 94 | + // biome-ignore lint/suspicious/noExplicitAny: backing driver resolved at runtime |
| 95 | + private readonly db: any; |
| 96 | + |
| 97 | + constructor(path: string) { |
| 98 | + this.db = new SqliteImpl(path); |
| 99 | + } |
| 100 | + |
| 101 | + /** Execute raw SQL (DDL statements, multi-statement strings). */ |
| 102 | + exec(sql: string): void { |
| 103 | + this.db.exec(sql); |
| 104 | + } |
| 105 | + |
| 106 | + /** |
| 107 | + * Prepare a SQL statement. |
| 108 | + * Returns a wrapper with `.get()`, `.all()`, `.run()`. |
| 109 | + * |
| 110 | + * Uses bun:sqlite's `.query()` (cached statements) when available, |
| 111 | + * falling back to node:sqlite's `.prepare()`. |
| 112 | + */ |
| 113 | + query(sql: string): StatementWrapper { |
| 114 | + // bun:sqlite exposes both .query() (cached) and .prepare() (fresh). |
| 115 | + // Prefer .query() to preserve the caching semantics all consumers |
| 116 | + // were written against. node:sqlite only has .prepare(). |
| 117 | + const prepFn = this.db.query ?? this.db.prepare; |
| 118 | + return wrapStatement(prepFn.call(this.db, sql)); |
| 119 | + } |
| 120 | + |
| 121 | + /** Close the database connection. */ |
| 122 | + close(): void { |
| 123 | + this.db.close(); |
| 124 | + } |
| 125 | + |
| 126 | + /** |
| 127 | + * Wrap a function in a transaction. Returns a callable that executes |
| 128 | + * the function within BEGIN/COMMIT, with ROLLBACK on error. |
| 129 | + */ |
| 130 | + transaction<T>(fn: () => T): () => T { |
| 131 | + // bun:sqlite has native transaction(); node:sqlite does not |
| 132 | + if (typeof this.db.transaction === "function") { |
| 133 | + return this.db.transaction(fn); |
| 134 | + } |
| 135 | + return () => { |
| 136 | + this.db.exec("BEGIN"); |
| 137 | + try { |
| 138 | + const result = fn(); |
| 139 | + this.db.exec("COMMIT"); |
| 140 | + return result; |
| 141 | + } catch (error) { |
| 142 | + this.db.exec("ROLLBACK"); |
| 143 | + throw error; |
| 144 | + } |
| 145 | + }; |
| 146 | + } |
| 147 | +} |
0 commit comments