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

MutationCache.md

291 lines6.1 KB

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