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

[TkDodo]

no, it doesn't really work, because you can't transform data in select. The signature is fixed to (string) => string. If you try to return anything but a string, it won't work: see this reproduction.

The idea is really that with options, you don't need a custom hook that accepts dynamic options. Why would I pass select to useSomeQuery if I could also just do:

const { data } = useQuery({
  ...someQueryOptions(10),
  select: (x) => Number(x)
})

which will work perfectly fine ...

[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!

[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