@tanstack/query-core 5.102.7 → 5.103.0

package/build/modern/queryClient.js

@@ -5,6 +5,24 @@ import { onlineManager } from "./onlineManager.js";
 import { MutationCache } from "./mutationCache.js";
 import { QueryCache } from "./queryCache.js";
 //#region src/queryClient.ts
+/**
+* `QueryClient` is used to interact with a cache of queries and mutations. It owns a
+* `QueryCache` and a `MutationCache` (creating default ones if none are passed in) and holds
+* the default options that are applied to queries and mutations created through it.
+*
+* @example
+* ```ts
+* const queryClient = new QueryClient({
+*   defaultOptions: {
+*     queries: {
+*       staleTime: Infinity,
+*     },
+*   },
+* })
+*
+* await queryClient.query({ queryKey: ['posts'], queryFn: fetchPosts })
+* ```
+*/
 var QueryClient = class {
 	#queryCache;
 	#mutationCache;
@@ -22,6 +40,12 @@ var QueryClient = class {
 		this.#mutationDefaults = /* @__PURE__ */ new Map();
 		this.#mountCount = 0;
 	}
+	/**
+	* Called by a framework adapter's `QueryClientProvider`-equivalent when it mounts, to start
+	* listening for focus/online events and resume paused mutations. Ref-counted via an internal
+	* mount count, so nested or multiple providers sharing the same `QueryClient` don't tear down
+	* the shared listeners until the last one unmounts.
+	*/
 	mount() {
 		this.#mountCount++;
 		if (this.#mountCount !== 1) return;
@@ -38,6 +62,11 @@ var QueryClient = class {
 			}
 		});
 	}
+	/**
+	* The inverse of {@link QueryClient#mount} — called by a framework adapter's
+	* `QueryClientProvider`-equivalent when it unmounts. Only tears down the focus/online
+	* listeners once the mount count returns to `0`.
+	*/
 	unmount() {
 		this.#mountCount--;
 		if (this.#mountCount !== 0) return;
@@ -46,12 +75,35 @@ var QueryClient = class {
 		this.#unsubscribeOnline?.();
 		this.#unsubscribeOnline = void 0;
 	}
+	/**
+	* Returns the number of queries in the cache that are currently fetching, optionally
+	* matching a set of filters. This includes background-fetching, loading new pages, and
+	* loading more infinite query results.
+	*
+	* @example
+	* ```ts
+	* if (queryClient.isFetching()) {
+	*   console.log('At least one query is fetching!')
+	* }
+	* ```
+	*/
 	isFetching(filters) {
 		return this.#queryCache.findAll({
 			...filters,
 			fetchStatus: "fetching"
 		}).length;
 	}
