Make QueryKey consistently an Array

[TkDodo]

When we pass the queryKey to the QueryFunctionContext, we make sure that it is an Array. This is great for global query functions, because you can just work with an Array<unknown> on type level.

However, in other situations where we provide the whole Query, accessing query.queryKey will still be string|Array<unknown>. For example, when using the predicate filter:

  queryClient.invalidateQueries({
    predicate: (query) => query.queryKey...
  })

here, it is not guaranteed that query.queryKey is an Array, so it's harder to work with

Proposed solution

only allow Arrays for QueryKeys (and for MutationKeys as well)

a codemod would be very good for this. we could let it run over all our examples, and we'd also need to update everything in the docs.

---

things to take care about:

• useQuery
• useInfiniteQuery
• useMutation
• queryCache.find
• mutationCache.find
• all methods on queryClient

[arnaudbzn]

I think this change is great but we have a type "symmetry" DX issue:

• queryKey: string | Array<unknown> in useQuery()
• query.queryKey: Array<unknown> in the predicate usage example.

A solution could be to add an alias: query.key: Array<unknown>

So Query exposes the queryKey with two properties:

• query.queryKey: string|Array<unknown> as in v3
• query.key: Array<unknown>

It also means no breaking changes.

[TkDodo]

We already do it for the queryFn. There, the queryKey passed to the queryFunctionContext is always of type array. This is needed so that you can have a global query function and don't need to do if (Array.isArray) type checks all the time.

other callbacks that can retrieve an arbitrary query don't get it that way, which is why this issue was suggested. Maybe the best thing would be to take away the string altogether? I guess the main reason it exists is so that you can do useQuery(`/todos?id=${id}`) and then your defaultQueryFn picks it up (where it then is again an Array and you have to get it via queryKey[0])

[arnaudbzn]

We already do it for the queryFn.

Right!

Maybe the best thing would be to take away the string altogether?

The v4 could be a great opportunity for this change!
That will improve the DX with consistent types and recommended practice.

[TkDodo]

@tannerlinsley would you also agree to that?

[tannerlinsley]

Sorry, I'm not sure what I'm agreeing to exactly

[TkDodo]

@tannerlinsley the initial proposal was to have the QueryKey be consistently an Array internally, so that all callbacks receive the query.queryKey as an Array, but to still allow to pass a string via the api, like useQuery('todos').

The new proposal would take this one step further and always need an array for the queryKey when you call useQuery, so it would a) be consistent and b) we wouldn't need to do any checking internally.

The reasoning is that it might come across as confusing if you call useQuery with a string as key, but then get it passed as an Array somewhere

[TkDodo]

Tanner just said we can always use Arrays 🚀

[TkDodo]

we could also add a codemod to this :)

[TkDodo]

@balazsmatepetro FYI