Skip to content
Source
Sign inSign up
TanStack/db
Open History to see the last commit

createPacedMutations.md

98 lines2.2 KB

1---
2id: createPacedMutations
3title: createPacedMutations
4---
5​
6# Function: createPacedMutations()
7​
8```ts
9function createPacedMutations<TVariables, T>(config): (variables) => Transaction<T>;
10```
11​
12Defined in: [packages/db/src/paced-mutations.ts:87](https://github.com/TanStack/db/blob/main/packages/db/src/paced-mutations.ts#L87)
13​
14Creates a paced mutations manager with pluggable timing strategies.
15​
16This function provides a way to control when and how optimistic mutations
17are persisted to the backend, using strategies like debouncing, queuing,
18or throttling. The optimistic updates are applied immediately via `onMutate`,
19and the actual persistence is controlled by the strategy.
20​
21The returned function accepts variables of type TVariables and returns a
22Transaction object that can be awaited to know when persistence completes
23or to handle errors.
24​
25## Type Parameters
26​
27### TVariables
28​
29`TVariables` = `unknown`
30​
31### T
32​
33`T` *extends* `object` = `Record`\<`string`, `unknown`\>
34​
35## Parameters
36​
37### config
38​
39[`PacedMutationsConfig`](../interfaces/PacedMutationsConfig.md)\<`TVariables`, `T`\>
40​
41Configuration including onMutate, mutationFn and strategy
42​
43## Returns
44​
45A function that accepts variables and returns a Transaction
46​
47```ts
48(variables): Transaction<T>;
49```
50​
51### Parameters
52​
53#### variables
54​
55`TVariables`
56​
57### Returns
58​
59[`Transaction`](../interfaces/Transaction.md)\<`T`\>
60​
61## Examples
62​
63```ts
64// Debounced mutations for auto-save
65const updateTodo = createPacedMutations<string>({
66 onMutate: (text) => {
67 // Apply optimistic update immediately
68 collection.update(id, draft => { draft.text = text })
69 },
70 mutationFn: async ({ transaction }) => {
71 await api.save(transaction.mutations)
72 },
73 strategy: debounceStrategy({ wait: 500 })
74})
75​
76// Call with variables, returns a transaction
77const tx = updateTodo('New text')
78​
79// Await persistence or handle errors
80await tx.isPersisted.promise
81```
82​
83```ts
84// Queue strategy for sequential processing
85const addTodo = createPacedMutations<{ text: string }>({
86 onMutate: ({ text }) => {
87 collection.insert({ id: uuid(), text, completed: false })
88 },
89 mutationFn: async ({ transaction }) => {
90 await api.save(transaction.mutations)
91 },
92 strategy: queueStrategy({
93 wait: 200,
94 addItemsTo: 'back',
95 getItemsFrom: 'front'
96 })
97})
98```