Open History to see the last commit
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
13}
14
15type OpSQLiteStatementResultLike = {
16 rows?: unknown
17 resultRows?: unknown
18 rowsAffected?: unknown
19 changes?: unknown
20 insertId?: unknown
21 lastInsertRowId?: unknown
22}
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
37}
38
39type OpSQLiteExistingDatabaseOptions = {
40 database: OpSQLiteDatabaseLike
41}
42
43type OpSQLiteOpenDatabaseOptions = {
44 openDatabase: () => OpSQLiteDatabaseLike
45}
46
47export type OpSQLiteDriverOptions =
48 | OpSQLiteExistingDatabaseOptions
49 | OpSQLiteOpenDatabaseOptions
50
51type TransactionContextStore = {
52 transactionDriver: SQLiteDriver
53}
54
55type AsyncLocalStorageLike<TStore> = {
56 getStore: () => TStore | undefined
57 run: <TResult>(store: TStore, callback: () => TResult) => TResult
58}
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`
72}
73
74function getNodeAsyncHooksSpecifier(): string {
75 const moduleName = `async_hooks`
76 return `node:${moduleName}`
77}
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
109}
110
111function isObjectRecord(value: unknown): value is Record<string, unknown> {
112 return typeof value === `object` && value !== null
113}
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
122}
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
151}
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
171}
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 )
218}
219
220function hasExistingDatabase(
221 options: OpSQLiteDriverOptions,
222): options is OpSQLiteExistingDatabaseOptions {
223 return `database` in options
224}
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 )
236}
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
258}
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 }
484}
485
486export function createOpSQLiteDriver(
487 options: OpSQLiteDriverOptions,
488): OpSQLiteDriver {
489 return new OpSQLiteDriver(options)
490}