@tanstack/query-core 5.102.7 → 5.103.0

package/src/mutation.ts

@@ -23,20 +23,54 @@ interface MutationConfig<TData, TError, TVariables, TOnMutateResult> {
   state?: MutationState<TData, TError, TVariables, TOnMutateResult>
 }
 
+/**
+ * The raw state stored on a `Mutation` instance. This is the underlying state
+ * that observer results (e.g. `MutationObserverResult`) are derived from.
+ */
 export interface MutationState<
   TData = unknown,
   TError = DefaultError,
   TVariables = unknown,
   TOnMutateResult = unknown,
 > {
+  /**
+   * The value returned by `onMutate`, if defined. Passed to `onSuccess`,
+   * `onError` and `onSettled` as the mutation's context.
+   */
   context: TOnMutateResult | undefined
+  /**
+   * The last successfully resolved data for the mutation.
+   */
   data: TData | undefined
+  /**
+   * The error object for the mutation, if the last attempt resulted in an error.
+   * - Defaults to `null`.
+   */
   error: TError | null
+  /**
+   * The number of times the mutation function has failed for the current attempt.
+   */
   failureCount: number
+  /**
+   * The reason the current attempt failed, as reported by the retryer.
+   */
   failureReason: TError | null
+  /**
+   * Whether the mutation is currently paused (see network mode), or is
+   * waiting for another mutation with the same `scope` to finish.
+   */
   isPaused: boolean
+  /**
+   * The status of the mutation.
+   */
   status: MutationStatus
+  /**
+   * The variables the mutation was last called with.
+   */
   variables: TVariables | undefined
+  /**
+   * The timestamp for when the mutation was submitted.
+   */
   submittedAt: number
 }
 
@@ -81,6 +115,23 @@ export type Action<TData, TError, TVariables, TOnMutateResult> =
 
 // CLASS
 
+/**
+ * Represents a single mutation attempt. A `Mutation` holds the mutation's
+ * options, state (data/error/status), and the `MutationObserver`s currently
+ * subscribed to it.
+ *
+ * Instances are created and managed internally by `MutationCache`; application
+ * code typically interacts with mutations indirectly through `QueryClient` or
+ * a framework hook like `useMutation`. Direct access to a `Mutation` instance
+ * is possible via `mutationCache.find()`/`getAll()` for inspecting cache state.
+ *
+ * @example
+ * ```ts
+ * const mutationCache = queryClient.getMutationCache()
+ *
+ * const mutation = mutationCache.find({ mutationKey: ['addPost'] })
+ * ```
+ */
 export class Mutation<
   TData = unknown,
   TError = DefaultError,
@@ -113,6 +164,7 @@ export class Mutation<
     this.scheduleGc()
   }
 
+  /** @internal */
   setOptions(
     options: MutationOptions<TData, TError, TVariables, TOnMutateResult>,
   ): void {
@@ -121,10 +173,14 @@ export class Mutation<
     this.updateGcTime(this.options.gcTime)
   }
 
+  /**
+   * The `meta` object passed in the mutation's options, if any.
+   */
   get meta(): MutationMeta | undefined {
     return this.options.meta
   }
 
+  /** @internal */
   addObserver(observer: MutationObserver<any, any, any, any>): void {
     if (!this.#observers.includes(observer)) {
       this.#observers.push(observer)
@@ -140,6 +196,7 @@ export class Mutation<
     }
   }
 
+  /** @internal */
   removeObserver(observer: MutationObserver<any, any, any, any>): void {
     this.#observers = this.#observers.filter((x) => x !== observer)
 
@@ -162,6 +219,27 @@ export class Mutation<
     }
   }
 
+  /**
+   * Resumes a mutation that is currently paused or was restored from a
+   * dehydrated, still-`pending` state.
+   *
+   * - If this mutation has an active retryer (it paused mid-attempt, e.g. due
+   *   to the network mode or scope-based queuing), its retryer is resumed.
+   * - Otherwise, if the mutation's status is still `pending` (e.g. it was
+   *   dehydrated while an attempt was in flight and never got a retryer in
+   *   this instance), `execute` is called again with the last known variables.
+   * - Otherwise the mutation has already settled and this resolves immediately
+   *   without running anything again.
+   *
+   * @example
+   * ```ts
+   * // typically driven by reconnect handling, e.g. queryClient.resumePausedMutations()
+   * const mutation = mutationCache.find({ mutationKey: ['addPost'] })
+   * await mutation?.continue()
+   * ```
+   *
+   * @see {@link Mutation#execute}
+   */
   continue(): Promise<unknown> {
     return (
       this.#retryer?.continue() ??
@@ -173,6 +251,36 @@ export class Mutation<
     )
   }
 
