Allow Register-ing of the QueryKey type via module augmentation

[neefrehman]

I'm working on a codebase that has a fairly straightforward hierarchy, and where generally we have the first part of a queryKey be the "area" of the app that the useQuery instance is in. Simplified, our queryKeys almost always look like this:

queryKey: ["paymentsDashboard", "payment", payment.id]
queryKey: ["accountDashboard", "usersList", currentCursor]
queryKey: ["global", "currentUser", user.id]

We use these "areas" to easily invalidate the relevant part of the app depending on what type of mutation has happened. As an example, we will always invalidate ["paymentsDashboard"] if a mutation has happened in that part of the app. Despite having this structured approach to query keys, QueryKey is typed as ReadonlyArray<unknown>, meaning we can't enforce or hint this structure across the entirety of the library's surface area, and so there is some risk of mispelling or the proliferation of non-conforming queryKey prefixes.

To get around this, we can create an enum or other typed utility in user-land, to help us create queryKeys with the desired prefixes. But an obvious downside is that any developer would have to remember to use it. This problem also seems like something the library itself could help with, by extending the use of Register to cover the QueryKey type, as can currently happen for QueryMeta and for DefaultError.

Exposing this ability would help solve this problem at a lower level than is possible in user-land, and with the added benefit of allowing enforcement. This TS Playground gives an example of how we could benefit from updating the types. As far as the implementation goes, I've had success patching the type locally as follows:

type QueryKey = Register extends {
    queryKey: infer TQueryKey;
}
  ? TQueryKey extends Array<unknown> // ensures that we can't override the type to something other than an `Array`
    ? TQueryKey
    : ReadonlyArray<unknown>
  : ReadonlyArray<unknown>;

And using the following in a .d.ts file:

import '@tanstack/react-query';

declare module '@tanstack/react-query' {
  interface Register {
    queryKey: [AppArea | (string & {}), ...ReadonlyArray<unknown>]; // provides intellisense, but does not raise a type error if the first item doesn't conform to `AppArea`
  }
}

Would be curious to hear from the maintainers if they think this is a good idea, and if so I'd be happy to open a PR. If not, I'm also keen to find out if there is a better approach!

[TkDodo]

yeah I think we could do that, should be non-breaking. If you want to file a PR, please do 🙌

[neefrehman]

@TkDodo great! I've just opened a PR for it: #8521