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

QueriesObserver.md

307 lines8.3 KB

1---
2id: QueriesObserver
3title: QueriesObserver
4---
5​
6<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7​
8Defined in: [packages/query-core/src/queriesObserver.ts:64](https://github.com/TanStack/query/blob/main/packages/query-core/src/queriesObserver.ts#L64)
9​
10A `QueriesObserver` watches an array of queries at once, exposing them as
11a single array of `QueryObserverResult`s (or, when a `combine` option is
12given, as a combined value derived from that array). It manages one
13internal `QueryObserver` per query, and is the primitive that framework
14adapters (e.g. `useQueries`) build their hooks on top of.
15​
16## Example
17​
18```ts
19const observer = new QueriesObserver(queryClient, [
20 { queryKey: ['post', 1], queryFn: fetchPost },
21 { queryKey: ['post', 2], queryFn: fetchPost },
22])
23​
24const unsubscribe = observer.subscribe((result) => {
25 console.log(result)
26})
27```
28​
29## Extends
30​
31- `Subscribable`\<`QueriesObserverListener`\>
32​
33## Type Parameters
34​
35### TCombinedResult
36​
37`TCombinedResult` = [`QueryObserverResult`](../type-aliases/QueryObserverResult.md)[]
38​
39## Constructors
40​
41### Constructor
42​
43```ts
44new QueriesObserver<TCombinedResult = QueryObserverResult[]>(
45 client: QueryClient,
46 queries: QueryObserverOptions<any, any, any, any, any, never>[],
47 options?: QueriesObserverOptions<TCombinedResult>
48): QueriesObserver<TCombinedResult>;
49```
50​
51Defined in: [packages/query-core/src/queriesObserver.ts:78](https://github.com/TanStack/query/blob/main/packages/query-core/src/queriesObserver.ts#L78)
52​
53#### Parameters
54​
55##### client
56​
57[`QueryClient`](QueryClient.md)
58​
59##### queries
60​
61[`QueryObserverOptions`](../interfaces/QueryObserverOptions.md)\<`any`, `any`, `any`, `any`, `any`, `never`\>[]
62​
63##### options?
64​
65[`QueriesObserverOptions`](../interfaces/QueriesObserverOptions.md)\<`TCombinedResult`\>
66​
67#### Returns
68​
69`QueriesObserver`\<`TCombinedResult`\>
70​
71#### Overrides
72​
73```ts
74Subscribable<QueriesObserverListener>.constructor
75```
76​
77## Methods
78​
79### destroy()
80​
81```ts
82destroy(): void;
83```
84​
85Defined in: [packages/query-core/src/queriesObserver.ts:114](https://github.com/TanStack/query/blob/main/packages/query-core/src/queriesObserver.ts#L114)
86​
87Stops observing all queries: clears all listeners and destroys every
88underlying `QueryObserver` this observer manages.
89​
90#### Returns
91​
92`void`
93​
94***
95​
96### getCurrentResult()
97​
98```ts
99getCurrentResult(): QueryObserverResult[];
100```
101​
102Defined in: [packages/query-core/src/queriesObserver.ts:219](https://github.com/TanStack/query/blob/main/packages/query-core/src/queriesObserver.ts#L219)
103​
104Returns the most recently computed array of `QueryObserverResult`s, one
105per observed query, in the same order as the queries passed to the
106constructor or `setQueries`.
107​
108#### Returns
109​
110[`QueryObserverResult`](../type-aliases/QueryObserverResult.md)[]
111​
112The current results.
113​
114#### Example
115​
116```ts
117const results = observer.getCurrentResult()
118const data = results.map((result) => result.data)
119```
120​
121***
122​
123### getObservers()
124​
125```ts
126getObservers(): QueryObserver<unknown, Error, unknown, unknown, readonly unknown[]>[];
127```
128​
129Defined in: [packages/query-core/src/queriesObserver.ts:238](https://github.com/TanStack/query/blob/main/packages/query-core/src/queriesObserver.ts#L238)
130​
131Returns the underlying `QueryObserver` instances this observer manages,
132in the same order as the queries passed to the constructor or
133`setQueries`.
134​
135#### Returns
136​
137[`QueryObserver`](QueryObserver.md)\<`unknown`, `Error`, `unknown`, `unknown`, readonly `unknown`[]\>[]
138​
139The managed query observers.
140​
141***
142​
143### getOptimisticResult()
144​
145```ts
146getOptimisticResult(queries: QueryObserverOptions<unknown, Error, unknown, unknown, readonly unknown[], never>[], combine: CombineFn<TCombinedResult> | undefined): [rawResult: QueryObserverResult[], combineResult: (r?: QueryObserverResult[]) => TCombinedResult, trackResult: () => QueryObserverResult[]];
147```
148​
149Defined in: [packages/query-core/src/queriesObserver.ts:255](https://github.com/TanStack/query/blob/main/packages/query-core/src/queriesObserver.ts#L255)
150​
151The `QueriesObserver` counterpart of [QueryObserver#getOptimisticResult](QueryObserver.md#getoptimisticresult) β€” computes
152the result for the given (already-defaulted) queries right now, synchronously. Called by
153framework adapters (e.g. `useQueries`) ahead of subscribing, returning a tuple of the raw
154per-query results, a function to compute the combined result from them, and a function to
155wrap the results for property-access tracking. When the queries match the observed ones, the
156results also become the current result, so a later `setQueries` call with the same queries
157does not notify the listeners about them.
158​
159#### Parameters
160​
161##### queries
162​
163[`QueryObserverOptions`](../interfaces/QueryObserverOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`, readonly `unknown`[], `never`\>[]
164​
165The defaulted options of the queries to compute the result for.
166​
167##### combine
168​
169`CombineFn`\<`TCombinedResult`\> \| `undefined`
170​
171The `combine` function used by the returned `combineResult`, if any.
172​
173#### Returns
174​
175\[`rawResult`: [`QueryObserverResult`](../type-aliases/QueryObserverResult.md)[], `combineResult`: (`r?`: [`QueryObserverResult`](../type-aliases/QueryObserverResult.md)[]) => `TCombinedResult`, `trackResult`: () => [`QueryObserverResult`](../type-aliases/QueryObserverResult.md)[]\]
176​
177A tuple of the per-query results, a function that computes the combined result, and a
178function that returns the results wrapped for property-access tracking.
179​
180***
181​
182### getQueries()
183​
184```ts
185getQueries(): Query<unknown, Error, unknown, readonly unknown[]>[];
186```
187​
188Defined in: [packages/query-core/src/queriesObserver.ts:228](https://github.com/TanStack/query/blob/main/packages/query-core/src/queriesObserver.ts#L228)
189​
190Returns the underlying `Query` instances currently being observed, in
191the same order as the queries passed to the constructor or `setQueries`.
192​
193#### Returns
194​
195[`Query`](Query.md)\<`unknown`, `Error`, `unknown`, readonly `unknown`[]\>[]
196​
197The observed queries.
198​
199***
200​
201### hasListeners()
202​
203```ts
204hasListeners(): boolean;
205```
206​
207Defined in: [packages/query-core/src/subscribable.ts:46](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L46)
208​
209Returns `true` while at least one listener is registered, `false` once they have all unsubscribed.
210​
211#### Returns
212​
213`boolean`
214​
215`true` if at least one listener is registered.
216​
217#### Inherited from
218​
219```ts
220Subscribable.hasListeners
221```
222​
223***
224​
225### setQueries()
226​
227```ts
228setQueries(queries: QueryObserverOptions<unknown, Error, unknown, unknown, readonly unknown[], never>[], options?: QueriesObserverOptions<TCombinedResult>): void;
229```
230​
231Defined in: [packages/query-core/src/queriesObserver.ts:136](https://github.com/TanStack/query/blob/main/packages/query-core/src/queriesObserver.ts#L136)
232​
233Replaces the set of queries being observed. Existing `QueryObserver`s
234are reused for queries that match an already-observed query hash;
235observers for queries that are no longer present are destroyed, and new
236observers are created and subscribed to for newly added queries.
237​
238#### Parameters
239​
240##### queries
241​
242[`QueryObserverOptions`](../interfaces/QueryObserverOptions.md)\<`unknown`, `Error`, `unknown`, `unknown`, readonly `unknown`[], `never`\>[]
243​
244The options of the queries to observe.
245​
246##### options?
247​
248[`QueriesObserverOptions`](../interfaces/QueriesObserverOptions.md)\<`TCombinedResult`\>
249​
250Replaces the observer's options, e.g. its `combine` function.
251​
252#### Returns
253​
254`void`
255​
256#### Example
257​
258```ts
259observer.setQueries([
260 { queryKey: ['post', 1], queryFn: fetchPost },
261 { queryKey: ['post', 3], queryFn: fetchPost },
262])
263```
264​
265***
266​
267### subscribe()
268​
269```ts
270subscribe(listener: QueriesObserverListener): () => void;
271```
272​
273Defined in: [packages/query-core/src/subscribable.ts:31](https://github.com/TanStack/query/blob/main/packages/query-core/src/subscribable.ts#L31)
274​
275Registers a listener to be called on every update this object notifies about. Returns a function
276that removes the listener again β€” call it to stop listening. The base class never drops a listener
277on its own, though some subclasses clear all of theirs in `destroy()`.
278​
279#### Parameters
280​
281##### listener
282​
283`QueriesObserverListener`
284​
285Called on each update, with whatever the subclass passes to its subscribers.
286​
287#### Returns
288​
289A function that removes the listener.
290​
291() => `void`
292​
293#### Example
294​
295```ts
296const unsubscribe = subscribable.subscribe(() => {
297 // react to the update
298})
299​
300unsubscribe()
301```
302​
303#### Inherited from
304​
305```ts
306Subscribable.subscribe
307```