@tanstack/query-core 5.102.7 → 5.103.0

package/src/queriesObserver.ts

@@ -23,9 +23,36 @@ type CombineFn<TCombinedResult> = (
 export interface QueriesObserverOptions<
   TCombinedResult = Array<QueryObserverResult>,
 > {
+  /**
+   * A function that combines the array of `QueryObserverResult`s (one per
+   * observed query) into a single value. The combined value is memoized and
+   * only recomputed when one of the underlying results, the query hashes, or
+   * the `combine` function itself changes.
+   *
+   * Defaults to returning the array of `QueryObserverResult`s unchanged.
+   */
   combine?: CombineFn<TCombinedResult>
 }
 
+/**
+ * A `QueriesObserver` watches an array of queries at once, exposing them as
+ * a single array of `QueryObserverResult`s (or, when a `combine` option is
+ * given, as a combined value derived from that array). It manages one
+ * internal `QueryObserver` per query, and is the primitive that framework
+ * adapters (e.g. `useQueries`) build their hooks on top of.
+ *
+ * @example
+ * ```ts
+ * const observer = new QueriesObserver(queryClient, [
+ *   { queryKey: ['post', 1], queryFn: fetchPost },
+ *   { queryKey: ['post', 2], queryFn: fetchPost },
+ * ])
+ *
+ * const unsubscribe = observer.subscribe((result) => {
+ *   console.log(result)
+ * })
+ * ```
+ */
 export class QueriesObserver<
   TCombinedResult = Array<QueryObserverResult>,
 > extends Subscribable<QueriesObserverListener> {
@@ -72,6 +99,10 @@ export class QueriesObserver<
     }
   }
 
+  /**
+   * Stops observing all queries: clears all listeners and destroys every
+   * underlying `QueryObserver` this observer manages.
+   */
   destroy(): void {
     this.listeners = new Set()
     this.#observers.forEach((observer) => {
@@ -79,6 +110,20 @@ export class QueriesObserver<
     })
   }
 
+  /**
+   * Replaces the set of queries being observed. Existing `QueryObserver`s
+   * are reused for queries that match an already-observed query hash;
+   * observers for queries that are no longer present are destroyed, and new
+   * observers are created and subscribed to for newly added queries.
+   *
+   * @example
+   * ```ts
+   * observer.setQueries([
+   *   { queryKey: ['post', 1], queryFn: fetchPost },
+   *   { queryKey: ['post', 3], queryFn: fetchPost },
+   * ])
+   * ```
+   */
   setQueries(
     queries: Array<QueryObserverOptions>,
     options?: QueriesObserverOptions<TCombinedResult>,
@@ -151,18 +196,45 @@ export class QueriesObserver<
     })
   }
 
+  /**
+   * Returns the most recently computed array of `QueryObserverResult`s, one
+   * per observed query, in the same order as the queries passed to the
+   * constructor or `setQueries`.
+   *
+   * @example
+   * ```ts
+   * const results = observer.getCurrentResult()
+   * const data = results.map((result) => result.data)
+   * ```
+   */
   getCurrentResult(): Array<QueryObserverResult> {
     return this.#result
   }
 
+  /**
+   * Returns the underlying `Query` instances currently being observed, in
+   * the same order as the queries passed to the constructor or `setQueries`.
+   */
   getQueries() {
     return this.#observers.map((observer) => observer.getCurrentQuery())
   }
 
+  /**
+   * Returns the underlying `QueryObserver` instances this observer manages,
+   * in the same order as the queries passed to the constructor or
+   * `setQueries`.
+   */
   getObservers() {
     return this.#observers
   }
 
+  /**
+   * The `QueriesObserver` counterpart of {@link QueryObserver#getOptimisticResult} — computes
+   * the result for the given (already-defaulted) queries right now, synchronously. Called by
+   * framework adapters (e.g. `useQueries`) ahead of subscribing, returning a tuple of the raw
+   * per-query results, a function to compute the combined result from them, and a function to
+   * wrap the results for property-access tracking.
+   */
   getOptimisticResult(
     queries: Array<QueryObserverOptions>,
     combine: CombineFn<TCombinedResult> | undefined,

package/src/query.ts

@@ -45,18 +45,70 @@ interface QueryConfig<
   state?: QueryState<TData, TError>
 }
 
+/**
+ * The raw state stored on a `Query` instance. This is the underlying state
+ * that observer results (e.g. `QueryObserverResult`) are derived from.
+ */
 export interface QueryState<TData = unknown, TError = DefaultError> {
+  /**
+   * The last successfully resolved data for the query.
+   */
   data: TData | undefined
+  /**
+   * The number of times the query has successfully resolved.
+   */
   dataUpdateCount: number
+  /**
+   * The timestamp for when the query most recently returned the `status` as `"success"`.
+   */
   dataUpdatedAt: number
+  /**
+   * The error object for the query, if the last attempt resulted in an error.
+   * - Defaults to `null`.
+   */
   error: TError | null
+  /**
+   * The sum of all errors, incremented every time the query resolves with an error.
+   */
   errorUpdateCount: number
+  /**
+   * The timestamp for when the query most recently returned the `status` as `"error"`.
+   */
   errorUpdatedAt: number
+  /**
+   * The failure count for the current fetch.
+   * - Incremented every time the fetch fails.
+   * - Reset to `0` when the fetch succeeds.
+   */
   fetchFailureCount: number
+  /**
+   * The reason the current fetch failed, as reported by the retryer.
+   * - Reset to `null` when the fetch succeeds.
+   */
   fetchFailureReason: TError | null
+  /**
+   * Metadata passed to the currently in-flight (or most recent) fetch, e.g. the
+   * `fetchMore` direction for infinite queries.
+   */
   fetchMeta: FetchMeta | null
+  /**
+   * Whether the query has been marked as invalidated via `invalidate()`.
+   * - Reset to `false` whenever the query resolves successfully.
+   */
   isInvalidated: boolean
+  /**
+   * The status of the query.
+   * - `pending` if there's no cached data and no attempt was finished yet.
+   * - `error` if the last attempt resulted in an error.
+   * - `success` if the query has data.
+   */
   status: QueryStatus
+  /**
+   * The fetch status of the query.
+   * - `fetching`: the `queryFn` is currently executing.
+   * - `paused`: a fetch wanted to run but has been paused (see network mode).
+   * - `idle`: the query is not fetching.
+   */
   fetchStatus: FetchStatus
 }
 
@@ -151,6 +203,25 @@ export type Action<TData, TError> =
 
 // CLASS
 
+/**
+ * Represents a single cached query. A `Query` holds the query's key, options,
+ * state (data/error/status), and the observers currently subscribed to it.
+ *
+ * Instances are created and managed internally by `QueryCache`; application
+ * code typically interacts with queries indirectly through `QueryClient` or
+ * a framework hook like `useQuery`. Direct access to a `Query` instance is
+ * possible via `queryCache.find()`/`findAll()` for inspecting cache state.
+ *
+ * @example
+ * ```ts
+ * const queryCache = queryClient.getQueryCache()
+ * const query = queryCache.find({ queryKey: ['posts'] })
+ *
+ * if (query) {
+ *   console.log(query.state.dataUpdatedAt)
+ * }
+ * ```
+ */
 export class Query<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -187,18 +258,27 @@ export class Query<
     this.state = config.state ?? this.#initialState
     this.scheduleGc()
   }
+  /**
+   * The `meta` object passed in the query's options, if any.
+   */
   get meta(): QueryMeta | undefined {
     return this.options.meta
   }
 
+  /** @internal */
   get queryType() {
     return this.#queryType
   }
 
+  /**
+   * The promise for the currently in-flight fetch, if the query is fetching.
+   * `undefined` when the query is not fetching.
+   */
   get promise(): Promise<TData> | undefined {
     return this.#retryer?.promise
   }
 
+  /** @internal */
   setOptions(
     options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,
   ): void {
@@ -228,6 +308,7 @@ export class Query<
     }
   }
 
+  /** @internal */
   setData(
     newData: TData,
     options?: SetDataOptions & { manual: boolean },
@@ -245,37 +326,77 @@ export class Query<
     return data
   }
 
+  /**
+   * Merges the given partial state directly into this query's state, notifying observers. Used
+   * by persistence and broadcast plugins to restore a state snapshot, and by devtools to let a
+   * user manually trigger a loading/error state or edit the cached data.
+   */
   setState(state: Partial<QueryState<TData, TError>>): void {
     this.#dispatch({ type: 'setState', state })
   }
 
+  /**
+   * Cancels the query's currently in-flight fetch, if any.
+   * - Returns a promise that resolves once the cancellation has settled.
+   * - If no fetch is in progress, resolves immediately.
+   *
+   * @example
+   * ```ts
+   * await query.cancel()
+   * ```
+   */
   cancel(options?: CancelOptions): Promise<void> {
     const promise = this.#retryer?.promise
     this.#retryer?.cancel(options)
     return promise ? promise.then(noop).catch(noop) : Promise.resolve()
   }
 
+  /**
+   * Clears the query's garbage collection timeout and silently cancels any
+   * in-flight fetch. Called by `QueryCache` when the query is removed from
+   * the cache.
+   *
+   * @see {@link Query#cancel}
+   */
   destroy(): void {
     super.destroy()
 
     this.cancel({ silent: true })
   }
 
+  /** @internal */
   get resetState(): QueryState<TData, TError> {
     return this.#initialState
   }
 
+  /**
+   * Resets the query back to its initial state (the state it had when it was
+   * first created, e.g. any `initialData`), destroying it first to cancel any
+   * in-flight fetch.
+   */
   reset(): void {
     this.destroy()
     this.setState(this.resetState)
   }
 
+  /**
+   * Returns `true` if the query has at least one observer for which `enabled`
+   * does not resolve to `false`.
+   */
   isActive(): boolean {
     return this.observers.some(
       (observer) => resolveQueryValue(observer.options.enabled, this) !== false,
     )
   }
 
+  /**
+   * Returns `true` if the query is disabled, meaning it will not fetch
+   * automatically.
+   * - If the query has observers, it is disabled when none of them are active
+   *   (see `isActive`).
+   * - If the query has no observers, it is disabled when its `queryFn` is
+   *   `skipToken` or it has never been fetched.
+   */
   isDisabled(): boolean {
     if (this.getObserversCount() > 0) {
       return !this.isActive()
@@ -284,10 +405,18 @@ export class Query<
     return this.options.queryFn === skipToken || !this.isFetched()
   }
 
+  /**
+   * Returns `true` if the query has been fetched, i.e. it has resolved with
+   * either data or an error at least once.
+   */
   isFetched() {
     return this.state.dataUpdateCount + this.state.errorUpdateCount > 0
   }
 
+  /**
+   * Returns `true` if the query has at least one observer configured with
+   * `staleTime: 'static'`, meaning it is treated as never stale.
+   */
   isStatic(): boolean {
     if (this.getObserversCount() > 0) {
       return this.observers.some(
@@ -299,6 +428,22 @@ export class Query<
     return false
   }
 
+  /**
+   * Returns `true` if the query is stale.
+   * - If the query has observers, defers to whether any observer's current
+   *   result reports `isStale` (which accounts for each observer's own
+   *   `staleTime` and `enabled` state).
+   * - If the query has no observers, it is considered stale when it has no
+   *   data or has been invalidated.
+   *
+   * @see {@link Query#isStaleByTime}
+   * @example
+   * ```ts
+   * if (query.isStale()) {
+   *   // refetch or otherwise treat the cached data as outdated
+   * }
+   * ```
+   */
   isStale(): boolean {
     // check observers first, their `isStale` has the source of truth
     // calculated with `isStaleByTime` and it takes `enabled` into account
@@ -311,6 +456,20 @@ export class Query<
     return this.state.data === undefined || this.state.isInvalidated
   }
 
+  /**
+   * Returns `true` if the query's data is stale relative to the given
+   * `staleTime` (defaults to `0`).
+   * - A query with no data is always stale.
+   * - `staleTime: 'static'` is never stale.
+   * - An invalidated query is always stale.
+   * - Otherwise, staleness is based on elapsed time since `dataUpdatedAt`.
+   *
+   * @see {@link Query#isStale}
+   * @example
+   * ```ts
+   * const isStale = query.isStaleByTime(1000 * 60)
+   * ```
+   */
   isStaleByTime(staleTime: StaleTime = 0): boolean {
     // no data is always stale
     if (this.state.data === undefined) {
@@ -328,6 +487,7 @@ export class Query<
     return !timeUntilStale(this.state.dataUpdatedAt, staleTime)
   }
 
+  /** @internal */
   onFocus(): void {
     const observer = this.observers.find((x) => x.shouldFetchOnWindowFocus())
 
@@ -337,6 +497,7 @@ export class Query<
     this.#retryer?.continue()
   }
 
+  /** @internal */
   onOnline(): void {
     const observer = this.observers.find((x) => x.shouldFetchOnReconnect())
 
@@ -346,6 +507,7 @@ export class Query<
     this.#retryer?.continue()
   }
 
+  /** @internal */
   addObserver(observer: QueryObserver<any, any, any, any, any>): void {
     if (!this.observers.includes(observer)) {
       this.observers.push(observer)
@@ -357,6 +519,7 @@ export class Query<
     }
   }
 
+  /** @internal */
   removeObserver(observer: QueryObserver<any, any, any, any, any>): void {
     const index = this.observers.indexOf(observer)
     if (index !== -1) {
@@ -384,16 +547,46 @@ export class Query<
     }
   }
 
+  /**
+   * Returns the number of observers currently subscribed to this query.
+   *
+   * @example
+   * ```ts
+   * if (query.getObserversCount() === 0) {
+   *   // no component is currently watching this query
+   * }
+   * ```
+   */
   getObserversCount(): number {
     return this.observers.length
   }
 
+  /**
+   * Marks the query as invalidated, unless it is already invalidated. This
+   * updates `state.isInvalidated` and notifies observers, but does not by
+   * itself trigger a refetch.
+   *
+   * @example
+   * ```ts
+   * query.invalidate()
+   * ```
+   */
   invalidate(): void {
     if (!this.state.isInvalidated) {
       this.#dispatch({ type: 'invalidate' })
     }
   }
 
+  /**
+   * Fetches the query, i.e. runs its `queryFn` (through any configured
+   * retryer/behavior) and updates the query's state with the result.
+   * - If a fetch is already in flight, returns its promise instead of
+   *   starting a new one, unless `fetchOptions.cancelRefetch` is set and the
+   *   query already has data, in which case the current fetch is silently
+   *   cancelled first.
+   * - If `options` is passed, it replaces the query's current options
+   *   before fetching.
+   */
   async fetch(
     options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,
     fetchOptions?: FetchOptions<TQueryFnData>,

package/src/queryCache.ts

@@ -16,12 +16,21 @@ import type { QueryObserver } from './queryObserver'
 
 // TYPES
 
+/**
+ * Global callbacks that fire for every query handled by a `QueryCache`, regardless of which
+ * component or observer triggered it. Unlike `QueryClient`'s `defaultOptions`, which a query can
+ * override, these callbacks are always called. Unlike `MutationCacheConfig`'s callbacks, these
+ * are fire-and-forget: their return value is not awaited before the query settles.
+ */
 export interface QueryCacheConfig {
+  /** Called when any query in the cache encounters an error. */
   onError?: (
     error: DefaultError,
     query: Query<unknown, unknown, unknown>,
   ) => void
+  /** Called when any query in the cache is successful. */
   onSuccess?: (data: unknown, query: Query<unknown, unknown, unknown>) => void
+  /** Called when any query in the cache is settled, either successfully or with an error. */
   onSettled?: (
     data: unknown | undefined,
     error: DefaultError | null,
@@ -68,6 +77,11 @@ interface NotifyEventQueryObserverOptionsUpdated extends NotifyEvent {
   observer: QueryObserver<any, any, any, any, any>
 }
 
+/**
+ * The event passed to a `QueryCache` subscriber. Fired whenever a query is added or removed from
+ * the cache, its state is updated (e.g. via `query.setState` or `queryClient.removeQueries`), or
+ * one of its observers is added, removed, or has its results or options updated.
+ */
 export type QueryCacheNotifyEvent =
   | NotifyEventQueryAdded
   | NotifyEventQueryRemoved
@@ -89,6 +103,23 @@ export interface QueryStore {
 
 // CLASS
 
+/**
+ * The `QueryCache` is the storage mechanism for TanStack Query. It stores all the data, meta
+ * information, and state of the queries it contains.
+ *
+ * Normally, you will not interact with the `QueryCache` directly and instead use a `QueryClient`
+ * for a specific cache. You can subscribe to it (inherited from `Subscribable`) to be informed of
+ * safe/known updates to the cache, such as queries being added, removed, or updated — updates made
+ * outside of the cache's own tracked mechanisms (e.g. mutating a query's state object directly) do
+ * not notify subscribers.
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = queryCache.subscribe((event) => {
+ *   console.log(event.type, event.query)
+ * })
+ * ```
+ */
 export class QueryCache extends Subscribable<QueryCacheListener> {
   #queries: QueryStore
 
@@ -97,6 +128,22 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     this.#queries = new Map<string, Query>()
   }
 
+  /**
+   * Returns the existing `Query` instance for the given options' `queryKey`/`queryHash`, or
+   * builds and adds a new one to the cache if none exists yet. Used by framework adapters and
+   * plugins (e.g. broadcast/persistence) that need to get-or-create a `Query` directly, bypassing
+   * the reactive `QueryObserver` machinery.
+   *
+   * @example
+   * ```ts
+   * const queryCache = queryClient.getQueryCache()
+   *
+   * const query = queryCache.build(queryClient, {
+   *   queryKey: ['posts'],
+   *   queryFn: fetchPosts,
+   * })
+   * ```
+   */
   build<
     TQueryFnData = unknown,
     TError = DefaultError,
@@ -130,6 +177,7 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     return query
   }
 
+  /** @internal */
   add(query: Query<any, any, any, any>): void {
     if (!this.#queries.has(query.queryHash)) {
       this.#queries.set(query.queryHash, query)
@@ -141,6 +189,22 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     }
   }
 
+  /**
+   * Destroys the given `Query` and removes it from the cache, notifying subscribers with a
+   * `'removed'` event. A no-op if the query is no longer the one currently stored under its hash
+   * (e.g. it was already replaced). Used by plugins (e.g. the broadcast client) that mirror
+   * removals across `QueryCache` instances.
+   *
+   * @example
+   * ```ts
+   * const queryCache = queryClient.getQueryCache()
+   * const query = queryCache.find({ queryKey: ['posts'] })
+   *
+   * if (query) {
+   *   queryCache.remove(query)
+   * }
+   * ```
+   */
   remove(query: Query<any, any, any, any>): void {
     const queryInMap = this.#queries.get(query.queryHash)
 
@@ -155,6 +219,16 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     }
   }
 
+  /**
+   * Removes all queries from the cache.
+   *
+   * @example
+   * ```ts
+   * const queryCache = queryClient.getQueryCache()
+   *
+   * queryCache.clear()
+   * ```
+   */
   clear(): void {
     notifyManager.batch(() => {
       this.getAll().forEach((query) => {
@@ -163,6 +237,20 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     })
   }
 
+  /**
+   * Returns the `Query` instance stored under the given `queryHash`, or `undefined` if none
+   * exists. Unlike {@link QueryCache#find}, this looks up by the already-computed hash rather
+   * than by `QueryFilters`. Used by plugins (e.g. broadcast/hydration) that already have a hash
+   * to look up directly.
+   *
+   * @example
+   * ```ts
+   * const queryCache = queryClient.getQueryCache()
+   * const queryHash = hashKey(['posts'])
+   *
+   * const query = queryCache.get(queryHash)
+   * ```
+   */
   get<
     TQueryFnData = unknown,
     TError = DefaultError,
@@ -176,10 +264,38 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
       | undefined
   }
 
+  /**
+   * Returns all queries within the cache.
+   *
+   * @example
+   * ```ts
+   * const queryCache = queryClient.getQueryCache()
+   *
+   * const queries = queryCache.getAll()
+   * ```
+   */
   getAll(): Array<Query> {
     return [...this.#queries.values()]
   }
 
+  /**
+   * A slightly more advanced method that can be used to get an existing query instance from the
+   * cache. This instance not only contains all the state for the query, but all of the instances,
+   * and underlying guts of the query as well. If the query does not exist, `undefined` is
+   * returned.
+   *
+   * This is not typically needed for most applications, but can come in handy when needing more
+   * information about a query in rare scenarios (e.g. looking at `query.state.dataUpdatedAt` to
+   * decide whether a query is fresh enough to be used as an initial value).
+   *
+   * @see {@link QueryCache#findAll}
+   * @example
+   * ```ts
+   * const queryCache = queryClient.getQueryCache()
+   *
+   * const query = queryCache.find({ queryKey: ['posts'] })
+   * ```
+   */
   find<TQueryFnData = unknown, TError = DefaultError, TData = TQueryFnData>(
     filters: WithRequired<QueryFilters, 'queryKey'>,
   ): Query<TQueryFnData, TError, TData> | undefined {
@@ -190,6 +306,21 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     ) as Query<TQueryFnData, TError, TData> | undefined
   }
 
+  /**
+   * An even more advanced method that can be used to get existing query instances from the cache
+   * that partially match a query key. If no queries match, an empty array is returned.
+   *
+   * This is not typically needed for most applications, but can come in handy when needing more
+   * information about queries in rare scenarios.
+   *
+   * @see {@link QueryCache#find}
+   * @example
+   * ```ts
+   * const queryCache = queryClient.getQueryCache()
+   *
+   * const queries = queryCache.findAll({ queryKey: ['posts'] })
+   * ```
+   */
   findAll(filters: QueryFilters<any> = {}): Array<Query> {
     const queries = this.getAll()
     return Object.keys(filters).length > 0
@@ -197,6 +328,7 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
       : queries
   }
 
+  /** @internal */
   notify(event: QueryCacheNotifyEvent): void {
     notifyManager.batch(() => {
       this.listeners.forEach((listener) => {
@@ -205,6 +337,7 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     })
   }
 
+  /** @internal */
   onFocus(): void {
     notifyManager.batch(() => {
       this.getAll().forEach((query) => {
@@ -213,6 +346,7 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     })
   }
 
+  /** @internal */
   onOnline(): void {
     notifyManager.batch(() => {
       this.getAll().forEach((query) => {