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

MutationCache.md

288 lines6.0 KB

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