@tanstack/preact-query 5.102.2 → 5.102.4

package/build/legacy/useMutation.d.cts

@@ -1,6 +1,73 @@
 import { UseMutationOptions, UseMutationResult } from "./types.cjs";
 import { DefaultError, QueryClient } from "@tanstack/query-core";
 //#region src/useMutation.d.ts
+/**
+ * Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects.
+ * `useMutation` is the hook for that.
+ *
+ * @see {@link mutationOptions} to share these options across multiple `useMutation` call sites.
+ * @param options - The {@link UseMutationOptions} to use — everything you can pass to `useMutation`.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns `mutate`/`mutateAsync` also accept per-call `onSuccess`/`onError`/`onSettled` callbacks as a second
+ * argument, useful for triggering call-site side effects (e.g. navigation) without coupling them to the shared
+ * mutation definition. If you make multiple requests, `onSuccess` will fire only after the latest call you've
+ * made.
+ *
+ * @example
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodo() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => addMutation.mutate('Item')}>Add</button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Optimistic update via `onMutate`, rolling back on `onError`:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodo() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onMutate: async (newTodo) => {
+ *       await queryClient.cancelQueries({ queryKey: ['todos'] })
+ *       const previousTodos = queryClient.getQueryData<Array<string>>(['todos'])
+ *
+ *       queryClient.setQueryData<Array<string>>(['todos'], (old) => [
+ *         ...(old ?? []),
+ *         newTodo,
+ *       ])
+ *
+ *       // Passed to `onError` as `context` if the mutation fails.
+ *       return { previousTodos }
+ *     },
+ *     onError: (_err, _newTodo, context) => {
+ *       queryClient.setQueryData(['todos'], context?.previousTodos)
+ *     },
+ *     onSettled: () => {
+ *       queryClient.invalidateQueries({ queryKey: ['todos'] })
+ *     },
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => addMutation.mutate('Item')}>Add</button>
+ *   )
+ * }
+ * ```
+ */
 declare function useMutation<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown>(options: UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, queryClient?: QueryClient): UseMutationResult<TData, TError, TVariables, TOnMutateResult>;
 //#endregion
 export { useMutation };