+	/**
+	* Returns the number of mutations in the cache that are currently pending, optionally
+	* matching a set of filters.
+	*
+	* @example
+	* ```ts
+	* if (queryClient.isMutating()) {
+	*   console.log('At least one mutation is pending!')
+	* }
+	* ```
+	*/
 	isMutating(filters) {
 		return this.#mutationCache.findAll({
 			...filters,
@@ -64,6 +116,8 @@ var QueryClient = class {
 	*
 	* Hint: Do not use this function inside a component, because it won't receive updates.
 	* Use `useQuery` to create a `QueryObserver` that subscribes to changes.
+	*
+	* @see {@link QueryClient#getQueriesData}
 	*/
 	getQueryData(queryKey) {
 		const options = this.defaultQueryOptions({ queryKey });
@@ -80,11 +134,49 @@ var QueryClient = class {
 		if (options.revalidateIfStale && query.isStaleByTime(resolveQueryValue(defaultedOptions.staleTime, query))) this.prefetchQuery(defaultedOptions);
 		return Promise.resolve(cachedData);
 	}
+	/**
+	* Imperative (non-reactive) way to retrieve the cached data of multiple queries at once.
+	* Only queries matching the given filters are returned; if none match, an empty array is
+	* returned.
+	*
+	* Because the matched queries can hold data of different shapes (e.g. a broad filter can match
+	* queries with unrelated data types), the `TQueryFnData` generic defaults to `unknown` rather
+	* than being inferred. Passing a more specific type is a convenience for call sites that know
+	* every matched query holds the same shape — it is not checked against the actual cache
+	* contents.
+	*
+	* @see {@link QueryClient#getQueryData}
+	* @example
+	* ```ts
+	* const data = queryClient.getQueriesData({ queryKey: ['posts'] })
+	* ```
+	*/
 	getQueriesData(filters) {
 		return this.#queryCache.findAll(filters).map(({ queryKey, state }) => {
 			return [queryKey, state.data];
 		});
 	}
+	/**
+	* Synchronous way to immediately update a query's cached data. If the updater (or the value
+	* passed) resolves to `undefined`, the cache is left untouched and no query is created;
+	* otherwise, if the query does not exist yet, it will be created. To update multiple queries
+	* at once by partially matching query keys, use {@link QueryClient#setQueriesData} instead.
+	*
+	* Updates must be performed immutably: do not mutate `oldData`, or data previously retrieved
+	* via {@link QueryClient#getQueryData}, in place.
+	*
+	* @param queryKey - The query key to set data for.
+	* @param updater - Either the new data, or a function that receives the current data (which
+	* may be `undefined`) and returns the new data.
+	*
+	* @example
+	* ```ts
+	* queryClient.setQueryData(['posts'], newPosts)
+	*
+	* // Or, using an updater function that receives the current data:
+	* queryClient.setQueryData(['posts'], (oldPosts) => [...oldPosts, newPost])
+	* ```
+	*/
 	setQueryData(queryKey, updater, options) {
 		const defaultedOptions = this.defaultQueryOptions({ queryKey });
 		const prevData = this.#queryCache.get(defaultedOptions.queryHash)?.state.data;
@@ -95,13 +187,47 @@ var QueryClient = class {
 			manual: true
 		});
 	}
+	/**
+	* Synchronous way to immediately update the cached data of multiple queries at once, using
+	* filters or partial query key matching. Only queries that already exist and match the given
+	* filters are updated; no new cache entries are created. Internally this calls
+	* {@link QueryClient#setQueryData} for each matching query.
+	*
+	* @example
+	* ```ts
+	* queryClient.setQueriesData({ queryKey: ['posts'] }, (oldPosts) =>
+	*   oldPosts ? oldPosts.filter((post) => post.id !== deletedId) : oldPosts,
+	* )
+	* ```
+	*/
 	setQueriesData(filters, updater, options) {
 		return notifyManager.batch(() => this.#queryCache.findAll(filters).map(({ queryKey }) => [queryKey, this.setQueryData(queryKey, updater, options)]));
 	}
+	/**
+	* Imperative (non-reactive) way to retrieve an existing query's state. If the query does not
+	* exist, `undefined` is returned.
+	*
+	* @example
+	* ```ts
+	* const state = queryClient.getQueryState(['posts'])
+	* console.log(state?.dataUpdatedAt)
+	* ```
+	*/
 	getQueryState(queryKey) {
 		const options = this.defaultQueryOptions({ queryKey });
 		return this.#queryCache.get(options.queryHash)?.state;
 	}
+	/**
+	* Removes queries from the cache that match the given filters. Unlike
+	* {@link QueryClient#invalidateQueries} or {@link QueryClient#refetchQueries}, this removes
+	* matching queries from the cache instead of refetching them. Without filters, every query in
+	* the cache is removed.
+	*
+	* @example
+	* ```ts
+	* queryClient.removeQueries({ queryKey: ['posts'], exact: true })
+	* ```
+	*/
 	removeQueries(filters) {
 		const queryCache = this.#queryCache;
 		notifyManager.batch(() => {
@@ -110,6 +236,16 @@ var QueryClient = class {
 			});
 		});
 	}
+	/**
+	* Resets queries matching the given filters back to their initial state (e.g. any
+	* `initialData`), notifying subscribers rather than removing them. Active queries among the
+	* matched set are then refetched, and the returned promise resolves once that refetch settles.
+	*
+	* @example
+	* ```ts
+	* await queryClient.resetQueries({ queryKey: ['posts'], exact: true })
+	* ```
+	*/
 	resetQueries(filters, options) {
 		const queryCache = this.#queryCache;
 		return notifyManager.batch(() => {
@@ -124,6 +260,19 @@ var QueryClient = class {
 			}, options);
 		});
 	}
