Skip to content
Source
Sign inSign up
TanStack/db

docs: warn about isPersisted vs isPersisted.promise footgun #1322

ClosedDanny-Devs(GitHub profile, opens in a new tab)wants to merge 1 commit intomain fromrefs/pull/1322/headopened

Showing 1 changed file with 15 additions and 0 deletions.

x
0 of 1 viewed, 1 left
15 additions and 0 deletionsdocs/guides/mutations.mdModified
View file
@@ -1452,6 +1452,21 @@
+> [!IMPORTANT]
+> **Always use `tx.isPersisted.promise`, not `tx.isPersisted`.** The `isPersisted` property is a `Deferred` object, not a `Promise`. Since `Deferred` does not implement a `.then()` method, `await tx.isPersisted` resolves immediately to the `Deferred` object itself — it does **not** wait for the transaction to persist.
+> This is a silent bug that TypeScript will not catch, because `await` accepts any value.
+> ```typescript
+> // ❌ BUG: resolves immediately — does not wait for persistence
+> await tx.isPersisted
+> // ✅ CORRECT: waits for the transaction to complete or fail
+> await tx.isPersisted.promise
+> ```
+> If you forget `.promise`, your UI may clear forms, navigate, or show success messages before the server has confirmed the write. If the server then rejects the mutation, the optimistic state rolls back silently with no error handling.
+​
### State Transitions
The normal flow is: `pending` → `persisting` → `completed`