Typings for QueryClient functions inferred from query or mutation keys

[roblabat]

Hey, I would like to share here an Idea of a way to implement type inferrence of data from the query key or mutation key in the QueryClient functions getQueryData, setQueryData...

This Idea comes from the implementation of types inference for the functionality provide/inject in Vue.

The Idea is to define the key as an exported const with a typing hosting the type information of the query and then inferring the getQueryData type from the type of the key if possible:

Usage would look something like that:

// key file

import { QueryKey } from '@tanstack/vue-query';

interface Todo {
  text: string;
  finished: boolean;
}

export const TodosKey = ['todos'] as QueryKey<Todo[]>;

// Query file

const result = useQuery({
  queryKey: TodosKey,
  // here fetchTodos needs to return a promise of Todo[]
  queryFn: fetchTodos 
});

// Mutation file

useMutation({
  mutationFn: updateTodo,
  onMutate: async (newTodo) => {
    await queryClient.cancelQueries({ queryKey: TodosKey })

    // previousTodos is inferred as Todo[]
    const previousTodos = queryClient.getQueryData(TodosKey)

    // newTodos is checked to be of type Todo[]
    queryClient.setQueryData(TodosKey, (old) => [...old, newTodo])

    return { previousTodos }
  },
  onError: (err, newTodo, context) => {
    // context.previousTodos is checked to be of type Todo[]
    queryClient.setQueryData(TodosKey, context.previousTodos)
  },
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: TodosKey })
  },
})

Of course with this solution using a key directly as ['todos'] without using the shared TodosKey will not infer typings as currently but it would offer a way for users to type there queries as much as possible.

Maybe other currently untyped methods could also benefits from this patern.

My example is written for Vue as I'm currently working with the Vue package of TanstackQuery but this pattern could be applied to all implementations.

If this solution is considered a good solution I would be able to take a bit of time to make a PR implementing this.

Waiting for your feedbacks :)

Ps: see https://vuejs.org/guide/typescript/composition-api.html#typing-provide-inject for my inspiration source in Vue provide/inject mechanism

[TkDodo]

the idea that I've had for v5 is the following:

we have a new function queryOptions, that's already done and type-safe. With it, you can do:

const todoOptions = queryOptions({
  queryKey: ['todos'],
  queryFn: fetchTodos
})

this one is fully typed just like useQuery, but it only creates the options that you can then pass to multiple functions:

useQuery(todoOptions)
queryClient.prefetchQuery(todoOptions)
useQueries({
  queries: [todoOptions]
})

so, its an abstraction to share the options needed to run a query. At runtime, it's just an identity function: it returns the options you pass in:

query/packages/react-query/src/queryOptions.ts

Lines 56 to 58 in 3f057a2

	export function queryOptions(options: unknown) {
	return options
	}

50 lines of types, 1 line of runtime code 😅

So with that, I'd expect most users who want the best type safety to define their query options with that function. Now what if we'd take that a step further and we would allow passing queryOptions directly to the QueryClient:

new QueryClient({
  queryOptions: [todoOptions, postOptions]
})

This would basically be the upfront definition that we'd need to make queryClient.getQueryData(key) type-safe.

Thoughts?

[roblabat]

Effectively it would provide what we need to get queryClient.getQueryData(key) type safe but I'm not very found of the idea of defining a root new QueryClient as we would need to declare here all query options only for type safety, not sure it would be compatible with modularisation and lazy loaded bundles...

