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

MutationCache.md

286 lines5.9 KB

1---
2id: MutationCache
3title: MutationCache
4---
5​
6Defined in: [packages/query-core/src/mutationCache.ts:123](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationCache.ts#L123)
7​
8The `MutationCache` is the storage for mutations.
9​
10Normally, you will not interact with the `MutationCache` directly and instead use a
11`QueryClient`. You can subscribe to it (inherited from `Subscribable`) to be informed of
12safe/known updates to the cache, such as mutations being added, removed, or updated.
13​
14## Example
15​
16```ts
17const unsubscribe = mutationCache.subscribe((event) => {
18 console.log(event.type, event.mutation)
19})
20```
21​
22## Extends
23​
24- `Subscribable`\<`MutationCacheListener`\>
25​
26## Constructors
27​
28### Constructor
29​
30```ts
31new MutationCache(config?: MutationCacheConfig): MutationCache;
32```
33​
34Defined in: [packages/query-core/src/mutationCache.ts:128](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationCache.ts#L128)
35​
36#### Parameters
37​
38##### config?
39​
40[`MutationCacheConfig`](../interfaces/MutationCacheConfig.md) = `{}`
41​
42#### Returns
43​
44`MutationCache`
45​
46#### Overrides
47​
48```ts
49Subscribable<MutationCacheListener>.constructor
50```
51​
52## Properties
53​
54### config
55​
56```ts
57config: MutationCacheConfig = {};
58```
59​
60Defined in: [packages/query-core/src/mutationCache.ts:128](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationCache.ts#L128)
61​
62## Methods
63​
64### clear()
65​
66```ts
67clear(): void;
68```
69​
70Defined in: [packages/query-core/src/mutationCache.ts:262](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationCache.ts#L262)
71​
72Removes all mutations from the cache.
73​
74#### Returns
75​
76`void`
77​
78#### Example
79​
80```ts
81const mutationCache = queryClient.getMutationCache()
82​
83mutationCache.clear()
84```
85​
86***
87​
88### find()
89​
90```ts
91find<TData, TError, TVariables, TOnMutateResult>(filters: MutationFilters):
92 | Mutation<TData, TError, TVariables, TOnMutateResult>
93 | undefined;
94```
95​
96Defined in: [packages/query-core/src/mutationCache.ts:305](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationCache.ts#L305)
97​
98A slightly more advanced method that can be used to get an existing mutation instance from
99the cache. If the mutation does not exist, `undefined` is returned.
100​
101This is not typically needed for most applications, but can come in handy when needing more
102information about a mutation in rare scenarios.
103​
104#### Type Parameters
105​
106##### TData
107​
108`TData` = `unknown`
109​
110##### TError
111​
112`TError` = `Error`
113​
114##### TVariables
115​
116`TVariables` = `any`
117​
118##### TOnMutateResult
119​
120`TOnMutateResult` = `unknown`
121​
122#### Parameters
123​
124##### filters
125​
126[`MutationFilters`](../interfaces/MutationFilters.md)
127​
128The filters to match. `exact` defaults to `true`.
129​
130#### Returns
131​
132 \| [`Mutation`](Mutation.md)\<`TData`, `TError`, `TVariables`, `TOnMutateResult`\>
133 \| `undefined`
134​
135The first matching mutation, or `undefined`.
136​
137#### See
138​
139[MutationCache#findAll](#findall)
140​
141#### Example
142​
143```ts
144const mutationCache = queryClient.getMutationCache()
145​
146const mutation = mutationCache.find({ mutationKey: ['addPost'] })
147```
148​
149***
150​
151### findAll()
152​
153```ts
154findAll(filters?: MutationFilters): Mutation<unknown, Error, unknown, unknown>[];
155```
156​
157Defined in: [packages/query-core/src/mutationCache.ts:336](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationCache.ts#L336)
158​
159An even more advanced method that can be used to get existing mutation instances from the
160cache that match the given filters. If no mutations match, an empty array is returned.
161​
162This is not typically needed for most applications, but can come in handy when needing more
163information about mutations in rare scenarios.
164​
165#### Parameters
166​
167##### filters?
168​
169[`MutationFilters`](../interfaces/MutationFilters.md) = `{}`
170​
171The filters to match. Without filters, every mutation is returned.
172​
173#### Returns
174​
175[`Mutation`](Mutation.md)\<`unknown`, `Error`, `unknown`, `unknown`\>[]
176​
177The matching mutations.
178​
179#### See
180​
181[MutationCache#find](#find)
182​
183#### Example
184​
185```ts
186const mutationCache = queryClient.getMutationCache()
187​
188const mutations = mutationCache.findAll({ mutationKey: ['addPost'] })
189```
190​
191***
192​
193### getAll()
194​
195```ts
196getAll(): Mutation<unknown, Error, unknown, unknown>[];
197```
198​
199Defined in: [packages/query-core/src/mutationCache.ts:285](https://github.com/TanStack/query/blob/main/packages/query-core/src/mutationCache.ts#L285)
200​
201Returns all mutations within the cache.
202​
203This is not typically needed for most applications, but can come in handy when needing more
204information about a mutation in rare scenarios.
205​
206#### Returns
207​
208[`Mutation`](Mutation.md)\<`unknown`, `Error`, `unknown`, `unknown`\>[]
209​
210Every mutation in the cache.
211​
212#### Example
213​
214```ts
215const mutationCache = queryClient.getMutationCache()
216​
217const mutations = mutationCache.getAll()
218```
219​
220***
221​
222### hasListeners()
223​
224```ts
225hasListeners(): boolean;
226```
227​
228Defined in: [packages/query-core/src/subscribable.ts:43](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L43)
229​
230Returns `true` while at least one listener is registered, `false` once they have all unsubscribed.
231​
232#### Returns
233​
234`boolean`
235​
236`true` if at least one listener is registered.
237​
238#### Inherited from
239​
240```ts
241Subscribable.hasListeners
242```
243​
244***
245​
246### subscribe()
247​
248```ts
249subscribe(listener: MutationCacheListener): () => void;
250```
251​
252Defined in: [packages/query-core/src/subscribable.ts:28](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L28)
253​
254Registers a listener to be called on every update this object notifies about. Returns a function
255that removes the listener again β€” call it to stop listening. The base class never drops a listener
256on its own, though some subclasses clear all of theirs in `destroy()`.
257​
258#### Parameters
259​
260##### listener
261​
262`MutationCacheListener`
263​
264Called on each update, with whatever the subclass passes to its subscribers.
265​
266#### Returns
267​
268A function that removes the listener.
269​
270() => `void`
271​
272#### Example
273​
274```ts
275const unsubscribe = subscribable.subscribe(() => {
276 // react to the update
277})
278​
279unsubscribe()
280```
281​
282#### Inherited from
283​
284```ts
285Subscribable.subscribe
286```