TanStack Query · Reference · all subjects

queryclient methods: data mutation

10 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

mutationOptions helper usage

The mutationOptions helper is used to share mutation options between multiple places. At runtime, it returns whatever is passed into it, but provides type inference and type safety when used with TypeScript. You can define all possible options for a mutation in one place and get type safety across all usages.

mutationOptions example with updatePost

The mutationOptions helper accepts an object with properties including mutationFn (a function that takes data and returns a Promise), mutationKey (an array identifying the mutation), and onSuccess (a callback that receives the successful result). In the example, mutationFn takes a Post object, and the onSuccess callback receives newPost typed as Post, then calls queryClient.setQueryData to update related query data.

queryClient.setQueryData

queryClient.setQueryData is a synchronous function that immediately updates a query's cached data. If the query does not exist, it will be created. If the query is not utilized by a query hook within the default gcTime (defaults to 5 minutes if not configured), the query will be garbage collected. Takes queryKey and updater parameters. The updater can be a value or a function receiving oldData and returning new data. If updater returns undefined, the query data is not updated. Updates must be performed immutably - do not mutate oldData directly.

queryClient.setQueryData updater function behavior

When using setQueryData with an updater function, if the function returns undefined, the query data will not be updated. If the function receives undefined as input and returns undefined, this bails out of the update and does not create a new cache entry.

queryClient.setQueriesData

queryClient.setQueriesData is a synchronous function that updates cached data of multiple queries by using a filter function or partially matching the query key. Only existing queries are updated - no new cache entries are created. Calls setQueryData internally for each matching query. Takes filters (QueryFilters) and updater parameters.

queryClient.removeQueries

queryClient.removeQueries removes queries from the cache based on their query keys or other functionally accessible properties. Takes filters (QueryFilters) parameter. Does not return anything. Unlike invalidateQueries or refetchQueries, removeQueries removes matching queries from the cache instead of refetching them.

queryClient.resetQueries

queryClient.resetQueries resets queries in the cache to their initial state based on query keys or other properties. Takes filters (QueryFilters) and ResetOptions. Notifies subscribers (unlike clear which removes all subscribers) and resets query to pre-loaded state (unlike invalidateQueries). If query has initialData, data resets to that. If query is active, it will be refetched. ResetOptions include throwOnError (defaults to false) and cancelRefetch (defaults to true). Returns a promise that resolves when all active queries have been refetched.

queryClient.clear

queryClient.clear clears all connected caches (both query cache and mutation cache). Does not return anything.

Clear all queries and mutations from cache

To clear all queries and mutations from the cache, call queryClient.clear() which clears all connected caches.

queryClient.resumePausedMutations

queryClient.resumePausedMutations can be used to resume mutations that have been paused because there was no network connection.

Give your agent this brain