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

QueryCache.md

496 lines10.3 KB

1---
2id: QueryCache
3title: QueryCache
4---
5​
6<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7​
8Defined in: [packages/vue-query/src/queryCache.ts:16](https://github.com/TanStack/query/blob/main/packages/vue-query/src/queryCache.ts#L16)
9​
10Vue-aware subclass of `@tanstack/query-core`'s `QueryCache`. `find`/`findAll` also accept a
11MaybeRefDeep filters object, so `ref`s can be passed directly without unwrapping. Access it via
12`queryClient.getQueryCache()` β€” `QueryClient` constructs one of these by default.
13​
14## Extends
15​
16- `QueryCache`
17​
18## Constructors
19​
20### Constructor
21​
22```ts
23new QueryCache(config?: QueryCacheConfig): QueryCache;
24```
25​
26Defined in: [packages/query-core/src/queryCache.ts:143](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L143)
27​
28#### Parameters
29​
30##### config?
31​
32[`QueryCacheConfig`](../interfaces/QueryCacheConfig.md) = `{}`
33​
34#### Returns
35​
36`QueryCache`
37​
38#### Inherited from
39​
40```ts
41QC.constructor
42```
43​
44## Properties
45​
46### config
47​
48```ts
49config: QueryCacheConfig = {};
50```
51​
52Defined in: [packages/query-core/src/queryCache.ts:143](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L143)
53​
54#### Inherited from
55​
56```ts
57QC.config
58```
59​
60## Methods
61​
62### build()
63​
64```ts
65build<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(
66 client: QueryClient,
67 options: WithRequired<QueryOptions<TQueryFnData, TError, TData, TQueryKey, never>, "queryKey">,
68 state?: QueryState<TData, TError>
69): Query<TQueryFnData, TError, TData, TQueryKey>;
70```
71​
72Defined in: [packages/query-core/src/queryCache.ts:169](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L169)
73​
74Returns the existing `Query` instance for the given options' `queryKey`/`queryHash`, or
75builds and adds a new one to the cache if none exists yet. Used by framework adapters and
76plugins (e.g. broadcast/persistence) that need to get-or-create a `Query` directly, bypassing
77the reactive `QueryObserver` machinery.
78​
79#### Type Parameters
80​
81##### TQueryFnData
82​
83`TQueryFnData` = `unknown`
84​
85##### TError
86​
87`TError` = `Error`
88​
89##### TData
90​
91`TData` = `TQueryFnData`
92​
93##### TQueryKey
94​
95`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
96​
97#### Parameters
98​
99##### client
100​
101`QueryClient`
102​
103The client the query belongs to, used to default its options.
104​
105##### options
106​
107[`WithRequired`](../type-aliases/WithRequired.md)\<`QueryOptions`\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`, `never`\>, `"queryKey"`\>
108​
109The query options, including the `queryKey`. A new query is created with the
110options defaulted by [QueryClient#defaultQueryOptions](QueryClient.md#defaultqueryoptions).
111​
112##### state?
113​
114[`QueryState`](../interfaces/QueryState.md)\<`TData`, `TError`\>
115​
116The initial state of a newly created query, e.g. when hydrating. Ignored if the
117query already exists.
118​
119#### Returns
120​
121[`Query`](Query.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
122​
123The existing or newly created query.
124​
125#### Example
126​
127```ts
128const queryCache = queryClient.getQueryCache()
129​
130const query = queryCache.build(queryClient, {
131 queryKey: ['posts'],
132 queryFn: fetchPosts,
133})
134```
135​
136#### Inherited from
137​
138```ts
139QC.build
140```
141​
142***
143​
144### clear()
145​
146```ts
147clear(): void;
148```
149​
150Defined in: [packages/query-core/src/queryCache.ts:254](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L254)
151​
152Removes all queries from the cache.
153​
154#### Returns
155​
156`void`
157​
158#### Example
159​
160```ts
161const queryCache = queryClient.getQueryCache()
162​
163queryCache.clear()
164```
165​
166#### Inherited from
167​
168```ts
169QC.clear
170```
171​
172***
173​
174### find()
175​
176```ts
177find<TQueryFnData = unknown, TError = Error, TData = TQueryFnData>(filters: MaybeRefDeep<WithRequired<QueryFilters<readonly unknown[]>, "queryKey">>):
178 | Query<TQueryFnData, TError, TData, readonly unknown[]>
179 | undefined;
180```
181​
182Defined in: [packages/vue-query/src/queryCache.ts:17](https://github.com/TanStack/query/blob/main/packages/vue-query/src/queryCache.ts#L17)
183​
184A slightly more advanced method that can be used to get an existing query instance from the
185cache. This instance not only contains all the state for the query, but all of the instances,
186and underlying guts of the query as well. If the query does not exist, `undefined` is
187returned.
188​
189This is not typically needed for most applications, but can come in handy when needing more
190information about a query in rare scenarios (e.g. looking at `query.state.dataUpdatedAt` to
191decide whether a query is fresh enough to be used as an initial value).
192​
193#### Type Parameters
194​
195##### TQueryFnData
196​
197`TQueryFnData` = `unknown`
198​
199##### TError
200​
201`TError` = `Error`
202​
203##### TData
204​
205`TData` = `TQueryFnData`
206​
207#### Parameters
208​
209##### filters
210​
211`MaybeRefDeep`\<[`WithRequired`](../type-aliases/WithRequired.md)\<[`QueryFilters`](../interfaces/QueryFilters.md)\<readonly `unknown`[]\>, `"queryKey"`\>\>
212​
213The filters to match, including the required `queryKey`. `exact` defaults to
214`true`.
215​
216#### Returns
217​
218 \| [`Query`](Query.md)\<`TQueryFnData`, `TError`, `TData`, readonly `unknown`[]\>
219 \| `undefined`
220​
221The first matching query, or `undefined`.
222​
223#### See
224​
225[QueryCache#findAll](#findall)
226​
227#### Example
228​
229```ts
230const queryCache = queryClient.getQueryCache()
231​
232const query = queryCache.find({ queryKey: ['posts'] })
233```
234​
235#### Overrides
236​
237```ts
238QC.find
239```
240​
241***
242​
243### findAll()
244​
245```ts
246findAll(filters?: MaybeRefDeep<QueryFilters<readonly unknown[]>>): Query<unknown, Error, unknown, readonly unknown[]>[];
247```
248​
249Defined in: [packages/vue-query/src/queryCache.ts:27](https://github.com/TanStack/query/blob/main/packages/vue-query/src/queryCache.ts#L27)
250​
251An even more advanced method that can be used to get existing query instances from the cache
252that partially match a query key. If no queries match, an empty array is returned.
253​
254This is not typically needed for most applications, but can come in handy when needing more
255information about queries in rare scenarios.
256​
257#### Parameters
258​
259##### filters?
260​
261`MaybeRefDeep`\<[`QueryFilters`](../interfaces/QueryFilters.md)\<readonly `unknown`[]\>\> = `{}`
262​
263The filters to match. Without filters, every query is returned.
264​
265#### Returns
266​
267[`Query`](Query.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[]\>[]
268​
269The matching queries.
270​
271#### See
272​
273[QueryCache#find](#find)
274​
275#### Example
276​
277```ts
278const queryCache = queryClient.getQueryCache()
279​
280const queries = queryCache.findAll({ queryKey: ['posts'] })
281```
282​
283#### Overrides
284​
285```ts
286QC.findAll
287```
288​
289***
290​
291### get()
292​
293```ts
294get<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(queryHash: string):
295 | Query<TQueryFnData, TError, TData, TQueryKey>
296 | undefined;
297```
298​
299Defined in: [packages/query-core/src/queryCache.ts:277](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L277)
300​
301Returns the `Query` instance stored under the given `queryHash`, or `undefined` if none
302exists. Unlike [QueryCache#find](#find), this looks up by the already-computed hash rather
303than by `QueryFilters`. Used by plugins (e.g. broadcast/hydration) that already have a hash
304to look up directly.
305​
306#### Type Parameters
307​
308##### TQueryFnData
309​
310`TQueryFnData` = `unknown`
311​
312##### TError
313​
314`TError` = `Error`
315​
316##### TData
317​
318`TData` = `TQueryFnData`
319​
320##### TQueryKey
321​
322`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
323​
324#### Parameters
325​
326##### queryHash
327​
328`string`
329​
330The hash of the query to look up.
331​
332#### Returns
333​
334 \| [`Query`](Query.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
335 \| `undefined`
336​
337The query stored under the hash, or `undefined`.
338​
339#### Example
340​
341```ts
342const queryCache = queryClient.getQueryCache()
343const queryHash = hashKey(['posts'])
344​
345const query = queryCache.get(queryHash)
346```
347​
348#### Inherited from
349​
350```ts
351QC.get
352```
353​
354***
355​
356### getAll()
357​
358```ts
359getAll(): Query<unknown, Error, unknown, readonly unknown[]>[];
360```
361​
362Defined in: [packages/query-core/src/queryCache.ts:300](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L300)
363​
364Returns all queries within the cache.
365​
366#### Returns
367​
368[`Query`](Query.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[]\>[]
369​
370Every query in the cache.
371​
372#### Example
373​
374```ts
375const queryCache = queryClient.getQueryCache()
376​
377const queries = queryCache.getAll()
378```
379​
380#### Inherited from
381​
382```ts
383QC.getAll
384```
385​
386***
387​
388### hasListeners()
389​
390```ts
391hasListeners(): boolean;
392```
393​
394Defined in: [packages/query-core/src/subscribable.ts:43](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L43)
395​
396Returns `true` while at least one listener is registered, `false` once they have all unsubscribed.
397​
398#### Returns
399​
400`boolean`
401​
402`true` if at least one listener is registered.
403​
404#### Inherited from
405​
406```ts
407QC.hasListeners
408```
409​
410***
411​
412### remove()
413​
414```ts
415remove(query: Query<any, any, any, any>): void;
416```
417​
418Defined in: [packages/query-core/src/queryCache.ts:235](https://github.com/TanStack/query/blob/main/packages/query-core/src/queryCache.ts#L235)
419​
420Destroys the given `Query` and removes it from the cache, notifying subscribers with a
421`'removed'` event. A no-op if the query is no longer the one currently stored under its hash
422(e.g. it was already replaced). Used by plugins (e.g. the broadcast client) that mirror
423removals across `QueryCache` instances.
424​
425#### Parameters
426​
427##### query
428​
429[`Query`](Query.md)\<`any`, `any`, `any`, `any`\>
430​
431The query to remove.
432​
433#### Returns
434​
435`void`
436​
437#### Example
438​
439```ts
440const queryCache = queryClient.getQueryCache()
441const query = queryCache.find({ queryKey: ['posts'] })
442​
443if (query) {
444 queryCache.remove(query)
446```
447​
448#### Inherited from
449​
450```ts
451QC.remove
452```
453​
454***
455​
456### subscribe()
457​
458```ts
459subscribe(listener: QueryCacheListener): () => void;
460```
461​
462Defined in: [packages/query-core/src/subscribable.ts:28](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L28)
463​
464Registers a listener to be called on every update this object notifies about. Returns a function
465that removes the listener again β€” call it to stop listening. The base class never drops a listener
466on its own, though some subclasses clear all of theirs in `destroy()`.
467​
468#### Parameters
469​
470##### listener
471​
472`QueryCacheListener`
473​
474Called on each update, with whatever the subclass passes to its subscribers.
475​
476#### Returns
477​
478A function that removes the listener.
479​
480() => `void`
481​
482#### Example
483​
484```ts
485const unsubscribe = subscribable.subscribe(() => {
486 // react to the update
487})
488​
489unsubscribe()
490```
491​
492#### Inherited from
493​
494```ts
495QC.subscribe
496```