feat(query-core): pass mutation meta as optional second argument to mutationFn

[solastley]

Related discussion here. Below is copied from there:

I wanted to take a moment and make a case for making meta accessible in mutationFn!

In my mind, the meta field is a very convenient way to ensure access to shared context needed for all queries and/or mutations in an app. For example, in our web app, we have an API client which is instantiated once on load and then made accessible anywhere in the app through React Context. This is pretty convenient, but this API client is needed for every query or mutation we ever make that hits our API (which is 99% of them). So it is actually still pretty inconvenient that any time we ever want to use useQuery or useMutation, we also need to call useApiClient (our custom hook) to pass the API client into the query/mutation function.

When I read the docs for the meta option, and how we can globally override the type, I thought it seemed like the perfect way to implement a lightweight wrapper around useQuery and useMutation to always make the API client accessible in query/mutation functions by default. For example:

export function useApiQuery<
  TQueryFnData = unknown,
  TError = DefaultError,
  TData = TQueryFnData,
  TQueryKey extends QueryKey = QueryKey,
>(
  options: UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
  queryClient?: QueryClient,
) {
  const apiClient = useApiClient();

  return useQuery<TQueryFnData, TError, TData, TQueryKey>(
    {
      ...options,
      meta: {
        ...options.meta,
        apiClient,
      },
    },
    queryClient,
  );
}

Now instead of doing this every time we need to execute an API query:

const apiClient = useApiClient();

const { data } = useQuery({
  queryKey: ['someKey'],
  queryFn: () => getSomeData(apiClient),
});

We can simply do this:

const { data } = useApiQuery({
  queryKey: ['someKey'],
  queryFn: ({ meta }) => getSomeData(meta!.apiClient),
});

Ideally, we wouldn't have to assert that meta is defined either, but the benefit here outweighs that easily. We have hundreds, and will eventually have thousands, of these API queries in our app. So having this available in the queryFn saves writing a remarkable amount of boilerplate.

Much to my dismay, as I was implementing this, I realized that we do not get similar access to meta within the mutationFn used by useMutation. So we need to keep using the old pattern.

I wonder then if it would be reasonable to add meta or a similar context containing meta as a second argument to mutationFn. For us, it would be incredibly useful. I know that an authenticated API client accessible through context is a very common pattern in React apps, so I imagine this would be useful to others as well.

Let me know what you think!

[TkDodo]

we already have a much wider implementation here:

• feat(query-core): add MutationFunctionContext argument to mutateFn #9193