@tanstack/offline-transactions 1.0.54 → 1.0.58

package/src/executor/KeyScheduler.ts

@@ -3,21 +3,29 @@ import type { OfflineTransaction } from '../types'
 
 export class KeyScheduler {
   private pendingTransactions: Array<OfflineTransaction> = []
-  private isRunning = false
+  private activeTransactionId: string | undefined
 
-  schedule(transaction: OfflineTransaction): void {
-    withSyncSpan(
+  schedule(transaction: OfflineTransaction): boolean {
+    return withSyncSpan(
       `scheduler.schedule`,
       {
         'transaction.id': transaction.id,
         queueLength: this.pendingTransactions.length,
       },
       () => {
+        if (
+          this.pendingTransactions.some(
+            (pending) => pending.id === transaction.id,
+          )
+        ) {
+          return false
+        }
         this.pendingTransactions.push(transaction)
         // Sort by creation time to maintain FIFO order
         this.pendingTransactions.sort(
           (a, b) => a.createdAt.getTime() - b.createdAt.getTime(),
         )
+        return true
       },
     )
   }
@@ -27,7 +35,10 @@ export class KeyScheduler {
       `scheduler.getNext`,
       { pendingCount: this.pendingTransactions.length },
       (span) => {
-        if (this.isRunning || this.pendingTransactions.length === 0) {
+        if (
+          this.activeTransactionId !== undefined ||
+          this.pendingTransactions.length === 0
+        ) {
           span.setAttribute(`result`, `empty`)
           return undefined
         }
@@ -51,17 +62,17 @@ export class KeyScheduler {
     return Date.now() >= transaction.nextAttemptAt
   }
 
-  markStarted(_transaction: OfflineTransaction): void {
-    this.isRunning = true
+  markStarted(transaction: OfflineTransaction): void {
+    this.activeTransactionId = transaction.id
   }
 
   markCompleted(transaction: OfflineTransaction): void {
     this.removeTransaction(transaction)
-    this.isRunning = false
+    this.activeTransactionId = undefined
   }
 
   markFailed(_transaction: OfflineTransaction): void {
-    this.isRunning = false
+    this.activeTransactionId = undefined
   }
 
   private removeTransaction(transaction: OfflineTransaction): void {
@@ -74,16 +85,7 @@ export class KeyScheduler {
   }
 
   updateTransaction(transaction: OfflineTransaction): void {
-    const index = this.pendingTransactions.findIndex(
-      (tx) => tx.id === transaction.id,
-    )
-    if (index >= 0) {
-      this.pendingTransactions[index] = transaction
-      // Re-sort to maintain FIFO order after update
-      this.pendingTransactions.sort(
-        (a, b) => a.createdAt.getTime() - b.createdAt.getTime(),
-      )
-    }
+    this.updateTransactions([transaction])
   }
 
   getPendingCount(): number {
@@ -91,12 +93,23 @@ export class KeyScheduler {
   }
 
   getRunningCount(): number {
-    return this.isRunning ? 1 : 0
+    return this.activeTransactionId === undefined ? 0 : 1
   }
 
   clear(): void {
     this.pendingTransactions = []
-    this.isRunning = false
+    this.activeTransactionId = undefined
+  }
+
+  /** @internal Reconcile one replay snapshot without canceling issued work. */
+  removePendingTransactions(transactionIds: Iterable<string>): Array<string> {
+    const ids = new Set(transactionIds)
+    if (this.activeTransactionId !== undefined)
+      ids.delete(this.activeTransactionId)
+    this.pendingTransactions = this.pendingTransactions.filter(
+      ({ id }) => !ids.has(id),
+    )
+    return [...ids]
   }
 
   getAllPendingTransactions(): Array<OfflineTransaction> {
@@ -104,14 +117,12 @@ export class KeyScheduler {
   }
 
   updateTransactions(updatedTransactions: Array<OfflineTransaction>): void {
-    for (const updatedTx of updatedTransactions) {
-      const index = this.pendingTransactions.findIndex(
-        (tx) => tx.id === updatedTx.id,
-      )
-      if (index >= 0) {
-        this.pendingTransactions[index] = updatedTx
-      }
-    }
+    const updatedById = new Map(
+      updatedTransactions.map((transaction) => [transaction.id, transaction]),
+    )
+    this.pendingTransactions = this.pendingTransactions.map(
+      (transaction) => updatedById.get(transaction.id) ?? transaction,
+    )
     // Re-sort to maintain FIFO order after updates
     this.pendingTransactions.sort(
       (a, b) => a.createdAt.getTime() - b.createdAt.getTime(),

package/src/executor/TransactionExecutor.ts

@@ -56,12 +56,13 @@ export class TransactionExecutor {
     } finally {
       this.isExecuting = false
       this.executionPromise = null
+      this.scheduleNextRetry()
     }
   }
 
   private async runExecution(): Promise<void> {
     while (this.scheduler.getPendingCount() > 0) {
-      if (!this.isOnline()) {
+      if (!this.canExecute()) {
         break
       }
 
@@ -73,9 +74,6 @@ export class TransactionExecutor {
 
       await this.executeTransaction(transaction)
     }
-
-    // Schedule next retry after execution completes
-    this.scheduleNextRetry()
   }
 
   private async executeTransaction(
@@ -97,14 +95,9 @@ export class TransactionExecutor {
             span.setAttribute(`retry.attempt`, transaction.retryCount)
           }
 
+          let result: void
           try {
-            const result = await this.runMutationFn(transaction)
-
-            this.scheduler.markCompleted(transaction)
-            await this.outbox.remove(transaction.id)
-
-            span.setAttribute(`result`, `success`)
-            this.offlineExecutor.resolveTransaction(transaction.id, result)
+            result = await this.runMutationFn(transaction)
           } catch (error) {
             const err =
               error instanceof Error ? error : new Error(String(error))
@@ -115,6 +108,20 @@ export class TransactionExecutor {
             ;(err as any)[HANDLED_EXECUTION_ERROR] = true
             throw err
           }
+
+          let removalError: unknown
+          try {
+            // Replay can still see this ID until durable deletion settles.
+            await this.outbox.remove(transaction.id)
+          } catch (error) {
+            removalError = error
+          } finally {
+            this.scheduler.markCompleted(transaction)
+          }
+
+          span.setAttribute(`result`, `success`)
+          this.offlineExecutor.resolveTransaction(transaction.id, result)
+          if (removalError !== undefined) throw removalError
         },
       )
     } catch (error) {
@@ -176,8 +183,14 @@ export class TransactionExecutor {
         span.setAttribute(`shouldRetry`, shouldRetry)
 
         if (!shouldRetry) {
-          this.scheduler.markCompleted(transaction)
-          await this.outbox.remove(transaction.id)
+          let removalError: unknown
+          try {
+            await this.outbox.remove(transaction.id)
+          } catch (cleanupError) {
+            removalError = cleanupError
+          } finally {
+            this.scheduler.markCompleted(transaction)
+          }
           console.warn(
             `Transaction ${transaction.id} failed permanently:`,
             error,
@@ -186,6 +199,7 @@ export class TransactionExecutor {
           span.setAttribute(`result`, `permanent_failure`)
           // Signal permanent failure to the waiting transaction
           this.offlineExecutor.rejectTransaction(transaction.id, error)
+          if (removalError !== undefined) throw removalError
           return
         }
 
@@ -207,7 +221,6 @@ export class TransactionExecutor {
         span.setAttribute(`retryDelay`, delay)
         span.setAttribute(`nextRetryCount`, updatedTransaction.retryCount)
 
-        this.scheduler.markFailed(transaction)
         this.scheduler.updateTransaction(updatedTransaction)
 
         try {
@@ -217,42 +230,64 @@ export class TransactionExecutor {
           span.recordException(persistError as Error)
           span.setAttribute(`result`, `persist_failed`)
           throw persistError
+        } finally {
+          this.scheduler.markFailed(transaction)
         }
-
-        // Schedule retry timer
-        this.scheduleNextRetry()
       },
     )
   }
 
   async loadPendingTransactions(): Promise<void> {
-    const transactions = await this.outbox.getAll()
-    let filteredTransactions = transactions
+    let removedIds: Array<string> = []
+    await this.outbox.withAll((transactions) => {
+      const { isOfflineEnabled } = this.offlineExecutor
+      if (!isOfflineEnabled) return
+      let filteredTransactions = transactions
+
+      if (this.config.beforeRetry) {
+        filteredTransactions = this.config.beforeRetry(transactions)
+      }
 
-    if (this.config.beforeRetry) {
-      filteredTransactions = this.config.beforeRetry(transactions)
-    }
+      // The retry hook is user code and may synchronously revoke replay rights.
+      if (!this.offlineExecutor.isOfflineEnabled) return
 
-    for (const transaction of filteredTransactions) {
-      this.scheduler.schedule(transaction)
-    }
+      const newlyLoaded = filteredTransactions.filter((transaction) =>
+        this.scheduler.schedule(transaction),
+      )
 
-    // Restore optimistic state for loaded transactions
-    // This ensures the UI shows the optimistic data while transactions are pending
-    this.restoreOptimisticState(filteredTransactions)
+      const retainedIds = new Set(filteredTransactions.map(({ id }) => id))
+      removedIds = transactions
+        .filter(({ id }) => !retainedIds.has(id))
+        .map(({ id }) => id)
+      removedIds = this.scheduler.removePendingTransactions(removedIds)
 
-    // Reset retry delays for all loaded transactions so they can run immediately
-    this.resetRetryDelays()
+      // Restore optimistic state for loaded transactions
+      // This ensures the UI shows the optimistic data while transactions are pending
+      this.restoreOptimisticState(newlyLoaded)
 
-    // Schedule retry timer for loaded transactions
-    this.scheduleNextRetry()
+      // Reset retry delays for all loaded transactions so they can run immediately
+      this.resetRetryDelays()
 
-    const removedTransactions = transactions.filter(
-      (tx) => !filteredTransactions.some((filtered) => filtered.id === tx.id),
-    )
+      // Schedule retry timer for loaded transactions
+      this.scheduleNextRetry()
+    })
 
-    if (removedTransactions.length > 0) {
-      await this.outbox.removeMany(removedTransactions.map((tx) => tx.id))
+    if (removedIds.length > 0) {
+      const error = new NonRetriableError(`Transaction excluded by beforeRetry`)
+      await Promise.all(
+        removedIds.map(async (id) => {
+          try {
+            await this.outbox.remove(id)
+            this.offlineExecutor.rejectTransaction(id, error)
+          } catch (cleanupError) {
+            console.warn(
+              `Failed to remove transaction excluded by beforeRetry:`,
+              id,
+              cleanupError,
+            )
+          }
+        }),
+      )
     }
   }
 
@@ -326,6 +361,11 @@ export class TransactionExecutor {
     this.clearRetryTimer()
   }
 
+  pause(): void {
+    // Retain queued work and let the issued call finish its acknowledgment.
+    this.clearRetryTimer()
+  }
+
   getPendingCount(): number {
     return this.scheduler.getPendingCount()
   }
@@ -334,18 +374,17 @@ export class TransactionExecutor {
     // Clear existing timer
     this.clearRetryTimer()
 
-    if (!this.isOnline()) {
+    if (!this.canExecute()) {
       return
     }
 
-    // Find the earliest retry time among pending transactions
-    const earliestRetryTime = this.getEarliestRetryTime()
+    const nextRetryTime = this.getNextRetryTime()
 
-    if (earliestRetryTime === null) {
+    if (nextRetryTime === null) {
       return // No transactions pending retry
     }
 
-    const delay = Math.max(0, earliestRetryTime - Date.now())
+    const delay = Math.max(0, nextRetryTime - Date.now())
 
     this.retryTimer = setTimeout(() => {
       this.executeAll().catch((error) => {
@@ -354,14 +393,15 @@ export class TransactionExecutor {
     }, delay)
   }
 
-  private getEarliestRetryTime(): number | null {
+  private getNextRetryTime(): number | null {
     const allTransactions = this.scheduler.getAllPendingTransactions()
 
     if (allTransactions.length === 0) {
       return null
     }
 
-    return Math.min(...allTransactions.map((tx) => tx.nextAttemptAt))
+    // Later transactions cannot overtake the FIFO head, even if they are ready.
+    return allTransactions[0]!.nextAttemptAt
   }
 
   private clearRetryTimer(): void {
@@ -371,8 +411,10 @@ export class TransactionExecutor {
     }
   }
 
-  private isOnline(): boolean {
-    return this.offlineExecutor.isOnline()
+  private canExecute(): boolean {
+    return (
+      this.offlineExecutor.isOfflineEnabled && this.offlineExecutor.isOnline()
+    )
   }
 
   getRunningCount(): number {

package/src/outbox/OutboxManager.ts

@@ -1,5 +1,8 @@
 import { withSpan } from '../telemetry/tracer'
-import { TransactionSerializer } from './TransactionSerializer'
+import {
+  MissingTemporalConstructorError,
+  TransactionSerializer,
+} from './TransactionSerializer'
 import type { OfflineTransaction, StorageAdapter } from '../types'
 import type { Collection } from '@tanstack/db'
 
@@ -7,6 +10,9 @@ export class OutboxManager {
   private storage: StorageAdapter
   private serializer: TransactionSerializer
   private keyPrefix = `tx:`
+  private removalRevision = 0
+  private activeReads = new Set<{ revision: number }>()
+  private removedAtRevision = new Map<string, number>()
 
   constructor(
     storage: StorageAdapter,
@@ -21,6 +27,25 @@ export class OutboxManager {
     return `${this.keyPrefix}${id}`
   }
 
+  private recordRemovals(ids: Iterable<string>): void {
+    this.removalRevision++
+    if (this.activeReads.size === 0) return
+    for (const id of ids) this.removedAtRevision.set(id, this.removalRevision)
+    this.pruneRemovalHistory()
+  }
+
+  private pruneRemovalHistory(): void {
+    if (this.activeReads.size === 0) {
+      this.removedAtRevision.clear()
+      return
+    }
+    let oldestRead = Number.POSITIVE_INFINITY
+    for (const read of this.activeReads)
+      oldestRead = Math.min(oldestRead, read.revision)
+    for (const [id, revision] of this.removedAtRevision)
+      if (revision <= oldestRead) this.removedAtRevision.delete(id)
+  }
+
   async add(transaction: OfflineTransaction): Promise<void> {
     return withSpan(
       `outbox.add`,
@@ -52,6 +77,10 @@ export class OutboxManager {
         span.setAttribute(`result`, `found`)
         return transaction
       } catch (error) {
+        if (error instanceof MissingTemporalConstructorError) {
+          error.message = `transaction ${id}: ${error.message}`
+          throw error
+        }
         console.warn(`Failed to deserialize transaction ${id}:`, error)
         span.setAttribute(`result`, `deserialize_error`)
         return null
@@ -60,35 +89,57 @@ export class OutboxManager {
   }
 
   async getAll(): Promise<Array<OfflineTransaction>> {
-    return withSpan(`outbox.getAll`, {}, async (span) => {
-      const keys = await this.storage.keys()
-      const transactionKeys = keys.filter((key) =>
-        key.startsWith(this.keyPrefix),
-      )
-
-      span.setAttribute(`transactionCount`, transactionKeys.length)
-
-      const transactions: Array<OfflineTransaction> = []
-
-      for (const key of transactionKeys) {
-        const data = await this.storage.get(key)
-        if (data) {
-          try {
-            const transaction = this.serializer.deserialize(data)
-            transactions.push(transaction)
-          } catch (error) {
-            console.warn(
-              `Failed to deserialize transaction from key ${key}:`,
-              error,
-            )
+    return this.withAll((transactions) => transactions)
+  }
+
+  async withAll<T>(
+    consume: (transactions: Array<OfflineTransaction>) => T,
+  ): Promise<T> {
+    const read = { revision: this.removalRevision }
+    this.activeReads.add(read)
+    try {
+      return await withSpan(`outbox.getAll`, {}, async (span) => {
+        const keys = await this.storage.keys()
+        const transactionKeys = keys.filter((key) =>
+          key.startsWith(this.keyPrefix),
+        )
+
+        span.setAttribute(`transactionCount`, transactionKeys.length)
+
+        const transactions: Array<OfflineTransaction> = []
+
+        for (const key of transactionKeys) {
+          const data = await this.storage.get(key)
+          if (data) {
+            try {
+              const transaction = this.serializer.deserialize(data)
+              transactions.push(transaction)
+            } catch (error) {
+              if (error instanceof MissingTemporalConstructorError) {
+                error.message = `transaction ${key.slice(this.keyPrefix.length)}: ${error.message}`
+                throw error
+              }
+              console.warn(
+                `Failed to deserialize transaction from key ${key}:`,
+                error,
+              )
+            }
           }
         }
-      }
 
-      return transactions.sort(
-        (a, b) => a.createdAt.getTime() - b.createdAt.getTime(),
-      )
-    })
+        const currentTransactions = transactions
+          .filter(
+            ({ id }) => (this.removedAtRevision.get(id) ?? 0) <= read.revision,
+          )
+          .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+        // Keep the read registered until replay admission completes. A durable
+        // removal cannot land between filtering and this synchronous consumer.
+        return consume(currentTransactions)
+      })
+    } finally {
+      this.activeReads.delete(read)
+      this.pruneRemovalHistory()
+    }
   }
 
   async getByKeys(keys: Array<string>): Promise<Array<OfflineTransaction>> {
@@ -119,6 +170,7 @@ export class OutboxManager {
     return withSpan(`outbox.remove`, { 'transaction.id': id }, async () => {
       const key = this.getStorageKey(id)
       await this.storage.delete(key)
+      this.recordRemovals([id])
     })
   }
 
@@ -132,7 +184,9 @@ export class OutboxManager {
     const keys = await this.storage.keys()
     const transactionKeys = keys.filter((key) => key.startsWith(this.keyPrefix))
 
-    await Promise.all(transactionKeys.map((key) => this.storage.delete(key)))
+    await this.removeMany(
+      transactionKeys.map((key) => key.slice(this.keyPrefix.length)),
+    )
   }
 
   async count(): Promise<number> {