Mutation version of queryOptions().

[nix6839]

It would be nice to have a mutation version of queryOptions().

[TkDodo]

what would you need it for? The main reason for queryOptions is to have a way to share options between useQuery, useQueries and things like queryClient.prefetchQuery. There's no equivalent for mutations where this would be needed

[TkDodo]

you can execute a mutation from the queryClient like so (we do this in tests):

query/packages/query-core/src/tests/utils.ts

Lines 35 to 44 in 5d29f8f

	export const executeMutation = <TVariables>(
	queryClient: QueryClient,
	options: MutationOptions<any, any, TVariables, any>,
	variables: TVariables,
	) => {
	return queryClient
	.getMutationCache()
	.build(queryClient, options)
	.execute(variables)
	}

[chrisirhc]

That's what I needed. Thank you!

I thought that's what the original author was asking for but perhaps I'm wrong. This answers the question I had.

[dhulme]

We use queryOptions to help calling the same query in different components, and keep the API calling logic separate to the component. A mutationOptions function would allow us to do this same sharing/separation for mutations. Do you have any thoughts on this @TkDodo?

[TkDodo]

I don't think it's really necessary because you can just write custom mutation hooks? The advantage of queryOptions is that you can share them between hooks and imperative methods, like prefetchQuery in a type-safe way. At runtime, it doesn't do anything.

and keep the API calling logic separate to the component.

imo that's what a request layer, let's call it myApi, is for. It can abstract axios or fetch in a type-safe way so that you can call them in hooks:

const useUpdateUser = () => {
  const queryClient = useQueryClient()
 
  return useMutation({
    mutationFn: myApi.updateUser,
    onSuccess: (_, id) => {
      return queryClient.invalidateQueries(userQuery(id))
    }
  })
}

What's the advantage of extracting that logic to outside of hooks? How would you get access to the queryClient outside of hooks?

[dhulme]

Thank you for your suggestions. We had custom hooks for queries/mutations before v5, but the section in the docs on the new queryOptions led us to start moving away from custom hooks, but I see now they can both be used together.

I think it would be really useful to have a section in the docs of recommended practices for making queries/mutations reusable?

[smashercosmo]

I have another use case for mutationOptions. This will make it easier to create custom hooks. WDYT @TkDodo ?

function someMutationOptions() {
  return mutationOptions({
    mutationFn: ...
  });
}

type AdditionalOptions = Omit<
  ReturnType<typeof someMutationOptions>,
  "mutationFn"
>;

export default function useSomeMutation(
  additionalOptions?: AdditionalOptions
) {
  const options = someMutationOptions();

  return useMutation({
    ...options,
    ...additionalOptions,
  });
}

In this case additionalOptions type will be inferred from the mutationFn and we won't have to type options object manually

[smashercosmo]

I get the idea, but if I remember correctly the general recommendation by react-query team was that you should create custom hooks which increases code readability. So instead of

 const { data } = useQuery({
  ...getTodosQueryOptions(),
  ...additionalOptions
})

you should have

 const { data } = useGetTodosQuery(additionalOptions)

[TkDodo]

that recommendation has likely changed with queryOptions. I mean, you can still make custom hooks like before, but the recommendation about building custom hooks that accept arbitrary generic options was always: don't do it. So I think this is fine:

const useGetTodosQuery: ({ enabled }: { enabled: boolean}) => {
  return useQuery({ ...getTodosQueryOptions(), enabled })
}

even though I would also probably inline it. But having a whole options object be typed with QueryOptions and 4 type parameters is just not worth it and never was.

[hossamAlhamidi]

what if i wanted to write a global mutation hook that does exactly what useMutation do , it serves as a wrapper so if i wanted to migrate to a new version for example it would be easier , write now , im gonna lose auto complete functionality.
with queryOptions replacing UseQueryOptoins i can still do that
const { data, isLoading } = useGlobalQuery({ queryKey: ["todos"], queryFn: () => axiosInstance.get("https://jsonplaceholder.typicode.com/todos"), ...queryOptions({ staleTime: 1000 * 60 * 5 }) });
but on mutation i can't, so i think i can be helpful

[junwen-k]

Hi @TkDodo, I’d like to clarify a few things and get your thoughts on the following:

1. Is the current recommendation to use queryOptions directly with useQuery, useSuspenseQuery, etc. the recommended approach now, with useXQuery hooks no longer needed / encouraged?

