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

op-sqlite-driver.ts

490 lines13.2 KB

1import { InvalidPersistedCollectionConfigError } from '@tanstack/db-sqlite-persistence-core'
2import type { SQLiteDriver } from '@tanstack/db-sqlite-persistence-core'
3​
4type OpSQLiteExecuteFn = (
5 sql: string,
6 params?: ReadonlyArray<unknown>,
7) => unknown | Promise<unknown>
8​
9type OpSQLiteRowListLike = {
10 length?: unknown
11 item?: unknown
12 _array?: unknown
14​
15type OpSQLiteStatementResultLike = {
16 rows?: unknown
17 resultRows?: unknown
18 rowsAffected?: unknown
19 changes?: unknown
20 insertId?: unknown
21 lastInsertRowId?: unknown
23​
24const WRITE_RESULT_KEYS = new Set([
25 `rowsAffected`,
26 `changes`,
27 `insertId`,
28 `lastInsertRowId`,
29])
30​
31export type OpSQLiteDatabaseLike = {
32 execute?: OpSQLiteExecuteFn
33 executeAsync?: OpSQLiteExecuteFn
34 executeRaw?: OpSQLiteExecuteFn
35 execAsync?: OpSQLiteExecuteFn
36 close?: () => Promise<void> | void
38​
39type OpSQLiteExistingDatabaseOptions = {
40 database: OpSQLiteDatabaseLike
42​
43type OpSQLiteOpenDatabaseOptions = {
44 openDatabase: () => OpSQLiteDatabaseLike
46​
47export type OpSQLiteDriverOptions =
48 | OpSQLiteExistingDatabaseOptions
49 | OpSQLiteOpenDatabaseOptions
50​
51type TransactionContextStore = {
52 transactionDriver: SQLiteDriver
54​
55type AsyncLocalStorageLike<TStore> = {
56 getStore: () => TStore | undefined
57 run: <TResult>(store: TStore, callback: () => TResult) => TResult
59​
60type AsyncLocalStorageCtor = new <TStore>() => AsyncLocalStorageLike<TStore>
61​
62let asyncLocalStorageCtorPromise: Promise<AsyncLocalStorageCtor | null> | null =
63 null
64​
65function canAttemptNodeAsyncLocalStorageLoad(): boolean {
66 if (typeof process === `undefined`) {
67 return false
68 }
69 // In React Native, process is polyfilled but process.versions may not exist
70 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
71 return typeof process.versions?.node === `string`
73​
74function getNodeAsyncHooksSpecifier(): string {
75 const moduleName = `async_hooks`
76 return `node:${moduleName}`
78​
79async function resolveAsyncLocalStorageCtor(): Promise<AsyncLocalStorageCtor | null> {
80 if (asyncLocalStorageCtorPromise) {
81 return asyncLocalStorageCtorPromise
82 }
83​
84 asyncLocalStorageCtorPromise = (async () => {
85 if (!canAttemptNodeAsyncLocalStorageLoad()) {
86 return null
87 }
88​
89 try {
90 // Use Function constructor to hide the dynamic import from React Native
91 // bundlers — Metro rejects non-literal dynamic import() at transform time.
92 // On React Native this code path is never reached (guarded above).
93 const importFn = new Function(`s`, `return import(s)`) as (
94 specifier: string,
95 ) => Promise<{
96 AsyncLocalStorage?: AsyncLocalStorageCtor
97 }>
98 const asyncHooksModule = await importFn(getNodeAsyncHooksSpecifier())
99​
100 return typeof asyncHooksModule.AsyncLocalStorage === `function`
101 ? asyncHooksModule.AsyncLocalStorage
102 : null
103 } catch {
104 return null
105 }
106 })()
107​
108 return asyncLocalStorageCtorPromise
110​
111function isObjectRecord(value: unknown): value is Record<string, unknown> {
112 return typeof value === `object` && value !== null
114​
115function hasWriteResultMarker(value: Record<string, unknown>): boolean {
116 for (const key of WRITE_RESULT_KEYS) {
117 if (key in value) {
118 return true
119 }
120 }
121 return false
123​
124function toRowArray(rowsValue: unknown): Array<unknown> | null {
125 if (Array.isArray(rowsValue)) {
126 return rowsValue
127 }
128​
129 if (!isObjectRecord(rowsValue)) {
130 return null
131 }
132​
133 const rowsObject = rowsValue as OpSQLiteRowListLike
134 if (Array.isArray(rowsObject._array)) {
135 return rowsObject._array
136 }
137​
138 if (
139 typeof rowsObject.length === `number` &&
140 typeof rowsObject.item === `function`
141 ) {
142 const item = rowsObject.item as (index: number) => unknown
143 const rows: Array<unknown> = []
144 for (let index = 0; index < rowsObject.length; index++) {
145 rows.push(item(index))
146 }
147 return rows
148 }
149​
150 return null
152​
153function extractRowsFromStatementResult(
154 value: OpSQLiteStatementResultLike,
155): Array<unknown> | null {
156 const rowsFromRows = toRowArray(value.rows)
157 if (rowsFromRows) {
158 return rowsFromRows
159 }
160​
161 const rowsFromResultRows = toRowArray(value.resultRows)
162 if (rowsFromResultRows) {
163 return rowsFromResultRows
164 }
165​
166 if (hasWriteResultMarker(value as Record<string, unknown>)) {
167 return []
168 }
169​
170 return null
172​
173function extractRowsFromExecuteResult(
174 result: unknown,
175 sql: string,
176): Array<unknown> {
177 if (result == null) {
178 return []
179 }
180​
181 if (Array.isArray(result)) {
182 if (result.length === 0) {
183 return []
184 }
185​
186 const firstEntry = result[0]
187 if (isObjectRecord(firstEntry)) {
188 const rowsFromStatement = extractRowsFromStatementResult(firstEntry)
189 if (rowsFromStatement) {
190 return rowsFromStatement
191 }
192 }
193​
194 return result
195 }
196​
197 if (isObjectRecord(result)) {
198 const rowsFromStatement = extractRowsFromStatementResult(result)
199 if (rowsFromStatement) {
200 return rowsFromStatement
201 }
202​
203 const nestedResults = result.results
204 if (Array.isArray(nestedResults) && nestedResults.length > 0) {
205 const firstResult = nestedResults[0]
206 if (isObjectRecord(firstResult)) {
207 const rowsFromNested = extractRowsFromStatementResult(firstResult)
208 if (rowsFromNested) {
209 return rowsFromNested
210 }
211 }
212 }
213 }
214​
215 throw new InvalidPersistedCollectionConfigError(
216 `Unsupported op-sqlite query result shape for SQL "${sql}"`,
217 )
219​
220function hasExistingDatabase(
221 options: OpSQLiteDriverOptions,
222): options is OpSQLiteExistingDatabaseOptions {
223 return `database` in options
225​
226function assertTransactionCallbackHasDriverArg(
227 fn: (transactionDriver: SQLiteDriver) => Promise<unknown>,
228): void {
229 if (fn.length > 0) {
230 return
231 }
232​
233 throw new InvalidPersistedCollectionConfigError(
234 `SQLiteDriver.transaction callback must accept the transaction driver argument`,
235 )
237​
238function resolveExecuteMethod(
239 database: OpSQLiteDatabaseLike,
240): OpSQLiteExecuteFn {
241 const executeCandidates: Array<unknown> = [
242 database.executeAsync,
243 database.execute,
244 database.executeRaw,
245 database.execAsync,
246 ]
247 const executeMethod = executeCandidates.find(
248 (candidate) => typeof candidate === `function`,
249 )
250​
251 if (typeof executeMethod !== `function`) {
252 throw new InvalidPersistedCollectionConfigError(
253 `op-sqlite database object must provide execute/executeAsync/executeRaw/execAsync`,
254 )
255 }
256​
257 return executeMethod as OpSQLiteExecuteFn
259​
260export class OpSQLiteDriver implements SQLiteDriver {
261 private readonly database: OpSQLiteDatabaseLike
262 private readonly executeMethod: OpSQLiteExecuteFn
263 private readonly ownsDatabase: boolean
264 private queue: Promise<void> = Promise.resolve()
265 private nextSavepointId = 1
266 private transactionContextStoragePromise: Promise<AsyncLocalStorageLike<TransactionContextStore> | null> | null =
267 null
268​
269 constructor(options: OpSQLiteDriverOptions) {
270 if (hasExistingDatabase(options)) {
271 this.database = options.database
272 this.ownsDatabase = false
273 } else {
274 this.database = options.openDatabase()
275 this.ownsDatabase = true
276 }
277​
278 this.executeMethod = resolveExecuteMethod(this.database)
279 }
280​
281 async exec(sql: string): Promise<void> {
282 const activeTransactionDriver = await this.getActiveTransactionDriver()
283 if (activeTransactionDriver) {
284 await activeTransactionDriver.exec(sql)
285 return
286 }
287​
288 await this.enqueue(async () => {
289 await this.execute(sql)
290 })
291 }
292​
293 async query<T>(
294 sql: string,
295 params: ReadonlyArray<unknown> = [],
296 ): Promise<ReadonlyArray<T>> {
297 const activeTransactionDriver = await this.getActiveTransactionDriver()
298 if (activeTransactionDriver) {
299 return activeTransactionDriver.query<T>(sql, params)
300 }
301​
302 return this.enqueue(async () => {
303 const result = await this.execute(sql, params)
304 return extractRowsFromExecuteResult(result, sql) as ReadonlyArray<T>
305 })
306 }
307​
308 async run(sql: string, params: ReadonlyArray<unknown> = []): Promise<void> {
309 const activeTransactionDriver = await this.getActiveTransactionDriver()
310 if (activeTransactionDriver) {
311 await activeTransactionDriver.run(sql, params)
312 return
313 }
314​
315 await this.enqueue(async () => {
316 await this.execute(sql, params)
317 })
318 }
319​
320 async transaction<T>(
321 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
322 ): Promise<T> {
323 assertTransactionCallbackHasDriverArg(fn)
324​
325 const activeTransactionDriver = await this.getActiveTransactionDriver()
326 if (activeTransactionDriver) {
327 return activeTransactionDriver.transaction(fn)
328 }
329​
330 return this.transactionWithDriver((transactionDriver) =>
331 fn(transactionDriver),
332 )
333 }
334​
335 async transactionWithDriver<T>(
336 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
337 ): Promise<T> {
338 const activeTransactionDriver = await this.getActiveTransactionDriver()
339 if (
340 activeTransactionDriver &&
341 typeof activeTransactionDriver.transactionWithDriver === `function`
342 ) {
343 return activeTransactionDriver.transactionWithDriver(fn)
344 }
345​
346 return this.enqueue(async () => {
347 await this.execute(`BEGIN IMMEDIATE`)
348 const transactionDriver = this.createTransactionDriver()
349 try {
350 const result = await this.runWithTransactionContext(
351 transactionDriver,
352 async () => fn(transactionDriver),
353 )
354 await this.execute(`COMMIT`)
355 return result
356 } catch (error) {
357 try {
358 await this.execute(`ROLLBACK`)
359 } catch {
360 // Keep the original transaction failure as the primary error.
361 }
362 throw error
363 }
364 })
365 }
366​
367 async close(): Promise<void> {
368 if (!this.ownsDatabase || typeof this.database.close !== `function`) {
369 return
370 }
371​
372 await Promise.resolve(this.database.close())
373 }
374​
375 getDatabase(): OpSQLiteDatabaseLike {
376 return this.database
377 }
378​
379 private async execute(
380 sql: string,
381 params: ReadonlyArray<unknown> = [],
382 ): Promise<unknown> {
383 const normalizedParams =
384 params.length > 0
385 ? [...params]
386 : (undefined as ReadonlyArray<unknown> | undefined)
387 const result = this.executeMethod.call(this.database, sql, normalizedParams)
388 return Promise.resolve(result)
389 }
390​
391 private enqueue<T>(operation: () => Promise<T>): Promise<T> {
392 const queuedOperation = this.queue.then(operation, operation)
393 this.queue = queuedOperation.then(
394 () => undefined,
395 () => undefined,
396 )
397 return queuedOperation
398 }
399​
400 private async getTransactionContextStorage(): Promise<AsyncLocalStorageLike<TransactionContextStore> | null> {
401 if (this.transactionContextStoragePromise) {
402 return this.transactionContextStoragePromise
403 }
404​
405 this.transactionContextStoragePromise = (async () => {
406 const asyncLocalStorageCtor = await resolveAsyncLocalStorageCtor()
407 if (!asyncLocalStorageCtor) {
408 return null
409 }
410​
411 return new asyncLocalStorageCtor<TransactionContextStore>()
412 })()
413​
414 return this.transactionContextStoragePromise
415 }
416​
417 private async getActiveTransactionDriver(): Promise<SQLiteDriver | null> {
418 const transactionContextStorage = await this.getTransactionContextStorage()
419 const store = transactionContextStorage?.getStore()
420 return store?.transactionDriver ?? null
421 }
422​
423 private async runWithTransactionContext<TResult>(
424 transactionDriver: SQLiteDriver,
425 callback: () => Promise<TResult>,
426 ): Promise<TResult> {
427 const transactionContextStorage = await this.getTransactionContextStorage()
428 if (!transactionContextStorage) {
429 return callback()
430 }
431​
432 return transactionContextStorage.run({ transactionDriver }, callback)
433 }
434​
435 private createTransactionDriver(): SQLiteDriver {
436 const transactionDriver: SQLiteDriver = {
437 exec: async (sql) => {
438 await this.execute(sql)
439 },
440 query: async <T>(
441 sql: string,
442 params: ReadonlyArray<unknown> = [],
443 ): Promise<ReadonlyArray<T>> => {
444 const result = await this.execute(sql, params)
445 return extractRowsFromExecuteResult(result, sql) as ReadonlyArray<T>
446 },
447 run: async (sql, params = []) => {
448 await this.execute(sql, params)
449 },
450 transaction: async <T>(
451 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
452 ): Promise<T> => {
453 assertTransactionCallbackHasDriverArg(fn)
454 return this.runNestedTransaction(transactionDriver, async (driver) => {
455 return fn(driver)
456 })
457 },
458 transactionWithDriver: async <T>(
459 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
460 ): Promise<T> => this.runNestedTransaction(transactionDriver, fn),
461 }
462​
463 return transactionDriver
464 }
465​
466 private async runNestedTransaction<T>(
467 transactionDriver: SQLiteDriver,
468 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
469 ): Promise<T> {
470 const savepointName = `tsdb_sp_${this.nextSavepointId}`
471 this.nextSavepointId++
472 await this.execute(`SAVEPOINT ${savepointName}`)
473​
474 try {
475 const result = await fn(transactionDriver)
476 await this.execute(`RELEASE SAVEPOINT ${savepointName}`)
477 return result
478 } catch (error) {
479 await this.execute(`ROLLBACK TO SAVEPOINT ${savepointName}`)
480 await this.execute(`RELEASE SAVEPOINT ${savepointName}`)
481 throw error
482 }
483 }
485​
486export function createOpSQLiteDriver(
487 options: OpSQLiteDriverOptions,
488): OpSQLiteDriver {
489 return new OpSQLiteDriver(options)