Open History to see the last commit
1---
2id: MutationCache
3title: MutationCache
4---
5β
6The `MutationCache` is the storage for mutations.
7β
8**Normally, you will not interact with the MutationCache directly and instead use the `QueryClient`.**
9β
10```tsx
11import { MutationCache } from '@tanstack/react-query'
12β
13const mutationCache = new MutationCache({
14 onError: (error) => {
15 console.log(error)
16 },
17 onSuccess: (data) => {
18 console.log(data)
19 },
20})
21```
22β
23Its available methods are:
24β
25- [`getAll`](#mutationcachegetall)
26- [`subscribe`](#mutationcachesubscribe)
27- [`clear`](#mutationcacheclear)
28β
29**Options**
30β
31- `onError?: (error: unknown, variables: unknown, onMutateResult: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown`
32 - Optional
33 - This function will be called if some mutation encounters an error.
34 - If you return a Promise from it, it will be awaited
35- `onSuccess?: (data: unknown, variables: unknown, onMutateResult: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown`
36 - Optional
37 - This function will be called if some mutation is successful.
38 - If you return a Promise from it, it will be awaited
39- `onSettled?: (data: unknown | undefined, error: unknown | null, variables: unknown, onMutateResult: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown`
40 - Optional
41 - This function will be called if some mutation is settled (either successful or errored).
42 - If you return a Promise from it, it will be awaited
43- `onMutate?: (variables: unknown, mutation: Mutation, mutationFnContext: MutationFunctionContext) => Promise<unknown> | unknown`
44 - Optional
45 - This function will be called before some mutation executes.
46 - If you return a Promise from it, it will be awaited
47β
48## Global callbacks
49β
50The `onError`, `onSuccess`, `onSettled` and `onMutate` callbacks on the MutationCache can be used to handle these events on a global level. They are different to `defaultOptions` provided to the QueryClient because:
51β
52- `defaultOptions` can be overridden by each Mutation - the global callbacks will **always** be called.
53- `onMutate` does not allow returning a result.
54β
55## `mutationCache.getAll`
56β
57`getAll` returns all mutations within the cache.
58β
59> Note: This is not typically needed for most applications, but can come in handy when needing more information about a mutation in rare scenarios
60β
61```tsx
62const mutations = mutationCache.getAll()
63```
64β
65**Returns**
66β
67- `Mutation[]`
68 - Mutation instances from the cache
69β
70## `mutationCache.subscribe`
71β
72The `subscribe` method can be used to subscribe to the mutation cache as a whole and be informed of safe/known updates to the cache like mutation states changing or mutations being updated, added or removed.
73β
74```tsx
75const callback = (event) => {
76 console.log(event.type, event.mutation)
77}
78β
79const unsubscribe = mutationCache.subscribe(callback)
80```
81β
82**Options**
83β
84- `callback: (mutation?: MutationCacheNotifyEvent) => void`
85 - This function will be called with the mutation cache any time it is updated.
86β
87**Returns**
88β
89- `unsubscribe: Function => void`
90 - This function will unsubscribe the callback from the mutation cache.
91β
92## `mutationCache.clear`
93β
94The `clear` method can be used to clear the cache entirely and start fresh.
95β
96```tsx
97mutationCache.clear()
98```