feat(react-query): add typesafe query disabling via skipToken

[Jaaneek]

This pull request is heavily inspired by RTK query skipToken.

https://redux-toolkit.js.org/rtk-query/usage/conditional-fetching#overview

We are introducing skipToken which allows typesafe disabling of queries.

  const { data } = useQuery({
      queryKey: ['todos', filter],
      // ⬇️ disabled as long as the filter is undefined or empty
      queryFn: filter ? () => fetchTodos(filter) : skipToken,
  })

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

1 Ignored Deployment

Name	Status	Preview	Comments	Updated (UTC)
query	⬜️ Ignored (Inspect)	Visit Preview		Mar 5, 2024 1:11pm

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit efb6b6d:

Sandbox	Source
@tanstack/query-example-angular-basic	Configuration
@tanstack/query-example-react-basic-typescript	Configuration
@tanstack/query-example-solid-basic-typescript	Configuration
@tanstack/query-example-svelte-basic	Configuration
@tanstack/query-example-vue-basic	Configuration

[TkDodo]

two things to keep an eye on:

• it shouldn't be possible to pass a skipToken to suspense versions of the hooks, like useSuspenseQuery, because those always set enabled: true. We should likely forbid this on type level, and at runtime, only set enabled: false if we have a skipToken and enabled isn't already true
• we should watch out how this influences places where we try to infer the type of what the queryFn returns, because with skipToken, it might not be a function. queryOptions is one of those places, I think we should add a type-test for that.

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit efb6b6d. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 2 targets

• nx affected --targets=test:format,test:sherif,test:knip,test:eslint,test:lib,test:types,test:build,build --parallel=3
• nx run-many --targets=test:format,test:sherif,test:knip,test:eslint,test:lib,test:types,test:build,build --parallel=3

---

Sent with 💌 from NxCloud.

[Jaaneek]

two things to keep an eye on:

• it shouldn't be possible to pass a skipToken to suspense versions of the hooks, like useSuspenseQuery, because those always set enabled: true. We should likely forbid this on type level, and at runtime, only set enabled: false if we have a skipToken and enabled isn't already true
• we should watch out how this influences places where we try to infer the type of what the queryFn returns, because with skipToken, it might not be a function. queryOptions is one of those places, I think we should add a type-test for that.

Is it only for react-query package or should this be implemented in other implementations of query as well? Once we accept queryFn as skipToken it will work like that everywhere

Update: I implemented this on type level for useSuspenseQuery, I will implement type-test, why should we implement this for runtime? To help out people who are doing raw JS?

[Jaaneek]

@TkDodo

• useSuspenseQuery is handled
• added some tests
• Types are correctly inferred based on function.

Problems:

• Some tests are failing :D
• queryOptions function, I could use help with making the return type be accepted by useSuspenseQuery.

To consider:
Implementing this only in react-query, will be much easier & a lot less changes. When we pass props we would set enabled to false and that's it. Very similar to what I have done in trpc pull request.
Other packages could implement it in the same way, but core package wouldn't have changes

[TkDodo]

regarding queryOptions - does this still work?

const options = queryOptions({
  queryKey: ['key'],
  queryFn: () => Math.random() > 0.5 ? skipToken : Promise.resolve(5),
})

const data = queryClient.getQueryData(options.queryKey)

here, data should be of type number | undefined - inferred from the queryFn. I just want to make sure that the skipToken existence doesn't destroy that.

[Jaaneek]

regarding queryOptions - does this still work?

const options = queryOptions({
  queryKey: ['key'],
  queryFn: () => Math.random() > 0.5 ? skipToken : Promise.resolve(5),
})

const data = queryClient.getQueryData(options.queryKey)

here, data should be of type number | undefined - inferred from the queryFn. I just want to make sure that the skipToken existence doesn't destroy that.

This works:

Should we also handle returning the skipToken from a function? I think it's not "needed"?

[TkDodo]

Oh Great 👍
No I also don't think this is needed

[TkDodo]

the should respect skipToken test is constantly failing in CI, but it works fine locally. I don't know why :/

[Jaaneek]

@TkDodo I found potential problem when fixing the should respect skipToken test

The queryKeys I used were already declared in another test.
I fixed the test by simply changing the queryKeys to unique name.

Maybe we should do cleanup after every test to ensure that the queryKeys are not shared? I don't think there is a use in sharing them

[TkDodo]

Maybe we should do cleanup after every test to ensure that the queryKeys are not shared? I don't think there is a use in sharing them

yeah that's what the queryKey() function is for. it increments a value. no test should use hardcoded keys

[hichemfantar]

I can't find the documentation for skipToken.
I only discovered this thanks to TRPC

[Jaaneek]

I can't find the documentation for skipToken.

I only discovered this thanks to TRPC

https://tanstack.com/query/latest/docs/framework/react/guides/disabling-queries

[hichemfantar]

@Jaaneek thanks! any idea as to why skipToken isn't search indexed?