2. What if I need a custom useXMutation hook with built-in invalidateQueries, while still allowing users to override specific options like onSuccess to display a toast, for example? Would you recommend manually typing the onSuccess callback? This seems like a common scenario, as seen in bulletproof-react’s delete comment example. Similarly, this example demonstrates useDiscussions with generic options, which I understand is something you generally advise against. Could you share your thoughts on this approach?

It looks like this is all that's needed (taken from bulletproof-react) to support a fully type-safe and flexible hook with queryConfig and mutationConfig overrides:

// src/lib/react-query.ts
export type ApiFnReturnType<FnType extends (...args: any) => Promise<any>> =
  Awaited<ReturnType<FnType>>;

export type QueryConfig<T extends (...args: any[]) => any> = Omit<
  ReturnType<T>,
  'queryKey' | 'queryFn'
>;

export type MutationConfig<
  MutationFnType extends (...args: any) => Promise<any>,
> = UseMutationOptions<
  ApiFnReturnType<MutationFnType>,
  Error,
  Parameters<MutationFnType>[0]
>;

// src/features/discussions/apis/update-discussion.ts
type UseUpdateDiscussionOptions = {
  mutationConfig?: MutationConfig<typeof updateDiscussion>;
};

export const useUpdateDiscussion = ({
  mutationConfig,
}: UseUpdateDiscussionOptions = {}) => {
  const queryClient = useQueryClient();

  const { onSuccess, ...restConfig } = mutationConfig || {};

  return useMutation({
    onSuccess: (data, ...args) => {
      queryClient.refetchQueries({
        queryKey: getDiscussionQueryOptions(data.id).queryKey,
      });
      onSuccess?.(data, ...args);
    },
    ...restConfig,
    mutationFn: updateDiscussion,
  });
};

// src/features/discussions/apis/get-discussion.ts
export const getDiscussionQueryOptions = (discussionId: string) => {
  return queryOptions({
    queryKey: ['discussions', discussionId],
    queryFn: () => getDiscussion({ discussionId }),
  });
};

type UseDiscussionOptions = {
  discussionId: string;
  queryConfig?: QueryConfig<typeof getDiscussionQueryOptions>;
};

export const useDiscussion = ({
  discussionId,
  queryConfig,
}: UseDiscussionOptions) => {
  return useQuery({
    ...getDiscussionQueryOptions(discussionId),
    ...queryConfig,
  });
};

3. I’ve seen recommendations against fully type-safe, generic hooks multiple times, like here and here. Is the main concern the complexity of getting generics typed correctly? I can see how this might not be worth the effort in many cases if not all options or flexibility are needed, but if the complexity can be managed easily, are there any other downsides?

Hi @smashercosmo, I’ve also created a TypeScript playground here which solves what you are trying to do initially. It shows how we can maintain type-safe defaults while allowing overrides like onSuccess.

Thank you for all the work you’ve put into this library!

[TkDodo]

Is the current recommendation to use queryOptions directly with useQuery, useSuspenseQuery, etc. the recommended approach now, with useXQuery hooks no longer needed / encouraged?

make queryOptions abstractions, and as long as your hook is just:

const useTodos = () => useQuery(todosOptions)

I don’t see a reason to make that extra abstraction. But sure, you can do it.

What if I need a custom useXMutation hook with built-in invalidateQueries, while still allowing users to override specific options like onSuccess to display a toast, for example?

Not necessary as showing toast messages should likely to go the callbacks of mutate. But sure you can just make your custom hook accept: onSuccess: () => void, which should be enough for most cases.

[DylanVann]

I'm working on an e-commerce app where we want to show a state for mutation in progress on a certain item in a users cart and using mutationOptions to narrow the type of options here could be useful:

import { updateItemQuantityMutationKey } from '@/shopify/updateItemQuantityMutationKey'
import { useQueryClient } from '@tanstack/react-query'

export const useIsModifyingLineItem = (id: string) => {
  const queryClient = useQueryClient()
  return (
    queryClient.isMutating({
      mutationKey: updateItemQuantityMutationKey,
      predicate: (options) => {
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        return Boolean(options.state.variables?.lines?.find((line: any) => line?.id === id))
      },
    }) > 0
  )
}

Although I think in this case I'm just going to hoist the state up slightly so I don't have to use this code. If I was able to narrow the type using something like mutationOptions I might have left it.

[andyto]

Tried the following and seems to work well for me.

import type { DefaultError } from "@tanstack/query-core";
import type { UseMutationOptions } from "@tanstack/react-query";

export function mutationOptions<
  TData = unknown,
  TError = DefaultError,
  TVariables = void,
  TContext = unknown,
