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

TransactionManager.ts

393 lines12.7 KB

1import { Store } from "@tanstack/store"
2import { SortedMap } from "./SortedMap"
3import { createDeferred } from "./deferred"
4import type { TransactionStore } from "./TransactionStore"
5import type { Collection } from "./collection"
6import type {
7 MutationStrategy,
8 PendingMutation,
9 Transaction,
10 TransactionState,
11} from "./types"
12​
13// Singleton instance of TransactionManager with type map
14​
15const transactionManagerInstances = new Map<string, TransactionManager<any>>()
16​
17/**
18 * Get the global TransactionManager instance for a specific type
19 * Creates a new instance if one doesn't exist for that type
20 *
21 * @param store - The transaction store for persistence
22 * @param collection - The collection this manager is associated with
23 * @returns The TransactionManager instance
24 */
25export function getTransactionManager<
26 T extends object = Record<string, unknown>,
27>(store?: TransactionStore, collection?: Collection<T>): TransactionManager<T> {
28 if (!store || !collection) {
29 throw new Error(
30 `TransactionManager not initialized. You must provide store and collection parameters on first call.`
31 )
32 }
33​
34 if (!transactionManagerInstances.has(collection.id)) {
35 transactionManagerInstances.set(
36 collection.id,
37 new TransactionManager(store, collection)
38 )
39 }
40 return transactionManagerInstances.get(collection.id) as TransactionManager<T>
42​
43export class TransactionManager<T extends object = Record<string, unknown>> {
44 private store: TransactionStore
45 private collection: Collection<T>
46 public transactions: Store<SortedMap<string, Transaction>>
47​
48 /**
49 * Creates a new TransactionManager instance
50 *
51 * @param store - The transaction store for persistence
52 * @param collection - The collection this manager is associated with
53 */
54 constructor(store: TransactionStore, collection: Collection<T>) {
55 this.store = store
56 this.collection = collection
57 // Initialize store with SortedMap that sorts by createdAt
58 this.transactions = new Store(
59 new SortedMap<string, Transaction>(
60 (a, b) => a.createdAt.getTime() - b.createdAt.getTime()
61 )
62 )
63​
64 // Load transactions from store on init
65 this.store.getTransactions().then((transactions) => {
66 transactions.forEach((tx) => {
67 this.transactions.setState((sortedMap) => {
68 sortedMap.set(tx.id, tx)
69 return sortedMap
70 })
71 })
72 })
73 }
74​
75 /**
76 * Retrieves a transaction by its ID
77 *
78 * @param id - The unique identifier of the transaction
79 * @returns The transaction if found, undefined otherwise
80 */
81 getTransaction(id: string): Transaction | undefined {
82 return this.transactions.state.get(id)
83 }
84​
85 private setTransaction(transaction: Transaction): void {
86 this.transactions.setState((sortedMap) => {
87 sortedMap.set(transaction.id, transaction)
88 return sortedMap
89 })
90​
91 this.collection.commitPendingTransactions()
92 }
93​
94 /**
95 * Create a live transaction reference that always returns the latest values
96 * @param id Transaction ID
97 * @returns A proxy that always gets the latest transaction values
98 */
99 createLiveTransactionReference(id: string): Transaction {
100 const self: TransactionManager<T> = this
101 return new Proxy(
102 {
103 // Implement the toObject method directly on the proxy target
104 toObject() {
105 const transaction = self.getTransaction(id)
106 if (!transaction) {
107 throw new Error(`Transaction with id ${id} not found`)
108 }
109​
110 // Create a shallow copy of the transaction without the toObject method
111​
112 const { toObject, ...transactionData } = transaction
113 return { ...transactionData }
114 },
115 } as Transaction,
116 {
117 get(target, prop) {
118 // If the property is toObject, return the method from the target
119 if (prop === `toObject`) {
120 return target.toObject
121 }
122​
123 // Otherwise, get the latest transaction data
124 const latest = self.getTransaction(id)
125 if (!latest) {
126 throw new Error(`Transaction with id ${id} not found`)
127 }
128 return latest[prop as keyof Transaction]
129 },
130 set() {
131 // We don't allow direct setting of properties on the transaction
132 console.warn(
133 `Direct modification of transaction properties is not allowed. Use setTransactionState if updating the state`
134 )
135 return true
136 },
137 }
138 )
139 }
140​
141 /**
142 * Applies a transaction with the given mutations using the specified strategy
143 *
144 * @param mutations - Array of pending mutations to apply
145 * @param strategy - Strategy to use when applying the transaction
146 * @returns A live reference to the created or updated transaction
147 */
148 applyTransaction(
149 mutations: Array<PendingMutation>,
150 strategy: MutationStrategy
151 ): Transaction {
152 // See if there's an existing overlapping queued mutation.
153 const mutationKeys = mutations.map((m) => m.key)
154 let transaction: Transaction | undefined = Array.from(
155 this.transactions.state.values()
156 ).filter(
157 (t) =>
158 t.state === `queued` &&
159 t.mutations.some((m) => mutationKeys.includes(m.key))
160 )[0]
161​
162 // If there's a transaction, overwrite matching mutations.
163 if (transaction) {
164 for (const newMutation of mutations) {
165 const existingIndex = transaction.mutations.findIndex(
166 (m) => m.key === newMutation.key
167 )
168​
169 if (existingIndex >= 0) {
170 // Replace existing mutation
171 // TODO this won't work for cases where different mutations modify different keys
172 transaction.mutations[existingIndex] = newMutation
173 } else {
174 // Insert new mutation
175 transaction.mutations.push(newMutation)
176 }
177 }
178 } else {
179 // Create a new transaction if none exists
180 transaction = {
181 id: crypto.randomUUID(),
182 state: `pending`,
183 createdAt: new Date(),
184 updatedAt: new Date(),
185 mutations,
186 metadata: {},
187 strategy,
188 isSynced: createDeferred(),
189 isPersisted: createDeferred(),
190 }
191 }
192​
193 // For ordered transactions, check if we need to queue behind another transaction
194 if (strategy.type === `ordered`) {
195 const activeTransactions = this.getActiveTransactions()
196 const orderedTransactions = activeTransactions.filter(
197 (tx) => tx.strategy.type === `ordered` && tx.state !== `queued`
198 )
199​
200 // Find any active transaction that has overlapping mutations
201 const conflictingTransaction = orderedTransactions.find((tx) =>
202 this.hasOverlappingMutations(tx.mutations, mutations)
203 )
204​
205 if (conflictingTransaction) {
206 transaction.state = `queued`
207 transaction.queuedBehind = conflictingTransaction.id
208 } else {
209 this.setTransaction(transaction)
210 this.processTransaction(transaction.id)
211 }
212 }
213​
214 this.setTransaction(transaction)
215 // Persist async
216 this.store.putTransaction(transaction)
217​
218 // Return a live reference to the transaction
219 return this.createLiveTransactionReference(transaction.id)
220 }
221​
222 /**
223 * Process a transaction through persist and awaitSync
224 *
225 * @param transactionId - The ID of the transaction to process
226 * @private
227 */
228 private processTransaction(transactionId: string): void {
229 const transaction = this.getTransaction(transactionId)
230 if (!transaction) return
231​
232 this.setTransactionState(transactionId, `persisting`)
233​
234 this.collection.config.mutationFn
235 .persist({
236 transaction: this.createLiveTransactionReference(transactionId),
237 collection: this.collection,
238 })
239 .then((persistResult) => {
240 const tx = this.getTransaction(transactionId)
241 if (!tx) return
242​
243 tx.isPersisted?.resolve(true)
244 if (this.collection.config.mutationFn.awaitSync) {
245 this.setTransactionState(transactionId, `persisted_awaiting_sync`)
246​
247 // Create a promise that rejects after 2 seconds
248 const timeoutPromise = new Promise<never>((_, reject) => {
249 setTimeout(() => {
250 reject(new Error(`Sync operation timed out after 2 seconds`))
251 }, this.collection.config.mutationFn.awaitSyncTimeoutMs ?? 2000)
252 })
253​
254 // Race the awaitSync promise against the timeout
255 Promise.race([
256 this.collection.config.mutationFn.awaitSync({
257 transaction: this.createLiveTransactionReference(transactionId),
258 collection: this.collection,
259 persistResult,
260 }),
261 timeoutPromise,
262 ])
263 .then(() => {
264 const updatedTx = this.getTransaction(transactionId)
265 if (!updatedTx) return
266​
267 updatedTx.isSynced?.resolve(true)
268 this.setTransactionState(transactionId, `completed`)
269 })
270 // Catch awaitSync errors or timeout
271 .catch((error) => {
272 const updatedTx = this.getTransaction(transactionId)
273 if (!updatedTx) return
274​
275 // Update transaction with error information
276 updatedTx.error = {
277 message: error.message || `Error during sync`,
278 error:
279 error instanceof Error ? error : new Error(String(error)),
280 }
281​
282 // Reject the isSynced promise
283 updatedTx.isSynced?.reject(error)
284​
285 // Set transaction state to failed
286 this.setTransaction(updatedTx)
287 this.setTransactionState(transactionId, `failed`)
288 })
289 } else {
290 this.setTransactionState(transactionId, `completed`)
291 }
292 })
293 .catch((error) => {
294 const tx = this.getTransaction(transactionId)
295 if (!tx) return
296​
297 // Update transaction with error information
298 tx.error = {
299 message: error.message || `Error during persist`,
300 error: error instanceof Error ? error : new Error(String(error)),
301 }
302​
303 // Reject both promises
304 tx.isPersisted?.reject(error)
305 tx.isSynced?.reject(error)
306​
307 // Set transaction state to failed
308 this.setTransactionState(transactionId, `failed`)
309 })
310 }
311​
312 /**
313 * Updates the state of a transaction
314 *
315 * @param id - The unique identifier of the transaction
316 * @param newState - The new state to set
317 * @throws Error if the transaction is not found
318 */
319 setTransactionState(id: string, newState: TransactionState): void {
320 const transaction = this.getTransaction(id)
321 if (!transaction) {
322 throw new Error(`Transaction ${id} not found`)
323 }
324​
325 // Force a small delay to ensure updatedAt is different
326 const updatedTransaction: Transaction = {
327 ...transaction,
328 state: newState,
329 updatedAt: new Date(Date.now() + 1),
330 }
331​
332 this.setTransaction(updatedTransaction)
333​
334 // Check if the transaction is in a terminal state
335 if (newState === `completed` || newState === `failed`) {
336 // Delete from IndexedDB if in terminal state
337 this.store.deleteTransaction(id)
338 } else {
339 // Persist async only if not in terminal state
340 this.store.putTransaction(updatedTransaction)
341 }
342​
343 // If this transaction is completing, check if any are queued behind it
344 if (
345 (newState === `completed` || newState === `failed`) &&
346 transaction.strategy.type === `ordered`
347 ) {
348 // Get all ordered transactions that are queued behind this one
349 const queuedTransactions = Array.from(
350 this.transactions.state.values()
351 ).filter(
352 (tx) =>
353 tx.state === `queued` &&
354 tx.strategy.type === `ordered` &&
355 tx.queuedBehind === transaction.id
356 )
357​
358 // Process each queued transaction
359 for (const queuedTransaction of queuedTransactions) {
360 queuedTransaction.queuedBehind = undefined
361 this.setTransaction(queuedTransaction)
362 this.processTransaction(queuedTransaction.id)
363 }
364 }
365 }
366​
367 /**
368 * Gets all active transactions (those not in completed or failed state)
369 *
370 * @returns Array of active transactions
371 */
372 getActiveTransactions(): Array<Transaction> {
373 return Array.from(this.transactions.state.values()).filter(
374 (tx) => tx.state !== `completed` && tx.state !== `failed`
375 )
376 }
377​
378 /**
379 * Checks if two sets of mutations have overlapping keys
380 *
381 * @param mutations1 - First set of mutations
382 * @param mutations2 - Second set of mutations
383 * @returns True if there are overlapping mutations, false otherwise
384 */
385 hasOverlappingMutations(
386 mutations1: Array<PendingMutation>,
387 mutations2: Array<PendingMutation>
388 ): boolean {
389 const ids1 = new Set(mutations1.map((m) => m.original.id))
390 const ids2 = new Set(mutations2.map((m) => m.original.id))
391 return Array.from(ids1).some((id) => ids2.has(id))
392 }