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

usePacedMutations.md

131 lines2.8 KB

1---
2id: usePacedMutations
3title: usePacedMutations
4---
5​
6# Function: usePacedMutations()
7​
8```ts
9function usePacedMutations<TVariables, T>(config): (variables) => Transaction<T>;
10```
11​
12Defined in: [usePacedMutations.ts:93](https://github.com/TanStack/db/blob/main/packages/react-db/src/usePacedMutations.ts#L93)
13​
14React hook for managing paced mutations with timing strategies.
15​
16Provides optimistic mutations with pluggable strategies like debouncing,
17queuing, or throttling. The optimistic updates are applied immediately via
18`onMutate`, and the actual persistence is controlled by the strategy.
19​
20## Type Parameters
21​
22### TVariables
23​
24`TVariables` = `unknown`
25​
26### T
27​
28`T` *extends* `object` = `Record`\<`string`, `unknown`\>
29​
30## Parameters
31​
32### config
33​
34`PacedMutationsConfig`\<`TVariables`, `T`\>
35​
36Configuration including onMutate, mutationFn and strategy
37​
38## Returns
39​
40A mutate function that accepts variables and returns Transaction objects
41​
42```ts
43(variables): Transaction<T>;
44```
45​
46### Parameters
47​
48#### variables
49​
50`TVariables`
51​
52### Returns
53​
54`Transaction`\<`T`\>
55​
56## Examples
57​
58```tsx
59// Debounced auto-save
60function AutoSaveForm({ formId }: { formId: string }) {
61 const mutate = usePacedMutations<string>({
62 onMutate: (value) => {
63 // Apply optimistic update immediately
64 formCollection.update(formId, draft => {
65 draft.content = value
66 })
67 },
68 mutationFn: async ({ transaction }) => {
69 await api.save(transaction.mutations)
70 },
71 strategy: debounceStrategy({ wait: 500 })
72 })
73​
74 const handleChange = async (value: string) => {
75 const tx = mutate(value)
76​
77 // Optional: await persistence or handle errors
78 try {
79 await tx.isPersisted.promise
80 console.log('Saved!')
81 } catch (error) {
82 console.error('Save failed:', error)
83 }
84 }
85​
86 return <textarea onChange={e => handleChange(e.target.value)} />
88```
89​
90```tsx
91// Throttled slider updates
92function VolumeSlider() {
93 const mutate = usePacedMutations<number>({
94 onMutate: (volume) => {
95 settingsCollection.update('volume', draft => {
96 draft.value = volume
97 })
98 },
99 mutationFn: async ({ transaction }) => {
100 await api.updateVolume(transaction.mutations)
101 },
102 strategy: throttleStrategy({ wait: 200 })
103 })
104​
105 return <input type="range" onChange={e => mutate(+e.target.value)} />
107```
108​
109```tsx
110// Debounce with leading/trailing for color picker (persist first + final only)
111function ColorPicker() {
112 const mutate = usePacedMutations<string>({
113 onMutate: (color) => {
114 themeCollection.update('primary', draft => {
115 draft.color = color
116 })
117 },
118 mutationFn: async ({ transaction }) => {
119 await api.updateTheme(transaction.mutations)
120 },
121 strategy: debounceStrategy({ wait: 0, leading: true, trailing: true })
122 })
123​
124 return (
125 <input
126 type="color"
127 onChange={e => mutate(e.target.value)}
128 />
129 )
131```