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

[holtgrewe]

I agree.

I would be extremely happy about some examples in the docs, e.g., also for how to invalidate based on tags in OpenAPI spec.

[mrlubos]

@holtgrewe now that I think about it, we might want to adjust how tags are stored. I believe TanStack Query won't fuzzy match partial array matches. Would be interesting to hear from the person who asked for tags how they do it. In the past, I'd write everything as objects, and there's a good reason for that: it gives you all the abilities from Effective React Query Keys with additional granularity. I plan to add tutorials to the website, but that's outside the plugin scope, hence I haven't done it yet. All in due time, this package isn't going anywhere 😬

[Redmega]

Array keys should go from most generic to most specific. Maybe we can use something from the https://tkdodo.eu/blog/effective-react-query-keys#use-query-key-factories pattern. As they stand right now one big object as the first item in the query key array does not allow for easy partial matching.

If I need to invalidate a query right now I need to pull in the query key method from the api client, and that can be annoying since some params might be necessary and I might not care about most of them if I just want to invalidate by operation.

I end up with things like this in a few places in my code:

// Somewhere in app code...
// @ts-expect-error we just need the _id so we don't care to pass params to the queryKey
queryClient.invalidateQueries({ predicate: matchesQueryKey(getPrescriptionsQueryKey()) });


// .... utils/query.ts
import { Query } from "@tanstack/react-query";

export function matchesQueryKey<TKey extends { _id: string }>(queryKey: [TKey], keys: (keyof TKey)[] = ["_id"]) {
  return function predicate(query: Query) {
    return keys.some((key) => (query.queryKey as [TKey])[0][key] === queryKey[0][key]);
  };
}

where getPrescriptionsQueryKey expects path and body params. I don't want to hard code the operationId as that should definitely just be coming from the openapi spec, so instead I'm left with expecting ts errors :(

[mrlubos]

There are some opinions that would just lead to further discussion and I don't want to focus on that right now, but that little helper is interesting. I expect we'd have the same problem with any query key design? If using the array design, how would you write a partial matcher? Anything we can do to improve that?

There's a bunch of frameworks for query design, https://tanstack.com/query/latest/docs/framework/react/community/community-projects#query-key-factory is another one. Ideally we'd want our solution to apply across the board

[Redmega]

If using the array design, how would you write a partial matcher? Anything we can do to improve that?

I’m not sure I follow — if the key wasn’t all in one object as the first element, then doing invalidateQueries([“getPrescriptions”]) would match regardless of where that appears in the array.

I’d advocate for a query key shape like [operationId, { path, body, query }] or something similar. Give the option to dive down into the request for granularity, but also enable simple invalidation based on operationId

if you replicate _id into the object and put it last like [{ _id, path, body, query }, operationId] it would even be backwards compatible