feat: Additional Router Level Tanstack Query Methods

[JonParton]

Describe the feature you'd like to request

ℹ️ Transferring here so the conversation isn't left on a completed PR

As requested by @TkDodo here currently we only expose the invalidate method on Routers from the tRPC Proxy (Implemented in #2711); However Tanstack-Query exposes many other fuzzy key match methods which are below:

---

• invalidateQueries✅
• getQueriesData
  • Returns the data for only queries that are currently in the Tanstack Query cache ...not trigger TRPC calls
• refetchQueries
  • TS types could be interesting ... but I think possible.
• cancelQueries
• removeQueries
• resetQueries
• getQueryDefaults
• setQueryDefaults
• setQueriesData
  • For the "updater" function to be trueley type safe when operating on multiple queries we would need to know which particular key the updater was currently working on.... I know this was on me to go look at adding to the tanstack API but I haven't managed to prioritise.
• getMutationDefaults
• setMutationDefaults

---

@TkDodo Would like to see if we can implement the other functionality as currently there is no way of doing these on our existing API.

ℹ️ Note: We have already discounted adding the Root level functionality here with input from @juliusmarminge on the current approach.

Describe the solution you'd like to see

When interacting with the tRPC utils proxy (useContext) on the client side these methods should be exposed at any router level for use:

For Exmaple:

import { trpc } from '../utils/trpc';

function MyComponent() {

  const utils = trpc.useContext()

  utils.post.setQueryDefaults({ staleTime: Infinity }) // Where post is a router containing multiple, queries, mutations or sub routers

  utils.post.setMutationDefaults({ /* ...Mutation Default here such as a default onSuccess function */})

  // Defaults set will then apply to future instantiated hooks. 

  const { data: posts } = trpc.post.getAll.useQuery()
  const { data: postSeries } = trpc.post.getPostSeries.useQuery()
  const appPost = trpc.post.add.useMutation()

  utils.post.cancelQueries() // Cancelles both post queries above
    
})

  // [...]
}

Obviously there is more research in to how each of these methods would interact and a few differences in the API we would want to expose (Such as ommiting a few keys to limit the ability to set the mutationFn for MutationDefaults etc) but from a brief look they all seem to have value although some are nuanced use cases.

Describe alternate solutions

1. It looks like we have started to consider some overrides defined on the createTRPCReact function ... Some of these may fit in here too such as the mutation defaults? Although I guess we would want to be specific to a particular router rather then across the query client! ... being able to define them multiple times in code rather then on initialisation may also allow some greater flexibility but not 100% sure on the consequences of doing so in Tanstack Query etc ...
   • Thoughts @TkDodo ?

---

2. Make people just construct these functions by using the internally generated QueryKey and using the vanilla Tanstack Query useQueryClient() api. However, we miss the opportunity here to handle the QueryKey generation for developers and also to provide type safety around the ones that return values / accept inputs

To help with this we could add a .getQueryKey(input) to our utils object... A kind of typesafe query key builder that could be called at a router or procedure level and used with the vanilla Tanstack-Query queryClient methods

const queryClient = useQueryClient()
queryClient.removeQueries(utils.post.getById.getQueryKey()) // QueryKey => [["post","getById"]]
queryClient.removeQueries(utils.post.getById.getQueryKey({userId:10})) // QueryKey => [["post","getById"],{userId:10}]
queryClient.setQueryDefaults(utils.post.getQueryKey(), { staleTime: Infinity }) // [["post"]]

Plausibly with this exposed you could also then infer the correct types of any returns in userland using the provided tRPC infer methods ... but that could get tricky for some!

---

3. Only implement a sub set of the above requested methods!

---

4. A mixture of the above 🤷

Additional information

