Open History to see the last commit
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```