@tanstack/offline-transactions 1.0.65 → 1.1.0

package/skills/offline/SKILL.md

@@ -165,6 +165,7 @@ interface OfflineConfig {
   storage?: StorageAdapter // Custom storage (default: auto-detect)
   maxConcurrency?: number // Parallel execution limit
   jitter?: boolean // Add jitter to retry delays
+  shouldRetry?: (error: Error, retryCount: number) => boolean | undefined // Override retry decision
   beforeRetry?: (txs) => txs // Transform/filter before retry
   onUnknownMutationFn?: (name, tx) => void // Handle orphaned transactions
   onLeadershipChange?: (isLeader) => void // Leadership state callback
@@ -206,7 +207,55 @@ const executor = startOfflineExecutor({
 })
 ```
 
-Throwing `NonRetriableError` stops retry and removes the transaction from the outbox. Use for permanent failures (validation errors, conflicts, 4xx responses).
+Throwing `NonRetriableError` stops retry and removes the transaction from the outbox. Use it for failures known to be permanent under the server contract, such as validation errors or a 409 that means an unrecoverable duplicate. A recoverable 401 can instead reach `shouldRetry`.
+
+### Retry decisions
+
+Set `shouldRetry` to override the default decision for a named mutation function
+error. The hook receives the named mutation function's `Error` and retry count
+(`0` on the first failure). The same `Error` instance is passed through; a
+non-`Error` rejection is converted to an `Error` and may lose custom fields.
+Return `true` to retry, `false` to stop, or `undefined` to use the
+default decision. For example, return `true` for a recoverable 401 and
+`undefined` otherwise. `NonRetriableError` always stops without calling the
+hook. The default backoff and configured jitter still determine retry timing.
+The hook is synchronous and shared by all named mutation functions. An async
+hook returns a Promise, which fails its outbox row. Put function-specific
+context on the thrown error when retry rules differ between functions.
+If the hook throws or returns another value, the executor records a terminal
+rejection for that row, removes it from the outbox, and rejects its waiting
+promises with the hook failure. Other queued rows continue after the failed
+row's deletion is acknowledged. New commits may join the queue during cleanup,
+but cannot run ahead of that deletion. A fresh executor does not replay the
+failed row. The named mutation function error is logged; the hook failure is
+the caller-facing and stored error. Stored errors retain `name`, `message`, and
+`stack`, but a restart does not restore an arbitrary error subclass or its
+custom fields.
+If marker storage or deletion fails, the caller still receives the hook error
+while the executor stops with the storage error and retains queued work. A
+saved terminal marker skips the named mutation function after restart; an
+unmarked row can replay.
+To decide from an HTTP status, throw an error carrying `response.status` in
+the named mutation function and inspect its numeric status in `shouldRetry`.
+
+```ts
+class HttpError extends Error {
+  constructor(readonly status: number) {
+    super(`HTTP ${status}`)
+    this.name = 'HttpError'
+  }
+}
+
+function throwOnHttpFailure(response: Response): void {
+  if (!response.ok) throw new HttpError(response.status)
+}
+
+const retryOnRecoverable401 = (error: Error): boolean | undefined =>
+  error instanceof HttpError && error.status === 401 ? true : undefined
+```
+
+Call `throwOnHttpFailure(response)` in the named mutation function and pass
+`shouldRetry: retryOnRecoverable401` in the executor config.
 
 ### Idempotency keys
 
@@ -339,18 +388,37 @@ mutationFns: {
 Correct:
 
 ```ts
+class HttpError extends Error {
+  constructor(readonly status: number) {
+    super(`HTTP ${status}`)
+    this.name = 'HttpError'
+  }
+}
+
 mutationFns: {
   createTodo: async ({ transaction }) => {
     const res = await fetch('/api/todos', { ... })
-    if (res.status >= 400 && res.status < 500) {
-      throw new NonRetriableError(`Client error: ${res.status}`)
+    if (res.status === 422) {
+      throw new NonRetriableError('Invalid todo')
+    }
+    if (res.status === 409) {
+      throw new NonRetriableError('Duplicate detected')
+    }
+    // This todo API also treats these responses as permanent.
+    if ([404, 405, 410].includes(res.status)) {
+      throw new NonRetriableError(`Todo endpoint rejected: ${res.status}`)
     }
-    if (!res.ok) throw new Error('Server error')
+    if (!res.ok) throw new HttpError(res.status)
   },
 }
 ```
 
-Without distinguishing retriable from permanent errors, 4xx responses (validation, auth, not found) will retry forever until max retries, wasting resources and filling logs.
+Classify failures according to whether the app can recover. The default policy
+stops when an error message contains 400, 401, 403, or 422; it can retry other
+errors indefinitely. This example marks 404, 405, and 410 as permanent for the
+todo API while leaving 408 and 429 available for retry. Use `shouldRetry` when
+a 401 can recover after credentials refresh, and use `NonRetriableError` for
+known permanent failures.
 
 See also: db-core/mutations-optimistic/SKILL.md — for the underlying mutation primitives.
 

package/src/OfflineExecutor.ts

@@ -547,26 +547,11 @@ export class OfflineExecutor {
       return
     }
 
-    // Mark as completed so recomputeOptimisticState removes it from consideration.
-    // The actual data will come from the sync.
+    // Mark as completed: every Collection that tracked it recomputes and
+    // releases it. The actual data will come from the sync.
     restorationTx.setState(`completed`)
-
-    // Remove from each collection's transaction map and recompute
-    const touchedCollections = new Set<string>()
-    for (const mutation of restorationTx.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
-      }
-      touchedCollections.add(collectionId)
-      mutation.collection._state.transactions.delete(restorationTx.id)
-      mutation.collection._state.recomputeOptimisticState(false)
-    }
+    restorationTx.isPersisted.resolve(restorationTx)
+    restorationTx.touchCollection()
   }
 
   async removeFromOutbox(id: string): Promise<void> {

package/src/api/OfflineTransaction.ts

@@ -33,7 +33,9 @@ export class OfflineTransaction {
   }
 
   mutate(callback: () => void): Transaction {
-    this.transaction = createTransaction({
+    // Repeated calls add to the same transaction: one offline transaction is
+    // one transaction, and its id is unique among live transactions.
+    this.transaction ??= createTransaction({
       id: this.offlineId,
       autoCommit: false,
       mutationFn: async () => {

package/src/executor/TransactionExecutor.ts

@@ -1,4 +1,4 @@
-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'
@@ -13,6 +13,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
@@ -107,8 +114,7 @@ export class TransactionExecutor {
             try {
               await this.runMutationFn(transaction)
             } catch (error) {
-              const err =
-                error instanceof Error ? error : new Error(String(error))
+              const err = toError(error)
 
               span.setAttribute(`result`, `error`)
 
@@ -153,8 +159,9 @@ export class TransactionExecutor {
       )
     } 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
       }
@@ -202,38 +209,77 @@ export class TransactionExecutor {
         'error.message': error.message,
       },
       async (span) => {
-        const shouldRetry = this.retryPolicy.shouldRetry(
-          error,
-          transaction.retryCount,
-        )
+        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`,
+              )
+            }
+          } catch (hookError) {
+            hookFailure = toError(hookError)
+          }
+          if (hookFailure) {
+            shouldRetry = false
+          } else {
+            shouldRetry =
+              decision ??
+              this.retryPolicy.shouldRetry(error, transaction.retryCount)
+          }
+        }
 
         span.setAttribute(`shouldRetry`, shouldRetry)
 
         if (!shouldRetry) {
+          const terminalError = hookFailure ?? error
           const rejectionPending: OfflineTransaction = {
             ...transaction,
             outboxPhase: `rejection-pending`,
             lastError: {
-              name: error.name,
-              message: error.message,
-              stack: error.stack,
+              name: terminalError.name,
+              message: terminalError.message,
+              stack: terminalError.stack,
             },
           }
-          console.warn(
-            `Transaction ${transaction.id} failed permanently:`,
-            error,
-          )
+          if (hookFailure) {
+            span.recordException(hookFailure)
+            console.warn(
+              `Retry decision failed for transaction ${transaction.id}:`,
+              hookFailure,
+              `Named mutation function error:`,
+              error,
+            )
+          } else {
+            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)
+            this.offlineExecutor.rejectTransaction(
+              transaction.id,
+              terminalError,
+            )
             throw storageError
           }
 
-          span.setAttribute(`result`, `permanent_failure`)
-          this.offlineExecutor.rejectTransaction(transaction.id, error)
+          span.setAttribute(
+            `result`,
+            hookFailure ? `retry_decision_failure` : `permanent_failure`,
+          )
+          this.offlineExecutor.rejectTransaction(transaction.id, terminalError)
           return
         }
 
@@ -261,6 +307,15 @@ export class TransactionExecutor {
           await this.outbox.update(transaction.id, updatedTransaction)
           span.setAttribute(`result`, `scheduled_retry`)
         } 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)
+            span.setAttribute(`result`, `outbox_removed`)
+            this.offlineExecutor.rejectTransaction(transaction.id, error)
+            return
+          }
           span.recordException(persistError as Error)
           span.setAttribute(`result`, `persist_failed`)
           throw persistError
@@ -287,8 +342,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()
@@ -408,25 +462,19 @@ export class TransactionExecutor {
 
         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 +482,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/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>