Open History to see the last commit
1import { AsyncLocalStorage } from 'node:async_hooks'
2import BetterSqlite3 from 'better-sqlite3'
3import { InvalidPersistedCollectionConfigError } from '@tanstack/db-sqlite-persistence-core'
4import type { SQLiteDriver } from '@tanstack/db-sqlite-persistence-core'
5
6const DEFAULT_PRAGMAS = [
7 `journal_mode = WAL`,
8 `synchronous = NORMAL`,
9 `foreign_keys = ON`,
10] as const
11
12const INVALID_PRAGMA_PATTERN = /(;|--|\/\*)/
13
14export type BetterSqlite3Database = InstanceType<typeof BetterSqlite3>
15export type BetterSqlite3OpenOptions = ConstructorParameters<
16 typeof BetterSqlite3
17>[1]
18
19type BetterSqlite3ExistingDatabaseOptions = {
20 database: BetterSqlite3Database
21 pragmas?: ReadonlyArray<string>
22}
23
24type BetterSqlite3OpenFileOptions = {
25 filename: string
26 options?: BetterSqlite3OpenOptions
27 pragmas?: ReadonlyArray<string>
28}
29
30export type BetterSqlite3DriverOptions =
31 | BetterSqlite3ExistingDatabaseOptions
32 | BetterSqlite3OpenFileOptions
33
34type TransactionContext = {
35 depth: number
36}
37
38function assertTransactionCallbackHasDriverArg(
39 fn: (transactionDriver: SQLiteDriver) => Promise<unknown>,
40): void {
41 if (fn.length > 0) {
42 return
43 }
44
45 throw new InvalidPersistedCollectionConfigError(
46 `SQLiteDriver.transaction callback must accept the transaction driver argument`,
47 )
48}
49
50function hasExistingDatabase(
51 options: BetterSqlite3DriverOptions,
52): options is BetterSqlite3ExistingDatabaseOptions {
53 return `database` in options
54}
55
56export class BetterSqlite3SQLiteDriver implements SQLiteDriver {
57 private readonly database: BetterSqlite3Database
58 private readonly ownsDatabase: boolean
59 private readonly transactionContext =
60 new AsyncLocalStorage<TransactionContext>()
61 private queue: Promise<void> = Promise.resolve()
62 private nextSavepointId = 1
63
64 constructor(options: BetterSqlite3DriverOptions) {
65 if (hasExistingDatabase(options)) {
66 this.database = options.database
67 this.ownsDatabase = false
68 this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS)
69 return
70 }
71
72 if (options.filename.trim().length === 0) {
73 throw new InvalidPersistedCollectionConfigError(
74 `Node SQLite driver filename cannot be empty`,
75 )
76 }
77
78 this.database = new BetterSqlite3(options.filename, options.options)
79 this.ownsDatabase = true
80 this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS)
81 }
82
83 async exec(sql: string): Promise<void> {
84 if (this.isInsideTransaction()) {
85 this.database.exec(sql)
86 return
87 }
88
89 await this.enqueue(() => {
90 this.database.exec(sql)
91 })
92 }
93
94 async query<T>(
95 sql: string,
96 params: ReadonlyArray<unknown> = [],
97 ): Promise<ReadonlyArray<T>> {
98 if (this.isInsideTransaction()) {
99 return this.executeQuery<T>(sql, params)
100 }
101
102 return this.enqueue(() => this.executeQuery<T>(sql, params))
103 }
104
105 async run(sql: string, params: ReadonlyArray<unknown> = []): Promise<void> {
106 if (this.isInsideTransaction()) {
107 this.executeRun(sql, params)
108 return
109 }
110
111 await this.enqueue(() => {
112 this.executeRun(sql, params)
113 })
114 }
115
116 async transaction<T>(
117 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
118 ): Promise<T> {
119 assertTransactionCallbackHasDriverArg(fn)
120
121 if (this.isInsideTransaction()) {
122 return this.runNestedTransaction(fn)
123 }
124
125 return this.enqueue(async () => {
126 this.database.exec(`BEGIN IMMEDIATE`)
127 try {
128 const result = await this.transactionContext.run(
129 { depth: 1 },
130 async () => fn(this),
131 )
132 this.database.exec(`COMMIT`)
133 return result
134 } catch (error) {
135 try {
136 this.database.exec(`ROLLBACK`)
137 } catch {
138 // Keep the original transaction error as the primary failure.
139 }
140 throw error
141 }
142 })
143 }
144
145 async transactionWithDriver<T>(
146 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
147 ): Promise<T> {
148 return this.transaction(fn)
149 }
150
151 close(): void {
152 if (!this.ownsDatabase) {
153 return
154 }
155
156 this.database.close()
157 }
158
159 getDatabase(): BetterSqlite3Database {
160 return this.database
161 }
162
163 private applyPragmas(pragmas: ReadonlyArray<string>): void {
164 for (const pragma of pragmas) {
165 const trimmedPragma = pragma.trim()
166 if (trimmedPragma.length === 0) {
167 continue
168 }
169
170 if (INVALID_PRAGMA_PATTERN.test(trimmedPragma)) {
171 throw new InvalidPersistedCollectionConfigError(
172 `Invalid SQLite PRAGMA: "${pragma}"`,
173 )
174 }
175
176 this.database.exec(`PRAGMA ${trimmedPragma}`)
177 }
178 }
179
180 private isInsideTransaction(): boolean {
181 return this.transactionContext.getStore() !== undefined
182 }
183
184 private executeQuery<T>(
185 sql: string,
186 params: ReadonlyArray<unknown>,
187 ): ReadonlyArray<T> {
188 const statement = this.database.prepare(sql)
189 if (params.length === 0) {
190 return statement.all() as ReadonlyArray<T>
191 }
192
193 return statement.all(...params) as ReadonlyArray<T>
194 }
195
196 private executeRun(sql: string, params: ReadonlyArray<unknown>): void {
197 const statement = this.database.prepare(sql)
198 if (params.length === 0) {
199 statement.run()
200 return
201 }
202
203 statement.run(...params)
204 }
205
206 private enqueue<T>(operation: () => Promise<T> | T): Promise<T> {
207 const queuedOperation = this.queue.then(operation, operation)
208 this.queue = queuedOperation.then(
209 () => undefined,
210 () => undefined,
211 )
212 return queuedOperation
213 }
214
215 private async runNestedTransaction<T>(
216 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
217 ): Promise<T> {
218 const context = this.transactionContext.getStore()
219 if (!context) {
220 return fn(this)
221 }
222
223 const savepointName = `tsdb_sp_${this.nextSavepointId}`
224 this.nextSavepointId++
225 this.database.exec(`SAVEPOINT ${savepointName}`)
226
227 try {
228 const result = await this.transactionContext.run(
229 { depth: context.depth + 1 },
230 async () => fn(this),
231 )
232 this.database.exec(`RELEASE SAVEPOINT ${savepointName}`)
233 return result
234 } catch (error) {
235 this.database.exec(`ROLLBACK TO SAVEPOINT ${savepointName}`)
236 this.database.exec(`RELEASE SAVEPOINT ${savepointName}`)
237 throw error
238 }
239 }
240}
241
242export function createBetterSqlite3Driver(
243 options: BetterSqlite3DriverOptions,
244): BetterSqlite3SQLiteDriver {
245 return new BetterSqlite3SQLiteDriver(options)
246}