@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

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

[AdrianMrn]

@Redmega We're considering somehow overwriting the generated createQueryKey to output an array where the operationId is the first index and options are added afterwards. I'd write it as a PR but this would be a breaking change for people currently doing predicate: query => query.queryKey[0]._id.

Any idea if I'm missing anything and there's a better solution available?

FYI both the predicate solution and prefixing the queryKey gives us type-errors based on what the generated options expect, but this isn't a huge issue as long as we move it to a helper with a bunch of typecasts and comments 😅

[Redmega]

The lib is still v0 so breaking changes aren't unheard of, I'd defer to @mrlubos for if a PR for that would be considered or not :)

If you wanted to make it slightly less of a breaking change you could append the operationId to the end of the query. Query keys are hashed deterministically, so order doesn't matter and you could still invalidate queries using the operationId (or writing a predicate for more complex requirements like query.queryKey.some(key => [operationId1,operationId2].includes(key))).

[hydenp]

I would second what everyone else has discussed. Everything else with the plugin is making sense so far, but the querykey part is a little un-intuitive overall.