Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

node-driver.ts

273 lines7.1 KB

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>
23​
24type BetterSqlite3OpenFileOptions = {
25 filename: string
26 options?: BetterSqlite3OpenOptions
27 pragmas?: ReadonlyArray<string>
29​
30export type BetterSqlite3DriverOptions =
31 | BetterSqlite3ExistingDatabaseOptions
32 | BetterSqlite3OpenFileOptions
33​
34type TransactionContext = {
35 depth: number
37​
38type DatabaseExecutionState = {
39 transactionContext: AsyncLocalStorage<TransactionContext>
40 queue: Promise<void>
41 nextSavepointId: number
43​
44const databaseExecutionStates = new WeakMap<
45 BetterSqlite3Database,
46 DatabaseExecutionState
47>()
48​
49function getDatabaseExecutionState(
50 database: BetterSqlite3Database,
51): DatabaseExecutionState {
52 const existing = databaseExecutionStates.get(database)
53 if (existing) {
54 return existing
55 }
56​
57 const state: DatabaseExecutionState = {
58 transactionContext: new AsyncLocalStorage<TransactionContext>(),
59 queue: Promise.resolve(),
60 nextSavepointId: 1,
61 }
62 databaseExecutionStates.set(database, state)
63 return state
65​
66function assertTransactionCallbackHasDriverArg(
67 fn: (transactionDriver: SQLiteDriver) => Promise<unknown>,
68): void {
69 if (fn.length > 0) {
70 return
71 }
72​
73 throw new InvalidPersistedCollectionConfigError(
74 `SQLiteDriver.transaction callback must accept the transaction driver argument`,
75 )
77​
78function hasExistingDatabase(
79 options: BetterSqlite3DriverOptions,
80): options is BetterSqlite3ExistingDatabaseOptions {
81 return `database` in options
83​
84export class BetterSqlite3SQLiteDriver implements SQLiteDriver {
85 private readonly database: BetterSqlite3Database
86 private readonly ownsDatabase: boolean
87 private readonly executionState: DatabaseExecutionState
88​
89 constructor(options: BetterSqlite3DriverOptions) {
90 if (hasExistingDatabase(options)) {
91 this.database = options.database
92 this.ownsDatabase = false
93 this.executionState = getDatabaseExecutionState(this.database)
94 this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS)
95 return
96 }
97​
98 if (options.filename.trim().length === 0) {
99 throw new InvalidPersistedCollectionConfigError(
100 `Node SQLite driver filename cannot be empty`,
101 )
102 }
103​
104 this.database = new BetterSqlite3(options.filename, options.options)
105 this.ownsDatabase = true
106 this.executionState = getDatabaseExecutionState(this.database)
107 this.applyPragmas(options.pragmas ?? DEFAULT_PRAGMAS)
108 }
109​
110 async exec(sql: string): Promise<void> {
111 if (this.isInsideTransaction()) {
112 this.database.exec(sql)
113 return
114 }
115​
116 await this.enqueue(() => {
117 this.database.exec(sql)
118 })
119 }
120​
121 async query<T>(
122 sql: string,
123 params: ReadonlyArray<unknown> = [],
124 ): Promise<ReadonlyArray<T>> {
125 if (this.isInsideTransaction()) {
126 return this.executeQuery<T>(sql, params)
127 }
128​
129 return this.enqueue(() => this.executeQuery<T>(sql, params))
130 }
131​
132 async run(sql: string, params: ReadonlyArray<unknown> = []): Promise<void> {
133 if (this.isInsideTransaction()) {
134 this.executeRun(sql, params)
135 return
136 }
137​
138 await this.enqueue(() => {
139 this.executeRun(sql, params)
140 })
141 }
142​
143 async transaction<T>(
144 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
145 ): Promise<T> {
146 assertTransactionCallbackHasDriverArg(fn)
147​
148 if (this.isInsideTransaction()) {
149 return this.runNestedTransaction(fn)
150 }
151​
152 return this.enqueue(async () => {
153 this.database.exec(`BEGIN IMMEDIATE`)
154 try {
155 const result = await this.executionState.transactionContext.run(
156 { depth: 1 },
157 async () => fn(this),
158 )
159 this.database.exec(`COMMIT`)
160 return result
161 } catch (error) {
162 try {
163 this.database.exec(`ROLLBACK`)
164 } catch {
165 // Keep the original transaction error as the primary failure.
166 }
167 throw error
168 }
169 })
170 }
171​
172 async transactionWithDriver<T>(
173 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
174 ): Promise<T> {
175 return this.transaction(fn)
176 }
177​
178 close(): void {
179 if (!this.ownsDatabase) {
180 return
181 }
182​
183 this.database.close()
184 }
185​
186 getDatabase(): BetterSqlite3Database {
187 return this.database
188 }
189​
190 private applyPragmas(pragmas: ReadonlyArray<string>): void {
191 for (const pragma of pragmas) {
192 const trimmedPragma = pragma.trim()
193 if (trimmedPragma.length === 0) {
194 continue
195 }
196​
197 if (INVALID_PRAGMA_PATTERN.test(trimmedPragma)) {
198 throw new InvalidPersistedCollectionConfigError(
199 `Invalid SQLite PRAGMA: "${pragma}"`,
200 )
201 }
202​
203 this.database.exec(`PRAGMA ${trimmedPragma}`)
204 }
205 }
206​
207 private isInsideTransaction(): boolean {
208 return this.executionState.transactionContext.getStore() !== undefined
209 }
210​
211 private executeQuery<T>(
212 sql: string,
213 params: ReadonlyArray<unknown>,
214 ): ReadonlyArray<T> {
215 const statement = this.database.prepare(sql)
216 if (params.length === 0) {
217 return statement.all() as ReadonlyArray<T>
218 }
219​
220 return statement.all(...params) as ReadonlyArray<T>
221 }
222​
223 private executeRun(sql: string, params: ReadonlyArray<unknown>): void {
224 const statement = this.database.prepare(sql)
225 if (params.length === 0) {
226 statement.run()
227 return
228 }
229​
230 statement.run(...params)
231 }
232​
233 private enqueue<T>(operation: () => Promise<T> | T): Promise<T> {
234 const queuedOperation = this.executionState.queue.then(operation, operation)
235 this.executionState.queue = queuedOperation.then(
236 () => undefined,
237 () => undefined,
238 )
239 return queuedOperation
240 }
241​
242 private async runNestedTransaction<T>(
243 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
244 ): Promise<T> {
245 const context = this.executionState.transactionContext.getStore()
246 if (!context) {
247 return fn(this)
248 }
249​
250 const savepointName = `tsdb_sp_${this.executionState.nextSavepointId}`
251 this.executionState.nextSavepointId++
252 this.database.exec(`SAVEPOINT ${savepointName}`)
253​
254 try {
255 const result = await this.executionState.transactionContext.run(
256 { depth: context.depth + 1 },
257 async () => fn(this),
258 )
259 this.database.exec(`RELEASE SAVEPOINT ${savepointName}`)
260 return result
261 } catch (error) {
262 this.database.exec(`ROLLBACK TO SAVEPOINT ${savepointName}`)
263 this.database.exec(`RELEASE SAVEPOINT ${savepointName}`)
264 throw error
265 }
266 }
268​
269export function createBetterSqlite3Driver(
270 options: BetterSqlite3DriverOptions,
271): BetterSqlite3SQLiteDriver {
272 return new BetterSqlite3SQLiteDriver(options)