Defined in: packages/query-core/src/queryObserver.ts:57
A QueryObserver watches a single query in the QueryCache and computes a
QueryObserverResult from its state, recomputing and notifying subscribers
whenever the underlying query (or the observer's options) changes. It is
the primitive that framework adapters (e.g. useQuery) build their hooks
on top of, but it can also be used directly to observe and switch between
queries outside of any framework.
Example#
const observer = new QueryObserver(queryClient, {
queryKey: ['posts'],
queryFn: fetchPosts,
})
const unsubscribe = observer.subscribe((result) => {
console.log(result.data)
})
Extends#
Subscribable<QueryObserverListener<TData,TError>>
Extended by#
Type Parameters#
TQueryFnData#
TQueryFnData = unknown
TError#
TError = DefaultError
TData#
TData = TQueryFnData
TQueryData#
TQueryData = TQueryFnData
TQueryKey#
TQueryKey extends QueryKey = QueryKey
Constructors#
Constructor#
new QueryObserver<TQueryFnData, TError, TData, TQueryData, TQueryKey>(client: QueryClient, options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): QueryObserver<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
Defined in: packages/query-core/src/queryObserver.ts:87
Parameters#
client#
options#
QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
Returns#
QueryObserver<TQueryFnData, TError, TData, TQueryData, TQueryKey>
Overrides#
Subscribable<QueryObserverListener<TData, TError>>.constructor
Properties#
listeners#
protected listeners: Set<QueryObserverListener<TData, TError>>;
Defined in: packages/query-core/src/subscribable.ts:2
Inherited from#
Subscribable.listeners
options#
options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
Defined in: packages/query-core/src/queryObserver.ts:89
Methods#
bindMethods()#
protected bindMethods(): void;
Defined in: packages/query-core/src/queryObserver.ts:106
Returns#
void
createResult()#
protected createResult(query: Query<TQueryFnData, TError, TQueryData, TQueryKey>, options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): QueryObserverResult<TData, TError>;
Defined in: packages/query-core/src/queryObserver.ts:559
Parameters#
query#
Query<TQueryFnData, TError, TQueryData, TQueryKey>
options#
QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
Returns#
QueryObserverResult<TData, TError>
destroy()#
destroy(): void;
Defined in: packages/query-core/src/queryObserver.ts:161
Stops observing the current query: clears all listeners, cancels the stale and refetch-interval timers, and removes this observer from the query it was observing.
Returns#
void
fetch()#
protected fetch(fetchOptions: ObserverFetchOptions): Promise<QueryObserverResult<TData, TError>>;
Defined in: packages/query-core/src/queryObserver.ts:448
Parameters#
fetchOptions#
ObserverFetchOptions
Returns#
Promise<QueryObserverResult<TData, TError>>
fetchOptimistic()#
fetchOptimistic(options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): Promise<QueryObserverResult<TData, TError>>;
Defined in: packages/query-core/src/queryObserver.ts:395
Fetches a query defined by the given options without affecting this
observer's own tracked query or result, and returns a promise that
resolves with the QueryObserverResult for that fetch. This is useful
for prefetching data that another observer (e.g. a query about to be
navigated to) will need, ahead of time.
Parameters#
options#
QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
Returns#
Promise<QueryObserverResult<TData, TError>>
Example#
const result = await observer.fetchOptimistic({
queryKey: ['posts', 2],
queryFn: () => fetchPost(2),
})
console.log(result.data)
getCurrentQuery()#
getCurrentQuery(): Query<TQueryFnData, TError, TQueryData, TQueryKey>;
Defined in: packages/query-core/src/queryObserver.ts:357
Returns the Query instance this observer is currently observing.
Returns#
Query<TQueryFnData, TError, TQueryData, TQueryKey>
getCurrentResult()#
getCurrentResult(): QueryObserverResult<TData, TError>;
Defined in: packages/query-core/src/queryObserver.ts:321
Returns the most recently computed QueryObserverResult for the
observed query. This is a point-in-time read; to be notified of updates
as they happen, subscribe to the observer instead (its inherited
subscribe method).
Returns#
QueryObserverResult<TData, TError>
Example#
const result = observer.getCurrentResult()
console.log(result.status, result.data)
getOptimisticResult()#
getOptimisticResult(options: DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): QueryObserverResult<TData, TError>;
Defined in: packages/query-core/src/queryObserver.ts:272
Computes the result the observer would produce for the given (already-defaulted) options
right now, building the underlying Query if it doesn't exist yet, without waiting for a
subscription callback. Called by framework adapters on every render (e.g. useQuery) so the
returned value is available synchronously, ahead of setOptions triggering an actual fetch.
Parameters#
options#
DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
Returns#
QueryObserverResult<TData, TError>
hasListeners()#
hasListeners(): boolean;
Defined in: packages/query-core/src/subscribable.ts:19
Returns#
boolean
Inherited from#
Subscribable.hasListeners
onSubscribe()#
protected onSubscribe(): void;
Defined in: packages/query-core/src/queryObserver.ts:110
Returns#
void
Overrides#
Subscribable.onSubscribe
onUnsubscribe()#
protected onUnsubscribe(): void;
Defined in: packages/query-core/src/queryObserver.ts:124
Returns#
void
Overrides#
Subscribable.onUnsubscribe
refetch()#
refetch(__namedParameters: RefetchOptions): Promise<QueryObserverResult<TData, TError>>;
Defined in: packages/query-core/src/queryObserver.ts:371
Refetches the observed query and returns a promise that resolves with
the resulting QueryObserverResult.
Parameters#
__namedParameters#
RefetchOptions = {}
Returns#
Promise<QueryObserverResult<TData, TError>>
Example#
const result = await observer.refetch({ cancelRefetch: false })
console.log(result.data)
setOptions()#
setOptions(options: QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): void;
Defined in: packages/query-core/src/queryObserver.ts:182
Updates the observer's options. This will re-resolve the query being
observed (switching to a different query if the queryKey changed),
trigger a fetch if the new options require one and the observer has
subscribers, recompute the current result, and reschedule the stale and
refetch-interval timers as needed.
Parameters#
options#
QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
Returns#
void
Example#
observer.setOptions({ queryKey: ['posts', 1], queryFn: () => fetchPost(1) })
// later: switch to a different query, reusing the same observer
observer.setOptions({ queryKey: ['posts', 2], queryFn: () => fetchPost(2) })
shouldFetchOnReconnect()#
shouldFetchOnReconnect(): boolean;
Defined in: packages/query-core/src/queryObserver.ts:135
Returns whether the observed query is currently stale and configured
(via the refetchOnReconnect option) to refetch when the network
reconnects.
Returns#
boolean
shouldFetchOnWindowFocus()#
shouldFetchOnWindowFocus(): boolean;
Defined in: packages/query-core/src/queryObserver.ts:148
Returns whether the observed query is currently stale and configured
(via the refetchOnWindowFocus option) to refetch when the window
regains focus.
Returns#
boolean
subscribe()#
subscribe(listener: QueryObserverListener): () => void;
Defined in: packages/query-core/src/subscribable.ts:8
Parameters#
listener#
QueryObserverListener
Returns#
(): void;
Returns#
void
Inherited from#
Subscribable.subscribe
trackProp()#
trackProp(key:
| "error"
| "data"
| "isError"
| "isPending"
| "isLoading"
| "isLoadingError"
| "isRefetchError"
| "isSuccess"
| "isPlaceholderData"
| "status"
| "dataUpdatedAt"
| "errorUpdatedAt"
| "failureCount"
| "failureReason"
| "errorUpdateCount"
| "isFetched"
| "isFetchedAfterMount"
| "isFetching"
| "isInitialLoading"
| "isPaused"
| "isRefetching"
| "isStale"
| "isEnabled"
| "refetch"
| "fetchStatus"): void;
Defined in: packages/query-core/src/queryObserver.ts:350
Records that the given QueryObserverResult property was read, so a subsequent update only
notifies this observer if a tracked property actually changed. Normally called indirectly via
QueryObserver#trackResult's proxy; exposed directly for adapters that track property
access themselves (e.g. through their own reactivity system) instead of via the proxy.
Parameters#
key#
"error" | "data" | "isError" | "isPending" | "isLoading" | "isLoadingError" | "isRefetchError" | "isSuccess" | "isPlaceholderData" | "status" | "dataUpdatedAt" | "errorUpdatedAt" | "failureCount" | "failureReason" | "errorUpdateCount" | "isFetched" | "isFetchedAfterMount" | "isFetching" | "isInitialLoading" | "isPaused" | "isRefetching" | "isStale" | "isEnabled" | "refetch" | "fetchStatus"
Returns#
void
trackResult()#
trackResult(result: QueryObserverResult<TData, TError>, onPropTracked?: (key:
| "error"
| "data"
| "isError"
| "isPending"
| "isLoading"
| "isLoadingError"
| "isRefetchError"
| "isSuccess"
| "isPlaceholderData"
| "status"
| "dataUpdatedAt"
| "errorUpdatedAt"
| "failureCount"
| "failureReason"
| "errorUpdateCount"
| "isFetched"
| "isFetchedAfterMount"
| "isFetching"
| "isInitialLoading"
| "isPaused"
| "isRefetching"
| "isStale"
| "isEnabled"
| "refetch"
| "fetchStatus") => void): QueryObserverResult<TData, TError>;
Defined in: packages/query-core/src/queryObserver.ts:331
Wraps a QueryObserverResult in a Proxy that records which properties are read, via
QueryObserver#trackProp (and an optional onPropTracked callback). Used by framework
adapters when notifyOnChangeProps is not set, to implement its default "only re-render on
properties you actually read" behavior.
Parameters#
result#
QueryObserverResult<TData, TError>
onPropTracked?#
(key:
| "error"
| "data"
| "isError"
| "isPending"
| "isLoading"
| "isLoadingError"
| "isRefetchError"
| "isSuccess"
| "isPlaceholderData"
| "status"
| "dataUpdatedAt"
| "errorUpdatedAt"
| "failureCount"
| "failureReason"
| "errorUpdateCount"
| "isFetched"
| "isFetchedAfterMount"
| "isFetching"
| "isInitialLoading"
| "isPaused"
| "isRefetching"
| "isStale"
| "isEnabled"
| "refetch"
| "fetchStatus") => void
Returns#
QueryObserverResult<TData, TError>
updateResult()#
updateResult(): void;
Defined in: packages/query-core/src/queryObserver.ts:735
Recomputes and stores the current result from the current query/options, notifying listeners if it changed. Framework adapters call this right after subscribing to make sure no query update was missed in the gap between creating the observer and subscribing to it.
Returns#
void