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

node-driver.ts

246 lines6.3 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​
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 )
49​
50function hasExistingDatabase(
51 options: BetterSqlite3DriverOptions,
52): options is BetterSqlite3ExistingDatabaseOptions {
53 return `database` in options
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 }
241​
242export function createBetterSqlite3Driver(
243 options: BetterSqlite3DriverOptions,
244): BetterSqlite3SQLiteDriver {
245 return new BetterSqlite3SQLiteDriver(options)