@tanstack/offline-transactions 1.0.56 → 1.0.59

package/src/executor/KeyScheduler.ts

@@ -3,7 +3,7 @@ import type { OfflineTransaction } from '../types'
 
 export class KeyScheduler {
   private pendingTransactions: Array<OfflineTransaction> = []
-  private isRunning = false
+  private activeTransactionId: string | undefined
 
   schedule(transaction: OfflineTransaction): boolean {
     return withSyncSpan(
@@ -35,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
         }
@@ -59,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 {
@@ -82,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 {
@@ -99,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> {
@@ -112,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

@@ -1,4 +1,5 @@
 import { createTransaction } from '@tanstack/db'
+import { OutboxTransactionNotFoundError } from '../outbox/OutboxManager'
 import { DefaultRetryPolicy } from '../retry/RetryPolicy'
 import { NonRetriableError } from '../types'
 import { withNestedSpan } from '../telemetry/tracer'
@@ -21,6 +22,7 @@ export class TransactionExecutor {
   private executionPromise: Promise<void> | null = null
   private offlineExecutor: TransactionSignaler
   private retryTimer: ReturnType<typeof setTimeout> | null = null
+  private fatalError: Error | null = null
 
   constructor(
     scheduler: KeyScheduler,
@@ -39,11 +41,13 @@ export class TransactionExecutor {
   }
 
   async execute(transaction: OfflineTransaction): Promise<void> {
+    this.assertHealthy()
     this.scheduler.schedule(transaction)
     await this.executeAll()
   }
 
   async executeAll(): Promise<void> {
+    this.assertHealthy()
     if (this.isExecuting) {
       return this.executionPromise!
     }
@@ -56,6 +60,7 @@ export class TransactionExecutor {
     } finally {
       this.isExecuting = false
       this.executionPromise = null
+      this.scheduleNextRetry()
     }
   }
 
@@ -73,9 +78,6 @@ export class TransactionExecutor {
 
       await this.executeTransaction(transaction)
     }
-
-    // Schedule next retry after execution completes
-    this.scheduleNextRetry()
   }
 
   private async executeTransaction(
@@ -91,33 +93,61 @@ export class TransactionExecutor {
           'transaction.keyCount': transaction.keys.length,
         },
         async (span) => {
+          const terminalError =
+            transaction.outboxPhase === `rejection-pending`
+              ? this.getTerminalError(transaction)
+              : undefined
           this.scheduler.markStarted(transaction)
 
           if (transaction.retryCount > 0) {
             span.setAttribute(`retry.attempt`, transaction.retryCount)
           }
 
-          try {
-            const result = await this.runMutationFn(transaction)
-
+          if (!transaction.outboxPhase) {
             try {
-              // Replay can still see this ID until durable deletion settles.
-              await this.outbox.remove(transaction.id)
-            } finally {
-              this.scheduler.markCompleted(transaction)
+              await this.runMutationFn(transaction)
+            } catch (error) {
+              const err =
+                error instanceof Error ? error : new Error(String(error))
+
+              span.setAttribute(`result`, `error`)
+
+              await this.handleError(transaction, err)
+              ;(err as any)[HANDLED_EXECUTION_ERROR] = true
+              throw err
             }
+          }
 
-            span.setAttribute(`result`, `success`)
-            this.offlineExecutor.resolveTransaction(transaction.id, result)
+          // A successful provider call can outlive this executor. Persist that
+          // fact before removal so a restarted executor only retries deletion.
+          const deletionPending: OfflineTransaction = transaction.outboxPhase
+            ? transaction
+            : { ...transaction, outboxPhase: `deletion-pending` }
+          try {
+            await this.removeSettledTransaction(
+              deletionPending,
+              !transaction.outboxPhase,
+            )
           } catch (error) {
-            const err =
-              error instanceof Error ? error : new Error(String(error))
-
-            span.setAttribute(`result`, `error`)
+            const storageError = error as Error
+            span.recordException(storageError)
+            span.setAttribute(`result`, `outbox_failure`)
+            this.offlineExecutor.rejectTransaction(
+              transaction.id,
+              terminalError ?? storageError,
+            )
+            throw storageError
+          }
 
-            await this.handleError(transaction, err)
-            ;(err as any)[HANDLED_EXECUTION_ERROR] = true
-            throw err
+          if (terminalError) {
+            span.setAttribute(`result`, `permanent_failure`)
+            this.offlineExecutor.rejectTransaction(
+              transaction.id,
+              terminalError,
+            )
+          } else {
+            span.setAttribute(`result`, `success`)
+            this.offlineExecutor.resolveTransaction(transaction.id, undefined)
           }
         },
       )
@@ -180,15 +210,29 @@ export class TransactionExecutor {
         span.setAttribute(`shouldRetry`, shouldRetry)
 
         if (!shouldRetry) {
-          this.scheduler.markCompleted(transaction)
-          await this.outbox.remove(transaction.id)
+          const rejectionPending: OfflineTransaction = {
+            ...transaction,
+            outboxPhase: `rejection-pending`,
+            lastError: {
+              name: error.name,
+              message: error.message,
+              stack: error.stack,
+            },
+          }
           console.warn(
             `Transaction ${transaction.id} failed permanently:`,
             error,
           )
+          try {
+            await this.removeSettledTransaction(rejectionPending, true)
+          } catch (storageError) {
+            span.recordException(storageError as Error)
+            span.setAttribute(`result`, `outbox_failure`)
+            this.offlineExecutor.rejectTransaction(transaction.id, error)
+            throw storageError
+          }
 
           span.setAttribute(`result`, `permanent_failure`)
-          // Signal permanent failure to the waiting transaction
           this.offlineExecutor.rejectTransaction(transaction.id, error)
           return
         }
@@ -211,7 +255,6 @@ export class TransactionExecutor {
         span.setAttribute(`retryDelay`, delay)
         span.setAttribute(`nextRetryCount`, updatedTransaction.retryCount)
 
-        this.scheduler.markFailed(transaction)
         this.scheduler.updateTransaction(updatedTransaction)
 
         try {
@@ -221,45 +264,116 @@ 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
-
-    if (this.config.beforeRetry) {
-      filteredTransactions = this.config.beforeRetry(transactions)
+  private async removeSettledTransaction(
+    transaction: OfflineTransaction,
+    persistMarker: boolean,
+  ): Promise<void> {
+    try {
+      if (persistMarker) {
+        try {
+          await this.outbox.update(transaction.id, transaction)
+        } catch (error) {
+          // A public removal can finish while the provider is still running.
+          if (!(error instanceof OutboxTransactionNotFoundError)) throw error
+        }
+      }
+      await this.outbox.remove(transaction.id)
+      this.scheduler.markCompleted(transaction)
+    } catch (error) {
+      const storageError =
+        error instanceof Error ? error : new Error(String(error))
+      this.fatalError = storageError
+      this.scheduler.markFailed(transaction)
+      this.clearRetryTimer()
+      throw storageError
     }
+  }
 
-    // The outbox read or retry hook may outlive this owner's right to replay.
-    if (!this.offlineExecutor.isOfflineEnabled) return
+  assertHealthy(): void {
+    if (this.fatalError) throw this.fatalError
+  }
 
-    const newlyLoaded = filteredTransactions.filter((transaction) =>
-      this.scheduler.schedule(transaction),
-    )
+  private getTerminalError(transaction: OfflineTransaction): Error {
+    if (!transaction.lastError)
+      throw new Error(`Terminal transaction ${transaction.id} has no error`)
+    const { name, message, stack } = transaction.lastError
+    const error =
+      name === `NonRetriableError`
+        ? new NonRetriableError(message)
+        : new Error(message)
+    error.name = name
+    error.stack = stack
+    return error
+  }
+
+  async loadPendingTransactions(): Promise<void> {
+    let removedIds: Array<string> = []
+    await this.outbox.withAll((transactions) => {
+      const { isOfflineEnabled } = this.offlineExecutor
+      if (!isOfflineEnabled) return
+      const providerPending = transactions.filter(
+        (transaction) => !transaction.outboxPhase,
+      )
+      const selectedProvider = this.config.beforeRetry
+        ? this.config.beforeRetry(providerPending)
+        : providerPending
+      const selectedById = new Map(selectedProvider.map((tx) => [tx.id, tx]))
+      const filteredTransactions = transactions.flatMap((transaction) => {
+        if (transaction.outboxPhase) return [transaction]
+        const selected = selectedById.get(transaction.id)
+        return selected ? [selected] : []
+      })
 
-    // Restore optimistic state for loaded transactions
-    // This ensures the UI shows the optimistic data while transactions are pending
-    this.restoreOptimisticState(newlyLoaded)
+      // The retry hook is user code and may synchronously revoke replay rights.
+      if (!this.offlineExecutor.isOfflineEnabled) return
 
-    // Reset retry delays for all loaded transactions so they can run immediately
-    this.resetRetryDelays()
+      const newlyLoaded = filteredTransactions.filter((transaction) =>
+        this.scheduler.schedule(transaction),
+      )
 
-    // Schedule retry timer for loaded transactions
-    this.scheduleNextRetry()
+      removedIds = providerPending
+        .filter(({ id }) => !selectedById.has(id))
+        .map(({ id }) => id)
+      removedIds = this.scheduler.removePendingTransactions(removedIds)
+
+      // Restore optimistic state for loaded transactions
+      // This ensures the UI shows the optimistic data while transactions are pending
+      this.restoreOptimisticState(
+        newlyLoaded.filter(
+          (transaction) => transaction.outboxPhase !== `rejection-pending`,
+        ),
+      )
 
-    const removedTransactions = transactions.filter(
-      (tx) => !filteredTransactions.some((filtered) => filtered.id === tx.id),
-    )
+      // Reset retry delays for all loaded transactions so they can run immediately
+      this.resetRetryDelays()
 
-    if (removedTransactions.length > 0) {
-      await this.outbox.removeMany(removedTransactions.map((tx) => tx.id))
+      // Schedule retry timer for loaded transactions
+      this.scheduleNextRetry()
+    })
+
+    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,
+            )
+          }
+        }),
+      )
     }
   }
 
@@ -346,7 +460,7 @@ export class TransactionExecutor {
     // Clear existing timer
     this.clearRetryTimer()
 
-    if (!this.canExecute()) {
+    if (this.fatalError || !this.canExecute()) {
       return
     }
 

package/src/outbox/OutboxManager.ts

@@ -1,12 +1,20 @@
 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'
 
+export class OutboxTransactionNotFoundError extends Error {}
+
 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 +29,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 +79,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 +91,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>> {
@@ -107,7 +160,7 @@ export class OutboxManager {
     return withSpan(`outbox.update`, { 'transaction.id': id }, async () => {
       const existing = await this.get(id)
       if (!existing) {
-        throw new Error(`Transaction ${id} not found`)
+        throw new OutboxTransactionNotFoundError(`Transaction ${id} not found`)
       }
 
       const updated = { ...existing, ...updates }
@@ -119,6 +172,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 +186,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> {