package/build/legacy/useMutation.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"useMutation.d.cts","names":[],"sources":["../../src/useMutation.ts"],"mappings":";;;iBAmBgB,YACd,iBACA,SAAS,cACT,mBACA,2BAEA,SAAS,mBAAmB,OAAO,QAAQ,YAAY,kBACvD,cAAc,cACb,kBAAkB,OAAO,QAAQ,YAAY"}
+{"version":3,"file":"useMutation.d.cts","names":[],"sources":["../../src/useMutation.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsFgB,YACd,iBACA,SAAS,cACT,mBACA,2BAEA,SAAS,mBAAmB,OAAO,QAAQ,YAAY,kBACvD,cAAc,cACb,kBAAkB,OAAO,QAAQ,YAAY"}

package/build/legacy/useMutation.d.ts

@@ -1,6 +1,73 @@
 import { UseMutationOptions, UseMutationResult } from "./types.js";
 import { DefaultError, QueryClient } from "@tanstack/query-core";
 //#region src/useMutation.d.ts
+/**
+ * Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects.
+ * `useMutation` is the hook for that.
+ *
+ * @see {@link mutationOptions} to share these options across multiple `useMutation` call sites.
+ * @param options - The {@link UseMutationOptions} to use — everything you can pass to `useMutation`.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns `mutate`/`mutateAsync` also accept per-call `onSuccess`/`onError`/`onSettled` callbacks as a second
+ * argument, useful for triggering call-site side effects (e.g. navigation) without coupling them to the shared
+ * mutation definition. If you make multiple requests, `onSuccess` will fire only after the latest call you've
+ * made.
+ *
+ * @example
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodo() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => addMutation.mutate('Item')}>Add</button>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * Optimistic update via `onMutate`, rolling back on `onError`:
+ * ```tsx
+ * import { useMutation, useQueryClient } from '@tanstack/preact-query'
+ *
+ * function AddTodo() {
+ *   const queryClient = useQueryClient()
+ *
+ *   const addMutation = useMutation({
+ *     mutationFn: addTodo,
+ *     onMutate: async (newTodo) => {
+ *       await queryClient.cancelQueries({ queryKey: ['todos'] })
+ *       const previousTodos = queryClient.getQueryData<Array<string>>(['todos'])
+ *
+ *       queryClient.setQueryData<Array<string>>(['todos'], (old) => [
+ *         ...(old ?? []),
+ *         newTodo,
+ *       ])
+ *
+ *       // Passed to `onError` as `context` if the mutation fails.
+ *       return { previousTodos }
+ *     },
+ *     onError: (_err, _newTodo, context) => {
+ *       queryClient.setQueryData(['todos'], context?.previousTodos)
+ *     },
+ *     onSettled: () => {
+ *       queryClient.invalidateQueries({ queryKey: ['todos'] })
+ *     },
+ *   })
+ *
+ *   return (
+ *     <button onClick={() => addMutation.mutate('Item')}>Add</button>
+ *   )
+ * }
+ * ```
+ */
 declare function useMutation<TData = unknown, TError = DefaultError, TVariables = void, TOnMutateResult = unknown>(options: UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, queryClient?: QueryClient): UseMutationResult<TData, TError, TVariables, TOnMutateResult>;
 //#endregion
 export { useMutation };

package/build/legacy/useMutation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useMutation.d.ts","names":[],"sources":["../../src/useMutation.ts"],"mappings":";;;iBAmBgB,YACd,iBACA,SAAS,cACT,mBACA,2BAEA,SAAS,mBAAmB,OAAO,QAAQ,YAAY,kBACvD,cAAc,cACb,kBAAkB,OAAO,QAAQ,YAAY"}
+{"version":3,"file":"useMutation.d.ts","names":[],"sources":["../../src/useMutation.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsFgB,YACd,iBACA,SAAS,cACT,mBACA,2BAEA,SAAS,mBAAmB,OAAO,QAAQ,YAAY,kBACvD,cAAc,cACb,kBAAkB,OAAO,QAAQ,YAAY"}

package/build/legacy/useMutation.js

@@ -3,6 +3,73 @@ import { useSyncExternalStore } from "./utils.js";
 import { MutationObserver, noop, notifyManager, shouldThrowError } from "@tanstack/query-core";
 import { useCallback, useEffect, useState } from "preact/hooks";
 //#region src/useMutation.ts
+/**
+* Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects.
+* `useMutation` is the hook for that.
+*
+* @see {@link mutationOptions} to share these options across multiple `useMutation` call sites.
+* @param options - The {@link UseMutationOptions} to use — everything you can pass to `useMutation`.
+* @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+* be used.
+* @returns `mutate`/`mutateAsync` also accept per-call `onSuccess`/`onError`/`onSettled` callbacks as a second
+* argument, useful for triggering call-site side effects (e.g. navigation) without coupling them to the shared
+* mutation definition. If you make multiple requests, `onSuccess` will fire only after the latest call you've
+* made.
+*
+* @example
+* ```tsx
+* import { useMutation, useQueryClient } from '@tanstack/preact-query'
+*
+* function AddTodo() {
+*   const queryClient = useQueryClient()
+*
+*   const addMutation = useMutation({
+*     mutationFn: addTodo,
+*     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
+*   })
+*
+*   return (
+*     <button onClick={() => addMutation.mutate('Item')}>Add</button>
+*   )
+* }
+* ```
+*
+* @example
+* Optimistic update via `onMutate`, rolling back on `onError`:
+* ```tsx
+* import { useMutation, useQueryClient } from '@tanstack/preact-query'
+*
+* function AddTodo() {
+*   const queryClient = useQueryClient()
+*
+*   const addMutation = useMutation({
+*     mutationFn: addTodo,
+*     onMutate: async (newTodo) => {
+*       await queryClient.cancelQueries({ queryKey: ['todos'] })
+*       const previousTodos = queryClient.getQueryData<Array<string>>(['todos'])
+*
+*       queryClient.setQueryData<Array<string>>(['todos'], (old) => [
+*         ...(old ?? []),
+*         newTodo,
+*       ])
+*
+*       // Passed to `onError` as `context` if the mutation fails.
+*       return { previousTodos }
+*     },
+*     onError: (_err, _newTodo, context) => {
+*       queryClient.setQueryData(['todos'], context?.previousTodos)
+*     },
+*     onSettled: () => {
+*       queryClient.invalidateQueries({ queryKey: ['todos'] })
+*     },
+*   })
+*
+*   return (
+*     <button onClick={() => addMutation.mutate('Item')}>Add</button>
+*   )
+* }
+* ```
+*/
 function useMutation(options, queryClient) {
 	const client = useQueryClient(queryClient);
 	const [observer] = useState(() => new MutationObserver(client, options));

package/build/legacy/useMutation.js.map

@@ -1 +1 @@
-{"version":3,"file":"useMutation.js","names":[],"sources":["../../src/useMutation.ts"],"sourcesContent":["import {\n  MutationObserver,\n  noop,\n  notifyManager,\n  shouldThrowError,\n} from '@tanstack/query-core'\nimport type { DefaultError, QueryClient } from '@tanstack/query-core'\nimport { useCallback, useEffect, useState } from 'preact/hooks'\n\nimport { useQueryClient } from './QueryClientProvider'\nimport type {\n  UseMutateFunction,\n  UseMutationOptions,\n  UseMutationResult,\n} from './types'\nimport { useSyncExternalStore } from './utils'\n\n// HOOK\n\nexport function useMutation<\n  TData = unknown,\n  TError = DefaultError,\n  TVariables = void,\n  TOnMutateResult = unknown,\n>(\n  options: UseMutationOptions<TData, TError, TVariables, TOnMutateResult>,\n  queryClient?: QueryClient,\n): UseMutationResult<TData, TError, TVariables, TOnMutateResult> {\n  const client = useQueryClient(queryClient)\n\n  const [observer] = useState(\n    () =>\n      new MutationObserver<TData, TError, TVariables, TOnMutateResult>(\n        client,\n        options,\n      ),\n  )\n\n  useEffect(() => {\n    observer.setOptions(options)\n  }, [observer, options])\n\n  const result = useSyncExternalStore(\n    useCallback(\n      (onStoreChange) =>\n        observer.subscribe(notifyManager.batchCalls(onStoreChange)),\n      [observer],\n    ),\n    () => observer.getCurrentResult(),\n  )\n\n  const mutate = useCallback<\n    UseMutateFunction<TData, TError, TVariables, TOnMutateResult>\n  >(\n    (\n      ...args: Parameters<\n        UseMutateFunction<TData, TError, TVariables, TOnMutateResult>\n      >\n    ) => {\n      observer.mutate(args[0] as TVariables, args[1]).catch(noop)\n    },\n    [observer],\n  )\n\n  if (\n    result.error &&\n    shouldThrowError(observer.options.throwOnError, [result.error])\n  ) {\n    throw result.error\n  }\n\n  return { ...result, mutate, mutateAsync: result.mutate }\n}\n"],"mappings":";;;;;AAmBA,SAAgB,YAMd,SACA,aAC+D;CAC/D,MAAM,SAAS,eAAe,WAAW;CAEzC,MAAM,CAAC,YAAY,eAEf,IAAI,iBACF,QACA,OACF,CACJ;CAEA,gBAAgB;EACd,SAAS,WAAW,OAAO;CAC7B,GAAG,CAAC,UAAU,OAAO,CAAC;CAEtB,MAAM,SAAS,qBACb,aACG,kBACC,SAAS,UAAU,cAAc,WAAW,aAAa,CAAC,GAC5D,CAAC,QAAQ,CACX,SACM,SAAS,iBAAiB,CAClC;CAEA,MAAM,SAAS,aAIX,GAAG,SAGA;EACH,SAAS,OAAO,KAAK,IAAkB,KAAK,EAAE,CAAC,CAAC,MAAM,IAAI;CAC5D,GACA,CAAC,QAAQ,CACX;CAEA,IACE,OAAO,SACP,iBAAiB,SAAS,QAAQ,cAAc,CAAC,OAAO,KAAK,CAAC,GAE9D,MAAM,OAAO;CAGf,OAAO;EAAE,GAAG;EAAQ;EAAQ,aAAa,OAAO;CAAO;AACzD"}
+{"version":3,"file":"useMutation.js","names":[],"sources":["../../src/useMutation.ts"],"sourcesContent":["import {\n  MutationObserver,\n  noop,\n  notifyManager,\n  shouldThrowError,\n} from '@tanstack/query-core'\nimport type { DefaultError, QueryClient } from '@tanstack/query-core'\nimport { useCallback, useEffect, useState } from 'preact/hooks'\n\nimport { useQueryClient } from './QueryClientProvider'\nimport type {\n  UseMutateFunction,\n  UseMutationOptions,\n  UseMutationResult,\n} from './types'\nimport { useSyncExternalStore } from './utils'\n\n// HOOK\n\n/**\n * Unlike queries, mutations are typically used to create/update/delete data or perform server side-effects.\n * `useMutation` is the hook for that.\n *\n * @see {@link mutationOptions} to share these options across multiple `useMutation` call sites.\n * @param options - The {@link UseMutationOptions} to use — everything you can pass to `useMutation`.\n * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will\n * be used.\n * @returns `mutate`/`mutateAsync` also accept per-call `onSuccess`/`onError`/`onSettled` callbacks as a second\n * argument, useful for triggering call-site side effects (e.g. navigation) without coupling them to the shared\n * mutation definition. If you make multiple requests, `onSuccess` will fire only after the latest call you've\n * made.\n *\n * @example\n * ```tsx\n * import { useMutation, useQueryClient } from '@tanstack/preact-query'\n *\n * function AddTodo() {\n *   const queryClient = useQueryClient()\n *\n *   const addMutation = useMutation({\n *     mutationFn: addTodo,\n *     onSuccess: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),\n *   })\n *\n *   return (\n *     <button onClick={() => addMutation.mutate('Item')}>Add</button>\n *   )\n * }\n * ```\n *\n * @example\n * Optimistic update via `onMutate`, rolling back on `onError`:\n * ```tsx\n * import { useMutation, useQueryClient } from '@tanstack/preact-query'\n *\n * function AddTodo() {\n *   const queryClient = useQueryClient()\n *\n *   const addMutation = useMutation({\n *     mutationFn: addTodo,\n *     onMutate: async (newTodo) => {\n *       await queryClient.cancelQueries({ queryKey: ['todos'] })\n *       const previousTodos = queryClient.getQueryData<Array<string>>(['todos'])\n *\n *       queryClient.setQueryData<Array<string>>(['todos'], (old) => [\n *         ...(old ?? []),\n *         newTodo,\n *       ])\n *\n *       // Passed to `onError` as `context` if the mutation fails.\n *       return { previousTodos }\n *     },\n *     onError: (_err, _newTodo, context) => {\n *       queryClient.setQueryData(['todos'], context?.previousTodos)\n *     },\n *     onSettled: () => {\n *       queryClient.invalidateQueries({ queryKey: ['todos'] })\n *     },\n *   })\n *\n *   return (\n *     <button onClick={() => addMutation.mutate('Item')}>Add</button>\n *   )\n * }\n * ```\n */\nexport function useMutation<\n  TData = unknown,\n  TError = DefaultError,\n  TVariables = void,\n  TOnMutateResult = unknown,\n>(\n  options: UseMutationOptions<TData, TError, TVariables, TOnMutateResult>,\n  queryClient?: QueryClient,\n): UseMutationResult<TData, TError, TVariables, TOnMutateResult> {\n  const client = useQueryClient(queryClient)\n\n  const [observer] = useState(\n    () =>\n      new MutationObserver<TData, TError, TVariables, TOnMutateResult>(\n        client,\n        options,\n      ),\n  )\n\n  useEffect(() => {\n    observer.setOptions(options)\n  }, [observer, options])\n\n  const result = useSyncExternalStore(\n    useCallback(\n      (onStoreChange) =>\n        observer.subscribe(notifyManager.batchCalls(onStoreChange)),\n      [observer],\n    ),\n    () => observer.getCurrentResult(),\n  )\n\n  const mutate = useCallback<\n    UseMutateFunction<TData, TError, TVariables, TOnMutateResult>\n  >(\n    (\n      ...args: Parameters<\n        UseMutateFunction<TData, TError, TVariables, TOnMutateResult>\n      >\n    ) => {\n      observer.mutate(args[0] as TVariables, args[1]).catch(noop)\n    },\n    [observer],\n  )\n\n  if (\n    result.error &&\n    shouldThrowError(observer.options.throwOnError, [result.error])\n  ) {\n    throw result.error\n  }\n\n  return { ...result, mutate, mutateAsync: result.mutate }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsFA,SAAgB,YAMd,SACA,aAC+D;CAC/D,MAAM,SAAS,eAAe,WAAW;CAEzC,MAAM,CAAC,YAAY,eAEf,IAAI,iBACF,QACA,OACF,CACJ;CAEA,gBAAgB;EACd,SAAS,WAAW,OAAO;CAC7B,GAAG,CAAC,UAAU,OAAO,CAAC;CAEtB,MAAM,SAAS,qBACb,aACG,kBACC,SAAS,UAAU,cAAc,WAAW,aAAa,CAAC,GAC5D,CAAC,QAAQ,CACX,SACM,SAAS,iBAAiB,CAClC;CAEA,MAAM,SAAS,aAIX,GAAG,SAGA;EACH,SAAS,OAAO,KAAK,IAAkB,KAAK,EAAE,CAAC,CAAC,MAAM,IAAI;CAC5D,GACA,CAAC,QAAQ,CACX;CAEA,IACE,OAAO,SACP,iBAAiB,SAAS,QAAQ,cAAc,CAAC,OAAO,KAAK,CAAC,GAE9D,MAAM,OAAO;CAGf,OAAO;EAAE,GAAG;EAAQ;EAAQ,aAAa,OAAO;CAAO;AACzD"}

package/build/legacy/useMutationState.cjs

@@ -4,6 +4,25 @@ const require_utils = require("./utils.cjs");
 let _tanstack_query_core = require("@tanstack/query-core");
 let preact_hooks = require("preact/hooks");
 //#region src/useMutationState.ts
+/**
+* `useIsMutating` is an optional hook that returns the `number` of mutations that your application is fetching
+* (useful for app-wide loading indicators).
+*
+* @param filters - The {@link MutationFilters} to narrow down the matched mutations.
+* @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+* be used.
+* @returns Will be the `number` of the mutations that your application is currently fetching.
+*
+* @example
+* ```tsx
+* import { useIsMutating } from '@tanstack/preact-query'
+*
+* // How many mutations are fetching?
+* const isMutating = useIsMutating()
+* // How many mutations matching the posts prefix are fetching?
+* const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
+* ```
+*/
 function useIsMutating(filters, queryClient) {
 	const client = require_QueryClientProvider.useQueryClient(queryClient);
 	return useMutationState({ filters: {
@@ -14,6 +33,61 @@ function useIsMutating(filters, queryClient) {
 function getResult(mutationCache, options) {
 	return mutationCache.findAll(options.filters).map((mutation) => options.select ? options.select(mutation) : mutation.state);
 }
+/**
+* `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
+* `filters` ({@link MutationFilters}) to narrow down your mutations, and `select` to transform the mutation
+* state.
+*
+* @param options - The `filters` to narrow down matched mutations, and an optional `select` to transform the
+* mutation state.
+* @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+* be used.
+* @returns Will be an Array of whatever `select` returns for each matching mutation.
+*
+* @example
+* Get all variables of all running mutations:
+* ```tsx
+* import { useMutationState } from '@tanstack/preact-query'
+*
+* const variables = useMutationState({
+*   filters: { status: 'pending' },
+*   select: (mutation) => mutation.state.variables,
+* })
+* ```
+*
+* @example
+* Get all data for specific mutations via the `mutationKey`:
+* ```tsx
+* import { useMutation, useMutationState } from '@tanstack/preact-query'
+*
+* const mutationKey = ['posts']
+*
+* // Some mutation that we want to get the state for
+* const mutation = useMutation({
+*   mutationKey,
+*   mutationFn: createPosts,
+* })
+*
+* const data = useMutationState({
+*   // this mutation key needs to match the mutation key of the given mutation (see above)
+*   filters: { mutationKey },
+*   select: (mutation) => mutation.state.data,
+* })
+* ```
+*
+* @example
+* Access the latest mutation data via the `mutationKey`. Each invocation of `mutate` adds a new entry to the
+* mutation cache for `gcTime` milliseconds — check the last item that `useMutationState` returns to get the
+* latest invocation:
+* ```tsx
+* const data = useMutationState({
+*   filters: { mutationKey: ['posts'] },
+*   select: (mutation) => mutation.state.data,
+* })
+*
+* const latest = data[data.length - 1]
+* ```
+*/
 function useMutationState(options = {}, queryClient) {
 	const mutationCache = require_QueryClientProvider.useQueryClient(queryClient).getMutationCache();
 	const optionsRef = (0, preact_hooks.useRef)(options);

package/build/legacy/useMutationState.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useMutationState.cjs","names":["useQueryClient","useRef","useSyncExternalStore","useCallback","replaceEqualDeep"],"sources":["../../src/useMutationState.ts"],"sourcesContent":["import { notifyManager, replaceEqualDeep } from '@tanstack/query-core'\nimport type {\n  Mutation,\n  MutationCache,\n  MutationFilters,\n  MutationState,\n  QueryClient,\n} from '@tanstack/query-core'\nimport { useCallback, useEffect, useRef } from 'preact/hooks'\n\nimport { useQueryClient } from './QueryClientProvider'\nimport { useSyncExternalStore } from './utils'\n\nexport function useIsMutating(\n  filters?: MutationFilters,\n  queryClient?: QueryClient,\n): number {\n  const client = useQueryClient(queryClient)\n  return useMutationState(\n    { filters: { ...filters, status: 'pending' } },\n    client,\n  ).length\n}\n\ntype MutationTypeFromResult<TResult> = [TResult] extends [\n  MutationState<\n    infer TData,\n    infer TError,\n    infer TVariables,\n    infer TOnMutateResult\n  >,\n]\n  ? Mutation<TData, TError, TVariables, TOnMutateResult>\n  : Mutation\n\ntype MutationStateOptions<\n  TResult = MutationState,\n  TMutation extends Mutation<any, any, any, any> =\n    MutationTypeFromResult<TResult>,\n> = {\n  filters?: MutationFilters\n  select?: (mutation: TMutation) => TResult\n}\n\nfunction getResult<\n  TResult = MutationState,\n  TMutation extends Mutation<any, any, any, any> =\n    MutationTypeFromResult<TResult>,\n>(\n  mutationCache: MutationCache,\n  options: MutationStateOptions<TResult, TMutation>,\n): Array<TResult> {\n  return mutationCache\n    .findAll(options.filters)\n    .map(\n      (mutation): TResult =>\n        (options.select\n          ? options.select(mutation as TMutation)\n          : mutation.state) as TResult,\n    )\n}\n\nexport function useMutationState<\n  TResult = MutationState,\n  TMutation extends Mutation<any, any, any, any> =\n    MutationTypeFromResult<TResult>,\n>(\n  options: MutationStateOptions<TResult, TMutation> = {},\n  queryClient?: QueryClient,\n): Array<TResult> {\n  const mutationCache = useQueryClient(queryClient).getMutationCache()\n  const optionsRef = useRef(options)\n  const result = useRef<Array<TResult>>(null)\n  if (result.current === null) {\n    result.current = getResult(mutationCache, options)\n  }\n\n  useEffect(() => {\n    optionsRef.current = options\n  })\n\n  return useSyncExternalStore(\n    useCallback(\n      (onStoreChange) =>\n        mutationCache.subscribe(() => {\n          const nextResult = replaceEqualDeep(\n            result.current,\n            getResult(mutationCache, optionsRef.current),\n          )\n          if (result.current !== nextResult) {\n            result.current = nextResult\n            notifyManager.schedule(onStoreChange)\n          }\n        }),\n      [mutationCache],\n    ),\n    () => result.current,\n  )!\n}\n"],"mappings":";;;;;;AAaA,SAAgB,cACd,SACA,aACQ;CACR,MAAM,SAASA,4BAAAA,eAAe,WAAW;CACzC,OAAO,iBACL,EAAE,SAAS;EAAE,GAAG;EAAS,QAAQ;CAAU,EAAE,GAC7C,MACF,CAAC,CAAC;AACJ;AAsBA,SAAS,UAKP,eACA,SACgB;CAChB,OAAO,cACJ,QAAQ,QAAQ,OAAO,CAAC,CACxB,KACE,aACE,QAAQ,SACL,QAAQ,OAAO,QAAqB,IACpC,SAAS,KACjB;AACJ;AAEA,SAAgB,iBAKd,UAAoD,CAAC,GACrD,aACgB;CAChB,MAAM,gBAAgBA,4BAAAA,eAAe,WAAW,CAAC,CAAC,iBAAiB;CACnE,MAAM,cAAA,GAAaC,aAAAA,OAAAA,CAAO,OAAO;CACjC,MAAM,UAAA,GAASA,aAAAA,OAAAA,CAAuB,IAAI;CAC1C,IAAI,OAAO,YAAY,MACrB,OAAO,UAAU,UAAU,eAAe,OAAO;CAGnD,CAAA,GAAA,aAAA,UAAA,OAAgB;EACd,WAAW,UAAU;CACvB,CAAC;CAED,OAAOC,cAAAA,sBAAAA,GACLC,aAAAA,YAAAA,EACG,kBACC,cAAc,gBAAgB;EAC5B,MAAM,cAAA,GAAaC,qBAAAA,iBAAAA,CACjB,OAAO,SACP,UAAU,eAAe,WAAW,OAAO,CAC7C;EACA,IAAI,OAAO,YAAY,YAAY;GACjC,OAAO,UAAU;GACjB,qBAAA,cAAc,SAAS,aAAa;EACtC;CACF,CAAC,GACH,CAAC,aAAa,CAChB,SACM,OAAO,OACf;AACF"}
+{"version":3,"file":"useMutationState.cjs","names":["useQueryClient","useRef","useSyncExternalStore","useCallback","replaceEqualDeep"],"sources":["../../src/useMutationState.ts"],"sourcesContent":["import { notifyManager, replaceEqualDeep } from '@tanstack/query-core'\nimport type {\n  Mutation,\n  MutationCache,\n  MutationFilters,\n  MutationState,\n  QueryClient,\n} from '@tanstack/query-core'\nimport { useCallback, useEffect, useRef } from 'preact/hooks'\n\nimport { useQueryClient } from './QueryClientProvider'\nimport { useSyncExternalStore } from './utils'\n\n/**\n * `useIsMutating` is an optional hook that returns the `number` of mutations that your application is fetching\n * (useful for app-wide loading indicators).\n *\n * @param filters - The {@link MutationFilters} to narrow down the matched mutations.\n * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will\n * be used.\n * @returns Will be the `number` of the mutations that your application is currently fetching.\n *\n * @example\n * ```tsx\n * import { useIsMutating } from '@tanstack/preact-query'\n *\n * // How many mutations are fetching?\n * const isMutating = useIsMutating()\n * // How many mutations matching the posts prefix are fetching?\n * const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })\n * ```\n */\nexport function useIsMutating(\n  filters?: MutationFilters,\n  queryClient?: QueryClient,\n): number {\n  const client = useQueryClient(queryClient)\n  return useMutationState(\n    { filters: { ...filters, status: 'pending' } },\n    client,\n  ).length\n}\n\ntype MutationTypeFromResult<TResult> = [TResult] extends [\n  MutationState<\n    infer TData,\n    infer TError,\n    infer TVariables,\n    infer TOnMutateResult\n  >,\n]\n  ? Mutation<TData, TError, TVariables, TOnMutateResult>\n  : Mutation\n\ntype MutationStateOptions<\n  TResult = MutationState,\n  TMutation extends Mutation<any, any, any, any> =\n    MutationTypeFromResult<TResult>,\n> = {\n  filters?: MutationFilters\n  select?: (mutation: TMutation) => TResult\n}\n\nfunction getResult<\n  TResult = MutationState,\n  TMutation extends Mutation<any, any, any, any> =\n    MutationTypeFromResult<TResult>,\n>(\n  mutationCache: MutationCache,\n  options: MutationStateOptions<TResult, TMutation>,\n): Array<TResult> {\n  return mutationCache\n    .findAll(options.filters)\n    .map(\n      (mutation): TResult =>\n        (options.select\n          ? options.select(mutation as TMutation)\n          : mutation.state) as TResult,\n    )\n}\n\n/**\n * `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass\n * `filters` ({@link MutationFilters}) to narrow down your mutations, and `select` to transform the mutation\n * state.\n *\n * @param options - The `filters` to narrow down matched mutations, and an optional `select` to transform the\n * mutation state.\n * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will\n * be used.\n * @returns Will be an Array of whatever `select` returns for each matching mutation.\n *\n * @example\n * Get all variables of all running mutations:\n * ```tsx\n * import { useMutationState } from '@tanstack/preact-query'\n *\n * const variables = useMutationState({\n *   filters: { status: 'pending' },\n *   select: (mutation) => mutation.state.variables,\n * })\n * ```\n *\n * @example\n * Get all data for specific mutations via the `mutationKey`:\n * ```tsx\n * import { useMutation, useMutationState } from '@tanstack/preact-query'\n *\n * const mutationKey = ['posts']\n *\n * // Some mutation that we want to get the state for\n * const mutation = useMutation({\n *   mutationKey,\n *   mutationFn: createPosts,\n * })\n *\n * const data = useMutationState({\n *   // this mutation key needs to match the mutation key of the given mutation (see above)\n *   filters: { mutationKey },\n *   select: (mutation) => mutation.state.data,\n * })\n * ```\n *\n * @example\n * Access the latest mutation data via the `mutationKey`. Each invocation of `mutate` adds a new entry to the\n * mutation cache for `gcTime` milliseconds — check the last item that `useMutationState` returns to get the\n * latest invocation:\n * ```tsx\n * const data = useMutationState({\n *   filters: { mutationKey: ['posts'] },\n *   select: (mutation) => mutation.state.data,\n * })\n *\n * const latest = data[data.length - 1]\n * ```\n */\nexport function useMutationState<\n  TResult = MutationState,\n  TMutation extends Mutation<any, any, any, any> =\n    MutationTypeFromResult<TResult>,\n>(\n  options: MutationStateOptions<TResult, TMutation> = {},\n  queryClient?: QueryClient,\n): Array<TResult> {\n  const mutationCache = useQueryClient(queryClient).getMutationCache()\n  const optionsRef = useRef(options)\n  const result = useRef<Array<TResult>>(null)\n  if (result.current === null) {\n    result.current = getResult(mutationCache, options)\n  }\n\n  useEffect(() => {\n    optionsRef.current = options\n  })\n\n  return useSyncExternalStore(\n    useCallback(\n      (onStoreChange) =>\n        mutationCache.subscribe(() => {\n          const nextResult = replaceEqualDeep(\n            result.current,\n            getResult(mutationCache, optionsRef.current),\n          )\n          if (result.current !== nextResult) {\n            result.current = nextResult\n            notifyManager.schedule(onStoreChange)\n          }\n        }),\n      [mutationCache],\n    ),\n    () => result.current,\n  )!\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,cACd,SACA,aACQ;CACR,MAAM,SAASA,4BAAAA,eAAe,WAAW;CACzC,OAAO,iBACL,EAAE,SAAS;EAAE,GAAG;EAAS,QAAQ;CAAU,EAAE,GAC7C,MACF,CAAC,CAAC;AACJ;AAsBA,SAAS,UAKP,eACA,SACgB;CAChB,OAAO,cACJ,QAAQ,QAAQ,OAAO,CAAC,CACxB,KACE,aACE,QAAQ,SACL,QAAQ,OAAO,QAAqB,IACpC,SAAS,KACjB;AACJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgB,iBAKd,UAAoD,CAAC,GACrD,aACgB;CAChB,MAAM,gBAAgBA,4BAAAA,eAAe,WAAW,CAAC,CAAC,iBAAiB;CACnE,MAAM,cAAA,GAAaC,aAAAA,OAAAA,CAAO,OAAO;CACjC,MAAM,UAAA,GAASA,aAAAA,OAAAA,CAAuB,IAAI;CAC1C,IAAI,OAAO,YAAY,MACrB,OAAO,UAAU,UAAU,eAAe,OAAO;CAGnD,CAAA,GAAA,aAAA,UAAA,OAAgB;EACd,WAAW,UAAU;CACvB,CAAC;CAED,OAAOC,cAAAA,sBAAAA,GACLC,aAAAA,YAAAA,EACG,kBACC,cAAc,gBAAgB;EAC5B,MAAM,cAAA,GAAaC,qBAAAA,iBAAAA,CACjB,OAAO,SACP,UAAU,eAAe,WAAW,OAAO,CAC7C;EACA,IAAI,OAAO,YAAY,YAAY;GACjC,OAAO,UAAU;GACjB,qBAAA,cAAc,SAAS,aAAa;EACtC;CACF,CAAC,GACH,CAAC,aAAa,CAChB,SACM,OAAO,OACf;AACF"}

package/build/legacy/useMutationState.d.cts

@@ -1,11 +1,85 @@
 import { Mutation, MutationFilters, MutationState, QueryClient } from "@tanstack/query-core";
 //#region src/useMutationState.d.ts
+/**
+ * `useIsMutating` is an optional hook that returns the `number` of mutations that your application is fetching
+ * (useful for app-wide loading indicators).
+ *
+ * @param filters - The {@link MutationFilters} to narrow down the matched mutations.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns Will be the `number` of the mutations that your application is currently fetching.
+ *
+ * @example
+ * ```tsx
+ * import { useIsMutating } from '@tanstack/preact-query'
+ *
+ * // How many mutations are fetching?
+ * const isMutating = useIsMutating()
+ * // How many mutations matching the posts prefix are fetching?
+ * const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
+ * ```
+ */
 declare function useIsMutating(filters?: MutationFilters, queryClient?: QueryClient): number;
 type MutationTypeFromResult<TResult> = [TResult] extends [MutationState<infer TData, infer TError, infer TVariables, infer TOnMutateResult>] ? Mutation<TData, TError, TVariables, TOnMutateResult> : Mutation;
 type MutationStateOptions<TResult = MutationState, TMutation extends Mutation<any, any, any, any> = MutationTypeFromResult<TResult>> = {
   filters?: MutationFilters;
   select?: (mutation: TMutation) => TResult;
 };
+/**
+ * `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
+ * `filters` ({@link MutationFilters}) to narrow down your mutations, and `select` to transform the mutation
+ * state.
+ *
+ * @param options - The `filters` to narrow down matched mutations, and an optional `select` to transform the
+ * mutation state.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns Will be an Array of whatever `select` returns for each matching mutation.
+ *
+ * @example
+ * Get all variables of all running mutations:
+ * ```tsx
+ * import { useMutationState } from '@tanstack/preact-query'
+ *
+ * const variables = useMutationState({
+ *   filters: { status: 'pending' },
+ *   select: (mutation) => mutation.state.variables,
+ * })
+ * ```
+ *
+ * @example
+ * Get all data for specific mutations via the `mutationKey`:
+ * ```tsx
+ * import { useMutation, useMutationState } from '@tanstack/preact-query'
+ *
+ * const mutationKey = ['posts']
+ *
+ * // Some mutation that we want to get the state for
+ * const mutation = useMutation({
+ *   mutationKey,
+ *   mutationFn: createPosts,
+ * })
+ *
+ * const data = useMutationState({
+ *   // this mutation key needs to match the mutation key of the given mutation (see above)
+ *   filters: { mutationKey },
+ *   select: (mutation) => mutation.state.data,
+ * })
+ * ```
+ *
+ * @example
+ * Access the latest mutation data via the `mutationKey`. Each invocation of `mutate` adds a new entry to the
+ * mutation cache for `gcTime` milliseconds — check the last item that `useMutationState` returns to get the
+ * latest invocation:
+ * ```tsx
+ * const data = useMutationState({
+ *   filters: { mutationKey: ['posts'] },
+ *   select: (mutation) => mutation.state.data,
+ * })
+ *
+ * const latest = data[data.length - 1]
+ * ```
+ */
 declare function useMutationState<TResult = MutationState, TMutation extends Mutation<any, any, any, any> = MutationTypeFromResult<TResult>>(options?: MutationStateOptions<TResult, TMutation>, queryClient?: QueryClient): Array<TResult>;
 //#endregion
 export { useIsMutating, useMutationState };

package/build/legacy/useMutationState.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"useMutationState.d.cts","names":[],"sources":["../../src/useMutationState.ts"],"mappings":";;iBAagB,cACd,UAAU,iBACV,cAAc;KASX,uBAAuB,YAAY,kBACtC,oBACQ,aACA,cACA,kBACA,oBAGN,SAAS,OAAO,QAAQ,YAAY,mBACpC;KAEC,qBACH,UAAU,eACV,kBAAkB,+BAChB,uBAAuB;EAEzB,UAAU;EACV,UAAU,UAAU,cAAc;;iBAqBpB,iBACd,UAAU,eACV,kBAAkB,+BAChB,uBAAuB,UAEzB,UAAS,qBAAqB,SAAS,YACvC,cAAc,cACb,MAAM"}
+{"version":3,"file":"useMutationState.d.cts","names":[],"sources":["../../src/useMutationState.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;iBAgCgB,cACd,UAAU,iBACV,cAAc;KASX,uBAAuB,YAAY,kBACtC,oBACQ,aACA,cACA,kBACA,oBAGN,SAAS,OAAO,QAAQ,YAAY,mBACpC;KAEC,qBACH,UAAU,eACV,kBAAkB,+BAChB,uBAAuB;EAEzB,UAAU;EACV,UAAU,UAAU,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4EpB,iBACd,UAAU,eACV,kBAAkB,+BAChB,uBAAuB,UAEzB,UAAS,qBAAqB,SAAS,YACvC,cAAc,cACb,MAAM"}

package/build/legacy/useMutationState.d.ts

@@ -1,11 +1,85 @@
 import { Mutation, MutationFilters, MutationState, QueryClient } from "@tanstack/query-core";
 //#region src/useMutationState.d.ts
+/**
+ * `useIsMutating` is an optional hook that returns the `number` of mutations that your application is fetching
+ * (useful for app-wide loading indicators).
+ *
+ * @param filters - The {@link MutationFilters} to narrow down the matched mutations.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns Will be the `number` of the mutations that your application is currently fetching.
+ *
+ * @example
+ * ```tsx
+ * import { useIsMutating } from '@tanstack/preact-query'
+ *
+ * // How many mutations are fetching?
+ * const isMutating = useIsMutating()
+ * // How many mutations matching the posts prefix are fetching?
+ * const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
+ * ```
+ */
 declare function useIsMutating(filters?: MutationFilters, queryClient?: QueryClient): number;
 type MutationTypeFromResult<TResult> = [TResult] extends [MutationState<infer TData, infer TError, infer TVariables, infer TOnMutateResult>] ? Mutation<TData, TError, TVariables, TOnMutateResult> : Mutation;
 type MutationStateOptions<TResult = MutationState, TMutation extends Mutation<any, any, any, any> = MutationTypeFromResult<TResult>> = {
   filters?: MutationFilters;
   select?: (mutation: TMutation) => TResult;
 };
+/**
+ * `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
+ * `filters` ({@link MutationFilters}) to narrow down your mutations, and `select` to transform the mutation
+ * state.
+ *
+ * @param options - The `filters` to narrow down matched mutations, and an optional `select` to transform the
+ * mutation state.
+ * @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+ * be used.
+ * @returns Will be an Array of whatever `select` returns for each matching mutation.
+ *
+ * @example
+ * Get all variables of all running mutations:
+ * ```tsx
+ * import { useMutationState } from '@tanstack/preact-query'
+ *
+ * const variables = useMutationState({
+ *   filters: { status: 'pending' },
+ *   select: (mutation) => mutation.state.variables,
+ * })
+ * ```
+ *
+ * @example
+ * Get all data for specific mutations via the `mutationKey`:
+ * ```tsx
+ * import { useMutation, useMutationState } from '@tanstack/preact-query'
+ *
+ * const mutationKey = ['posts']
+ *
+ * // Some mutation that we want to get the state for
+ * const mutation = useMutation({
+ *   mutationKey,
+ *   mutationFn: createPosts,
+ * })
+ *
+ * const data = useMutationState({
+ *   // this mutation key needs to match the mutation key of the given mutation (see above)
+ *   filters: { mutationKey },
+ *   select: (mutation) => mutation.state.data,
+ * })
+ * ```
+ *
+ * @example
+ * Access the latest mutation data via the `mutationKey`. Each invocation of `mutate` adds a new entry to the
+ * mutation cache for `gcTime` milliseconds — check the last item that `useMutationState` returns to get the
+ * latest invocation:
+ * ```tsx
+ * const data = useMutationState({
+ *   filters: { mutationKey: ['posts'] },
+ *   select: (mutation) => mutation.state.data,
+ * })
+ *
+ * const latest = data[data.length - 1]
+ * ```
+ */
 declare function useMutationState<TResult = MutationState, TMutation extends Mutation<any, any, any, any> = MutationTypeFromResult<TResult>>(options?: MutationStateOptions<TResult, TMutation>, queryClient?: QueryClient): Array<TResult>;
 //#endregion
 export { useIsMutating, useMutationState };

package/build/legacy/useMutationState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useMutationState.d.ts","names":[],"sources":["../../src/useMutationState.ts"],"mappings":";;iBAagB,cACd,UAAU,iBACV,cAAc;KASX,uBAAuB,YAAY,kBACtC,oBACQ,aACA,cACA,kBACA,oBAGN,SAAS,OAAO,QAAQ,YAAY,mBACpC;KAEC,qBACH,UAAU,eACV,kBAAkB,+BAChB,uBAAuB;EAEzB,UAAU;EACV,UAAU,UAAU,cAAc;;iBAqBpB,iBACd,UAAU,eACV,kBAAkB,+BAChB,uBAAuB,UAEzB,UAAS,qBAAqB,SAAS,YACvC,cAAc,cACb,MAAM"}
+{"version":3,"file":"useMutationState.d.ts","names":[],"sources":["../../src/useMutationState.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;iBAgCgB,cACd,UAAU,iBACV,cAAc;KASX,uBAAuB,YAAY,kBACtC,oBACQ,aACA,cACA,kBACA,oBAGN,SAAS,OAAO,QAAQ,YAAY,mBACpC;KAEC,qBACH,UAAU,eACV,kBAAkB,+BAChB,uBAAuB;EAEzB,UAAU;EACV,UAAU,UAAU,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4EpB,iBACd,UAAU,eACV,kBAAkB,+BAChB,uBAAuB,UAEzB,UAAS,qBAAqB,SAAS,YACvC,cAAc,cACb,MAAM"}

package/build/legacy/useMutationState.js

@@ -3,6 +3,25 @@ import { useSyncExternalStore } from "./utils.js";
 import { notifyManager, replaceEqualDeep } from "@tanstack/query-core";
 import { useCallback, useEffect, useRef } from "preact/hooks";
 //#region src/useMutationState.ts
+/**
+* `useIsMutating` is an optional hook that returns the `number` of mutations that your application is fetching
+* (useful for app-wide loading indicators).
+*
+* @param filters - The {@link MutationFilters} to narrow down the matched mutations.
+* @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+* be used.
+* @returns Will be the `number` of the mutations that your application is currently fetching.
+*
+* @example
+* ```tsx
+* import { useIsMutating } from '@tanstack/preact-query'
+*
+* // How many mutations are fetching?
+* const isMutating = useIsMutating()
+* // How many mutations matching the posts prefix are fetching?
+* const isMutatingPosts = useIsMutating({ mutationKey: ['posts'] })
+* ```
+*/
 function useIsMutating(filters, queryClient) {
 	const client = useQueryClient(queryClient);
 	return useMutationState({ filters: {
@@ -13,6 +32,61 @@ function useIsMutating(filters, queryClient) {
 function getResult(mutationCache, options) {
 	return mutationCache.findAll(options.filters).map((mutation) => options.select ? options.select(mutation) : mutation.state);
 }
+/**
+* `useMutationState` is a hook that gives you access to all mutations in the `MutationCache`. You can pass
+* `filters` ({@link MutationFilters}) to narrow down your mutations, and `select` to transform the mutation
+* state.
+*
+* @param options - The `filters` to narrow down matched mutations, and an optional `select` to transform the
+* mutation state.
+* @param queryClient - Use this to use a custom `QueryClient`. Otherwise, the one from the nearest context will
+* be used.
+* @returns Will be an Array of whatever `select` returns for each matching mutation.
+*
+* @example
+* Get all variables of all running mutations:
+* ```tsx
+* import { useMutationState } from '@tanstack/preact-query'
+*
+* const variables = useMutationState({
+*   filters: { status: 'pending' },
+*   select: (mutation) => mutation.state.variables,
+* })
+* ```
+*
+* @example
+* Get all data for specific mutations via the `mutationKey`:
+* ```tsx
+* import { useMutation, useMutationState } from '@tanstack/preact-query'
+*
+* const mutationKey = ['posts']
+*
+* // Some mutation that we want to get the state for
+* const mutation = useMutation({
+*   mutationKey,
+*   mutationFn: createPosts,
+* })
+*
+* const data = useMutationState({
+*   // this mutation key needs to match the mutation key of the given mutation (see above)
+*   filters: { mutationKey },
+*   select: (mutation) => mutation.state.data,
+* })
+* ```
+*
+* @example
+* Access the latest mutation data via the `mutationKey`. Each invocation of `mutate` adds a new entry to the
+* mutation cache for `gcTime` milliseconds — check the last item that `useMutationState` returns to get the
+* latest invocation:
+* ```tsx
+* const data = useMutationState({
+*   filters: { mutationKey: ['posts'] },
+*   select: (mutation) => mutation.state.data,
+* })
+*
+* const latest = data[data.length - 1]
+* ```
+*/
 function useMutationState(options = {}, queryClient) {
 	const mutationCache = useQueryClient(queryClient).getMutationCache();
 	const optionsRef = useRef(options);