feat(react-query): add support for mutations to createTRPCQueryUtils and improve offline support

[simonecervini]

Closes #5800

💡 Motivation

This PR is largely motivated by the need to improve offline support in tRPC. According to my research, there were two main missing pieces:

• a type-safe way to call utils.anyRouter.anyMutationProcedure.setMutationDefaults()
• a type-safe way to call the canonical mutation function (the one defined implicitly by tRPC) when setting mutationFn with setMutationDefaults()

I decided to go further and implement all the missing QueryClient methods useful to interact with mutations, and I added specific tests for offline scenarios.

🎯 Changes

This PR adds to createTRPCQueryUtils all the utility functions for managing mutations.

There are 5 mutation methods in the QueryClient class:

• isMutating
• getMutationDefaults
• setMutationDefaults
• getMutationCache
• resumePausedMutations

The last two methods, getMutationCache and resumePausedMutations, don’t accepts arguments and can be called directly from the QueryClient instance, so we don’t need to implement them in createTRPCQueryUtils.

✅ Checklist

• I have followed the steps listed in the Contributing guide.
• If necessary, I have added documentation related to the changes made.
• I have added or updated the tests related to the changes made.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
www	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jun 26, 2024 9:58am

[vercel]

@simonecervini is attempting to deploy a commit to the trpc Team on Vercel.

A member of the Team first needs to authorize it.

[simonecervini]

Not sure about this type. string[][] should be better than MutationKey from TanStack Query, which is defined as ReadonlyArray<unknown>. But I am not sure what the relationship between this type and TRPCQueryKey should be, assuming there should be a relationship

[simonecervini]

Probably [string[]] is a better choice here (= TRPCQueryKey without the optional second value of the tuple)

We can also define it as [TRPCQueryKey[0]] or define a new alias

[simonecervini]

Updated in 790ec8e

[juliusmarminge]

Hey, appreciate the time you put into this PR

However, I struggle to find the value added with this. What is trpc specific here? The wrappers you added here doesn't use the procedure input/output in any way afaict, so why can't you just use the queryClient.isMutating() or similar directly here?

[simonecervini]

Hey @juliusmarminge

isMutating() is arguably the most useless function added. I included it just to make the API complete, and you’re right about that.

However, getMutationDefaults and setMutationDefaults actually use the procedure input/output, and the tRPC wrapper around React Query solves multiple problems. For example:

1. With this implementation, you cannot call mutation utility functions for query procedures or query utility functions for mutation procedures. Without tRPC, you can call queryClient.getMutationDefaults(['post.list']) without getting type errors, which is very problematic in an offline-first app with dozens of setMutationDefaults calls outside React for almost every mutation procedure.

2. There’s not an easy way, without tRPC-specific wrappers, to call the canonical mutation function when setting the default mutation function (required for offline persistence). Instead of:

utils.post.create.setMutationDefaults(({canonicalMutationFn}) => ({ mutationFn: canonicalMutationFn }))

you should need to write something like this:

const mutationKey = getQueryKey(procedure)[0];
queryClient.setMutationDefaults(mutationKey, {
  mutationFn: (input: unknown) =>
    trpcClient.mutation(mutationKey.join("."), { input }),
});

And you don't get errors if procedure isn't a mutation procedure.

3. All the callbacks are type-safe: