@tanstack/query-core 5.102.7 → 5.103.0

package/src/queryObserver.ts

@@ -34,6 +34,26 @@ interface ObserverFetchOptions extends FetchOptions {
   throwOnError?: boolean
 }
 
+/**
+ * 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
+ * ```ts
+ * const observer = new QueryObserver(queryClient, {
+ *   queryKey: ['posts'],
+ *   queryFn: fetchPosts,
+ * })
+ *
+ * const unsubscribe = observer.subscribe((result) => {
+ *   console.log(result.data)
+ * })
+ * ```
+ */
 export class QueryObserver<
   TQueryFnData = unknown,
   TError = DefaultError,
@@ -107,6 +127,11 @@ export class QueryObserver<
     }
   }
 
+  /**
+   * Returns whether the observed query is currently stale and configured
+   * (via the `refetchOnReconnect` option) to refetch when the network
+   * reconnects.
+   */
   shouldFetchOnReconnect(): boolean {
     return shouldFetchOn(
       this.#currentQuery,
@@ -115,6 +140,11 @@ export class QueryObserver<
     )
   }
 
+  /**
+   * Returns whether the observed query is currently stale and configured
+   * (via the `refetchOnWindowFocus` option) to refetch when the window
+   * regains focus.
+   */
   shouldFetchOnWindowFocus(): boolean {
     return shouldFetchOn(
       this.#currentQuery,
@@ -123,6 +153,11 @@ export class QueryObserver<
     )
   }
 
+  /**
+   * 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.
+   */
   destroy(): void {
     this.listeners = new Set()
     this.#clearStaleTimeout()
@@ -130,6 +165,20 @@ export class QueryObserver<
     this.#currentQuery.removeObserver(this)
   }
 
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * 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) })
+   * ```
+   */
   setOptions(
     options: QueryObserverOptions<
       TQueryFnData,
@@ -214,6 +263,12 @@ export class QueryObserver<
     }
   }
 
+  /**
+   * 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.
+   */
   getOptimisticResult(
     options: DefaultedQueryObserverOptions<
       TQueryFnData,
@@ -251,10 +306,28 @@ export class QueryObserver<
     return result
   }
 
+  /**
+   * 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).
+   *
+   * @example
+   * ```ts
+   * const result = observer.getCurrentResult()
+   * console.log(result.status, result.data)
+   * ```
+   */
   getCurrentResult(): QueryObserverResult<TData, TError> {
     return this.#currentResult
   }
 
+  /**
+   * Wraps a `QueryObserverResult` in a `Proxy` that records which properties are read, via
+   * {@link 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.
+   */
   trackResult(
     result: QueryObserverResult<TData, TError>,
     onPropTracked?: (key: keyof QueryObserverResult) => void,
@@ -268,14 +341,33 @@ export class QueryObserver<
     })
   }
 
+  /**
+   * 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
+   * {@link 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.
+   */
   trackProp(key: keyof QueryObserverResult) {
     this.#trackedProps.add(key)
   }
 
+  /**
+   * Returns the `Query` instance this observer is currently observing.
+   */
   getCurrentQuery(): Query<TQueryFnData, TError, TQueryData, TQueryKey> {
     return this.#currentQuery
   }
 
+  /**
+   * Refetches the observed query and returns a promise that resolves with
+   * the resulting `QueryObserverResult`.
+   *
+   * @example
+   * ```ts
+   * const result = await observer.refetch({ cancelRefetch: false })
+   * console.log(result.data)
+   * ```
+   */
   refetch({ ...options }: RefetchOptions = {}): Promise<
     QueryObserverResult<TData, TError>
   > {
@@ -284,6 +376,22 @@ export class QueryObserver<
     })
   }
 
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * const result = await observer.fetchOptimistic({
+   *   queryKey: ['posts', 2],
+   *   queryFn: () => fetchPost(2),
+   * })
+   * console.log(result.data)
+   * ```
+   */
   fetchOptimistic(
     options: QueryObserverOptions<
       TQueryFnData,
@@ -402,9 +510,8 @@ export class QueryObserver<
 
   #computeRefetchInterval() {
     return (
-      (typeof this.options.refetchInterval === 'function'
-        ? this.options.refetchInterval(this.#currentQuery)
-        : this.options.refetchInterval) ?? false
+      resolveQueryValue(this.options.refetchInterval, this.#currentQuery) ??
+      false
     )
   }
 
@@ -620,6 +727,11 @@ export class QueryObserver<
     return nextResult
   }
 
+  /**
+   * 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.
+   */
   updateResult(): void {
     const prevResult = this.#currentResult as
       | QueryObserverResult<TData, TError>
@@ -712,6 +824,7 @@ export class QueryObserver<
     }
   }
 
+  /** @internal */
   onQueryUpdate(): void {
     this.updateResult()
 
@@ -757,7 +870,7 @@ function shouldFetchOn(
     resolveQueryValue(options.enabled, query) !== false &&
     resolveQueryValue(options.staleTime, query) !== 'static'
   ) {
-    const value = typeof field === 'function' ? field(query) : field
+    const value = resolveQueryValue(field, query)
 
     return value === 'always' || (value !== false && isStale(query, options))
   }

package/src/retryer.ts

@@ -56,6 +56,24 @@ export function canFetch(networkMode: NetworkMode | undefined): boolean {
     : true
 }
 
+/**
+ * The error thrown by a `Retryer` (and surfaced to `query.promise`/`mutation`) when a fetch is cancelled, e.g. via
+ * `query.cancel()`. `revert`, if `true`, tells the caller to restore the state the query was in before the fetch
+ * started instead of surfacing the error. `silent`, if `true`, tells the caller to suppress this error and instead
+ * resolve with the promise of the fetch that triggered the cancellation.
+ * @example
+ * ```ts
+ * query.cancel()
+ *
+ * try {
+ *   await query.promise
+ * } catch (error) {
+ *   if (error instanceof CancelledError) {
+ *     // the fetch was cancelled, e.g. via `query.cancel()`
+ *   }
+ * }
+ * ```
+ */
 export class CancelledError extends Error {
   revert?: boolean
   silent?: boolean

package/src/streamedQuery.ts

@@ -7,9 +7,16 @@ import type {
 } from './types'
 
 type BaseStreamedQueryParams<TQueryFnData, TQueryKey extends QueryKey> = {
+  /** The function that returns an `AsyncIterable` to stream data from. */
   streamFn: (
     context: QueryFunctionContext<TQueryKey>,
   ) => AsyncIterable<TQueryFnData> | Promise<AsyncIterable<TQueryFnData>>
+  /**
+   * Defines how refetches are handled.
+   * - `'reset'` (default): erases all data and puts the query back into `pending` state.
+   * - `'append'`: appends new data to the existing data.
+   * - `'replace'`: writes all data to the cache once the stream ends.
+   */
   refetchMode?: 'append' | 'reset' | 'replace'
 }
 
@@ -26,7 +33,15 @@ type ReducibleStreamedQueryParams<
   TData,
   TQueryKey extends QueryKey,
 > = BaseStreamedQueryParams<TQueryFnData, TQueryKey> & {
+  /**
+   * Reduces streamed chunks into the final data shape. Required whenever `TData` is not an
+   * array, since there is no default way to accumulate non-array chunks.
+   */
   reducer: (acc: TData, chunk: TQueryFnData) => TData
+  /**
+   * The value used while the first chunk is being fetched, and returned if the stream yields no
+   * values. Required together with a custom `reducer`.
+   */
   initialValue: TData
 }
 
@@ -39,7 +54,7 @@ type StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> =
  * Data will be an Array of all the chunks received.
  * The query will be in a 'pending' state until the first chunk of data is received, but will go to 'success' after that.
  * The query will stay in fetchStatus 'fetching' until the stream ends.
- * @param queryFn - The function that returns an AsyncIterable to stream data from.
+ * @param streamFn - The function that returns an AsyncIterable to stream data from.
  * @param refetchMode - Defines how re-fetches are handled.
  * Defaults to `'reset'`, erases all data and puts the query back into `pending` state.
  * Set to `'append'` to append new data to the existing data.
@@ -47,6 +62,15 @@ type StreamedQueryParams<TQueryFnData, TData, TQueryKey extends QueryKey> =
  * @param reducer - A function to reduce the streamed chunks into the final data.
  * Defaults to a function that appends chunks to the end of the array.
  * @param initialValue - Initial value to be used while the first chunk is being fetched, and returned if the stream yields no values.
+ * @example
+ * ```ts
+ * await queryClient.query({
+ *   queryKey: ['data'],
+ *   queryFn: streamedQuery({
+ *     streamFn: fetchDataInChunks,
+ *   }),
+ * })
+ * ```
  */
 export function streamedQuery<
   TQueryFnData = unknown,

package/src/timeoutManager.ts

@@ -18,6 +18,12 @@ export type ManagedTimerId = number | { [Symbol.toPrimitive]: () => number }
 
 /**
  * Backend for timer functions.
+ *
+ * Timers are performance-sensitive: short-lived timers (delays under a few seconds) tend to be
+ * latency-sensitive, while long-lived ones may benefit more from coalescing — batching timers
+ * with similar deadlines together — which the default provider (backed by the platform's global
+ * `setTimeout`/`setInterval`) does not do. A custom provider can implement coalescing, and can
+ * also support delays longer than the ~24-day maximum of the global `setTimeout`.
  */
 export type TimeoutProvider<TTimerId extends ManagedTimerId = ManagedTimerId> =
   {
@@ -72,6 +78,31 @@ export class TimeoutManager implements Omit<TimeoutProvider, 'name'> {
   #provider: TimeoutProvider<any> = defaultTimeoutProvider
   #providerCalled = false
 
+  /**
+   * `setTimeoutProvider` can be used to set a custom implementation of the
+   * `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` functions,
+   * called a `TimeoutProvider`.
+   *
+   * This may be useful if you notice event loop performance issues with
+   * thousands of queries. A custom TimeoutProvider could also support timer
+   * delays longer than the global `setTimeout` maximum delay value of about
+   * 24 days.
+   *
+   * It is important to call `setTimeoutProvider` before creating a
+   * QueryClient or queries, so that the same provider is used consistently
+   * for all timers in the application, since different TimeoutProviders
+   * cannot cancel each others' timers.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager, QueryClient } from '@tanstack/query-core'
+   * import { CustomTimeoutProvider } from './CustomTimeoutProvider'
+   *
+   * timeoutManager.setTimeoutProvider(new CustomTimeoutProvider())
+   *
+   * export const queryClient = new QueryClient()
+   * ```
+   */
   setTimeoutProvider<TTimerId extends ManagedTimerId>(
     provider: TimeoutProvider<TTimerId>,
   ): void {
@@ -101,6 +132,26 @@ export class TimeoutManager implements Omit<TimeoutProvider, 'name'> {
     }
   }
 
+  /**
+   * `setTimeout` schedules a callback to run after approximately `delay`
+   * milliseconds, like the global `setTimeout` function. The callback can be
+   * canceled with `clearTimeout`.
+   *
+   * It returns a timer ID, which may be a number or an object that can be
+   * coerced to a number via `Symbol.toPrimitive`.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager } from '@tanstack/query-core'
+   *
+   * const timeoutId = timeoutManager.setTimeout(
+   *   () => console.log('ran at:', new Date()),
+   *   1000,
+   * )
+   *
+   * const timeoutIdNumber: number = Number(timeoutId)
+   * ```
+   */
   setTimeout(callback: TimeoutCallback, delay: number): ManagedTimerId {
     if (process.env.NODE_ENV !== 'production') {
       this.#providerCalled = true
@@ -108,10 +159,44 @@ export class TimeoutManager implements Omit<TimeoutProvider, 'name'> {
     return this.#provider.setTimeout(callback, delay)
   }
 
+  /**
+   * `clearTimeout` cancels a timeout callback scheduled with `setTimeout`,
+   * like the global `clearTimeout` function. It should be called with a
+   * timer ID returned by `setTimeout`.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager } from '@tanstack/query-core'
+   *
+   * const timeoutId = timeoutManager.setTimeout(
+   *   () => console.log('ran at:', new Date()),
+   *   1000,
+   * )
+   *
+   * timeoutManager.clearTimeout(timeoutId)
+   * ```
+   */
   clearTimeout(timeoutId: ManagedTimerId | undefined): void {
     this.#provider.clearTimeout(timeoutId)
   }
 
+  /**
+   * `setInterval` schedules a callback to be called approximately every
+   * `delay` milliseconds, like the global `setInterval` function.
+   *
+   * Like `setTimeout`, it returns a timer ID, which may be a number or an
+   * object that can be coerced to a number via `Symbol.toPrimitive`.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager } from '@tanstack/query-core'
+   *
+   * const intervalId = timeoutManager.setInterval(
+   *   () => console.log('ran at:', new Date()),
+   *   1000,
+   * )
+   * ```
+   */
   setInterval(callback: TimeoutCallback, delay: number): ManagedTimerId {
     if (process.env.NODE_ENV !== 'production') {
       this.#providerCalled = true
@@ -119,11 +204,31 @@ export class TimeoutManager implements Omit<TimeoutProvider, 'name'> {
     return this.#provider.setInterval(callback, delay)
   }
 
+  /**
+   * `clearInterval` can be used to cancel an interval, like the global
+   * `clearInterval` function. It should be called with an interval ID
+   * returned by `setInterval`.
+   *
+   * @example
+   * ```ts
+   * import { timeoutManager } from '@tanstack/query-core'
+   *
+   * const intervalId = timeoutManager.setInterval(
+   *   () => console.log('ran at:', new Date()),
+   *   1000,
+   * )
+   *
+   * timeoutManager.clearInterval(intervalId)
+   * ```
+   */
   clearInterval(intervalId: ManagedTimerId | undefined): void {
     this.#provider.clearInterval(intervalId)
   }
 }
 
+/**
+ * Singleton instance of {@link TimeoutManager}, used throughout TanStack Query to schedule and cancel timers.
+ */
 export const timeoutManager = new TimeoutManager()
 
 /**