+  /**
+   * Runs the mutation function for the given variables through a retryer, and
+   * drives the mutation's state and lifecycle callbacks through to settlement.
+   *
+   * If this mutation's state is already `pending` when `execute` is called
+   * (i.e. it was restored, still in-flight, from a dehydrated state), the
+   * `onMutate` step is skipped and a `continue` action is dispatched to
+   * unpause it; otherwise a `pending` action is dispatched first, then the
+   * mutation cache's `onMutate` and the mutation's own `onMutate` option are
+   * awaited in that order, and the resulting context is stored.
+   *
+   * The mutation function is then run (subject to `retry`/`retryDelay`/
+   * `networkMode`, and to the mutation cache's scope-based serialization).
+   * On success, the cache's `onSuccess`/`onSettled` callbacks run before the
+   * mutation's own `onSuccess`/`onSettled` options, a `success` action is
+   * dispatched, and the resolved data is returned. On failure, the same
+   * cache-then-option ordering is used for `onError`/`onSettled`, but each of
+   * those four callbacks is individually caught so that a throwing callback
+   * cannot mask the original error; an `error` action is then dispatched and
+   * the original error is re-thrown.
+   *
+   * @example
+   * ```ts
+   * // Called internally by `MutationObserver.mutate` and `Mutation.continue` —
+   * // applications normally trigger mutations through those, not this method.
+   * const data = await mutation.execute(variables)
+   * ```
+   *
+   * @see {@link Mutation#continue}
+   */
   async execute(variables: TVariables): Promise<TData> {
     const onContinue = () => {
       this.#dispatch({ type: 'continue' })

package/src/mutationCache.ts

@@ -15,7 +15,16 @@ import type { MutationFilters } from './utils'
 
 // TYPES
 
+/**
+ * Global callbacks that fire for every mutation handled by a `MutationCache`, regardless of which
+ * component or observer triggered it. They differ from the `defaultOptions` provided to a
+ * `QueryClient` in two ways: `defaultOptions` can be overridden by each mutation, while these
+ * callbacks are always called, and `onMutate` here does not allow returning a result.
+ *
+ * If a callback returns a promise, it will be awaited before the mutation continues.
+ */
 export interface MutationCacheConfig {
+  /** Called when any mutation in the cache encounters an error. */
   onError?: (
     error: DefaultError,
     variables: unknown,
@@ -23,6 +32,7 @@ export interface MutationCacheConfig {
     mutation: Mutation<unknown, unknown, unknown>,
     context: MutationFunctionContext,
   ) => Promise<unknown> | unknown
+  /** Called when any mutation in the cache is successful. */
   onSuccess?: (
     data: unknown,
     variables: unknown,
@@ -30,11 +40,13 @@ export interface MutationCacheConfig {
     mutation: Mutation<unknown, unknown, unknown>,
     context: MutationFunctionContext,
   ) => Promise<unknown> | unknown
+  /** Called before any mutation in the cache executes. */
   onMutate?: (
     variables: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
     context: MutationFunctionContext,
   ) => Promise<unknown> | unknown
+  /** Called when any mutation in the cache is settled, either successfully or with an error. */
   onSettled?: (
     data: unknown | undefined,
     error: DefaultError | null,
@@ -78,6 +90,11 @@ interface NotifyEventMutationUpdated extends NotifyEvent {
   action: Action<any, any, any, any>
 }
 
+/**
+ * The event passed to a `MutationCache` subscriber. Fired whenever a mutation is added or removed
+ * from the cache, its state is updated, or one of its observers is added, removed, or has its
+ * options updated.
+ */
 export type MutationCacheNotifyEvent =
   | NotifyEventMutationAdded
   | NotifyEventMutationRemoved
@@ -90,6 +107,20 @@ type MutationCacheListener = (event: MutationCacheNotifyEvent) => void
 
 // CLASS
 
+/**
+ * The `MutationCache` is the storage for mutations.
+ *
+ * Normally, you will not interact with the `MutationCache` directly and instead use a
+ * `QueryClient`. You can subscribe to it (inherited from `Subscribable`) to be informed of
+ * safe/known updates to the cache, such as mutations being added, removed, or updated.
+ *
+ * @example
+ * ```ts
+ * const unsubscribe = mutationCache.subscribe((event) => {
+ *   console.log(event.type, event.mutation)
+ * })
+ * ```
+ */
 export class MutationCache extends Subscribable<MutationCacheListener> {
   #mutations: Set<Mutation<any, any, any, any>>
   #scopes: Map<string, Array<Mutation<any, any, any, any>>>
@@ -102,6 +133,7 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     this.#mutationId = 0
   }
 
+  /** @internal */
   build<TData, TError, TVariables, TOnMutateResult>(
     client: QueryClient,
     options: MutationOptions<TData, TError, TVariables, TOnMutateResult>,
@@ -120,6 +152,7 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     return mutation
   }
 
+  /** @internal */
   add(mutation: Mutation<any, any, any, any>): void {
     this.#mutations.add(mutation)
     const scope = scopeFor(mutation)
@@ -134,6 +167,7 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     this.notify({ type: 'added', mutation })
   }
 
+  /** @internal */
   remove(mutation: Mutation<any, any, any, any>): void {
     if (this.#mutations.delete(mutation)) {
       const scope = scopeFor(mutation)
@@ -157,6 +191,7 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     this.notify({ type: 'removed', mutation })
   }
 
+  /** @internal */
   canRun(mutation: Mutation<any, any, any, any>): boolean {
     const scope = scopeFor(mutation)
     if (typeof scope === 'string') {
@@ -174,6 +209,7 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     }
   }
 
+  /** @internal */
   runNext(mutation: Mutation<any, any, any, any>): Promise<unknown> {
     const scope = scopeFor(mutation)
     if (typeof scope === 'string') {
@@ -187,6 +223,16 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     }
   }
 
+  /**
+   * Removes all mutations from the cache.
+   *
+   * @example
+   * ```ts
+   * const mutationCache = queryClient.getMutationCache()
+   *
+   * mutationCache.clear()
+   * ```
+   */
   clear(): void {
     notifyManager.batch(() => {
       this.#mutations.forEach((mutation) => {
@@ -197,10 +243,38 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     })
   }
 
+  /**
+   * Returns all mutations within the cache.
+   *
+   * This is not typically needed for most applications, but can come in handy when needing more
+   * information about a mutation in rare scenarios.
+   *
+   * @example
+   * ```ts
+   * const mutationCache = queryClient.getMutationCache()
+   *
+   * const mutations = mutationCache.getAll()
+   * ```
+   */
   getAll(): Array<Mutation> {
     return Array.from(this.#mutations)
   }
 
+  /**
+   * A slightly more advanced method that can be used to get an existing mutation instance from
+   * the cache. If the mutation 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 mutation in rare scenarios.
+   *
+   * @see {@link MutationCache#findAll}
+   * @example
+   * ```ts
+   * const mutationCache = queryClient.getMutationCache()
+   *
+   * const mutation = mutationCache.find({ mutationKey: ['addPost'] })
+   * ```
+   */
   find<
     TData = unknown,
     TError = DefaultError,
@@ -216,10 +290,26 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     ) as Mutation<TData, TError, TVariables, TOnMutateResult> | undefined
   }
 
+  /**
+   * An even more advanced method that can be used to get existing mutation instances from the
+   * cache that match the given filters. If no mutations match, an empty array is returned.
+   *
+   * This is not typically needed for most applications, but can come in handy when needing more
+   * information about mutations in rare scenarios.
+   *
+   * @see {@link MutationCache#find}
+   * @example
+   * ```ts
+   * const mutationCache = queryClient.getMutationCache()
+   *
+   * const mutations = mutationCache.findAll({ mutationKey: ['addPost'] })
+   * ```
+   */
   findAll(filters: MutationFilters = {}): Array<Mutation> {
     return this.getAll().filter((mutation) => matchMutation(filters, mutation))
   }
 
+  /** @internal */
   notify(event: MutationCacheNotifyEvent) {
     notifyManager.batch(() => {
       this.listeners.forEach((listener) => {
@@ -228,6 +318,7 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     })
   }
 
+  /** @internal */
   resumePausedMutations(): Promise<unknown> {
     const pausedMutations = this.getAll().filter((x) => x.state.isPaused)
 

package/src/mutationObserver.ts

@@ -20,6 +20,21 @@ type MutationObserverListener<TData, TError, TVariables, TOnMutateResult> = (
 
 // CLASS
 
+/**
+ * Observes a single mutation and derives a `MutationObserverResult` from it.
+ * A framework hook like `useMutation` creates one `MutationObserver` per hook
+ * call, keeps it stable across re-renders, calls `setOptions` when the options
+ * passed to the hook change, subscribes to it to re-render on updates, and
+ * reads `getCurrentResult()` for the value to return. Calling `mutate()`
+ * builds a new underlying `Mutation` in the `MutationCache` and executes it.
+ *
+ * @example
+ * ```ts
+ * const observer = new MutationObserver(queryClient, {
+ *   mutationFn: (variables: { title: string }) => addPost(variables),
+ * })
+ * ```
+ */
 export class MutationObserver<
   TData = unknown,
   TError = DefaultError,
@@ -62,6 +77,22 @@ export class MutationObserver<
     this.reset = this.reset.bind(this)
   }
 
+  /**
+   * Updates the observer's options.
+   *
+   * If the new `mutationKey` differs from the previous one (and both were
+   * defined), the observer is reset, detaching it from the mutation it was
+   * observing. Otherwise, if the currently observed mutation is still
+   * `pending`, its options are updated in place as well.
+   *
+   * @example
+   * ```ts
+   * observer.setOptions({
+   *   mutationFn: (variables: { title: string }) => addPost(variables),
+   *   onSuccess: (data) => console.log(data),
+   * })
+   * ```
+   */
   setOptions(
     options: MutationObserverOptions<
       TData,
@@ -107,6 +138,7 @@ export class MutationObserver<
     }
   }
 
+  /** @internal */
   onMutationUpdate(
     action: Action<TData, TError, TVariables, TOnMutateResult>,
   ): void {
@@ -115,6 +147,11 @@ export class MutationObserver<
     this.#notify(action)
   }
 
+  /**
+   * Returns the observer's current result, derived from the observed
+   * mutation's state (or the default, `idle` state if no mutation has been
+   * built yet, e.g. before the first `mutate()` call or after `reset()`).
+   */
   getCurrentResult(): MutationObserverResult<
     TData,
     TError,
@@ -124,6 +161,22 @@ export class MutationObserver<
     return this.#currentResult
   }
 
+  /**
+   * Detaches the observer from the mutation it is currently observing (if
+   * any) and resets the observed result back to its default, `idle` state.
+   *
+   * This does not cancel an in-flight mutation; the mutation itself keeps
+   * running to completion and its own callbacks still fire, but this
+   * observer stops reflecting its state and a subsequent `mutate()` call
+   * will build a brand new mutation.
+   *
+   * @example
+   * ```ts
+   * observer.reset()
+   * ```
+   *
+   * @see {@link MutationObserver#mutate}
+   */
   reset(): void {
     // reset needs to remove the observer from the mutation because there is no way to "get it back"
     // another mutate call will yield a new mutation!
@@ -133,6 +186,24 @@ export class MutationObserver<
     this.#notify()
   }
 
+  /**
+   * Builds a new `Mutation` in the `MutationCache` using the observer's
+   * current options, detaches this observer from any previously observed
+   * mutation, attaches it to the new one, and executes it with the given
+   * variables.
+   *
+   * The optional per-call `options` (`onSuccess`/`onError`/`onSettled`) are
+   * invoked once the mutation settles, in addition to any callbacks defined
+   * on the observer's own options.
+   *
+   * @example
+   * ```ts
+   * await observer.mutate(
+   *   { title: 'New post' },
+   *   { onSuccess: (data) => console.log(data) },
+   * )
+   * ```
+   */
   mutate(
     variables: TVariables,
     options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>,

package/src/notifyManager.ts

@@ -12,6 +12,10 @@ type BatchCallsCallback<T extends Array<unknown>> = (...args: T) => void
 
 type ScheduleFunction = (callback: () => void) => void
 
+/**
+ * Default scheduling function used by the notify manager.
+ * Schedules the callback with the system's `setTimeout(callback, 0)`.
+ */
 export const defaultScheduler: ScheduleFunction = systemSetTimeoutZero
 
 export function createNotifyManager() {
@@ -49,6 +53,12 @@ export function createNotifyManager() {
   }
 
   return {
+    /**
+     * Batches all updates scheduled inside the passed callback.
+     * This is mainly used internally to optimize query client updating.
+     * Batches can be nested; the queue is only flushed once the outermost `batch` call finishes.
+     * The return value of `callback` is passed through.
+     */
     batch: <T>(callback: () => T): T => {
       let result
       transactions++
@@ -74,6 +84,10 @@ export function createNotifyManager() {
         })
       }
     },
+    /**
+     * Schedules a function to be run on the next batch.
+     * By default, the batch is run with a `setTimeout`, but this can be configured via `setScheduler`.
+     */
     schedule,
     /**
      * Use this method to set a custom notify function.
@@ -84,11 +98,38 @@ export function createNotifyManager() {
     },
     /**
      * Use this method to set a custom function to batch notifications together into a single tick.
-     * By default React Query will use the batch function provided by ReactDOM or React Native.
+     * Framework adapters use this to plug in their own batching primitive, so that a single query
+     * update only triggers one re-render instead of one per subscriber.
+     *
+     * @example
+     * ```ts
+     * import { notifyManager } from '@tanstack/query-core'
+     * import { batch } from 'solid-js'
+     *
+     * notifyManager.setBatchNotifyFunction(batch)
+     * ```
      */
     setBatchNotifyFunction: (fn: BatchNotifyFunction) => {
       batchNotifyFn = fn
     },
+    /**
+     * Configures a custom callback that schedules when the next batch runs.
+     * The default behavior is `setTimeout(callback, 0)`.
+     *
+     * @example
+     * ```ts
+     * import { notifyManager } from '@tanstack/query-core'
+     *
+     * // Schedule batches in the next microtask
+     * notifyManager.setScheduler(queueMicrotask)
+     *
+     * // Schedule batches before the next frame is rendered
+     * notifyManager.setScheduler(requestAnimationFrame)
+     *
+     * // Schedule batches some time in the future
+     * notifyManager.setScheduler((cb) => setTimeout(cb, 10))
+     * ```
+     */
     setScheduler: (fn: ScheduleFunction) => {
       scheduleFn = fn
     },
@@ -96,4 +137,8 @@ export function createNotifyManager() {
 }
 
 // SINGLETON
+
+/**
+ * Handles scheduling and batching callbacks in TanStack Query.
+ */
 export const notifyManager = createNotifyManager()

package/src/onlineManager.ts

@@ -3,6 +3,15 @@ import { Subscribable } from './subscribable'
 type Listener = (online: boolean) => void
 type SetupFn = (setOnline: Listener) => (() => void) | undefined
 
+/**
+ * The `OnlineManager` manages the online state within TanStack Query. It can
+ * be used to change the default event listeners or to manually change the
+ * online state.
+ *
+ * By default, the `onlineManager` assumes an active network connection, and
+ * listens to the `online` and `offline` events on the `window` object to
+ * detect changes.
+ */
 export class OnlineManager extends Subscribable<Listener> {
   #online = true
   #cleanup?: () => void
@@ -45,12 +54,44 @@ export class OnlineManager extends Subscribable<Listener> {
     }
   }
 
+  /**
+   * `setEventListener` can be used to set a custom event listener that will
+   * be used to determine the online state. The provided `setup` function
+   * receives a `setOnline` callback that should be called with a `boolean`
+   * whenever the online state changes.
+   *
+   * @example
+   * ```ts
+   * import NetInfo from '@react-native-community/netinfo'
+   * import { onlineManager } from '@tanstack/query-core'
+   *
+   * onlineManager.setEventListener((setOnline) => {
+   *   return NetInfo.addEventListener((state) => {
+   *     setOnline(!!state.isConnected)
+   *   })
+   * })
+   * ```
+   */
   setEventListener(setup: SetupFn): void {
     this.#setup = setup
     this.#cleanup?.()
     this.#cleanup = setup(this.setOnline.bind(this))
   }
 
+  /**
+   * `setOnline` can be used to manually set the online state.
+   *
+   * @example
+   * ```ts
+   * import { onlineManager } from '@tanstack/query-core'
+   *
+   * // Set to online
+   * onlineManager.setOnline(true)
+   *
+   * // Set to offline
+   * onlineManager.setOnline(false)
+   * ```
+   */
   setOnline(online: boolean): void {
     const changed = this.#online !== online
 
@@ -62,9 +103,15 @@ export class OnlineManager extends Subscribable<Listener> {
     }
   }
 
+  /**
+   * `isOnline` can be used to get the current online state.
+   */
   isOnline(): boolean {
     return this.#online
   }
 }
 
+/**
+ * Singleton instance of {@link OnlineManager}, used to manage and observe the online state within TanStack Query.
+ */
 export const onlineManager = new OnlineManager()