Skip to content

Commit d2b2c97

Browse files
committed
docs: Improve bypass mutations callout
- Clarify this is about not rewriting existing logic, not avoiding optimistic updates - Add Electric's awaitTxId as a sync option - Show collection-specific approaches (QueryCollection refetch vs Electric awaitTxId) - Provide examples for both patterns
1 parent a6d2c49 commit d2b2c97

File tree

1 file changed

+15
-6
lines changed

1 file changed

+15
-6
lines changed

docs/guides/mutations.md

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,23 +38,32 @@ With an instant inner loop of optimistic state, superseded in time by the slower
3838
> [!TIP]
3939
> **You Can Skip TanStack DB Mutations Entirely**
4040
>
41-
> If you already have mutation logic in an existing system or simply prefer not to use optimistic updates, you can **completely bypass** TanStack DB's mutation system. For many collection types (especially `QueryCollection`), you can:
41+
> If you already have mutation logic in an existing system and don't want to rewrite it, you can **completely bypass** TanStack DB's mutation system. For many collection types, you can:
4242
>
43-
> 1. Call your backend mutation API directly
44-
> 2. Wait for sync systems to sync changes back, **OR** manually refetch the collection with `collection.utils.refetch()`
43+
> 1. Call your backend mutation API directly (using your existing logic)
44+
> 2. Wait for changes to sync back:
45+
> - **QueryCollection**: Manually refetch with `collection.utils.refetch()`
46+
> - **ElectricCollection**: Use `collection.utils.awaitTxId(txid)` to wait for sync
47+
> - **Other sync systems**: Wait for your sync mechanism to update the collection
4548
>
4649
> ```tsx
4750
> // Bypass TanStack DB mutations - use your existing mutation logic
4851
> const handleUpdateTodo = async (todoId, changes) => {
49-
> // Call your backend directly
52+
> // Call your backend directly with your existing logic
5053
> await api.todos.update(todoId, changes)
5154
>
52-
> // Refetch to get updated data
55+
> // Wait for sync back
5356
> await todoCollection.utils.refetch()
5457
> }
58+
>
59+
> // With Electric
60+
> const handleUpdateTodo = async (todoId, changes) => {
61+
> const { txid } = await api.todos.update(todoId, changes)
62+
> await todoCollection.utils.awaitTxId(txid)
63+
> }
5564
> ```
5665
>
57-
> This approach is perfectly valid! The mutation system is optional and designed for scenarios where you want optimistic updates and automatic state management.
66+
> This approach is perfectly valid! The mutation system is optional and designed for when you want the built-in optimistic updates and automatic state management patterns.
5867
5968
### Simplified Mutations vs Traditional Approaches
6069

0 commit comments

Comments
 (0)