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]

Well, but it does https://www.typescriptlang.org/play/?#code/JYWwDg9gTgLgBAbzgRwK4FMoE8DyYbAQB2AzgDRyonoCKG2cAvnAGZQQhwDkAAjAIakBAYwDWAeijp+wmAFo0mLFwBQKlqiKzCROCQ616ufDpIAKYETCoYALjhFUIAEaYAlIhVw4UmKii6ith4BMTmCF7eKEYA0uhY9gDaXAAW6AA26RBcFJbWMAC6ZJHeQVgAYkT2Zh4AvAB8nlFRvv66AArsIMDUAHRS+ukAbugWVja9MBAAyjBQlgDmNW4lTJGMK4xqMFhg6HAAggAmR8ChRPzpIaZwtXA43TAAPJEASuh+AQAqu+hPO3sICw9AY6EprmF6sVvAAiMpxLAwuAAHzgcKMlRhKnqAG41Cp0AAPSCwOBHdAsfiodLwDRac6UajTUFGMyRPI2eyOFyYaFwfgnM46S4Q0gAfnsx1O5xFJjCKg8EW8wjC8AgctItxBIEM4I15g5MDceMirQCjN12DMSqivTt6vO5FWdt6Aulwqu+r5GzxWxUVHQzJ1YKtAEYAAwUG3UdLoWTVI78AR1RqJgQqDZAA

You can see that 'select' function argument is inferred from the queryFn here and I don't need to type it 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

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