Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Danny-Devs wants to merge 1 commit into
base: main
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions docs/guides/mutations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1452,6 +1452,21 @@ try {
}
```

> [!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`
Expand Down