I prefer the idea from Vue Inject/provide as defining a shared key is already a good practice I implement even without typings (it simplify query renaming and avoid queryKey miss spelling.

But the downside of this approach is that you have to explicitely define the returned type of the query and cannot infer it for the queryFn return...

Maybe we could have a mixed approach with yours by exporting the key of todoOptions and using it in useQueryClient. It would make something like that:

export const todoOptions = queryOptions({
  queryKey: ['todos'],
  queryFn: fetchTodos
})

export const todoKey = todoOptions.queryKey // infered to QueryKey<Todo[]>

useQueryClient().getQueryData(todoKey) // infered to Todo[]

with those two mechanism we would have type safety in queryClient.getQueryData(key)with type inference of the return type of query and without root definition of the queryClient.

I stay available if you need some implementation examples (I quickly tested the Idea locally and it should work like a charm ^^)

[roblabat]

btw I'm not sure we would be able to infer typing from clientQuery.getqueryData(key)without the cheat of having a "fake" type on the key like the Vue InjectKey<T> type. even if its possible we would for sure have to add a const type to the todoOptions key definition as without it typescript will infer queryKey to be of type string[] and then won't be able to sort the different query definitions.
definition wil have to looks more like this:

const todoOptions = queryOptions({
  queryKey: ['todos'] as const,
  queryFn: fetchTodos
})

[TkDodo]

as we would need to declare here all query options only for type safety, not sure it would be compatible with modularisation and lazy loaded bundles...

of course it wouldn't, but that's the trade-off. For type-safety, you need an up-front definition.

But I just realized it won't work with useQueryClient anyways, because that hook has no typings and doesn't know which QueryClient it will return, so the proposal is not good.

Maybe we could have a mixed approach with yours by exporting the key of todoOptions and using it in useQueryClient.

I think this is promising and could in fact work, but the queryFn would need to be required in queryOptions (which I don't think it currently is). Do you want to look into that?

[TkDodo]

another alternative would be to make an option of queryClient.getQueryData that accepts the whole queryOptions object:

queryClient.getQueryData(todoOptions)

and given that todoOptions is typed correctly, we could take the types from the queryFn passed into it (or unknown if there is no queryFn)

[TkDodo]

here's a first poc in that direction, thanks to @Andarist 🙏

typescript playground

[TkDodo]

since we removed the onSuccess callback in v5, I think refetchInterval is the only one left that gets data transformed via select passed. What if we changed that and made the function only get the query passed?

- refetchInterval: (data, query) => ...
+ refetchInterval: (query) => ...

I think that should make the troubles go away, no? It would also be more in line with other callbacks, like the one for refetchOnWindowFocus, which is:

refetchOnWindowFocus: boolean | "always" | ((query: Query) => boolean | "always")`

this too is an observer level property, but it doesn't receive transformed data either ...

[TkDodo]

I think I like that idea regardless, we should probably make a separate PR and then see if that fixes the type issues ?

[TkDodo]

the change was straight forward, can you try against this PR please:

• refactor: only pass query to refetchInterval function #6128

[TkDodo]

oh yeah, I could revert the test back to what it was; love it:

4695de8

this is a breaking change, and its a bit late given that we are in rc, but I doubt that many people use refetchInterval as a function + select together. If you really need that, you can still run the select function manually against query.state.data inside the interval function ...

[roblabat]

Yes as refetchInterval is the last callback using TData changing it like in your PR should do the trick. I'll rebase my PR on your branch when I'll have some time ^^

I think I like that idea regardless, we should probably make a separate PR and then see if that fixes the type issues ?

Yes a separate PR would be better. Currently my main issue with this new approach is type inference failing to infer arguments in callbacks like select, you can see this here if you have any idea to solve this I could then try to make a PR for that.

[roblabat]

@TkDodo

I made a PR (#6227) to add this new functionality to vue-query as it's currently only available on react-query.

I also investigated a bit more about the issue of the approach described here it seems related a typescript inference limitations when working with nested extends. There seems to be no solutions at least in current state of TS, maybe we would be able it work with future releases of TS.

Also my PR on Vue is implemented based on current type for QueryKey based on the first poc from @Andarist so if we want to migrate to my suggestion from PR #6201 it will need an update to make the Vue code working in the new approach. So keep me touch if you want to switch to my type suggestion and I'll make the update.