Before anyone puts any effort into this I think it would be worth a bit of input from the A Team (@KATT , @sachinraja , @juliusmarminge etc) on if we think this addition to the API surface is a good idea and a finger in air on if we are happy to add the extra types that may effect TS Performance (🤷 ... couldn't see an effect from adding invalidate() after the optimisations that have been done recently!)

👨‍👧‍👦 Contributing

• 🙋‍♂️ Yes, I'd be down to file a PR implementing this feature! (Although it may be a slow burn if I implement!)

[JonParton]

I've added an extension to "Alternate Solutions" 2. - Basically a half way house of aiding use of the Vanilla queryClient methods.

Not sure if this is the right answer here but I actually have a use for this queryKey Builder else where so it may actually open other use cases too without additional API surface from tRPC.

Note - It would not be 100% perfect as there are some thing we don't want people doing with the vanilla query client such as overiding the mutateFn etc so it may invite some wierd userland mistakes!

---

The other use case for the query key builder:

I'm doing something maybe a little out of the normal usage and making it so a server side event (A received web hook or a Worker Task completing etc) can ask clients to invalidate certain queries if they have them.

This is useful for if the server knows something will have changed for the client and so it wants to ask them to update without them having to do lots of polling etc (I've implemented this via a notification system on the client that polls a tRPC InifiniteQuery for new notifications, keeps a record of ones it's already seen and processes new notifications)

At the moment to make an invalidate request specific to a router or procedure I have to make a JSON string of the key I want to pass and then use it on the vanialla client like:

if (notification.invalidateQueries) {
  queryClient.invalidateQueries(
    JSON.parse(notification.invalidateQueryKeyJSON) // JSON Key could be "[["post","getById"],{"userId":10}]"
  )
}

However, on the server side that produces the notification it is totally un type safe and I am just manually creating the Key ... It would be nice to import the server types and have this be type safe / automatically renamed when I do a refactor etc. (The Notification generators will be in the same Monorepo 💪)

[TkDodo]

queryClient.setQueryDefaults(utils.post.getQueryKey(), { staleTime: Infinity }) // [["post"]]

for setting defaults, this would work pretty well. But for calling methods like refetchQueries or resetQueries, it would probably be better to expose separate util functions like we have now for invalidation.

If we don't want to replicate / expose all the functions of the queryClient via a dedicated method, I think getQueryKey() work well as an escape hatch.

---

a related thought and actually where my request was initially coming from: I have some endpoints that need a dedicated staleTime (yes, infinity), because it's information we want to get once that doesn't change. I currently do:

const instance = trpc.instance.get.useQuery(undefined, { staleTime: Number.POSITIVE_INFINITY })

This is a bit ugly, but fine, problem is if we use this in multiple places, I need to make a custom hook abstraction wrapper around trpc:

const useInstance = () => trpc.instance.get.useQuery(undefined, { staleTime: Number.POSITIVE_INFINITY })

again, not a big deal, but we have to let developers know that they probably shouldn't just use trpc directly then, and I don't really like the extra layer of indirection.

So maybe it would be possible to define those things somehow on the router level? I'm thinking specifically about cacheTime / staleTime, because these are usually resource specific settings that we could easily set "on the server" where we define the router, and then the defaults would be set on the frontend directly via that?

Of course, the server knows nothing about react / react-query so maybe that isn't doable - I just thought it would be nice to define on the router directly how long my resource will be fresh):

// not real code

export const instanceRouter = t.router({
    get: t.procedure.query(({ ctx }) => "fetch some instance things"
}, {
    staleTime: Infinity
    cacheTime: Infinity
})

[TkDodo]

@JonParton the more I think about it (and use trpc v10), the more I feel the need to get access to the queryKey as an "escape hatch", even if the result is not typesafe. For things like queryClient.setQueryDefaults, this doesn't even matter, because the types are the same for all queries.

So I think it would be beneficial regardless of additional methods being added to trpc. I could create a separate feature request for that? What do you think?

[JonParton]

@JonParton the more I think about it (and use trpc v10), the more I feel the need to get access to the queryKey as an "escape hatch", even if the result is not typesafe. For things like queryClient.setQueryDefaults, this doesn't even matter, because the types are the same for all queries.

So I think it would be beneficial regardless of additional methods being added to trpc. I could create a separate feature request for that? What do you think?

Totally agree @TkDodo! I just haven't had time to put some effort on to it!

I was also considering where to put it, wierdly I have a use case where I want to use it not within the current react context (ie not client side) and so I was wondering if it should be a seperate utill similar to the type inference helpers that get instantiated with the AppRouter type, rather then off the trpc.useContext() object.

I think putting it as a seperate feature request will properly put it on the radar so please go ahead! 😊

[sjc5]

I'd love to have the equivalent of queryClient.clear() as well, for just wiping everything on log-out if you aren't doing a full page reload.

[JonParton]

I'd love to have the equivalent of queryClient.clear() as well, for just wiping everything on log-out if you aren't doing a full page reload.

For calls like this that effect the whole query cache etc it's still suggested to just use the @tansatck/react-query queryClient directly as you have said above!

import { useQueryClient } from '@tanstack/react-query';
function MyComponent() {
  const queryClient = useQueryClient();
  queryClient.clear()
}

This will still work with tRPC 🙂

[sjc5]

I'd love to have the equivalent of queryClient.clear() as well, for just wiping everything on log-out if you aren't doing a full page reload.

For calls like this that effect the whole query cache etc it's still suggested to just use the @tansatck/react-query queryClient directly as you have said above!

import { useQueryClient } from '@tanstack/react-query';
function MyComponent() {
  const queryClient = useQueryClient();
  queryClient.clear()
}

This will still work with tRPC 🙂

Yes, I realized that I was clearing the cache immediately before actually killing the session, when vice versa was needed (which lead me to believe it wasn't working with the vanilla queryClient). Sorry for the false alarm! Direct import of the queryClient is a perfectly acceptable solution.

[TkDodo]

I think putting it as a seperate feature request will properly put it on the radar so please go ahead! 😊

@JonParton separate feature request created here:

• feat: expose queryKey #3295

[KATT]

I'm going to close this and let people create individual feature requests for now. I think #3295 is a good step in a direction where it's more managable