+	/**
+	* Cancels outgoing fetches for queries matching the given filters. Most useful when performing
+	* optimistic updates, since any outgoing refetch that resolves afterwards would otherwise
+	* overwrite the optimistic update. By default (`revert: true`), a cancelled query's data is
+	* reverted to its state before the outgoing fetch started.
+	*
+	* The returned promise never rejects, even if individual cancellations fail.
+	*
+	* @example
+	* ```ts
+	* await queryClient.cancelQueries({ queryKey: ['posts'], exact: true })
+	* ```
+	*/
 	cancelQueries(filters, cancelOptions = {}) {
 		const defaultedCancelOptions = {
 			revert: true,
@@ -132,6 +281,19 @@ var QueryClient = class {
 		const promises = notifyManager.batch(() => this.#queryCache.findAll(filters).map((query) => query.cancel(defaultedCancelOptions)));
 		return Promise.all(promises).then(noop).catch(noop);
 	}
+	/**
+	* Marks queries matching the given filters as invalidated. Unlike
+	* {@link QueryClient#removeQueries}, invalidated queries stay in the cache.
+	*
+	* Unless `filters.refetchType` is `'none'`, matching queries are then refetched via
+	* {@link QueryClient#refetchQueries}, using `filters.refetchType` if set, otherwise
+	* `filters.type`, otherwise `'active'`.
+	*
+	* @example
+	* ```ts
+	* await queryClient.invalidateQueries({ queryKey: ['posts'], refetchType: 'active' })
+	* ```
+	*/
 	invalidateQueries(filters, options = {}) {
 		return notifyManager.batch(() => {
 			this.#queryCache.findAll(filters).forEach((query) => {
@@ -144,6 +306,21 @@ var QueryClient = class {
 			}, options);
 		});
 	}
+	/**
+	* Refetches queries matching the given filters, regardless of whether they are stale. Without
+	* filters, every query in the cache is refetched. Queries that are disabled, or static (only
+	* have observers with a static `staleTime`), are never refetched.
+	*
+	* By default (`cancelRefetch: true`), a currently running fetch is cancelled before the new
+	* one starts. The returned promise resolves once all matching queries have settled; it does
+	* not reject on individual query failures unless `throwOnError` is set.
+	*
+	* @example
+	* ```ts
+	* // refetch all active queries partially matching a query key:
+	* await queryClient.refetchQueries({ queryKey: ['posts'], type: 'active' })
+	* ```
+	*/
 	refetchQueries(filters, options = {}) {
 		const fetchOptions = {
 			...options,
@@ -156,6 +333,37 @@ var QueryClient = class {
 		}));
 		return Promise.all(promises).then(noop);
 	}
+	/**
+	* Asynchronous method to fetch and cache a query, resolving with the data or throwing with
+	* the error.
+	*
+	* If the query already exists in the cache and its data is not stale (per the given
+	* `staleTime`), the cached data is returned without fetching. Otherwise, the query is fetched
+	* and the promise resolves once the fetch settles. If a `select` function is provided, it is
+	* applied to the data in both cases (cached or freshly fetched) before it is returned.
+	*
+	* Unlike a reactive observer, retries are disabled by default here (`retry: false`) unless
+	* explicitly configured, since there is no component to catch a thrown error and retry through
+	* re-render.
+	*
+	* The accepted options are `QueryObserverOptions` minus the fields that only make sense for a
+	* reactive observer — `enabled`, `refetchInterval`, `refetchIntervalInBackground`,
+	* `refetchOnWindowFocus`, `refetchOnReconnect`, `refetchOnMount`, `retryOnMount`,
+	* `notifyOnChangeProps`, `throwOnError`, `suspense`, and `placeholderData` are not part of this
+	* method's options.
+	*
+	* This method replaces the deprecated `fetchQuery`, and — combined with
+	* `{ staleTime: 'static' }` — the deprecated `ensureQueryData`.
+	*
+	* @example
+	* ```ts
+	* try {
+	*   const data = await queryClient.query({ queryKey, queryFn, staleTime: 10000 })
+	* } catch (error) {
+	*   console.log(error)
+	* }
+	* ```
+	*/
 	async query(options) {
 		const defaultedOptions = this.defaultQueryOptions(options);
 		if (defaultedOptions.retry === void 0) defaultedOptions.retry = false;
@@ -180,6 +388,27 @@ var QueryClient = class {
 	prefetchQuery(options) {
 		return this.fetchQuery(options).then(noop).catch(noop);
 	}
+	/**
+	* Asynchronous method to fetch and cache an infinite query, resolving with an
+	* {@link InfiniteData} object or throwing with the error.
+	*
+	* Behaves like {@link QueryClient#query}, accepting the same options (minus
+	* `initialPageParam`), plus the required `initialPageParam`, and an optional `pages` /
+	* `getNextPageParam` pair used to refetch a fixed number of pages from the start.
+	*
+	* This method replaces the deprecated `fetchInfiniteQuery`, and — combined with
+	* `{ staleTime: 'static' }` — the deprecated `ensureInfiniteQueryData`.
+	*
+	* @example
+	* ```ts
+	* try {
+	*   const data = await queryClient.infiniteQuery({ queryKey, queryFn, initialPageParam: 0 })
+	*   console.log(data.pages)
+	* } catch (error) {
+	*   console.log(error)
+	* }
+	* ```
+	*/
 	infiniteQuery(options) {
 		options._type = "infinite";
 		return this.query(options);
@@ -204,28 +433,118 @@ var QueryClient = class {
 		options._type = "infinite";
 		return this.ensureQueryData(options);
 	}
+	/**
+	* Resumes mutations that were paused because there was no network connection. Does nothing
+	* (resolving immediately) if the client is currently offline.
+	*
+	* @example
+	* ```ts
+	* import { QueryClient } from '@tanstack/query-core'
+	*
+	* const queryClient = new QueryClient()
+	* await queryClient.resumePausedMutations()
+	* ```
+	*/
 	resumePausedMutations() {
 		if (onlineManager.isOnline()) return this.#mutationCache.resumePausedMutations();
 		return Promise.resolve();
 	}
+	/**
+	* Returns the query cache this client is connected to.
+	*
+	* @example
+	* ```ts
+	* import { QueryClient } from '@tanstack/query-core'
+	*
+	* const queryClient = new QueryClient()
+	* const queryCache = queryClient.getQueryCache()
+	* const queries = queryCache.findAll({ queryKey: ['posts'] })
+	* ```
+	*/
 	getQueryCache() {
 		return this.#queryCache;
 	}
+	/**
+	* Returns the mutation cache this client is connected to.
+	*
+	* @example
+	* ```ts
+	* import { QueryClient } from '@tanstack/query-core'
+	*
+	* const queryClient = new QueryClient()
+	* const mutationCache = queryClient.getMutationCache()
+	* const mutations = mutationCache.findAll({ status: 'pending' })
+	* ```
+	*/
 	getMutationCache() {
 		return this.#mutationCache;
 	}
+	/**
+	* Returns the default options that were set when creating the client, or via
+	* {@link QueryClient#setDefaultOptions}.
+	*
+	* @example
+	* ```ts
+	* import { QueryClient } from '@tanstack/query-core'
+	*
+	* const queryClient = new QueryClient()
+	* const defaultOptions = queryClient.getDefaultOptions()
+	* ```
+	*/
 	getDefaultOptions() {
 		return this.#defaultOptions;
 	}
+	/**
+	* Dynamically sets the default options for this client, overwriting any previously defined
+	* default options.
+	*
+	* @see {@link QueryClient#getDefaultOptions}
+	* @example
+	* ```ts
+	* import { QueryClient } from '@tanstack/query-core'
+	*
+	* const queryClient = new QueryClient()
+	* queryClient.setDefaultOptions({
+	*   queries: {
+	*     staleTime: Infinity,
+	*   },
+	* })
+	* ```
+	*/
 	setDefaultOptions(options) {
 		this.#defaultOptions = options;
 	}
+	/**
+	* Sets default options for queries whose query key partially matches the given `queryKey`.
+	*
+	* If several registered query defaults match a given query key, they are merged together in
+	* registration order by {@link QueryClient#getQueryDefaults}, so register defaults from the
+	* most generic key to the least generic one — more specific defaults should be registered
+	* after more generic ones so they take precedence.
+	*
+	* @example
+	* ```ts
+	* queryClient.setQueryDefaults(['posts'], { queryFn: fetchPosts })
+	*
+	* await queryClient.query({ queryKey: ['posts'] })
+	* ```
+	*/
 	setQueryDefaults(queryKey, options) {
 		this.#queryDefaults.set(hashKey(queryKey), {
 			queryKey,
 			defaultOptions: options
 		});
 	}
+	/**
+	* Returns the default options registered for queries whose query key partially matches the
+	* given `queryKey`, via {@link QueryClient#setQueryDefaults}. If multiple registered defaults
+	* match, they are merged together in registration order.
+	*
+	* @example
+	* ```ts
+	* const defaultOptions = queryClient.getQueryDefaults(['posts'])
+	* ```
+	*/
 	getQueryDefaults(queryKey) {
 		const defaults = [...this.#queryDefaults.values()];
 		const result = {};
@@ -234,12 +553,33 @@ var QueryClient = class {
 		});
 		return result;
 	}
+	/**
+	* Sets default options for mutations whose mutation key partially matches the given
+	* `mutationKey`. As with {@link QueryClient#setQueryDefaults}, the order of registration
+	* matters when several registered defaults match the same mutation key.
+	*
+	* @see {@link QueryClient#getMutationDefaults}
+	* @example
+	* ```ts
+	* queryClient.setMutationDefaults(['addPost'], { mutationFn: addPost })
+	* ```
+	*/
 	setMutationDefaults(mutationKey, options) {
 		this.#mutationDefaults.set(hashKey(mutationKey), {
 			mutationKey,
 			defaultOptions: options
 		});
 	}
