@tanstack/offline-transactions 1.0.65 → 1.1.1

package/src/executor/KeyScheduler.ts

@@ -1,4 +1,3 @@
-import { withSyncSpan } from '../telemetry/tracer'
 import type { OfflineTransaction } from '../types'
 
 export class KeyScheduler {
@@ -6,56 +5,28 @@ export class KeyScheduler {
   private activeTransactionId: string | undefined
 
   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
-      },
+    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
   }
 
   getNext(): OfflineTransaction | undefined {
-    return withSyncSpan(
-      `scheduler.getNext`,
-      { pendingCount: this.pendingTransactions.length },
-      (span) => {
-        if (
-          this.activeTransactionId !== undefined ||
-          this.pendingTransactions.length === 0
-        ) {
-          span.setAttribute(`result`, `empty`)
-          return undefined
-        }
-
-        const firstTransaction = this.pendingTransactions[0]!
-
-        if (!this.isReadyToRun(firstTransaction)) {
-          span.setAttribute(`result`, `waiting_for_first`)
-          span.setAttribute(`transaction.id`, firstTransaction.id)
-          return undefined
-        }
-
-        span.setAttribute(`result`, `found`)
-        span.setAttribute(`transaction.id`, firstTransaction.id)
-        return firstTransaction
-      },
-    )
+    if (
+      this.activeTransactionId !== undefined ||
+      this.pendingTransactions.length === 0
+    ) {
+      return undefined
+    }
+    const firstTransaction = this.pendingTransactions[0]!
+    return this.isReadyToRun(firstTransaction) ? firstTransaction : undefined
   }
 
   private isReadyToRun(transaction: OfflineTransaction): boolean {

package/src/executor/TransactionExecutor.ts

@@ -1,8 +1,7 @@
-import { createTransaction } from '@tanstack/db'
+import { DuplicateTransactionIdError, createTransaction } from '@tanstack/db'
 import { OutboxTransactionNotFoundError } from '../outbox/OutboxManager'
 import { DefaultRetryPolicy } from '../retry/RetryPolicy'
 import { NonRetriableError } from '../types'
-import { withNestedSpan } from '../telemetry/tracer'
 import type { KeyScheduler } from './KeyScheduler'
 import type { OutboxManager } from '../outbox/OutboxManager'
 import type {
@@ -13,6 +12,13 @@ import type {
 
 const HANDLED_EXECUTION_ERROR = Symbol(`HandledExecutionError`)
 
+function toError(value: unknown): Error {
+  return value instanceof Error ||
+    Object.prototype.toString.call(value) === `[object Error]`
+    ? (value as Error)
+    : new Error(String(value))
+}
+
 export class TransactionExecutor {
   private scheduler: KeyScheduler
   private outbox: OutboxManager
@@ -84,77 +90,53 @@ export class TransactionExecutor {
     transaction: OfflineTransaction,
   ): Promise<void> {
     try {
-      await withNestedSpan(
-        `transaction.execute`,
-        {
-          'transaction.id': transaction.id,
-          'transaction.mutationFnName': transaction.mutationFnName,
-          'transaction.retryCount': transaction.retryCount,
-          '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)
-          }
-
-          if (!transaction.outboxPhase) {
-            try {
-              await this.runMutationFn(transaction)
-            } catch (error) {
-              const err =
-                error instanceof Error ? error : new Error(String(error))
+      const terminalError =
+        transaction.outboxPhase === `rejection-pending`
+          ? this.getTerminalError(transaction)
+          : undefined
+      this.scheduler.markStarted(transaction)
 
-              span.setAttribute(`result`, `error`)
+      if (!transaction.outboxPhase) {
+        try {
+          await this.runMutationFn(transaction)
+        } catch (error) {
+          const err = toError(error)
 
-              await this.handleError(transaction, err)
-              ;(err as any)[HANDLED_EXECUTION_ERROR] = true
-              throw err
-            }
-          }
+          await this.handleError(transaction, err)
+          ;(err as any)[HANDLED_EXECUTION_ERROR] = true
+          throw err
+        }
+      }
 
-          // 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 storageError = error as Error
-            span.recordException(storageError)
-            span.setAttribute(`result`, `outbox_failure`)
-            this.offlineExecutor.rejectTransaction(
-              transaction.id,
-              terminalError ?? storageError,
-            )
-            throw storageError
-          }
+      // 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 storageError = error as Error
+        this.offlineExecutor.rejectTransaction(
+          transaction.id,
+          terminalError ?? storageError,
+        )
+        throw storageError
+      }
 
-          if (terminalError) {
-            span.setAttribute(`result`, `permanent_failure`)
-            this.offlineExecutor.rejectTransaction(
-              transaction.id,
-              terminalError,
-            )
-          } else {
-            span.setAttribute(`result`, `success`)
-            this.offlineExecutor.resolveTransaction(transaction.id, undefined)
-          }
-        },
-      )
+      if (terminalError) {
+        this.offlineExecutor.rejectTransaction(transaction.id, terminalError)
+      } else {
+        this.offlineExecutor.resolveTransaction(transaction.id, undefined)
+      }
     } catch (error) {
       if (
-        error instanceof Error &&
-        (error as any)[HANDLED_EXECUTION_ERROR] === true
+        error !== null &&
+        typeof error === `object` &&
+        (error as Record<symbol, unknown>)[HANDLED_EXECUTION_ERROR] === true
       ) {
         return
       }
@@ -194,81 +176,97 @@ export class TransactionExecutor {
     transaction: OfflineTransaction,
     error: Error,
   ): Promise<void> {
-    return withNestedSpan(
-      `transaction.handleError`,
-      {
-        'transaction.id': transaction.id,
-        'error.name': error.name,
-        'error.message': error.message,
-      },
-      async (span) => {
-        const shouldRetry = this.retryPolicy.shouldRetry(
-          error,
-          transaction.retryCount,
-        )
-
-        span.setAttribute(`shouldRetry`, shouldRetry)
-
-        if (!shouldRetry) {
-          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,
+    let shouldRetry: boolean
+    let hookFailure: Error | undefined
+    if (error instanceof NonRetriableError) {
+      shouldRetry = false
+    } else {
+      let decision: boolean | undefined
+      try {
+        decision = this.config.shouldRetry?.(error, transaction.retryCount)
+        if (decision !== undefined && typeof decision !== `boolean`) {
+          // An async hook is invalid, but its rejection must stay row-local.
+          void Promise.resolve(decision).catch(() => {})
+          throw new TypeError(
+            `OfflineConfig.shouldRetry must return true, false, or undefined`,
           )
-          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`)
-          this.offlineExecutor.rejectTransaction(transaction.id, error)
-          return
         }
+      } catch (hookError) {
+        hookFailure = toError(hookError)
+      }
+      if (hookFailure) {
+        shouldRetry = false
+      } else {
+        shouldRetry =
+          decision ??
+          this.retryPolicy.shouldRetry(error, transaction.retryCount)
+      }
+    }
 
-        const delay = Math.max(
-          0,
-          this.retryPolicy.calculateDelay(transaction.retryCount),
+    if (!shouldRetry) {
+      const terminalError = hookFailure ?? error
+      const rejectionPending: OfflineTransaction = {
+        ...transaction,
+        outboxPhase: `rejection-pending`,
+        lastError: {
+          name: terminalError.name,
+          message: terminalError.message,
+          stack: terminalError.stack,
+        },
+      }
+      if (hookFailure) {
+        console.warn(
+          `Retry decision failed for transaction ${transaction.id}:`,
+          hookFailure,
+          `Named mutation function error:`,
+          error,
         )
-        const updatedTransaction: OfflineTransaction = {
-          ...transaction,
-          retryCount: transaction.retryCount + 1,
-          nextAttemptAt: Date.now() + delay,
-          lastError: {
-            name: error.name,
-            message: error.message,
-            stack: error.stack,
-          },
-        }
-
-        span.setAttribute(`retryDelay`, delay)
-        span.setAttribute(`nextRetryCount`, updatedTransaction.retryCount)
+      } else {
+        console.warn(`Transaction ${transaction.id} failed permanently:`, error)
+      }
+      try {
+        await this.removeSettledTransaction(rejectionPending, true)
+      } catch (storageError) {
+        this.offlineExecutor.rejectTransaction(transaction.id, terminalError)
+        throw storageError
+      }
 
-        this.scheduler.updateTransaction(updatedTransaction)
+      this.offlineExecutor.rejectTransaction(transaction.id, terminalError)
+      return
+    }
 
-        try {
-          await this.outbox.update(transaction.id, updatedTransaction)
-          span.setAttribute(`result`, `scheduled_retry`)
-        } catch (persistError) {
-          span.recordException(persistError as Error)
-          span.setAttribute(`result`, `persist_failed`)
-          throw persistError
-        } finally {
-          this.scheduler.markFailed(transaction)
-        }
-      },
+    const delay = Math.max(
+      0,
+      this.retryPolicy.calculateDelay(transaction.retryCount),
     )
+    const updatedTransaction: OfflineTransaction = {
+      ...transaction,
+      retryCount: transaction.retryCount + 1,
+      nextAttemptAt: Date.now() + delay,
+      lastError: {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      },
+    }
+
+    this.scheduler.updateTransaction(updatedTransaction)
+
+    try {
+      await this.outbox.update(transaction.id, updatedTransaction)
+    } catch (persistError) {
+      // Public removal can finish while the named mutation function runs.
+      // The removed row cannot be retried, but its caller still owns the
+      // provider failure and later queued work must be able to run.
+      if (persistError instanceof OutboxTransactionNotFoundError) {
+        this.scheduler.markCompleted(transaction)
+        this.offlineExecutor.rejectTransaction(transaction.id, error)
+        return
+      }
+      throw persistError
+    } finally {
+      this.scheduler.markFailed(transaction)
+    }
   }
 
   private async removeSettledTransaction(
@@ -287,8 +285,7 @@ export class TransactionExecutor {
       await this.outbox.remove(transaction.id)
       this.scheduler.markCompleted(transaction)
     } catch (error) {
-      const storageError =
-        error instanceof Error ? error : new Error(String(error))
+      const storageError = toError(error)
       this.fatalError = storageError
       this.scheduler.markFailed(transaction)
       this.clearRetryTimer()
@@ -399,34 +396,21 @@ export class TransactionExecutor {
           mutationFn: async () => {},
         })
 
-        // Prevent unhandled promise rejection when cleanup calls rollback()
-        // We don't care about this promise - it's just for holding mutations
-        restorationTx.isPersisted.promise.catch(() => {
-          // Intentionally ignored - restoration transactions are cleaned up
-          // via cleanupRestorationTransaction, not through normal commit flow
-        })
-
         restorationTx.applyMutations(offlineTx.mutations)
 
-        // Register with each affected collection's state manager
-        const touchedCollections = new Set<string>()
-        for (const mutation of offlineTx.mutations) {
-          // Defensive check for corrupted deserialized data
-          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-          if (!mutation.collection) {
-            continue
-          }
-          const collectionId = mutation.collection.id
-          if (touchedCollections.has(collectionId)) {
-            continue
+        // Register with each affected Collection. If one cannot track it, roll
+        // it back, so no Collection keeps a restoration nothing will settle.
+        try {
+          // The serializer resolves every mutation's Collection or throws.
+          for (const mutation of offlineTx.mutations) {
+            if (mutation.collection._state.trackTransaction(restorationTx))
+              mutation.collection._state.recomputeOptimisticState(true)
           }
-          touchedCollections.add(collectionId)
-
-          mutation.collection._state.transactions.set(
-            restorationTx.id,
-            restorationTx,
-          )
-          mutation.collection._state.recomputeOptimisticState(true)
+        } catch (error) {
+          // A secondary rollback settles only this restoration; it must not
+          // roll back the user's live transactions on the same keys.
+          restorationTx.rollback({ isSecondaryRollback: true })
+          throw error
         }
 
         this.offlineExecutor.registerRestorationTransaction(
@@ -434,6 +418,8 @@ export class TransactionExecutor {
           restorationTx,
         )
       } catch (error) {
+        // A live transaction with this id already shows these mutations.
+        if (error instanceof DuplicateTransactionIdError) continue
         console.warn(
           `Failed to restore optimistic state for transaction ${offlineTx.id}:`,
           error,

package/src/outbox/OutboxManager.ts

@@ -1,4 +1,3 @@
-import { withSpan } from '../telemetry/tracer'
 import {
   MissingTemporalConstructorError,
   TransactionSerializer,
@@ -49,45 +48,26 @@ export class OutboxManager {
   }
 
   async add(transaction: OfflineTransaction): Promise<void> {
-    return withSpan(
-      `outbox.add`,
-      {
-        'transaction.id': transaction.id,
-        'transaction.mutationFnName': transaction.mutationFnName,
-        'transaction.keyCount': transaction.keys.length,
-      },
-      async () => {
-        const key = this.getStorageKey(transaction.id)
-        const serialized = this.serializer.serialize(transaction)
-        await this.storage.set(key, serialized)
-      },
-    )
+    const key = this.getStorageKey(transaction.id)
+    const serialized = this.serializer.serialize(transaction)
+    await this.storage.set(key, serialized)
   }
 
   async get(id: string): Promise<OfflineTransaction | null> {
-    return withSpan(`outbox.get`, { 'transaction.id': id }, async (span) => {
-      const key = this.getStorageKey(id)
-      const data = await this.storage.get(key)
-
-      if (!data) {
-        span.setAttribute(`result`, `not_found`)
-        return null
-      }
+    const key = this.getStorageKey(id)
+    const data = await this.storage.get(key)
+    if (!data) return null
 
-      try {
-        const transaction = this.serializer.deserialize(data)
-        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
+    try {
+      return this.serializer.deserialize(data)
+    } catch (error) {
+      if (error instanceof MissingTemporalConstructorError) {
+        error.message = `transaction ${id}: ${error.message}`
+        throw error
       }
-    })
+      console.warn(`Failed to deserialize transaction ${id}:`, error)
+      return null
+    }
   }
 
   async getAll(): Promise<Array<OfflineTransaction>> {
@@ -100,44 +80,40 @@ export class OutboxManager {
     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,
-              )
+      const keys = await this.storage.keys()
+      const transactionKeys = keys.filter((key) =>
+        key.startsWith(this.keyPrefix),
+      )
+
+      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,
+            )
           }
         }
+      }
 
-        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)
-      })
+      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 await consume(currentTransactions)
     } finally {
       this.activeReads.delete(read)
       this.pruneRemovalHistory()
@@ -157,29 +133,21 @@ export class OutboxManager {
     id: string,
     updates: Partial<OfflineTransaction>,
   ): Promise<void> {
-    return withSpan(`outbox.update`, { 'transaction.id': id }, async () => {
-      const existing = await this.get(id)
-      if (!existing) {
-        throw new OutboxTransactionNotFoundError(`Transaction ${id} not found`)
-      }
-
-      const updated = { ...existing, ...updates }
-      await this.add(updated)
-    })
+    const existing = await this.get(id)
+    if (!existing) {
+      throw new OutboxTransactionNotFoundError(`Transaction ${id} not found`)
+    }
+    await this.add({ ...existing, ...updates })
   }
 
   async remove(id: string): Promise<void> {
-    return withSpan(`outbox.remove`, { 'transaction.id': id }, async () => {
-      const key = this.getStorageKey(id)
-      await this.storage.delete(key)
-      this.recordRemovals([id])
-    })
+    const key = this.getStorageKey(id)
+    await this.storage.delete(key)
+    this.recordRemovals([id])
   }
 
   async removeMany(ids: Array<string>): Promise<void> {
-    return withSpan(`outbox.removeMany`, { count: ids.length }, async () => {
-      await Promise.all(ids.map((id) => this.remove(id)))
-    })
+    await Promise.all(ids.map((id) => this.remove(id)))
   }
 
   async clear(): Promise<void> {

package/src/types.ts

@@ -101,6 +101,16 @@ export interface OfflineConfig {
   storage?: StorageAdapter
   maxConcurrency?: number
   jitter?: boolean
+  /**
+   * Override retry decisions for errors from all named mutation functions.
+   * Return synchronously; undefined uses the default decision. Put any
+   * function-specific context needed by this shared hook on the Error.
+   * NonRetriableError always stops retry.
+   * A throw or invalid return fails only that outbox row and rejects its
+   * waiters with the hook failure. Queued work runs after terminal cleanup.
+   * The default policy still supplies the delay and configured jitter.
+   */
+  shouldRetry?: (error: Error, retryCount: number) => boolean | undefined
   beforeRetry?: (
     transactions: Array<OfflineTransaction>,
   ) => Array<OfflineTransaction>

package/dist/cjs/retry/NonRetriableError.d.cts

@@ -1 +0,0 @@
-export { NonRetriableError } from '../types.cjs';