@TanStack/Query array queryKeys

[digistaal]

Hi community,

I noticed that the queryKey that's being generated for the @TanStack/Query plugin is an array with one object as an entry. This object contains an id, baseUrl and some information about params. I was wondering why these generated queryKeys don't follow the best practise of the identifier of your query being spread out as an hierarchal array instead of an object. Currently because of this design, invalidation of the queries works a bit different than the package designed it to. Normally queries can be invalidated on a higher level by only providing the first queryKey array's entry and can specify a more specific query by supplying more entries of this queryKey.

See the @TanStack/Query docs and this blog regarding best practises for more information.

Really curious about the reasoning behind this, please let me know!

[mrlubos]

Hi @digistaal, does the query key design pose any challenge with invalidation?

The idea is you could invalidate on ANY level, but obviously it's not quite the same as the links you shared. A better starting point would be to look at issues you're facing and go from there?

[digistaal]

Sorry for the late reply, I just came back from my holiday. We are currently researching whether we can use query generation in a large organisation so we are mostly worried about the uniqueness of the query keys. With the current setup the uniqueness comes from the combination of baseUrl, operationId and path. We're working in a microservice architecture where the baseUrl will be the same for all these teams and operationId isn't guaranteed to be unique - multiple teams could implement a "getPost" method. Using the URL split on the / character would for example solve this issue. Is there any way we can hook into the queryKey generation so that we can alter this? Prepending a team name would also solve this issue already.

Besides that, the issue I see with invalidation in the current setup is that it's currently very easy to create hidden side effects. For example, invalidating the below queryKey would invalidate all models across the app with id "1", without you directly seeing this result. Having an array based query key would force you to scope the queryKey you want to invalidate and therefore wouldn't have any potential side effects.

Thanks for your help, I'm looking forward to your reply.

client.invalidateQueries({
  key: {
   path: {
    id: 1
   }
  }
});

[mrlubos]

Hi @digistaal, no worries! Are you able to link me to the "below queryKey?"

[digistaal]

@mrlubos Whoops.. Edited my message now 😄

[mrlubos]

Thanks! Okay I hear you on the query key hook. I'm curious though how does split on / solve the issue for you? Are you able to provide more query keys you'd generate if you had that ability?

On invalidation, my understanding is that the current pattern allows you to scope the query key. The issue you're concerned about is not being forced to do that? I'd be open to exploring how we can "force" scoping, but I don't think we'd want to blanket apply the forcing mechanism (eg. using the array structure) on everyone.

Beyond that, I'm curious which large company you're talking about! I have many many questions there, not related to this issue. Please contact me privately if you'd be willing to talk more

[digistaal]

Since a URL is always unique, splitting the path on / will always result in a hierarchal and unique array, whereas operationIds from OpenAPI don't guarantee uniqueness. Although as said, just being able to prepend a string to the query key array would also solve the issue already. I'm thinking of something like this where I'm able to prepend a custom value to the queryKey array, since the plugin does output an array, just with 1 entry.

generateQueryKeyFn: (queryKey: any[], options: Options) => {
  const someUniqueString = options.someProperty // This would be an argument that I pass to the plugin when running it, just as "queryOptions", "mutationOptions", etc. 
  return [someUniqueString, ...queryKey];
 }

Regarding the scoping of the query key, I think the current setup makes a lot of sense when you have a project of reasonable size where one team knows all the potential query keys that are being used. However, since we're working in a larger repository where multiple teams own multiple queries, for us this setup quickly leads to unforeseen side effects. Besides our own team, we have no idea of the other query keys that will be impacted by a certain invalidation, so we're trying to think of a setup that will make it very explicit for developers what effect their code has. I'll also reach out to you directly.

[Redmega]

You can use the queryKey generator functions to generate the query keys to invalidate

[digistaal]

Hey @Redmega , I can't seem to find this in the docs, could you point me to this?

[Redmega]

https://heyapi.dev/openapi-ts/plugins/tanstack-query#query-keys

You'd do something like:

queryClient.invalidateQueries({ queryKey : getPetByIdQueryKey({ path: { petId: 1 } }) })

and just use the same options passed to the query originally. No need to manually recreate the query key yourself.

If you need to add stuff to the query key you can pull the queryKey out from the options:

const queryOptions = getPetByIdOptions({ path: { petId: 1 } });
const { data, error } = useQuery({
  ...queryOptions,
  queryKey: ["getPets", ...queryOptions.queryKey]
});

or use the generator function:

const options = { path: { petId: 1 } };
const { data, error } = useQuery({
  ...getPetByIdOptions(options),
  queryKey: ["getPets", ...getPetByIdQueryKey(options)]
});

[Redmega]

You could also use a predicate:

queryClient.invalidateQueries({ 
  predicate: query => query.queryKey[0]._id === getPetByIdQueryKey(options)[0]._id
})

if the options are required (e.x. path parameter or required body/query parameter) you can just use the operation id I think. This one I'm not sure, you'd have to test it out with your own openapi spec. For me, the generated keys are all related to the operationIds

queryClient.invalidateQueries({ 
  predicate: query => query.queryKey[0]._id === "getPetById" // assuming operation id is get-pet-by-id?
})

You can use the predicate similarly to target the path or whatever other part of the query key you need.

All this to say, It would be nice if heyapi support this natively, but there are workarounds available to you if you need it!

[mrlubos]

Hi @Redmega sorry I got lost a bit, which part would be nice to be supported natively?

[Redmega]

If the query key were generated to be something like ["getPets", { _id: "getPets", path: { ... } }] etc, where the operation id or derived name was on its own in the query key array, it could be used to more easily invalidate queries without the need for predicates or having the entire options object sent to the queryKey function at time of invalidation.