React Query and TypeScript
Tags: react, typescript, webdev, javascript
Published: 2021-05-24 08:19:04

[TypeScript](https://www.typescriptlang.org/) is 🔥 - this seems to be a common understanding now in the frontend community. Many developers expect libraries to either be written in TypeScript, or at least provide good type definitions. For me, if a library is written in TypeScript, the type definitions are the best documentation there is. It's never wrong because it directly reflects the implementation. I frequently look at type definitions before I read API docs.

React Query was initially written in JavaScript (v1), and was then re-written to TypeScript with v2. This means that right now, there is very good support for TypeScript consumers.

There are however a couple of "gotchas" when working with TypeScript due to how dynamic and unopinionated React Query is. Let's go through them one by one to make your experience with it even better.

# Generics

React Query heavily uses [Generics](https://www.typescriptlang.org/docs/handbook/2/generics.html). This is necessary because the library does not actually fetch data for you, and it cannot know what _type_ the data will have that your api returns.

The TypeScript section in the [official docs](https://react-query.tanstack.com/typescript) is not very extensive, and it tells us to explicitly specify the Generics that _useQuery_ expects when calling it:

```ts
function useGroups() {
    return useQuery<Group[], Error>('groups', fetchGroups)
}
```

Over time, React Query has added more Generics to the _useQuery_ hook (there are now four of them), mainly because more functionality was added. The above code works, and it will make sure that the _data_ property of our custom hook is correctly typed to `Group[] | undefined` as well as that our _error_ will be of type `Error | undefined`. But it will not work like that for more advanced use-cases, especially when the other two Generics are needed.

## The four Generics

This is the current definition of the _useQuery_ hook:

```ts
export function useQuery<
    TQueryFnData = unknown,
    TError = unknown,
    TData = TQueryFnData,
    TQueryKey extends QueryKey = QueryKey
>
```

There's a lot of stuff going on, so let's try to break it down:

-   `TQueryFnData`: the type returned from the _queryFn_. In the above example, it's `Group[]`.
-   `TError`: the type of Errors to expect from the _queryFn_. `Error` in the example.
-   `TData`: the type our _data_ property will eventually have. Only relevant if you use the _select_ option, because then the _data_ property can be different from what the _queryFn_ returns. Otherwise, it will default to whatever the _queryFn_ returns.
-   `TQueryKey`: the type of our QueryKey, only relevant if you use the QueryKey that is passed to your _queryFn_.

As you can also see, all those Generics have default values, which means that if you don't provide them, TypeScript will fall back to those types. This works pretty much the same as default parameters in JavaScript:

```js
function multiply(a, b = 2) {
    return a * b
}

multiply(10) // ✅ 20
multiply(10, 3) // ✅ 30
```

## Type Inference

TypeScript works best if you let it infer (or figure out) what type something should be on its own. Not only does it make code easier to _write_ (because you don't have to type all the types 😅), but it will also make it easier to _read_. In many instances, it can make code look exactly like JavaScript. Some simple examples of type inference would be:

```ts
const num = Math.random() + 5 // ✅ `number`

// 🚀 both greeting and the result of greet will be string
function greet(greeting = 'ciao') {
    return `${greeting}, ${getName()}`
}
```

When it comes to Generics, they can also generally be inferred from their usage, which is super awesome. You could also provide them manually, but in many cases, you don't need to.

```ts
function identity<T>(value: T): T {
    return value
}

// 🚨 no need to provide the generic
let result = identity<number>(23)

// ⚠️ or to annotate the result
let result: number = identity(23)

// 😎 infers correctly to `string`
let result = identity('react-query')
```

## Partial Type Argument Inference

...doesn't exist in TypeScript yet (see this [open issue](https://github.com/microsoft/TypeScript/issues/26242)). This basically means that if you provide _one_ Generic, you have to provide _all_ of them. But because React Query has default values for Generics, we might not notice right away that they will be taken. The resulting error messages can be quite cryptic. Let's look at an example where this actually backfires:

```ts
function useGroupCount() {
    return useQuery<Group[], Error>('groups', fetchGroups, {
        select: (groups) => groups.length,
        // 🚨 Type '(groups: Group[]) => number' is not assignable to type '(data: Group[]) => Group[]'.
        // Type 'number' is not assignable to type 'Group[]'.ts(2322)
    })
}
```

Because we haven't provided the 3rd Generic, the default value kicks in, which is also `Group[]`, but we return `number` from our _select_ function. One fix is to simply add the 3rd Generic:

```ts
function useGroupCount() {
    // ✅ fixed it
    return useQuery<Group[], Error, number>('groups', fetchGroups, {
        select: (groups) => groups.length,
    })
}
```

As long as we don't have Partial Type Argument Inference, we have to work with what we got.

So what's the alternative?

## Infer all the things

Let's start by _not_ passing in any Generics at all and let TypeScript figure out what to do. For this to work, we need the _queryFn_ to have a good return type. Of course, if you inline that function without an explicit return type, you will have _any_ - because that's what _axios_ or _fetch_ give you:

```ts
function useGroups() {
    // 🚨 data will be `any` here
    return useQuery('groups', () => axios.get('groups').then((response) => respone.data))
}
```

If you (like me) like to keep your api layer separated from your queries, you'll need to add type definitions anyways to avoid _implicit any_, so React Query can infer the rest:

```ts
function fetchGroups(): Promise<Group[]> {
    return axios.get('groups').then((response) => response.data)
}

// ✅ data will be `Group[] | undefined` here
function useGroups() {
    return useQuery('groups', fetchGroups)
}

// ✅ data will be `number | undefined` here
function useGroupCount() {
    return useQuery('groups', fetchGroups, {
        select: (groups) => groups.length,
    })
}
```

Advantages of this approach are:

-   no more manually specifying Generics
-   works for cases where the 3rd (select) and 4th (QueryKey) Generic are needed
-   will continue to work if more Generics are added
-   code is less confusing / looks more like JavaScript

## What about error?

What about error, you might ask? Per default, without any Generics, error will be inferred to _unknown_. This might sound like a bug, why is it not _Error_? But it is actually on purpose, because in JavaScript, you can throw _anything_ - it doesn't have to be of type `Error`:

```js
throw 5
throw undefined
throw Symbol('foo')
```

Since React Query is not in charge of the function that returns the Promise, it also can't know what type of errors it might produce. So _unknown_ is correct. Once TypeScript allows skipping some generics when calling a function with multiple generics (see [this issue for more information](https://github.com/microsoft/TypeScript/issues/10571)), we could handle this better, but for now, if we need to work with errors and don't want to resort to passing Generics, we can narrow the type with an instanceof check:

```ts
const groups = useGroups()

if (groups.error) {
    // 🚨 this doesn't work because: Object is of type 'unknown'.ts(2571)
    return <div>An error occurred: {groups.error.message}</div>
}

// ✅ the instanceOf check narrows to type `Error`
if (groups.error instanceof Error) {
    return <div>An error occurred: {groups.error.message}</div>
}
```

Since we need to make some kind of check anyways to see if we have an error, the instanceof check doesn't look like a bad idea at all, and it will also make sure that our error actually has a property message at runtime. This is also in line with what TypeScript has planned for the 4.4 release, where they'll introduce a new compiler flag _useUnknownInCatchVariables_, where catch variables will be _unknown_ instead of _any_ (see [here](https://github.com/microsoft/TypeScript/issues/41016)).

# Type Narrowing

I rarely use destructuring when working with React Query. First of all, names like _data_ and _error_ are quite universal (purposefully so), so you'll likely rename them anyway. Keeping the whole object will keep the context of what data it is or where the error is coming from. It will further help TypeScript to narrow types when using the status field or one of the status booleans, which it cannot do if you use destructuring:

```ts
const { data, isSuccess } = useGroups()
if (isSuccess) {
    // 🚨 data will still be `Group[] | undefined` here
}

const groupsQuery = useGroups()
if (groupsQuery.isSuccess) {
    // ✅ groupsQuery.data will now be `Group[]`
}
```

This has nothing to do with React Query, it is just how TypeScript works. [@danvdk](https://twitter.com/danvdk) has a good explanation for this behaviour

{% twitter 1363614288103964672 %}

# Type safety with the enabled option

I've expressed my ♥️ for the [enabled option](https://tkdodo.eu/blog/practical-react-query#the-enabled-option-is-very-powerful) right from the start, but it can be a bit tricky on type level if you want to use it for [dependent queries](https://react-query.tanstack.com/guides/dependent-queries) and disable your query for as long as some parameters are not yet defined:

```ts
function fetchGroup(id: number): Promise<Group> {
    return axios.get(`group/${id}`).then((response) => response.data)
}

function useGroup(id: number | undefined) {
    return useQuery(['group', id], () => fetchGroup(id), { enabled: Boolean(id) })
    // 🚨 Argument of type 'number | undefined' is not assignable to parameter of type 'number'.
    //  Type 'undefined' is not assignable to type 'number'.ts(2345)
}
```

Technically, TypeScript is right, _id_ is possibly _undefined_: the _enabled_ option does not perform any type narrowing. Also, there are ways to bypass the _enabled_ option, for example by calling the _refetch_ method returned from _useQuery_. In that case, the _id_ might really be _undefined_.

I've found the best way to go here, if you don't like the [non-null assertion operator](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator), is to accept that _id_ can be _undefined_ and reject the Promise in the _queryFn_. It's a bit of duplication, but it's also explicit and safe:

```ts
function fetchGroup(id: number | undefined): Promise<Group> {
    // ✅ check id at runtime because it can be `undefined`
    return typeof id === 'undefined'
        ? Promise.reject(new Error('Invalid id'))
        : axios.get(`group/${id}`).then((response) => response.data)
}

function useGroup(id: number | undefined) {
    return useQuery(['group', id], () => fetchGroup(id), { enabled: Boolean(id) })
}
```

# Optimistic Updates

Getting optimistic updates right in TypeScript is not an easy feat, so we've decided to add it as a comprehensive [example](https://react-query.tanstack.com/examples/optimistic-updates-typescript) to the docs.

The important part is: You have to explicitly type the _variables_ argument passed to _onMutate_ in order to get the best type inference. I don't fully comprehend why that is, but it again seems to have something to do with inference of Generics. Have a look [at this comment](https://github.com/tannerlinsley/react-query/pull/1366#discussion_r538459890) for more information.

# useInfiniteQuery

For the most parts, typing _useInfiniteQuery_ is no different from typing _useQuery_. One noticeable gotcha is that the _pageParam_ value, which is passed to the _queryFn_, is typed as _any_. Could be improved in the library for sure, but as long as it's _any_, it's probably best to explicitly annotate it:

```ts
type GroupResponse = { next?: number, groups: Group[] }
const queryInfo = useInfiniteQuery(
    'groups',
    // ⚠️ explicitly type pageParam to override `any`
    ({ pageParam = 0 }: { pageParam: GroupResponse['next']) => fetchGroups(groups, pageParam),
    {
        getNextPageParam: (lastGroup) => lastGroup.next,
    }
)
```

If _fetchGroups_ returns a _GroupResponse_, _lastGroup_ will have its type nicely inferred, and we can use the same type to annotate _pageParam_.

# Typing the default query function

I am personally not using a [defaultQueryFn](https://react-query.tanstack.com/guides/default-query-function), but I know many people are. It's a neat way to leverage the passed _queryKey_ to directly build your request url. If you inline the function when creating the _queryClient_, the type of the passed _QueryFunctionContext_ will also be inferred for you. TypeScript is just so much better when you inline stuff :)

```ts
const queryClient = new QueryClient({
    defaultOptions: {
        queries: {
            queryFn: async ({ queryKey: [url] }) => {
                const { data } = await axios.get(`${baseUrl}/${url}`)
                return data
            },
        },
    },
})
```

This just works, however, _url_ is inferred to type _unknown_, because the whole queryKey is an _unknown Array_. At the time of the creation of the queryClient, there is absolutely no guarantee how the queryKeys will be constructed when calling _useQuery_, so there is only so much React Query can do. That is just the nature of this highly dynamic feature. It's not a bad thing though because it means you now have to work defensively and narrow the type with runtime checks to work with it, for example:

```ts
const queryClient = new QueryClient({
    defaultOptions: {
        queries: {
            queryFn: async ({ queryKey: [url] }) => {
                // ✅ narrow the type of url to string so that we can work with it
                if (typeof url === 'string') {
                    const { data } = await axios.get(`${baseUrl}/${url.toLowerCase()}`)
                    return data
                }
                throw new Error('Invalid QueryKey')
            },
        },
    },
})
```

I think this shows quite well why _unknown_ is such a great (and underused) type compared to _any_. It has become my favourite type lately - but that is subject for another blog post 😊.

---

That's it for today. Feel free to reach out to me on [twitter](https://twitter.com/tkdodo)
if you have any questions, or just leave a comment below ⬇️