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

node-driver.ts

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