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

do-driver.ts

263 lines7.4 KB

1import { InvalidPersistedCollectionConfigError } from '@tanstack/db-sqlite-persistence-core'
2import type { SQLiteDriver } from '@tanstack/db-sqlite-persistence-core'
3​
4type DurableObjectSqlRow = Record<string, unknown>
5​
6type DurableObjectSqlCursorLike = Iterable<DurableObjectSqlRow> & {
7 toArray?: () => Array<DurableObjectSqlRow>
8}
9​
10export type DurableObjectSqlStorageLike = {
11 exec: (
12 sql: string,
13 ...params: ReadonlyArray<unknown>
14 ) => DurableObjectSqlCursorLike | ReadonlyArray<DurableObjectSqlRow> | null
16​
17export type DurableObjectTransactionExecutor = <T>(
18 fn: () => Promise<T>,
19) => Promise<T>
20​
21export type DurableObjectStorageLike = {
22 sql: DurableObjectSqlStorageLike
23 transaction?: DurableObjectTransactionExecutor
25​
26type CloudflareDOProvidedSqlOptions = {
27 sql: DurableObjectSqlStorageLike
28 transaction?: DurableObjectTransactionExecutor
30​
31type CloudflareDOProvidedStorageOptions = {
32 storage: DurableObjectStorageLike
34​
35export type CloudflareDOSQLiteDriverOptions =
36 | CloudflareDOProvidedSqlOptions
37 | CloudflareDOProvidedStorageOptions
38​
39function assertTransactionCallbackHasDriverArg(
40 fn: (transactionDriver: SQLiteDriver) => Promise<unknown>,
41): void {
42 if (fn.length > 0) {
43 return
44 }
45​
46 throw new InvalidPersistedCollectionConfigError(
47 `SQLiteDriver.transaction callback must accept the transaction driver argument`,
48 )
50​
51function isIterableRecord(
52 value: unknown,
53): value is Iterable<DurableObjectSqlRow> {
54 if (!value || typeof value !== `object`) {
55 return false
56 }
57​
58 const iterator = (value as { [Symbol.iterator]?: unknown })[Symbol.iterator]
59 return typeof iterator === `function`
61​
62function toRowArray<T>(
63 result: ReturnType<DurableObjectSqlStorageLike[`exec`]>,
64 sql: string,
65): ReadonlyArray<T> {
66 if (result == null) {
67 return []
68 }
69​
70 if (Array.isArray(result)) {
71 return result as ReadonlyArray<T>
72 }
73​
74 const cursorResult = result as DurableObjectSqlCursorLike
75 if (typeof cursorResult.toArray === `function`) {
76 return cursorResult.toArray() as ReadonlyArray<T>
77 }
78​
79 if (isIterableRecord(cursorResult)) {
80 return Array.from(cursorResult as Iterable<T>)
81 }
82​
83 throw new InvalidPersistedCollectionConfigError(
84 `Unsupported Durable Object SQL result shape for query "${sql}"`,
85 )
87​
88export class CloudflareDOSQLiteDriver implements SQLiteDriver {
89 private readonly sqlStorage: DurableObjectSqlStorageLike
90 private readonly storage: DurableObjectStorageLike
91 private readonly transactionExecutor: DurableObjectTransactionExecutor | null
92 private queue: Promise<void> = Promise.resolve()
93 private nextSavepointId = 1
94​
95 constructor(options: CloudflareDOSQLiteDriverOptions) {
96 const resolvedStorage: DurableObjectStorageLike =
97 `storage` in options
98 ? options.storage
99 : {
100 sql: options.sql,
101 ...(typeof options.transaction === `function`
102 ? { transaction: options.transaction }
103 : {}),
104 }
105 const resolvedSqlStorage = resolvedStorage.sql
106 if (typeof resolvedSqlStorage.exec !== `function`) {
107 throw new InvalidPersistedCollectionConfigError(
108 `Cloudflare DO SQL driver requires a sql.exec function`,
109 )
110 }
111 this.storage = resolvedStorage
112 this.sqlStorage = resolvedSqlStorage
113 if (typeof resolvedStorage.transaction === `function`) {
114 const transactionMethod = resolvedStorage.transaction
115 this.transactionExecutor = <T>(fn: () => Promise<T>) =>
116 Promise.resolve(
117 transactionMethod.call(resolvedStorage, fn) as Promise<T> | T,
118 )
119 } else {
120 this.transactionExecutor = null
121 }
122 }
123​
124 async exec(sql: string): Promise<void> {
125 await this.enqueue(() => {
126 this.execute(sql)
127 })
128 }
129​
130 async query<T>(
131 sql: string,
132 params: ReadonlyArray<unknown> = [],
133 ): Promise<ReadonlyArray<T>> {
134 return this.enqueue(() => this.executeQuery<T>(sql, params))
135 }
136​
137 async run(sql: string, params: ReadonlyArray<unknown> = []): Promise<void> {
138 await this.enqueue(() => {
139 this.execute(sql, params)
140 })
141 }
142​
143 async transaction<T>(
144 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
145 ): Promise<T> {
146 assertTransactionCallbackHasDriverArg(fn)
147​
148 return this.enqueue(async () => {
149 const transactionDriver = this.createTransactionDriver()
150 if (this.transactionExecutor) {
151 return this.transactionExecutor(() => fn(transactionDriver))
152 }
153​
154 this.execute(`BEGIN IMMEDIATE`)
155 try {
156 const result = await fn(transactionDriver)
157 this.execute(`COMMIT`)
158 return result
159 } catch (error) {
160 try {
161 this.execute(`ROLLBACK`)
162 } catch {
163 // Keep the original transaction error as the primary failure.
164 }
165 throw error
166 }
167 })
168 }
169​
170 async transactionWithDriver<T>(
171 fn: (transactionDriver: SQLiteDriver) => Promise<T>,
172 ): Promise<T> {
173 return this.transaction(fn)
174 }
175​
176 getStorage(): DurableObjectStorageLike {
177 return this.storage
178 }
179​
180 private execute(sql: string, params: ReadonlyArray<unknown> = []): unknown {
181 return this.sqlStorage.exec(sql, ...params)
182 }
183​
184 private executeQuery<T>(
185 sql: string,
186 params: ReadonlyArray<unknown>,
187 ): ReadonlyArray<T> {
188 const result = this.execute(sql, params)
189 return toRowArray<T>(
190 result as ReturnType<DurableObjectSqlStorageLike[`exec`]>,
191 sql,
192 )
193 }
194​
195 private enqueue<T>(operation: () => Promise<T> | T): Promise<T> {
196 const queuedOperation = this.queue.then(operation, operation)
197 this.queue = queuedOperation.then(
198 () => undefined,
199 () => undefined,
200 )
201 return queuedOperation
202 }
203​
204 private createTransactionDriver(): SQLiteDriver {
205 const transactionDriver: SQLiteDriver = {
206 exec: (sql) => {
207 this.execute(sql)
208 return Promise.resolve()
209 },
210 query: <T>(
211 sql: string,
212 params: ReadonlyArray<unknown> = [],
213 ): Promise<ReadonlyArray<T>> =>
214 Promise.resolve(this.executeQuery<T>(sql, params)),
215 run: (sql, params = []) => {
216 this.execute(sql, params)
217 return Promise.resolve()
218 },
219 transaction: <T>(
220 fn: (nestedDriver: SQLiteDriver) => Promise<T>,
221 ): Promise<T> => {
222 assertTransactionCallbackHasDriverArg(fn)
223 return this.runNestedTransaction(transactionDriver, fn)
224 },
225 transactionWithDriver: <T>(
226 fn: (nestedDriver: SQLiteDriver) => Promise<T>,
227 ): Promise<T> => this.runNestedTransaction(transactionDriver, fn),
228 }
229​
230 return transactionDriver
231 }
232​
233 private async runNestedTransaction<T>(
234 transactionDriver: SQLiteDriver,
235 fn: (nestedDriver: SQLiteDriver) => Promise<T>,
236 ): Promise<T> {
237 if (this.transactionExecutor) {
238 throw new InvalidPersistedCollectionConfigError(
239 `Nested SQL savepoints are not supported when using Durable Object transaction API`,
240 )
241 }
242​
243 const savepointName = `tsdb_sp_${this.nextSavepointId}`
244 this.nextSavepointId++
245 this.execute(`SAVEPOINT ${savepointName}`)
246​
247 try {
248 const result = await fn(transactionDriver)
249 this.execute(`RELEASE SAVEPOINT ${savepointName}`)
250 return result
251 } catch (error) {
252 this.execute(`ROLLBACK TO SAVEPOINT ${savepointName}`)
253 this.execute(`RELEASE SAVEPOINT ${savepointName}`)
254 throw error
255 }
256 }
258​
259export function createCloudflareDOSQLiteDriver(
260 options: CloudflareDOSQLiteDriverOptions,
261): CloudflareDOSQLiteDriver {
262 return new CloudflareDOSQLiteDriver(options)