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

TransactionExecutor.ts

505 lines15.0 KB

1import { DuplicateTransactionIdError, createTransaction } from '@tanstack/db'
2import { OutboxTransactionNotFoundError } from '../outbox/OutboxManager'
3import { DefaultRetryPolicy } from '../retry/RetryPolicy'
4import { NonRetriableError } from '../types'
5import type { KeyScheduler } from './KeyScheduler'
6import type { OutboxManager } from '../outbox/OutboxManager'
7import type {
8 OfflineConfig,
9 OfflineTransaction,
10 TransactionSignaler,
11} from '../types'
12​
13const HANDLED_EXECUTION_ERROR = Symbol(`HandledExecutionError`)
14​
15function toError(value: unknown): Error {
16 return value instanceof Error ||
17 Object.prototype.toString.call(value) === `[object Error]`
18 ? (value as Error)
19 : new Error(String(value))
21​
22export class TransactionExecutor {
23 private scheduler: KeyScheduler
24 private outbox: OutboxManager
25 private config: OfflineConfig
26 private retryPolicy: DefaultRetryPolicy
27 private isExecuting = false
28 private executionPromise: Promise<void> | null = null
29 private offlineExecutor: TransactionSignaler
30 private retryTimer: ReturnType<typeof setTimeout> | null = null
31 private fatalError: Error | null = null
32​
33 constructor(
34 scheduler: KeyScheduler,
35 outbox: OutboxManager,
36 config: OfflineConfig,
37 offlineExecutor: TransactionSignaler,
38 ) {
39 this.scheduler = scheduler
40 this.outbox = outbox
41 this.config = config
42 this.retryPolicy = new DefaultRetryPolicy(
43 Number.POSITIVE_INFINITY,
44 config.jitter ?? true,
45 )
46 this.offlineExecutor = offlineExecutor
47 }
48​
49 async execute(transaction: OfflineTransaction): Promise<void> {
50 this.assertHealthy()
51 this.scheduler.schedule(transaction)
52 await this.executeAll()
53 }
54​
55 async executeAll(): Promise<void> {
56 this.assertHealthy()
57 if (this.isExecuting) {
58 return this.executionPromise!
59 }
60​
61 this.isExecuting = true
62 this.executionPromise = this.runExecution()
63​
64 try {
65 await this.executionPromise
66 } finally {
67 this.isExecuting = false
68 this.executionPromise = null
69 this.scheduleNextRetry()
70 }
71 }
72​
73 private async runExecution(): Promise<void> {
74 while (this.scheduler.getPendingCount() > 0) {
75 if (!this.canExecute()) {
76 break
77 }
78​
79 const transaction = this.scheduler.getNext()
80​
81 if (!transaction) {
82 break
83 }
84​
85 await this.executeTransaction(transaction)
86 }
87 }
88​
89 private async executeTransaction(
90 transaction: OfflineTransaction,
91 ): Promise<void> {
92 try {
93 const terminalError =
94 transaction.outboxPhase === `rejection-pending`
95 ? this.getTerminalError(transaction)
96 : undefined
97 this.scheduler.markStarted(transaction)
98​
99 if (!transaction.outboxPhase) {
100 try {
101 await this.runMutationFn(transaction)
102 } catch (error) {
103 const err = toError(error)
104​
105 await this.handleError(transaction, err)
106 ;(err as any)[HANDLED_EXECUTION_ERROR] = true
107 throw err
108 }
109 }
110​
111 // A successful provider call can outlive this executor. Persist that
112 // fact before removal so a restarted executor only retries deletion.
113 const deletionPending: OfflineTransaction = transaction.outboxPhase
114 ? transaction
115 : { ...transaction, outboxPhase: `deletion-pending` }
116 try {
117 await this.removeSettledTransaction(
118 deletionPending,
119 !transaction.outboxPhase,
120 )
121 } catch (error) {
122 const storageError = error as Error
123 this.offlineExecutor.rejectTransaction(
124 transaction.id,
125 terminalError ?? storageError,
126 )
127 throw storageError
128 }
129​
130 if (terminalError) {
131 this.offlineExecutor.rejectTransaction(transaction.id, terminalError)
132 } else {
133 this.offlineExecutor.resolveTransaction(transaction.id, undefined)
134 }
135 } catch (error) {
136 if (
137 error !== null &&
138 typeof error === `object` &&
139 (error as Record<symbol, unknown>)[HANDLED_EXECUTION_ERROR] === true
140 ) {
141 return
142 }
143​
144 throw error
145 }
146 }
147​
148 private async runMutationFn(transaction: OfflineTransaction): Promise<void> {
149 const mutationFn = this.config.mutationFns[transaction.mutationFnName]
150​
151 if (!mutationFn) {
152 const errorMessage = `Unknown mutation function: ${transaction.mutationFnName}`
153​
154 if (this.config.onUnknownMutationFn) {
155 this.config.onUnknownMutationFn(transaction.mutationFnName, transaction)
156 }
157​
158 throw new NonRetriableError(errorMessage)
159 }
160​
161 // Mutations are already PendingMutation objects with collections attached
162 // from the deserializer, so we can use them directly
163 const transactionWithMutations = {
164 id: transaction.id,
165 mutations: transaction.mutations,
166 metadata: transaction.metadata ?? {},
167 }
168​
169 await mutationFn({
170 transaction: transactionWithMutations as any,
171 idempotencyKey: transaction.idempotencyKey,
172 })
173 }
174​
175 private async handleError(
176 transaction: OfflineTransaction,
177 error: Error,
178 ): Promise<void> {
179 let shouldRetry: boolean
180 let hookFailure: Error | undefined
181 if (error instanceof NonRetriableError) {
182 shouldRetry = false
183 } else {
184 let decision: boolean | undefined
185 try {
186 decision = this.config.shouldRetry?.(error, transaction.retryCount)
187 if (decision !== undefined && typeof decision !== `boolean`) {
188 // An async hook is invalid, but its rejection must stay row-local.
189 void Promise.resolve(decision).catch(() => {})
190 throw new TypeError(
191 `OfflineConfig.shouldRetry must return true, false, or undefined`,
192 )
193 }
194 } catch (hookError) {
195 hookFailure = toError(hookError)
196 }
197 if (hookFailure) {
198 shouldRetry = false
199 } else {
200 shouldRetry =
201 decision ??
202 this.retryPolicy.shouldRetry(error, transaction.retryCount)
203 }
204 }
205​
206 if (!shouldRetry) {
207 const terminalError = hookFailure ?? error
208 const rejectionPending: OfflineTransaction = {
209 ...transaction,
210 outboxPhase: `rejection-pending`,
211 lastError: {
212 name: terminalError.name,
213 message: terminalError.message,
214 stack: terminalError.stack,
215 },
216 }
217 if (hookFailure) {
218 console.warn(
219 `Retry decision failed for transaction ${transaction.id}:`,
220 hookFailure,
221 `Named mutation function error:`,
222 error,
223 )
224 } else {
225 console.warn(`Transaction ${transaction.id} failed permanently:`, error)
226 }
227 try {
228 await this.removeSettledTransaction(rejectionPending, true)
229 } catch (storageError) {
230 this.offlineExecutor.rejectTransaction(transaction.id, terminalError)
231 throw storageError
232 }
233​
234 this.offlineExecutor.rejectTransaction(transaction.id, terminalError)
235 return
236 }
237​
238 const delay = Math.max(
239 0,
240 this.retryPolicy.calculateDelay(transaction.retryCount),
241 )
242 const updatedTransaction: OfflineTransaction = {
243 ...transaction,
244 retryCount: transaction.retryCount + 1,
245 nextAttemptAt: Date.now() + delay,
246 lastError: {
247 name: error.name,
248 message: error.message,
249 stack: error.stack,
250 },
251 }
252​
253 this.scheduler.updateTransaction(updatedTransaction)
254​
255 try {
256 await this.outbox.update(transaction.id, updatedTransaction)
257 } catch (persistError) {
258 // Public removal can finish while the named mutation function runs.
259 // The removed row cannot be retried, but its caller still owns the
260 // provider failure and later queued work must be able to run.
261 if (persistError instanceof OutboxTransactionNotFoundError) {
262 this.scheduler.markCompleted(transaction)
263 this.offlineExecutor.rejectTransaction(transaction.id, error)
264 return
265 }
266 throw persistError
267 } finally {
268 this.scheduler.markFailed(transaction)
269 }
270 }
271​
272 private async removeSettledTransaction(
273 transaction: OfflineTransaction,
274 persistMarker: boolean,
275 ): Promise<void> {
276 try {
277 if (persistMarker) {
278 try {
279 await this.outbox.update(transaction.id, transaction)
280 } catch (error) {
281 // A public removal can finish while the provider is still running.
282 if (!(error instanceof OutboxTransactionNotFoundError)) throw error
283 }
284 }
285 await this.outbox.remove(transaction.id)
286 this.scheduler.markCompleted(transaction)
287 } catch (error) {
288 const storageError = toError(error)
289 this.fatalError = storageError
290 this.scheduler.markFailed(transaction)
291 this.clearRetryTimer()
292 throw storageError
293 }
294 }
295​
296 assertHealthy(): void {
297 if (this.fatalError) throw this.fatalError
298 }
299​
300 private getTerminalError(transaction: OfflineTransaction): Error {
301 if (!transaction.lastError)
302 throw new Error(`Terminal transaction ${transaction.id} has no error`)
303 const { name, message, stack } = transaction.lastError
304 const error =
305 name === `NonRetriableError`
306 ? new NonRetriableError(message)
307 : new Error(message)
308 error.name = name
309 error.stack = stack
310 return error
311 }
312​
313 async loadPendingTransactions(): Promise<void> {
314 let removedIds: Array<string> = []
315 await this.outbox.withAll((transactions) => {
316 const { isOfflineEnabled } = this.offlineExecutor
317 if (!isOfflineEnabled) return
318 const providerPending = transactions.filter(
319 (transaction) => !transaction.outboxPhase,
320 )
321 const selectedProvider = this.config.beforeRetry
322 ? this.config.beforeRetry(providerPending)
323 : providerPending
324 const selectedById = new Map(selectedProvider.map((tx) => [tx.id, tx]))
325 const filteredTransactions = transactions.flatMap((transaction) => {
326 if (transaction.outboxPhase) return [transaction]
327 const selected = selectedById.get(transaction.id)
328 return selected ? [selected] : []
329 })
330​
331 // The retry hook is user code and may synchronously revoke replay rights.
332 if (!this.offlineExecutor.isOfflineEnabled) return
333​
334 const newlyLoaded = filteredTransactions.filter((transaction) =>
335 this.scheduler.schedule(transaction),
336 )
337​
338 removedIds = providerPending
339 .filter(({ id }) => !selectedById.has(id))
340 .map(({ id }) => id)
341 removedIds = this.scheduler.removePendingTransactions(removedIds)
342​
343 // Restore optimistic state for loaded transactions
344 // This ensures the UI shows the optimistic data while transactions are pending
345 this.restoreOptimisticState(
346 newlyLoaded.filter(
347 (transaction) => transaction.outboxPhase !== `rejection-pending`,
348 ),
349 )
350​
351 // Reset retry delays for all loaded transactions so they can run immediately
352 this.resetRetryDelays()
353​
354 // Schedule retry timer for loaded transactions
355 this.scheduleNextRetry()
356 })
357​
358 if (removedIds.length > 0) {
359 const error = new NonRetriableError(`Transaction excluded by beforeRetry`)
360 await Promise.all(
361 removedIds.map(async (id) => {
362 try {
363 await this.outbox.remove(id)
364 this.offlineExecutor.rejectTransaction(id, error)
365 } catch (cleanupError) {
366 console.warn(
367 `Failed to remove transaction excluded by beforeRetry:`,
368 id,
369 cleanupError,
370 )
371 }
372 }),
373 )
374 }
375 }
376​
377 /**
378 * Restore optimistic state from loaded transactions.
379 * Creates internal transactions to hold the mutations so the collection's
380 * state manager can show optimistic data while waiting for sync.
381 */
382 private restoreOptimisticState(
383 transactions: Array<OfflineTransaction>,
384 ): void {
385 for (const offlineTx of transactions) {
386 if (offlineTx.mutations.length === 0) {
387 continue
388 }
389​
390 try {
391 // Create a restoration transaction that holds mutations for optimistic state display.
392 // It will never commit - the real mutation is handled by the offline executor.
393 const restorationTx = createTransaction({
394 id: offlineTx.id,
395 autoCommit: false,
396 mutationFn: async () => {},
397 })
398​
399 restorationTx.applyMutations(offlineTx.mutations)
400​
401 // Register with each affected Collection. If one cannot track it, roll
402 // it back, so no Collection keeps a restoration nothing will settle.
403 try {
404 // The serializer resolves every mutation's Collection or throws.
405 for (const mutation of offlineTx.mutations) {
406 if (mutation.collection._state.trackTransaction(restorationTx))
407 mutation.collection._state.recomputeOptimisticState(true)
408 }
409 } catch (error) {
410 // A secondary rollback settles only this restoration; it must not
411 // roll back the user's live transactions on the same keys.
412 restorationTx.rollback({ isSecondaryRollback: true })
413 throw error
414 }
415​
416 this.offlineExecutor.registerRestorationTransaction(
417 offlineTx.id,
418 restorationTx,
419 )
420 } catch (error) {
421 // A live transaction with this id already shows these mutations.
422 if (error instanceof DuplicateTransactionIdError) continue
423 console.warn(
424 `Failed to restore optimistic state for transaction ${offlineTx.id}:`,
425 error,
426 )
427 }
428 }
429 }
430​
431 clear(): void {
432 this.scheduler.clear()
433 this.clearRetryTimer()
434 }
435​
436 pause(): void {
437 // Retain queued work and let the issued call finish its acknowledgment.
438 this.clearRetryTimer()
439 }
440​
441 getPendingCount(): number {
442 return this.scheduler.getPendingCount()
443 }
444​
445 private scheduleNextRetry(): void {
446 // Clear existing timer
447 this.clearRetryTimer()
448​
449 if (this.fatalError || !this.canExecute()) {
450 return
451 }
452​
453 const nextRetryTime = this.getNextRetryTime()
454​
455 if (nextRetryTime === null) {
456 return // No transactions pending retry
457 }
458​
459 const delay = Math.max(0, nextRetryTime - Date.now())
460​
461 this.retryTimer = setTimeout(() => {
462 this.executeAll().catch((error) => {
463 console.warn(`Failed to execute retry batch:`, error)
464 })
465 }, delay)
466 }
467​
468 private getNextRetryTime(): number | null {
469 const allTransactions = this.scheduler.getAllPendingTransactions()
470​
471 if (allTransactions.length === 0) {
472 return null
473 }
474​
475 // Later transactions cannot overtake the FIFO head, even if they are ready.
476 return allTransactions[0]!.nextAttemptAt
477 }
478​
479 private clearRetryTimer(): void {
480 if (this.retryTimer) {
481 clearTimeout(this.retryTimer)
482 this.retryTimer = null
483 }
484 }
485​
486 private canExecute(): boolean {
487 return (
488 this.offlineExecutor.isOfflineEnabled && this.offlineExecutor.isOnline()
489 )
490 }
491​
492 getRunningCount(): number {
493 return this.scheduler.getRunningCount()
494 }
495​
496 resetRetryDelays(): void {
497 const allTransactions = this.scheduler.getAllPendingTransactions()
498 const updatedTransactions = allTransactions.map((transaction) => ({
499 ...transaction,
500 nextAttemptAt: Date.now(),
501 }))
502​
503 this.scheduler.updateTransactions(updatedTransactions)
504 }