>(
  options: UseMutationOptions<TData, TError, TVariables, TContext>,
): UseMutationOptions<TData, TError, TVariables, TContext> {
  return options;
}

[leognmotta]

thanks

[iicdii]

You can actually import DefaultError from @tanstack/react-query directly instead of query-core since react-query re-export core so that you don't need to add @tanstack/query-core as a dependency in your project.

- import type { DefaultError } from "@tanstack/query-core";
- import type { UseMutationOptions } from "@tanstack/react-query";
+ import type { DefaultError, UseMutationOptions } from "@tanstack/react-query";

Final code:

import type { DefaultError, UseMutationOptions } from "@tanstack/react-query";

export function mutationOptions<
  TData = unknown,
  TError = DefaultError,
  TVariables = void,
  TContext = unknown,
>(
  options: UseMutationOptions<TData, TError, TVariables, TContext>,
): UseMutationOptions<TData, TError, TVariables, TContext> {
  return options;
}

[sshmaxime]

Could we have an official implementation of queryOptions ? What's the blocker here ?

[TkDodo]

The “blocker” is still that I think it’s not needed. We added it for queries because the options need to be shared between various hooks and imperative functions. We can also leverage typings between queryKey and queryFn to make methods on the queryClient more type-safe. None of this is the case for mutations. There’s no reason to not just write a custom hook, and making this method available suggests otherwise.

[MlNl-PEKKA]

what would you need it for? The main reason for queryOptions is to have a way to share options between useQuery, useQueries and things like queryClient.prefetchQuery. There's no equivalent for mutations where this would be needed

I'd like this for useMutationState. I believe this hook currently needs the types to be manually passed.

[TkDodo]

Please show as TypeScript playground. I’d like to see where you need to pass type params to useMutationState.

[MlNl-PEKKA]

👋 Hello TkDodo!! Thank you for responding. Here's my implementation of the useMutationState hook.

https://stackblitz.com/edit/vitejs-vite-ltocdd8d?file=src%2FTodos%2Findex.tsx

I’m still unsure whether useMutationState or queryCache manipulation is the better approach for handling optimistic updates. Is useMutationState recommended for managing optimistic updates?

Regarding passing types to the useMutationState hook, the generic doesn't seem to yield a helpful result. Type-casting the variables from the select callback seems to be the only way out in the my case.

Anyway, I imagined if there did exist a mutationOptions function, it would behave similar to queryOptions, eliminating the need for type-casting within mutation related APIs. What are your thoughts on this?

[TkDodo]

eliminating the need for type-casting within mutation related APIs

this isn’t quite true. useMutationState can capture different mutations - the mutationKey is just a filter that isn’t required. You can say: give me all variables of all mutations that ever happened. There’s no way to type this automatically. Also, even if there is a mutationKey present on mutationOptions (which wouldn’t be guaranteed as it isn’t required), the filter you can pass to useMutationState matches mutations fuzzily. So with one key, you could match mutations of different shapes with different types of variables. That’s fundamentally different from queryOptions. For the same reason, we haven’t typed queryClient.getQueryCache.find(filters), because everything there is fuzzy. No way to guarantee that a specific shape will be returned.

Further, just the presence of a mutationOptions function would not magically “solve” this issue. We would need to tie the mutationKey to useMutationState via something like the DataTag symbol we do on queryOptions.

[MlNl-PEKKA]

I'm not saying that we "have to" tie this to useMutationState, but rather consider something that does "Exact" mutationKey matching, guaranteeing the shape of the variables. I would like to be able to observe mutations in a type-safe manner for a specific mutationKey. Maybe a hook or a method consuming the dataTagSymbol information, which provides access to all mutations that are exactly tied to that mutationKey and further provide filtering capabilities as options, using the inferred type.

Optional mutationKey does pose a challenge to this idea, and I agree that calling it mutationOptions might not be entirely accurate. However, I still believe it’s worth exploring how we can achieve this in a type-safe way, especially since something similar has already been done with queryKey and dataTagSymbol.

[shoooe]

I understand that it's not strictly needed but on the other hand I don't understand what the downsides of providing such a function are.

"Make an API that is difficult to use incorrectly" is a great guideline for designing API but only when there are dangers to misusing the API. What are the dangers of creating a mutationOption and passing it to useMutation instead of creating a custom hook directly?

This also doesn't seem that costly in terms of API surface that needs to be added and people clearly would expect it to exist in a symmetrical way to queryOptions.

Just my 2 cents. As always: thanks for your contributions to this great library.

Peace ✌️

[TkDodo]

okay someone please make a PR, just to end this discussion 😂