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

QueriesObserver.md

302 lines7.8 KB

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