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

PowerSyncTransactor.ts

338 lines10.6 KB

1import { sanitizeSQL } from '@powersync/common'
2import DebugModule from 'debug'
3import { PendingOperationStore } from './PendingOperationStore'
4import { asPowerSyncRecord, mapOperationToPowerSync } from './helpers'
5import type { AbstractPowerSyncDatabase, LockContext } from '@powersync/common'
6import type { PendingMutation, Transaction } from '@tanstack/db'
7import type { PendingOperation } from './PendingOperationStore'
8import type {
9 EnhancedPowerSyncCollectionConfig,
10 PowerSyncCollectionMeta,
11} from './definitions'
12​
13const debug = DebugModule.debug(`ts/db:powersync`)
14​
15export type TransactorOptions = {
16 database: AbstractPowerSyncDatabase
18​
19/**
20 * Applies mutations to the PowerSync database. This method is called automatically by the collection's
21 * insert, update, and delete operations. You typically don't need to call this directly unless you
22 * have special transaction requirements.
23 *
24 * @example
25 * ```typescript
26 * // Create a collection
27 * const collection = createCollection(
28 * powerSyncCollectionOptions<Document>({
29 * database: db,
30 * table: APP_SCHEMA.props.documents,
31 * })
32 * )
33 *
34 * const addTx = createTransaction({
35 * autoCommit: false,
36 * mutationFn: async ({ transaction }) => {
37 * await new PowerSyncTransactor({ database: db }).applyTransaction(transaction)
38 * },
39 * })
40 *
41 * addTx.mutate(() => {
42 * for (let i = 0; i < 5; i++) {
43 * collection.insert({ id: randomUUID(), name: `tx-${i}` })
44 * }
45 * })
46 *
47 * await addTx.commit()
48 * await addTx.isPersisted.promise
49 * ```
50 *
51 * @param transaction - The transaction containing mutations to apply
52 * @returns A promise that resolves when the mutations have been persisted to PowerSync
53 */
54export class PowerSyncTransactor {
55 database: AbstractPowerSyncDatabase
56 pendingOperationStore: PendingOperationStore
57​
58 constructor(options: TransactorOptions) {
59 this.database = options.database
60 this.pendingOperationStore = PendingOperationStore.GLOBAL
61 }
62​
63 /**
64 * Persists a {@link Transaction} to the PowerSync SQLite database.
65 */
66 async applyTransaction(transaction: Transaction<any>) {
67 const { mutations } = transaction
68​
69 if (mutations.length == 0) {
70 return
71 }
72 /**
73 * The transaction might contain operations for different collections.
74 * We can do some optimizations for single-collection transactions.
75 */
76 const mutationsCollectionIds = mutations.map(
77 (mutation) => mutation.collection.id,
78 )
79 const collectionIds = Array.from(new Set(mutationsCollectionIds))
80 const lastCollectionMutationIndexes = new Map<string, number>()
81 const allCollections = collectionIds
82 .map((id) => mutations.find((mutation) => mutation.collection.id == id)!)
83 .map((mutation) => mutation.collection)
84 for (const collectionId of collectionIds) {
85 lastCollectionMutationIndexes.set(
86 collectionId,
87 mutationsCollectionIds.lastIndexOf(collectionId),
88 )
89 }
90​
91 // Check all the observers are ready before taking a lock
92 await Promise.all(
93 allCollections.map(async (collection) => {
94 if (collection.isReady()) {
95 return
96 }
97 await new Promise<void>((resolve) => collection.onFirstReady(resolve))
98 }),
99 )
100​
101 // Persist to PowerSync
102 const { whenComplete } = await this.database.writeTransaction(
103 async (tx) => {
104 const pendingOperations: Array<PendingOperation | null> = []
105​
106 for (const [index, mutation] of mutations.entries()) {
107 /**
108 * Each collection processes events independently. We need to make sure the
109 * last operation for each collection has been observed.
110 */
111 const shouldWait =
112 index == lastCollectionMutationIndexes.get(mutation.collection.id)
113 switch (mutation.type) {
114 case `insert`:
115 pendingOperations.push(
116 await this.handleInsert(mutation, tx, shouldWait),
117 )
118 break
119 case `update`:
120 pendingOperations.push(
121 await this.handleUpdate(mutation, tx, shouldWait),
122 )
123 break
124 case `delete`:
125 pendingOperations.push(
126 await this.handleDelete(mutation, tx, shouldWait),
127 )
128 break
129 }
130 }
131​
132 /**
133 * Return a promise from the writeTransaction, without awaiting it.
134 * This promise will resolve once the entire transaction has been
135 * observed via the diff triggers.
136 * We return without awaiting in order to free the write lock.
137 */
138 return {
139 whenComplete: Promise.all(
140 pendingOperations
141 .filter((op) => !!op)
142 .map((op) => this.pendingOperationStore.waitFor(op)),
143 ),
144 }
145 },
146 )
147​
148 // Wait for the change to be observed via the diff trigger
149 await whenComplete
150 }
151​
152 protected async handleInsert(
153 mutation: PendingMutation<any>,
154 context: LockContext,
155 waitForCompletion: boolean = false,
156 ): Promise<PendingOperation | null> {
157 debug(`insert`, mutation)
158​
159 return this.handleOperationWithCompletion(
160 mutation,
161 context,
162 waitForCompletion,
163 // eslint-disable-next-line no-shadow
164 async (tableName, mutation, serializeValue) => {
165 const values = serializeValue(mutation.modified)
166 const keys = Object.keys(values).map((key) => sanitizeSQL`${key}`)
167 const queryParameters = Object.values(values)
168​
169 const metadataValue = this.processMutationMetadata(mutation)
170 if (metadataValue != null) {
171 keys.push(`_metadata`)
172 queryParameters.push(metadataValue)
173 }
174​
175 await context.execute(
176 `
177 INSERT into ${tableName}
178 (${keys.join(`, `)})
179 VALUES
180 (${keys.map((_) => `?`).join(`, `)})
181 `,
182 queryParameters,
183 )
184 },
185 )
186 }
187​
188 protected async handleUpdate(
189 mutation: PendingMutation<any>,
190 context: LockContext,
191 waitForCompletion: boolean = false,
192 ): Promise<PendingOperation | null> {
193 debug(`update`, mutation)
194​
195 return this.handleOperationWithCompletion(
196 mutation,
197 context,
198 waitForCompletion,
199 // eslint-disable-next-line no-shadow
200 async (tableName, mutation, serializeValue) => {
201 const values = serializeValue(mutation.modified)
202 const keys = Object.keys(values).map((key) => sanitizeSQL`${key}`)
203 const queryParameters = Object.values(values)
204​
205 const metadataValue = this.processMutationMetadata(mutation)
206 if (metadataValue != null) {
207 keys.push(`_metadata`)
208 queryParameters.push(metadataValue)
209 }
210​
211 await context.execute(
212 `
213 UPDATE ${tableName}
214 SET ${keys.map((key) => `${key} = ?`).join(`, `)}
215 WHERE id = ?
216 `,
217 [...queryParameters, asPowerSyncRecord(mutation.modified).id],
218 )
219 },
220 )
221 }
222​
223 protected async handleDelete(
224 mutation: PendingMutation<any>,
225 context: LockContext,
226 waitForCompletion: boolean = false,
227 ): Promise<PendingOperation | null> {
228 debug(`update`, mutation)
229​
230 return this.handleOperationWithCompletion(
231 mutation,
232 context,
233 waitForCompletion,
234 // eslint-disable-next-line no-shadow
235 async (tableName, mutation) => {
236 const metadataValue = this.processMutationMetadata(mutation)
237 if (metadataValue != null) {
238 /**
239 * Delete operations with metadata require a different approach to handle metadata.
240 * This will delete the record.
241 */
242 await context.execute(
243 `
244 UPDATE ${tableName} SET _deleted = TRUE, _metadata = ? WHERE id = ?
245 `,
246 [metadataValue, asPowerSyncRecord(mutation.original).id],
247 )
248 } else {
249 await context.execute(
250 `
251 DELETE FROM ${tableName} WHERE id = ?
252 `,
253 [asPowerSyncRecord(mutation.original).id],
254 )
255 }
256 },
257 )
258 }
259​
260 /**
261 * Helper function which wraps a persistence operation by:
262 * - Fetching the mutation's collection's SQLite table details
263 * - Executing the mutation
264 * - Returning the last pending diff operation if required
265 */
266 protected async handleOperationWithCompletion(
267 mutation: PendingMutation<any>,
268 context: LockContext,
269 waitForCompletion: boolean,
270 handler: (
271 tableName: string,
272 mutation: PendingMutation<any>,
273 serializeValue: (value: any) => Record<string, unknown>,
274 ) => Promise<void>,
275 ): Promise<PendingOperation | null> {
276 const { tableName, trackedTableName, serializeValue } =
277 this.getMutationCollectionMeta(mutation)
278​
279 await handler(sanitizeSQL`${tableName}`, mutation, serializeValue)
280​
281 if (!waitForCompletion) {
282 return null
283 }
284​
285 // Need to get the operation in order to wait for it
286 const diffOperation = await context.get<{ id: string; timestamp: string }>(
287 sanitizeSQL`SELECT id, timestamp FROM ${trackedTableName} ORDER BY operation_id DESC LIMIT 1`,
288 )
289 return {
290 tableName,
291 id: diffOperation.id,
292 operation: mapOperationToPowerSync(mutation.type),
293 timestamp: diffOperation.timestamp,
294 }
295 }
296​
297 protected getMutationCollectionMeta(
298 mutation: PendingMutation<any>,
299 ): PowerSyncCollectionMeta<any> {
300 if (
301 typeof (mutation.collection.config as any).utils?.getMeta != `function`
302 ) {
303 throw new Error(`Collection is not a PowerSync collection.`)
304 }
305 return (
306 mutation.collection
307 .config as unknown as EnhancedPowerSyncCollectionConfig<any>
308 ).utils.getMeta()
309 }
310​
311 /**
312 * Processes collection mutation metadata for persistence to the database.
313 * We only support storing string metadata.
314 * @returns null if no metadata should be stored.
315 */
316 protected processMutationMetadata(
317 mutation: PendingMutation<any>,
318 ): string | null {
319 const { metadataIsTracked } = this.getMutationCollectionMeta(mutation)
320 if (!metadataIsTracked) {
321 // If it's not supported, we don't store metadata.
322 if (typeof mutation.metadata != `undefined`) {
323 // Log a warning if metadata is provided but not tracked.
324 this.database.logger.warn(
325 `Metadata provided for collection ${mutation.collection.id} but the PowerSync table does not track metadata. The PowerSync table should be configured with trackMetadata: true.`,
326 mutation.metadata,
327 )
328 }
329 return null
330 } else if (typeof mutation.metadata == `undefined`) {
331 return null
332 } else if (typeof mutation.metadata == `string`) {
333 return mutation.metadata
334 } else {
335 return JSON.stringify(mutation.metadata)
336 }
337 }