+	/**
+	* Returns the default options registered for mutations whose mutation key partially matches
+	* the given `mutationKey`, via {@link QueryClient#setMutationDefaults}. If multiple registered
+	* defaults match, they are merged together in registration order.
+	*
+	* @example
+	* ```ts
+	* const defaultOptions = queryClient.getMutationDefaults(['addPost'])
+	* ```
+	*/
 	getMutationDefaults(mutationKey) {
 		const defaults = [...this.#mutationDefaults.values()];
 		const result = {};
@@ -248,6 +588,12 @@ var QueryClient = class {
 		});
 		return result;
 	}
+	/**
+	* Called by framework adapters (e.g. inside `useQuery`) to resolve the options passed by the
+	* caller into their final, defaulted form: merging `queryClient.setQueryDefaults` for the
+	* given `queryKey`, then the client's own `defaultOptions.queries`, then the caller's options
+	* on top. A no-op if the options are already defaulted (`_defaulted: true`).
+	*/
 	defaultQueryOptions(options) {
 		if (options._defaulted) return options;
 		const defaultedOptions = {
@@ -263,6 +609,12 @@ var QueryClient = class {
 		if (defaultedOptions.queryFn === skipToken) defaultedOptions.enabled = false;
 		return defaultedOptions;
 	}
+	/**
+	* The mutation counterpart of {@link QueryClient#defaultQueryOptions}. Called by framework
+	* adapters (e.g. inside `useMutation`) to merge `queryClient.setMutationDefaults` for the
+	* given `mutationKey`, then the client's `defaultOptions.mutations`, then the caller's options
+	* on top. A no-op if the options are already defaulted (`_defaulted: true`).
+	*/
 	defaultMutationOptions(options) {
 		if (options?._defaulted) return options;
 		return {
@@ -272,6 +624,17 @@ var QueryClient = class {
 			_defaulted: true
 		};
 	}
+	/**
+	* Clears both the query cache and the mutation cache this client is connected to.
+	*
+	* @example
+	* ```ts
+	* import { QueryClient } from '@tanstack/query-core'
+	*
+	* const queryClient = new QueryClient()
+	* queryClient.clear()
+	* ```
+	*/
 	clear() {
 		this.#queryCache.clear();
 		this.#mutationCache.clear();