Clarify queueStrategy documentation (#1107)

KyleAMathews · claude · web-flow · commit 6745ed003dc2 · 2026-01-19T10:02:50.000-07:00
* docs: clarify queueStrategy error handling behavior The previous documentation implied that "every mutation is guaranteed to persist" which is misleading. This clarifies that: - Every mutation is guaranteed to be ATTEMPTED (not dropped) - Failed mutations are NOT automatically retried - Failed mutations transition to "failed" state - Subsequent mutations continue processing (queue doesn't stop) - Each mutation is independent (no all-or-nothing semantics) Fixes #1071 * docs: add retry behavior documentation and examples TanStack DB does not automatically retry failed mutations - this is by design since retry strategies vary by use case. This commit: - Adds a "Retry Behavior" section explaining why auto-retry isn't built-in - Provides a simple retry helper example with exponential backoff - Adds a queue strategy-specific retry example for file uploads - References p-retry library for more sophisticated strategies This helps answer the question from #1071 about what happens when mutations fail and how to handle retries. * docs: remove duplicative retry example from queue strategy section Link to the Retry Behavior section instead of duplicating the example. * docs: revert manual edit to generated reference doc The queueStrategy.md reference doc is auto-generated from JSDoc in the source file - the source already has the updated documentation. * chore: add changeset for queue strategy docs clarification Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: address review feedback on punctuation and backoff description - Replace em-dash with period for clarity (Kevin's feedback) - Fix "exponential backoff" comment to "increasing delay" since the code uses linear backoff (Kyle's earlier feedback) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/.changeset/clarify-queue-docs.md b/.changeset/clarify-queue-docs.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/db': patch
+---
+
+Clarify queueStrategy error handling behavior in documentation. Changed "guaranteed to persist" to "guaranteed to be attempted" and added explicit documentation about how failed mutations are handled (not retried, queue continues). Added new Retry Behavior section with example code for implementing custom retry logic.
diff --git a/docs/guides/mutations.md b/docs/guides/mutations.md
@@ -1093,7 +1093,7 @@ function VolumeSlider() {
 
 ### Queue Strategy
 
-The queue strategy creates a separate transaction for each mutation and processes them sequentially in order. Unlike debounce/throttle, **every mutation is guaranteed to persist**, making it ideal for workflows where you can't lose any operations.
+The queue strategy creates a separate transaction for each mutation and processes them sequentially in order. Unlike debounce/throttle which may drop intermediate mutations, **every mutation is guaranteed to be attempted**, making it ideal for workflows where you can't skip any operations.
 
 ```tsx
 import { usePacedMutations, queueStrategy } from "@tanstack/react-db"
@@ -1136,9 +1136,16 @@ function FileUploader() {
 - Each mutation becomes its own transaction
 - Processes sequentially in order (FIFO by default)
 - Can configure to LIFO by setting `getItemsFrom: 'back'`
-- All mutations guaranteed to persist
+- All mutations guaranteed to be attempted (unlike debounce/throttle which may skip intermediate mutations)
 - Waits for each transaction to complete before starting the next
 
+**Error handling**:
+- If a mutation fails, **it is not automatically retried** - the transaction transitions to "failed" state
+- Failed mutations surface their error via `transaction.isPersisted.promise` (which will reject)
+- **Subsequent mutations continue processing** - a single failure does not block the queue
+- Each mutation is independent; there is no all-or-nothing transaction semantics across multiple mutations
+- To implement retry logic, see [Retry Behavior](#retry-behavior)
+
 ### Choosing a Strategy
 
 Use this guide to pick the right strategy for your use case:
@@ -1453,6 +1460,45 @@ If an error occurs: `pending` → `persisting` → `failed`
 
 Failed transactions automatically rollback their optimistic state.
 
+### Retry Behavior
+
+**Important:** TanStack DB does not automatically retry failed mutations. If a mutation fails (network error, server error, etc.), the transaction transitions to `failed` state and the optimistic state is rolled back. This is by design. Automatic retry logic varies significantly based on your use case (idempotency requirements, error types, backoff strategies, etc.).
+
+To implement retry logic, wrap your API calls in your `mutationFn`:
+
+```typescript
+// Simple retry helper
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  maxRetries = 3,
+  delay = 1000
+): Promise<T> {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      if (attempt === maxRetries - 1) throw error
+      await new Promise(resolve => setTimeout(resolve, delay * (attempt + 1)))
+    }
+  }
+  throw new Error('Unreachable')
+}
+
+// Use in your collection
+const todoCollection = createCollection({
+  id: "todos",
+  onUpdate: async ({ transaction }) => {
+    const mutation = transaction.mutations[0]
+    // Retry up to 3 times with increasing delay
+    await withRetry(() =>
+      api.todos.update(mutation.original.id, mutation.changes)
+    )
+  },
+})
+```
+
+For more sophisticated retry strategies, consider using a library like [p-retry](https://github.com/sindresorhus/p-retry) which supports exponential backoff, custom retry conditions, and abort signals.
+
 ## Handling Temporary IDs
 
 When inserting new items into collections where the server generates the final ID, you'll need to handle the transition from temporary to real IDs carefully to avoid UI issues and operation failures.
diff --git a/packages/db/src/strategies/queueStrategy.ts b/packages/db/src/strategies/queueStrategy.ts
@@ -6,9 +6,15 @@ import type { Transaction } from '../transactions'
  * Creates a queue strategy that processes all mutations in order with proper serialization.
  *
  * Unlike other strategies that may drop executions, queue ensures every
- * mutation is processed sequentially. Each transaction commit completes before
+ * mutation is attempted sequentially. Each transaction commit completes before
  * the next one starts. Useful when data consistency is critical and
- * every operation must complete in order.
+ * every operation must be attempted in order.
+ *
+ * **Error handling behavior:**
+ * - If a mutation fails, it is NOT automatically retried - the transaction transitions to "failed" state
+ * - Failed mutations surface their error via `transaction.isPersisted.promise` (which will reject)
+ * - Subsequent mutations continue processing - a single failure does not block the queue
+ * - Each mutation is independent; there is no all-or-nothing transaction semantics
  *
  * @param options - Configuration for queue behavior (FIFO/LIFO, timing, size limits)
  * @returns A queue strategy instance

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@tanstack/db': patch
 +---
++
 +Clarify queueStrategy error handling behavior in documentation. Changed "guaranteed to persist" to "guaranteed to be attempted" and added explicit documentation about how failed mutations are handled (not retried, queue continues). Added new Retry Behavior section with example code for implementing custom retry logic.