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

op-sqlite-driver.ts

743 lines20.3 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​
15const WRITE_RESULT_KEYS = new Set([
16 `rowsAffected`,
17 `changes`,
18 `insertId`,
19 `lastInsertRowId`,
20])
21​
22const STATEMENT_RESULT_KEYS = new Set([
23 ...WRITE_RESULT_KEYS,
24 `rows`,
25 `resultRows`,
26 `rawRows`,
27 `columnNames`,
28 `results`,
29 `metadata`,
30])
31​
32export type OpSQLiteDatabaseLike = {
33 execute?: OpSQLiteExecuteFn
34 executeAsync?: OpSQLiteExecuteFn
35 executeRaw?: OpSQLiteExecuteFn
36 execAsync?: OpSQLiteExecuteFn
37 close?: () => Promise<void> | void
39​
40export type OpSQLiteArrayResultMode = `rows` | `statement-results`
41​
42type OpSQLiteResultOptions = {
43 /**
44 * Declares how to interpret a bare array when its first entry could be either
45 * a data row or a statement-result envelope. Published op-sqlite methods
46 * return object envelopes and do not need this option.
47 */
48 arrayResultMode?: OpSQLiteArrayResultMode
50​
51type OpSQLiteExistingDatabaseOptions = OpSQLiteResultOptions & {
52 database: OpSQLiteDatabaseLike
54​
55type OpSQLiteOpenDatabaseOptions = OpSQLiteResultOptions & {
56 openDatabase: () => OpSQLiteDatabaseLike
58​
59export type OpSQLiteDriverOptions =
60 OpSQLiteExistingDatabaseOptions | OpSQLiteOpenDatabaseOptions
61​
62type TransactionContextStore = {
63 transactionDriver: SQLiteDriver
65​
66type AsyncLocalStorageLike<TStore> = {
67 getStore: () => TStore | undefined
68 run: <TResult>(store: TStore, callback: () => TResult) => TResult
70​
71type AsyncLocalStorageCtor = new <TStore>() => AsyncLocalStorageLike<TStore>
72​
73type DatabaseExecutionState = {
74 queue: Promise<void>
75 nextSavepointId: number
76 transactionContextStoragePromise: Promise<AsyncLocalStorageLike<TransactionContextStore> | null> | null
78​
79const databaseExecutionStates = new WeakMap<
80 OpSQLiteDatabaseLike,
81 DatabaseExecutionState
82>()
83​
84function getDatabaseExecutionState(
85 database: OpSQLiteDatabaseLike,
86): DatabaseExecutionState {
87 const existing = databaseExecutionStates.get(database)
88 if (existing) {
89 return existing
90 }
91​
92 const state: DatabaseExecutionState = {
93 queue: Promise.resolve(),
94 nextSavepointId: 1,
95 transactionContextStoragePromise: null,
96 }
97 databaseExecutionStates.set(database, state)
98 return state
100​
101let asyncLocalStorageCtorPromise: Promise<AsyncLocalStorageCtor | null> | null =
102 null
103​
104function canAttemptNodeAsyncLocalStorageLoad(): boolean {
105 if (typeof process === `undefined`) {
106 return false
107 }
108 // In React Native, process is polyfilled but process.versions may not exist
109 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
110 return typeof process.versions?.node === `string`
112​
113function getNodeAsyncHooksSpecifier(): string {
114 const moduleName = `async_hooks`
115 return `node:${moduleName}`
117​
118async function resolveAsyncLocalStorageCtor(): Promise<AsyncLocalStorageCtor | null> {
119 if (asyncLocalStorageCtorPromise) {
120 return asyncLocalStorageCtorPromise
121 }
122​
123 asyncLocalStorageCtorPromise = (async () => {
124 if (!canAttemptNodeAsyncLocalStorageLoad()) {
125 return null
126 }
127​
128 try {
129 // Use Function constructor to hide the dynamic import from React Native
130 // bundlers — Metro rejects non-literal dynamic import() at transform time.
131 // On React Native this code path is never reached (guarded above).
132 const importFn = new Function(`s`, `return import(s)`) as (
133 specifier: string,
134 ) => Promise<{
135 AsyncLocalStorage?: AsyncLocalStorageCtor
136 }>
137 const asyncHooksModule = await importFn(getNodeAsyncHooksSpecifier())
138​
139 return typeof asyncHooksModule.AsyncLocalStorage === `function`
140 ? asyncHooksModule.AsyncLocalStorage
141 : null
142 } catch {
143 return null
144 }
145 })()
146​
147 return asyncLocalStorageCtorPromise
149​
150function isObjectRecord(value: unknown): value is Record<string, unknown> {
151 return typeof value === `object` && value !== null
153​
154function hasOwnKey(value: Record<string, unknown>, key: string): boolean {
155 return Object.prototype.hasOwnProperty.call(value, key)
157​
158function rejectInheritedCarrierKeys(
159 value: Record<string, unknown>,
160 sql: string,
161): void {
162 for (const key of [
163 `rows`,
164 `resultRows`,
165 `rawRows`,
166 `columnNames`,
167 `results`,
168 ]) {
169 if (!hasOwnKey(value, key) && key in value) {
170 unsupportedQueryResult(sql, `inherited ${key} carrier`)
171 }
172 }
174​
175function hasWriteResultMarker(value: Record<string, unknown>): boolean {
176 for (const key of WRITE_RESULT_KEYS) {
177 if (hasOwnKey(value, key)) {
178 return true
179 }
180 }
181 return false
183​
184function isWriteResultEnvelope(value: Record<string, unknown>): boolean {
185 return (
186 hasWriteResultMarker(value) &&
187 Object.keys(value).every((key) => WRITE_RESULT_KEYS.has(key))
188 )
190​
191function unsupportedQueryResult(sql: string, details?: string): never {
192 throw new InvalidPersistedCollectionConfigError(
193 `Unsupported op-sqlite query result shape for SQL "${sql}"${
194 details ? `: ${details}` : ``
195 }`,
196 )
198​
199function isValidRowList(
200 rowsObject: OpSQLiteRowListLike,
201): rowsObject is OpSQLiteRowListLike & {
202 length: number
203 item: (index: number) => unknown
204} {
205 return (
206 typeof rowsObject.length === `number` &&
207 Number.isSafeInteger(rowsObject.length) &&
208 rowsObject.length >= 0 &&
209 typeof rowsObject.item === `function`
210 )
212​
213function toRowArray(rowsValue: unknown): Array<unknown> | null {
214 if (Array.isArray(rowsValue)) {
215 return rowsValue
216 }
217​
218 if (!isObjectRecord(rowsValue)) {
219 return null
220 }
221​
222 const rowsObject = rowsValue as OpSQLiteRowListLike
223 if (Array.isArray(rowsObject._array)) {
224 return rowsObject._array
225 }
226​
227 if (isValidRowList(rowsObject)) {
228 const rows: Array<unknown> = []
229 for (let index = 0; index < rowsObject.length; index++) {
230 rows.push(rowsObject.item(index))
231 }
232 return rows
233 }
234​
235 return null
237​
238function isRowCarrier(rowsValue: unknown): boolean {
239 if (Array.isArray(rowsValue)) {
240 return true
241 }
242​
243 if (!isObjectRecord(rowsValue)) {
244 return false
245 }
246​
247 const rowsObject = rowsValue as OpSQLiteRowListLike
248 return Array.isArray(rowsObject._array) || isValidRowList(rowsObject)
250​
251function isStatementResultEnvelope(value: Record<string, unknown>): boolean {
252 if (!Object.keys(value).every((key) => STATEMENT_RESULT_KEYS.has(key))) {
253 return false
254 }
255​
256 // Bare arrays are also a supported row carrier. A legitimate row can contain
257 // only write-marker aliases, so markers alone cannot prove that an array is a
258 // statement wrapper; wrappers need an actual row structure.
259 const hasRowCarrier =
260 isRowCarrier(value.rows) ||
261 isRowCarrier(value.resultRows) ||
262 Array.isArray(value.results)
263 const hasStructuralCarrier =
264 hasRowCarrier ||
265 Array.isArray(value.rawRows) ||
266 Array.isArray(value.columnNames)
267​
268 return (
269 hasRowCarrier ||
270 (hasWriteResultMarker(value) && hasStructuralCarrier) ||
271 (Array.isArray(value.rawRows) && Array.isArray(value.columnNames))
272 )
274​
275function decodeColumnarRows(
276 value: Record<string, unknown>,
277 sql: string,
278): Array<Record<string, unknown>> | null {
279 const hasRawRows = hasOwnKey(value, `rawRows`)
280 const hasColumnNames = hasOwnKey(value, `columnNames`)
281 if (!hasRawRows && !hasColumnNames) {
282 return null
283 }
284​
285 if (!hasRawRows || !hasColumnNames) {
286 unsupportedQueryResult(
287 sql,
288 `columnar results require both rawRows and columnNames`,
289 )
290 }
291 const rawRows = value.rawRows
292 const columnNames = value.columnNames
293 if (
294 !Array.isArray(rawRows) ||
295 !Array.isArray(columnNames) ||
296 !columnNames.every((columnName) => typeof columnName === `string`)
297 ) {
298 unsupportedQueryResult(sql, `invalid columnar row or column metadata`)
299 }
300​
301 if (rawRows.length > 0 && columnNames.length === 0) {
302 unsupportedQueryResult(
303 sql,
304 `nonempty columnar results require at least one column name`,
305 )
306 }
307​
308 return rawRows.map((rawRow) => {
309 if (!Array.isArray(rawRow) || rawRow.length !== columnNames.length) {
310 unsupportedQueryResult(
311 sql,
312 `columnar row width does not match columnNames`,
313 )
314 }
315​
316 const row: Record<string, unknown> = {}
317 for (let index = 0; index < columnNames.length; index++) {
318 const columnName = columnNames[index]!
319 if (columnName === `__proto__`) {
320 Object.defineProperty(row, columnName, {
321 configurable: true,
322 enumerable: true,
323 value: rawRow[index],
324 writable: true,
325 })
326 } else {
327 row[columnName] = rawRow[index]
328 }
329 }
330 return row
331 })
333​
334function rejectPositionalRows(
335 rows: Array<unknown>,
336 sql: string,
337): Array<unknown> {
338 if (rows.some((row) => Array.isArray(row))) {
339 unsupportedQueryResult(sql, `positional rows require column metadata`)
340 }
341 return rows
343​
344function extractRowsFromStatementResult(
345 record: Record<string, unknown>,
346 sql: string,
347 allowResultsWrapper: boolean,
348): Array<unknown> {
349 rejectInheritedCarrierKeys(record, sql)
350 const rowCarrierKeys = [`rows`, `resultRows`].filter((key) =>
351 hasOwnKey(record, key),
352 )
353 const rowCarrierKey = rowCarrierKeys[0]
354 if (
355 rowCarrierKeys.length > 1 ||
356 (rowCarrierKeys.length > 0 &&
357 (hasOwnKey(record, `results`) ||
358 (rowCarrierKey === `resultRows` && hasOwnKey(record, `rawRows`))))
359 ) {
360 unsupportedQueryResult(sql, `query result contains conflicting carriers`)
361 }
362​
363 if (rowCarrierKeys.length === 1) {
364 const rows = toRowArray(record[rowCarrierKey!])
365 if (!rows) {
366 unsupportedQueryResult(sql, `invalid ${rowCarrierKey} carrier`)
367 }
368 return rejectPositionalRows(rows, sql)
369 }
370​
371 if (
372 (hasOwnKey(record, `rawRows`) || hasOwnKey(record, `columnNames`)) &&
373 hasOwnKey(record, `results`)
374 ) {
375 unsupportedQueryResult(sql, `query result contains conflicting carriers`)
376 }
377​
378 const columnarRows = decodeColumnarRows(record, sql)
379 if (columnarRows) {
380 return columnarRows
381 }
382​
383 if (hasOwnKey(record, `results`)) {
384 if (!allowResultsWrapper) {
385 unsupportedQueryResult(sql, `unsupported nested results depth`)
386 }
387 const nestedResults = record.results
388 if (
389 !Array.isArray(nestedResults) ||
390 nestedResults.length !== 1 ||
391 !isObjectRecord(nestedResults[0])
392 ) {
393 unsupportedQueryResult(sql, `invalid nested results carrier`)
394 }
395 return extractRowsFromStatementResult(nestedResults[0], sql, false)
396 }
397​
398 if (isWriteResultEnvelope(record)) {
399 return []
400 }
401​
402 return unsupportedQueryResult(sql)
404​
405function extractRowsFromExecuteResult(
406 result: unknown,
407 sql: string,
408 arrayResultMode?: OpSQLiteArrayResultMode,
409): Array<unknown> {
410 if (result == null) {
411 return unsupportedQueryResult(sql)
412 }
413​
414 if (Array.isArray(result)) {
415 if (result.length === 0) {
416 if (arrayResultMode === `statement-results`) {
417 return unsupportedQueryResult(
418 sql,
419 `statement-result arrays must contain exactly one result`,
420 )
421 }
422 return []
423 }
424​
425 if (arrayResultMode === `rows`) {
426 return rejectPositionalRows(result, sql)
427 }
428​
429 const firstEntry = result[0]
430 const isStructuralStatementResult =
431 isObjectRecord(firstEntry) && isStatementResultEnvelope(firstEntry)
432 if (arrayResultMode === `statement-results`) {
433 if (!isObjectRecord(firstEntry)) {
434 return unsupportedQueryResult(
435 sql,
436 `statement-results mode requires an object statement envelope`,
437 )
438 }
439 if (result.length !== 1) {
440 return unsupportedQueryResult(
441 sql,
442 `statement-result arrays must contain exactly one result`,
443 )
444 }
445 return extractRowsFromStatementResult(firstEntry, sql, false)
446 }
447​
448 if (isStructuralStatementResult) {
449 return unsupportedQueryResult(
450 sql,
451 `ambiguous bare result array; set arrayResultMode to "rows" or "statement-results"`,
452 )
453 }
454​
455 return rejectPositionalRows(result, sql)
456 }
457​
458 if (isObjectRecord(result)) {
459 return extractRowsFromStatementResult(result, sql, true)
460 }
461​
462 return unsupportedQueryResult(sql)
464​
465function hasExistingDatabase(
466 options: OpSQLiteDriverOptions,
467): options is OpSQLiteExistingDatabaseOptions {
468 return `database` in options
470​
471function assertTransactionCallbackHasDriverArg(
472 fn: (transactionDriver: SQLiteDriver) => Promise<unknown>,
473): void {
474 if (fn.length > 0) {
475 return
476 }
477​
478 throw new InvalidPersistedCollectionConfigError(
479 `SQLiteDriver.transaction callback must accept the transaction driver argument`,
480 )
482​
483function resolveExecuteMethod(
484 database: OpSQLiteDatabaseLike,
485): OpSQLiteExecuteFn {
486 const executeCandidates: Array<unknown> = [
487 database.executeAsync,
488 database.execute,
489 database.executeRaw,
490 database.execAsync,
491 ]
492 const executeMethod = executeCandidates.find(
493 (candidate) => typeof candidate === `function`,
494 )
495​
496 if (typeof executeMethod !== `function`) {
497 throw new InvalidPersistedCollectionConfigError(
498 `op-sqlite database object must provide execute/executeAsync/executeRaw/execAsync`,
499 )
500 }
501​
502 return executeMethod as OpSQLiteExecuteFn
504​
505export class OpSQLiteDriver implements SQLiteDriver {
506 private readonly database: OpSQLiteDatabaseLike
507 private readonly executeMethod: OpSQLiteExecuteFn
508 private readonly arrayResultMode: OpSQLiteArrayResultMode | undefined
509 private readonly ownsDatabase: boolean
510 private readonly executionState: DatabaseExecutionState
511​
512 constructor(options: OpSQLiteDriverOptions) {
513 if (hasExistingDatabase(options)) {
514 this.database = options.database
515 this.ownsDatabase = false
516 } else {
517 this.database = options.openDatabase()
518 this.ownsDatabase = true
519 }
520​
521 this.executeMethod = resolveExecuteMethod(this.database)
522 this.arrayResultMode = options.arrayResultMode
523 this.executionState = getDatabaseExecutionState(this.database)
524 }
525​
526 async exec(sql: string): Promise<void> {
527 const activeTransactionDriver = await this.getActiveTransactionDriver()
528 if (activeTransactionDriver) {
529 await activeTransactionDriver.exec(sql)
530 return
531 }
532​
533 await this.enqueue(async () => {
534 await this.execute(sql)
535 })
536 }
537​
538 async query<T>(
539 sql: string,
540 params: ReadonlyArray<unknown> = [],
541 ): Promise<ReadonlyArray<T>> {
542 const activeTransactionDriver = await this.getActiveTransactionDriver()
543 if (activeTransactionDriver) {
544 return activeTransactionDriver.query<T>(sql, params)
545 }
546​
547 return this.enqueue(async () => {
548 const result = await this.execute(sql, params)
549 return extractRowsFromExecuteResult(
550 result,
551 sql,
552 this.arrayResultMode,
553 ) as ReadonlyArray<T>
554 })
555 }
556​
557 async run(sql: string, params: ReadonlyArray<unknown> = []): Promise<void> {
558 const activeTransactionDriver = await this.getActiveTransactionDriver()
559 if (activeTransactionDriver) {
560 await activeTransactionDriver.run(sql, params)
561 return
562 }
563​
564 await this.enqueue(async () => {
565 await this.execute(sql, params)
566 })
567 }
568​
569 async transaction<T>(
570 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
571 ): Promise<T> {
572 assertTransactionCallbackHasDriverArg(fn)
573​
574 const activeTransactionDriver = await this.getActiveTransactionDriver()
575 if (activeTransactionDriver) {
576 return activeTransactionDriver.transaction(fn)
577 }
578​
579 return this.transactionWithDriver((transactionDriver) =>
580 fn(transactionDriver),
581 )
582 }
583​
584 async transactionWithDriver<T>(
585 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
586 ): Promise<T> {
587 const activeTransactionDriver = await this.getActiveTransactionDriver()
588 if (
589 activeTransactionDriver &&
590 typeof activeTransactionDriver.transactionWithDriver === `function`
591 ) {
592 return activeTransactionDriver.transactionWithDriver(fn)
593 }
594​
595 return this.enqueue(async () => {
596 await this.execute(`BEGIN IMMEDIATE`)
597 const transactionDriver = this.createTransactionDriver()
598 try {
599 const result = await this.runWithTransactionContext(
600 transactionDriver,
601 async () => fn(transactionDriver),
602 )
603 await this.execute(`COMMIT`)
604 return result
605 } catch (error) {
606 try {
607 await this.execute(`ROLLBACK`)
608 } catch {
609 // Keep the original transaction failure as the primary error.
610 }
611 throw error
612 }
613 })
614 }
615​
616 async close(): Promise<void> {
617 if (!this.ownsDatabase || typeof this.database.close !== `function`) {
618 return
619 }
620​
621 await Promise.resolve(this.database.close())
622 }
623​
624 getDatabase(): OpSQLiteDatabaseLike {
625 return this.database
626 }
627​
628 private async execute(
629 sql: string,
630 params: ReadonlyArray<unknown> = [],
631 ): Promise<unknown> {
632 const normalizedParams =
633 params.length > 0
634 ? [...params]
635 : (undefined as ReadonlyArray<unknown> | undefined)
636 const result = this.executeMethod.call(this.database, sql, normalizedParams)
637 return Promise.resolve(result)
638 }
639​
640 private enqueue<T>(operation: () => Promise<T>): Promise<T> {
641 const queuedOperation = this.executionState.queue.then(operation, operation)
642 this.executionState.queue = queuedOperation.then(
643 () => undefined,
644 () => undefined,
645 )
646 return queuedOperation
647 }
648​
649 private async getTransactionContextStorage(): Promise<AsyncLocalStorageLike<TransactionContextStore> | null> {
650 if (this.executionState.transactionContextStoragePromise) {
651 return this.executionState.transactionContextStoragePromise
652 }
653​
654 this.executionState.transactionContextStoragePromise = (async () => {
655 const asyncLocalStorageCtor = await resolveAsyncLocalStorageCtor()
656 if (!asyncLocalStorageCtor) {
657 return null
658 }
659​
660 return new asyncLocalStorageCtor<TransactionContextStore>()
661 })()
662​
663 return this.executionState.transactionContextStoragePromise
664 }
665​
666 private async getActiveTransactionDriver(): Promise<SQLiteDriver | null> {
667 const transactionContextStorage = await this.getTransactionContextStorage()
668 const store = transactionContextStorage?.getStore()
669 return store?.transactionDriver ?? null
670 }
671​
672 private async runWithTransactionContext<TResult>(
673 transactionDriver: SQLiteDriver,
674 callback: () => Promise<TResult>,
675 ): Promise<TResult> {
676 const transactionContextStorage = await this.getTransactionContextStorage()
677 if (!transactionContextStorage) {
678 return callback()
679 }
680​
681 return transactionContextStorage.run({ transactionDriver }, callback)
682 }
683​
684 private createTransactionDriver(): SQLiteDriver {
685 const transactionDriver: SQLiteDriver = {
686 exec: async (sql) => {
687 await this.execute(sql)
688 },
689 query: async <T>(
690 sql: string,
691 params: ReadonlyArray<unknown> = [],
692 ): Promise<ReadonlyArray<T>> => {
693 const result = await this.execute(sql, params)
694 return extractRowsFromExecuteResult(
695 result,
696 sql,
697 this.arrayResultMode,
698 ) as ReadonlyArray<T>
699 },
700 run: async (sql, params = []) => {
701 await this.execute(sql, params)
702 },
703 transaction: async <T>(
704 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
705 ): Promise<T> => {
706 assertTransactionCallbackHasDriverArg(fn)
707 return this.runNestedTransaction(transactionDriver, async (driver) => {
708 return fn(driver)
709 })
710 },
711 transactionWithDriver: async <T>(
712 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
713 ): Promise<T> => this.runNestedTransaction(transactionDriver, fn),
714 }
715​
716 return transactionDriver
717 }
718​
719 private async runNestedTransaction<T>(
720 transactionDriver: SQLiteDriver,
721 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
722 ): Promise<T> {
723 const savepointName = `tsdb_sp_${this.executionState.nextSavepointId}`
724 this.executionState.nextSavepointId++
725 await this.execute(`SAVEPOINT ${savepointName}`)
726​
727 try {
728 const result = await fn(transactionDriver)
729 await this.execute(`RELEASE SAVEPOINT ${savepointName}`)
730 return result
731 } catch (error) {
732 await this.execute(`ROLLBACK TO SAVEPOINT ${savepointName}`)
733 await this.execute(`RELEASE SAVEPOINT ${savepointName}`)
734 throw error
735 }
736 }
738​
739export function createOpSQLiteDriver(
740 options: OpSQLiteDriverOptions,
741): OpSQLiteDriver {
742 return new OpSQLiteDriver(options)