v5 Roadmap 🗺

[TkDodo]

TanStack Query v5 Roadmap

Update: The roadmap is now a milestone:

• https://github.com/TanStack/query/milestone/2

This is a first draft of what a v5 could look like in terms of breaking changes. Nothing of this is set in stone, and no implementation on anything here has started. This discussion should serve as an umbrella to track things we might want to do, and to find out very early if some proposals are not a good idea.

Please feel free to add your thoughts and ideas as comments:

status: pending

see details

context

In v4, we removed the idle state because it was only used in conjunction with disabled queries and led to a bunch of impossible states with the introduction of the new fetchStatus. You couldn't be in idle state and be fetching or paused at the same time. This was the only exception to the fact that all combinations of status and fetchStatus were valid, so we removed it.

In summary, we now have:

status:

• loading
• success
• error

fetchStatus:

• idle
• fetching
• paused

This led to the unfortunate situation that you cannot easily check when to display a loading spinner if your query is disabled, even if you use the enabled option conditionally, e.g. for lazy queries, because the query will start in loading state if it doesn't have data yet, even if it's not fetching because it's disabled.

So you had to combine two checks (isLoading && isFetching), which is why we introduced a new flag in v4.8.0 called isInitialLoading that combines the two.

---

However, isLoading would be a much better name for this condition. It literally means: show a loading spinner! What we currently have as loading state is a bit misleading because it doesn't mean "data is loading", it just means "we have no data yet". It is used to discriminate the data field - if you check for isSuccess, it is guaranteed that data is defined.

A better name for this mindset would be pending. pending as in "the promise is still pending" or "we don't have data yet". It doesn't say much about data being fetched or not. A disabled query can very well be in pending state - you wouldn't necessarily show a loading spinner just because data is pending.

proposal

• rename status: loading to status: pending and the derived boolean isLoading to isPending
• introduce a new, derived boolean flag isLoading that is implemented as isPending && isFetching

If we do this, isLoading and isInitialLoading will have the same meaning. We could just flat out remove isInitialLoading and tell people to go back to isLoading now, but I fear that this will not land well with the community because we just told them to go from isLoading to isInitialLoading with v4.8.0.

So I would deprecate isInitialLoading with v5, but keep it intact (just an alias for isLoading really) and remove it in v6.

remove overloads

see details

context

useQuery and friends have many overloads in TypeScript - different ways how the function can be invoked. As an example, let's look at useQuery. You can call it in three different ways:

useQuery(queryKey, queryFn, options)
useQuery(queryKey, options)
useQuery(options)

The queryKey is the only required property. The queryFn is optional because you might have defined it globally. If you use the syntax where you only pass one object in, the queryKey is also required.

Not only is this tough to maintain, type wise, it also requires a runtime check to see which type the first and the second parameter are to correctly create options. Internally, we only work with one options object.

Further, we started to add more overloads for features that are only doable with overloads. For example, if you pass initialData, the return type of data will not contain undefined. Because initialData can also be a function, we need another 3 overloads for each possibility to call useQuery, resulting in 9 total overloads.

The useQuery.ts file has 140 lines of code - only 3 of which are actual JavaScript.

Other functions suffer from the same problem, and overloads are also not consistent. For example, queryCache.findAll has overloads, but mutationCache.findAll does not.

proposal

• remove all overloads and only allow all functions to be called with a single signature - one object

This means that useQuery would need to be called:

useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  staleTime: 1000 * 20
})

This does not only affect useQuery, but all functions that accept overloads:

• useMutation(() => axios.post(...)) will become useMuation({ mutationFn: () => axios.post(...) })
• invalidateQueries(["todos"]) will become invalidateQueries({ queryKey: ["todos"] })

and so on...

We have actually tried this already for v4, see:

• remove overloads #2918

but there was a type inference issue that stopped the attempt. The issue was fixed with TS 4.7:

• Generic inference to unknown after using function arguments microsoft/TypeScript#43371

mitigation strategy

We will very likely provide a codemod that automatically transforms your queries to that syntax

require minimum of TS 4.7

see details

v4 supports TS4.1 or greater, v5 will need TS4.7 or greater for the reasons mentioned above. It might work fine with TS4.1, but you might run into type inference issues.

remove custom logger

see details

context

In v3, we had a global logger that you could set via setLogger to your own logging mechanism. This was a side effect which we tried to get rid of, so in v4, you can now pass a logger prop to the QueryClient.

The logger mainly does one thing: It logs failed queries to the console. This is fine for development, but it was confusing to many that it also showed up in production.

That's why we've removed all logging in production in v4, and we've also started to use the logger more to show development specific warnings, for example:

• when you pass a queryKey that isn't an Array.
• when you return undefined from your queryFn.
• when you set multiple, conflicting query defaults.

Those logs are meant to help developers find potential issues in their code. They are not meant to be shown in production. I'd see them on the same level as the warning you get from React in development mode, for example:

• Each child in a list should have a unique "key" prop.

There is also no way to show these warnings in production. This also helps with bundle size because all logging happens behind an env check, so it is stripped from the final bundle. This means we can be as verbose as we want with those messages.

---

All of this means that the custom logger is kind of unnecessary. Why would you want to pass a custom logger only to log differently in development mode? The logger prop itself cannot be tree-shaken, so it will always be included in the final bundle even though we actually never use it.

proposal

• remove the logger prop from QueryClient
• do not log failed queries to the console anymore, as failed queries are not a programmer "error" that we need to point people towards. The network tab shows failed requests just fine.

We should be able to just use the console for those development logs as it exists in all environments.

make TError default to Error instead of unknown

see details

context

In JavaScript, you can throw anything, even literals like 5 or Promises (?? suspense). That is why the generic for the type TError defaults to unknown. This is in line with how TypeScript itself handles errors in catch clauses since v4.4.

This is not very practical. Unless you explicitly throw a non-error, error will be at least of type Error. If you use axios, it might be of type AxiosError, but that is also not guaranteed. For example, if you have a runtime error in select, that will be caught, and it puts your query into error state. The error will be of type Error then.

Practically, it means that you either fall back to runtime checks:

const { error } = useQuery(...)
if (error instanceof Error) {
  // do something with error.message
}

or, you pass a generic to useQuery:

const { error, isError } = useQuery<Todos, Error>(...)
if (isError) {
  // do something with error.message
}

The second approach is bad for two reasons:

1. TError is the second generic, so you also have to annotate the first generic, which is the return type of the queryFn. This could actually be inferred.
2. useQuery has 4 generics, and if you only provide two of them, the other two will fall back to their default value instead of being inferred from their usage. That means select will not work as expected:

const { error, isError } = useQuery<Todos, Error>({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  select: (data) => data[0],
})

if (isError) {
  // do something with error.message
}

You'll get a weird error about no overload matching, see this TypeScript Playground.

proposal

• on type level, make the TError generic default to Error instead of unknown
• at runtime, wrap all errors that aren't errors into errors:

This will have to happen here:

query/packages/query-core/src/retryer.ts

Lines 143 to 148 in ca76777

	// Execute query
	try {
	promiseOrValue = config.fn()
	} catch (error) {
	promiseOrValue = Promise.reject(error)
	}

catch (error) {
-  promiseOrValue = Promise.reject(error)
+  const properError = error instanceof Error ? error : new Error(String(error))
+  promiseOrValue = Promise.reject(properError)
}

rename useErrorBoundary

see details

context

A property that starts with the prefix use is unfortunately named, as use usually indicates a hook in React. ErrorBoundary might also be a quite react specific term.

Renaming the property to e.g. throwError would more accurately describe what is happening: the error will be thrown. In React, it will be picked up by the nearest error boundary.

proposal

• rename useErrorBoundary to throwError

rename cacheTime

see details

context

Almost everyone gets cacheTime wrong (exhibit A). It sounds like "the amount of time that data is cached for", but that is not correct.

cacheTime does nothing as long as a query is still in used. It only kicks in as soon as the query becomes unused. After the time has passed, data will be "garbage collected" to avoid the cache from growing (see also this explanation).

RTK Query has the same feature - their prop is called keepUnusedDataFor. I think this is quite descriptive but also a bit long.

proposal

• rename cacheTime to gcTime

gc is referring to "garbage collect" time. It's a bit more technical, but also a quite well known abbreviation in computer science.

Also, it is not something that most people will have to customize. The default of 5 minutes is usually fine. A rename will reduce the chance that this property is mixed up with staleTime.

Lastly, if someone doesn't immediately know what gcTime stands for, they will (hopefully) consult the docs. This is a lot better than thinking they know what cacheTime does.

Here is an old discussion on that topic:

• Consider renaming cacheTime #1217

Alternatives:

After some discussions, a rename to inactiveCacheTime would also be possible. It' similar to the current name but clearly indicates: "The time that inactive queries will be cached for". It can take a way a lot of confusion about the cacheTime being valid for all queries, even those that are actively used (= active queries). Inactive is also the naming we show in the devtools as well as when using QueryFilters, so it fits well.

size improvements

see details

context

The "big" bundle size is a constant topic when TanStack Query is compared to other libraries. I think there are a few things that can be done to improve the situation:

don't transpile optional chaining

Optional chaining is used a lot in the codebase, and it's supported in 93.44% of all browsers. Transpiling it is quite costly:

- this.retryer?.continue()
+ this.retryer == null ? void 0 : this.retryer.continue()

switch to private class fields and methods

Private class fields are supported in 92.7% of all browsers. They have a bunch of advantages:

• they are private at runtime, not just at compile time
• because of that, they can be minified by terser
• as per this discussion, they would help us with circular references to private fields from within the QueryCache.

proposal

• adapt our current supported browserslist:

- Chrome >= 73
+ Chrome >= 84
- Firefox >= 78
+ Firefox >= 90
- Edge >= 79
+ Edge >= 84
- Safari >= 12.0
+ Safari >= 15
- iOS >= 12.0
+ iOS >= 15
- opera >= 53
+ opera >= 70

Out of these changes, Safari would be the "newest" supported browser, with a release date of September 2021. This would still likely mean at least 1.5 years of browser support for Safari when we release v5.

If people want to support older browsers, they can always transpile the code themselves.

• use private class fields and methods instead of the private TypeScript keyword.

remove isDataEqual property on useQuery

see details

We have two props that go together on useQuery that are around structural sharing:

• isDataEqual?: (oldData: TData | undefined, newData: TData) => boolean
  • default: undefined
• structuralSharing?: boolean | ((oldData: TData | undefined, newData: TData) => TData)
  • default: true

This is how it works internally when new data comes in, and we need to consolidate it with existing data:

• At first, we check if isDataEqual is passed. If it is, and it returns true, we just return the previousData.
• If it's not we used to check if structuralSharing is on (boolean). If it's not, we returned the new data
• If structuralSharing is on, we try to re-use as much as possible from previousData to keep referential identity. This sharing is not for free, so you can turn it off. It also only works on json compatible values per default.

With v4.2.0, we added a feature for custom structuralSharing functions. This way, consumers can still achieve the performance benefits of retained references even when cache data contains non-serializable values.

This feature has a nice side effect: you can now implement isDataEqual with it. All you need to do instead is do the same check in your structuralSharing function and return oldData if they are equal instead of true. The functions also have the exact same interface for the parameters passed in:

structuralSharing: (oldData, newData) =>
  isDataEqual(oldData, newData) ? oldData : replaceEqualDeep(oldData, newData)

proposal

• Deprecate isDataEqual in v4
  • show that you can implement it with structuralSharing. For this to work, we also need to expose the internal functionality that structural sharing is doing (currently named replaceEqualDeep).
• Remove isDataEqual from useQuery in v5

remove contextSharing

see details

context

The QueryClientProvider has a prop contextSharing: boolean. The docs say:

Set this to true to enable context sharing, which will share the first and at least one instance of the context across the window to ensure that if React Query is used across different bundles or microfrontends they will all use the same instance of context, regardless of module scoping.

To be honest - I don't really know how this property is working. There were some discussion on this issue that suggest that it is not really useful.

For microfrontends, isolation is often preferred. With v4, we introduced the option to pass a custom context, which allows for exactly that.

If you want your app to use the same client when it's composed of multiple packages, all you'd need to do is create one QueryClient in your app and let the different bundles pick those up. As long as they all use the same version of TanStack Query, this should work fine.

If you have more info on how contextSharing works or where it is useful, please share!

proposal

• Deprecate contextSharing in v4
• Remove contextSharing from QueryClientProvider in v5

replace custom context with custom queryClient

see details

context

in v4, we introduced the possibility to pass a custom context to all react-query hooks. This allowed for proper isolation when using MicroFrontends. See the migration guide for examples and details.

However, context is a react only feature. All that context does is give us access to the query client. We could achieve the same isolation by allowing to pass in a custom query client instead of a custom context that then serves the query client.

vue-query does have this api already, so it makes sense to streamline it in react as well.

see also:

• Hooks independant of context #4360

proposal

• replace custom context param on react hooks with custom queryClient param

drop support for React17

see details

context

With nextJs 13 also requiring React18, it makes sense to follow suit. All new features are build on top of react18. This means we can also drop the useSyncExternalStore shim, which has caused troubles in the past with react-native and ESM, and also adds a bit of bundle size.

proposal

• set the required peer dependency of react to ">=18.2.0"

remove remove returned from useQuery

see details

context

remove removes the query from the queryCache without informing observers about it. It is best used to remove data imperatively that is no longer needed, e.g. when logging a user out.

It doesn't make much sense to do this while a query is still active, because it will just trigger a hard loading state with the next re-render. So when would you ever use the remove function returned from useQuery, because at that point, you still have an active observer ?

anecdotal twitter thread

proposal

• remove remove in v5

remove unstable_batchedUpdates

see details

context

we currently use unstable_batchedUpdates as our batchNotifyFn in React and React Native:

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

Line 4 in 357ec04

notifyManager.setBatchNotifyFunction(unstable_batchedUpdates)

Apparently, this function is a "noop" in React18, as discussed here:

facebook/react#24831 (comment)

Unanswered questions:

• Do other frameworks need a batchFn ?
• Is the same true for react-native ?
• Should we keep the option to set a batchUpdatesFn via the notifyManager?

proposal

• remove the default side-effect that sets batchedUpdates
• this would also mean we would be completely side-effect free:

query/packages/react-query/package.json

Lines 24 to 26 in 9b21609

	"sideEffects": [
	"./src/setBatchUpdatesFn.ts"
	],

remove queryHash from useQuery options

see details

context

The queryHash is the result of the query key hashing, produced by the queryKeyHashFn. This function defaults to a stable JSON.stringify, but can also be passed in by users to do custom hashing, e.g. when non-json serializable things are used in the queryKey.

According to our TypeScript types, we can also pass in a queryHash directly into useQuery. This is not only undocumented, it's also redundant because you can achieve the same thing with a queryKeyHashFn:

- useQuery({ queryKey, queryFn, queryHash: 'myHash' })
+ useQuery({ queryKey, queryFn, queryKeyHashFn: () => 'myHash' })

proposal

• remove queryHash from useQuery options
  • no deprecation needed because this is undocumented

expose custom cache

see details

context

Inspired by swr cache provider, we can allow to pass a "custom cache" into our QueryCache:

new QueryClient({
  queryCache: new QueryCache({
    cache: myCache
  })
})

The cache would have to adhere to a map-like interface, and we should probably re-write our internal object to a standard Map.

This would allow features like:

• limit cache size (as discussed here)
  • you could evict unused cache entries by other criteria than being time-based
• persist to local storage on a per-query basis
  • limitation: writes could be async, but reads would need to be sync
• reset cache between test runs (we can already do that in different ways though)
• other use-cases I haven't thought of?

proposal

• re-write internal cache object to a Map
• allow custom caches to be passed in that adhere to a map-like interface

fix pageParams in infinite queries

see details

context

there are two issues related to pageParams that we likely cannot fix in a backwards compatible way:

• Infinite Queries: wrong auto refetching with manual pageParams #4464
• null is passed as pageParam with PersistQueryClientProvider #4309

proposal

• change how we store pageParam in InfiniteData (this would fix Infinite Queries: wrong auto refetching with manual pageParams #4464)

- pageParams: [undefined, 5, 50],
+ pageParams: [[{ param: undefined, manual: false }, { param: 5, manual: false }, { param: 50, manual: true }]],

• then, automatic refetches could rely on the manual flag to find out if page should be used for refetching or not.
• disallow to return null from getNextPageParam (this would fix null is passed as pageParam with PersistQueryClientProvider #4309)
  • null and undefined would both be treated as "no next page available"
  • internally, we would store null so that we can json serialize it

- pageParams: [[{ param: undefined, manual: false }],
+ pageParams: [[{ param: null, manual: false }],

• we would still always pass undefined to the queryFn so that default value assignment would still work:

queryFn: ({ pageParam = 1 }) => fetchPage(pageParam),

remove placeholderData as a function

we'll do this instead:

• RFC: Combine keepPreviousData with placeholderData #4426

see details

context

The real motivation is that we can remove a lot of internal code if we drop this feature, and there's no real gain to use a function over a value or a memoized value. To achieve memoization, you had to pass in a stable function (probably with useCallback). Since the function receives no input, you can just as well do this with useMemo. Unlike the initialData function, which only runs once per cache key, the placeholderData function runs on every render if placeholder data needs to be shown. So the advantage of it being potentially a function is minimal.

proposal

• deprecate placeholderData as a function in v4
• remove it in v5

[franky47]

+1 for removing useQuery overloads, the object one is what I use, for one good reason: it looks better after Prettier is done with it. 😅

[TkDodo]

let's just keep in mind that this will affect all functions that have overloads:

• useMutation(() => axios.post(...)) will become useMuation({ mutationFn: () => axios.post(...) })
• invalidateQueries(["todos"]) will beccome invalidateQueries({ queryKey: ["todos"] })

and so on... not saying it's a bad idea, just wanted to make it clear that this is a lot bigger than just useQuery ...

[viclafouch]

+1 ! still a good idea !

[rodrigofariow]

Cool stuff overall!
I have a few questions though @TkDodo :

at runtime, wrap all errors that aren't errors into errors:

1. How could I opt out of this behaviour? My team rellies on catching other things other than plain Error objects on onError.
   If this goes forward, what do you think of having an onCatch (or similar name) which would receive anything that is thrown instead of just Error?

RTK Query has the same feature - their prop is called keepUnusedDataFor. I think this is quite descriptive but also a bit long.

2. This is a classic debate but wouldn't we rather have a long descriptive name that doesn't "force" some people to go to the docs?
   As you said, it's not something that most people customize so I don't see the annoying part of having to write keepUnusedDataFor frequently.

I would understand if we renamed an option to something shorter if part of it was redudant, for instance:

const query = useQuery({
 queryKey: ['todos'],
 queryFn: fetchTodos,
})

would turn into

//  (not actually suggesting this should be a change on v5)
const query = useQuery({
 key: ['todos'],
 fn: fetchTodos,
})

but renaming an option to something that won't still be near 100% perceptible seems wrong to me :P

What do you think?

[TkDodo]

1. How could I opt out of this behaviour? My team rellies on catching other things other than plain Error objects on onError.

Interesting, I wouldn't have considered that throwing non-Errors is useful? Why would you do that instead of sub-classing your own Error? There is also a lint rule that enforces throwing errors. Am I missing a good use-case for this?

We could theoretically expose that function, yes, but it wouldn't be onCatch. onXXX to me means "event handlers", where you react to something that has happened. It doesn't allow you to "do something". Like, onSuccess cannot be used to transform successful responses - that's what select does. So it might be something like transformError or so. Still, I would need to know very good use-cases for this. One advantage would be that we could even infer the type of TError from the return type of this function.

[ecyrbe]

Hi, this is so well though plan.

CODEMOD

Maybe it's too early to talk about tooling, but i guess we can at least list codemod options:

• jscodeshift
• ast-grep

This could take care of:

• useQuery and friends transforms
• gcTime transforms
• pending transforms (for people who want to migrate to pending instead of using isLoading)
• isInitialLoading deprecated transforms
• useErrorBoundary transforms

Logger

This one i'm not sure about the reasonning.
Indeed, useQuery can be used in SSR rendering and then meaning be rendered on the backend (for example i know ryan plans to have first class support for solid-query on solid start for SSR)
Usually on backend you want to have structured logging with meta informations added (even in non prod environments)
Having only console log logging might be a no go since on backend you'll want to send your logs on ELK + Kibana or equivalent log tooling.
What do you think ?

[TkDodo]

for codemods, we have already successfully used jscodeshift, so I would continue that path.

This one i'm not sure about the reasonning.

The reasoning is mainly decreasing complexity / size of the library for a prop that doesn't do much.

Having only console log logging might be a no go since on backend you'll want to send your logs on ELK + Kibana or equivalent log tooling.

Why would you send development logs to kibana? I guess you can also patch the console object to achieve that if it's really necessary...

[ecyrbe]

To clarify, i'm not a user of the custom logger, since i use react query exclusively on web browser. I'm just doing devil advocate work here to check if maybe this would not break any users expectations.

For example, i have applications in multiple environments before they can touch production (dev env, integration env, homologation env, prod env). Usually i have kibana for all logs even for non production environments.

If you think that logs should only be helpfull in dev env only, i guess your point is fine. But if users expect them to only be disabled in prod, maybe they will be impacted and not happy. It's a big maybe. i really have no idea.

[TkDodo]

logging happens for process.env.NODE_ENV !== 'production', so if you run in staging or testing env, you'll also see the logs. We will use the logs more to show deprecation warnings etc, so I really don't think they should show up in production.

Again, I'd like to compare our logs to the development warnings you get from react. If you can make them show up in kibana, you can have our warnings show up there, too :)

[raszi]

We had issues with the default logging behavior. We had a data error in a production build setup where the only thing we saw was retries on a query and the application became slower because of the increased loading time (since the retries).

I believe it would be good to have a way (a configuration option on the QueryClient?) to change this behavior because otherwise we won't see these issues and it is really hard to debug since they do not propagate up.

Other options, I had in mind:

• Logging the final error, when the retries failed.
• Set the number of retries before this logging happens and that can be zero in development and maybe 2 or more in production per default, but should be configurable.

[TkDodo]

you can set an onError handler on the QueryCache globally. You can log there wherever you want to:

https://tanstack.com/query/v4/docs/react/reference/QueryCache

[Newbie012]

This might be a long shot, but would you consider supporting TaskEither as queryFn? Then onError argument could be inferred.

TaskEither<E, A> represents an asynchronous computation that either yields a value of type A or fails yielding an error of type E.

[TkDodo]

I don't think so.

[dustinsgoodman]

RE: rename cacheTime

I think the need for better name is great and your highlighted exhibits are definitely good reasons to do it. However, I don't think gcTime or keepUnusedDataFor are quite right. Some considerations I want to throw out there for any rename:

• Mental overhead - Clarity in naming is typically better than making it harder to understand. What I mean by this is when someone who uses the library regularly and is trying to think of this property/use it, it should be a memorable or easy to start autocompleting name. I know what gc is and recognize the name, but it's not what I think of when I try to find this feature. keepUnusedDataFor is closer and I'd probably remember the keep part so autocomplete could help me find it in my editor and the problem goes away.

• Short v Long names - I know as developers we can be lazy but to my last point, autocomplete and typescript completion is so good these days that I think the length of the term should be negligible in your decision and the clarity of what it does should take precedence in your decision making.

• Realism about docs - I prefer (and I'm sure others would prefer) being able to look through the configuration keys to find something that reasonably resembles what we're looking rather than having to search through descriptions. With gcTime, I'd probably scan the list 3-5 times before I found it which I think hurts people wanting to use the docs/tool as discoverability is thus lower.

• Consistency across tools - Since RTK has a standard for this that people seem to understand, it might be better to align with them for those transitioning back and forth between the tools. There's definitely some value in aligning terms community wide and I'd like to maybe urge you all in that direction. 😉

On Twitter, I pitched @TkDodo the idea of staleCachePersistTTL or something similar. I don't think this is the right name either but explicitness, to me, solves many of the identified problems above. I think keeping something that involves the word "cache" would be helpful because it'll help existing users of the library find the new config option faster. TTL is the truly canonical verbiage for the expiration. Cache is still relevant as that's the underlying behavior. unusedCacheTTL would combine the RTK idea, your existing naming, and the concept you're really trying to talk about. Thoughts?

[ecyrbe]

@TkDodo Maybe i'm suggesting something that was already evaluated and rejected. so excuse in advance my ignorance.

Did you consider switching to LRU cache strategy instead of a TTL cache strategy ? This way, there would be no cacheTime to setup, but only a cacheSize one.
This would also be easier to grasp for users, as cache size is something that is easy to understand.

[markerikson]

We didn't have any particular plans for renaming fields or options in RTK 2.0...

but if we're ever going to rename things that would be the right time for us to do it.

@phry , @msutkowski - any thoughts on maybe changing RTKQ's option name at all, and trying to coordinate here?

[TkDodo]

Did you consider switching to LRU cache strategy instead of a TTL cache strategy ?

Not really, no, but I can see a couple of difficulties with that. You'd need to know upfront how many queries you would need to use at the same time. What happens if your size is 5 and you mount another component that uses a new query? We couldn't evict anything as we never remove data that is still in-use ...

So I kinda like that caching is time-based, just like Cache-Control: max-age

[ecyrbe]

I don't think it's an issue, you can just evict at release once there are no more observable .
Temporarilly cache size would be allowed to be bigger.
In practice, you will never hit this use case, since cache size will be > number of active queries.
You should also notice that max-age while being Time base, does no garbage collection. It's just a timestamp. Browsers behind the scene use LRU strategies:
https://www.chromium.org/developers/design-documents/network-stack/disk-cache/#eviction

[TkDodo]

I see, but I haven't really thought about all the implications and I think it would be a rather bigger change. The cacheTime is also about to decide how "old" data can be before it becomes "too stale" to show to the user.

Right now, if I show a query with some data, and then leave that page and come back after a couple of hours, I will get a hard loading state. That might be preferred because if that data changes frequently, showing two-hour old data might do more harm than good (intense layout shifts, for example). Or I can change cacheTime to be longer and then that data will still be there if my resource is pretty static. It depends on the resource, how often it changes etc. I don't think it's better to change that to a cache-size approach, as it's not just about memory management.

[dustinsgoodman]

RE: remove overloads

This is a fantastic consideration! Would it maybe be better to go with:

useQuery(queryKey, options)

as the only signature. As you mentioned, queryKey is really the only required argument. Hiding that in options might make its discoverability in the docs harder and lead to more bugs for new developers using the library. Food for thought but I definitely like the idea of making the signature cleaner. 😄

[ecyrbe]

This signature will not allow anyone to use the wide factory pattern that is used in a lot of code bases (collocate queryKey + queryFn )
example:

const queries = {
  listUsers: () => {
           queryKey: ...,
           queryFn: () => ...,
  },
  getUser: (id) => {
           queryKey: ...,
           queryFn: () => ...,
  }
};

....
useQuery(queries.listUsers());
useQuery(queries.getUser(id));

[dustinsgoodman]

Oh that's a great argument. I haven't seen that pattern as much so wasn't aware of it in such demand. (TIL! 😄) I think the documentation issue still exists but there's definitely ways around that.

[TkDodo]

I started to use that pattern to be able to share code between useQuery and fetchQuery for the react-router article, and then @alexanderson1993 picked it up and tweeted about it:

https://twitter.com/ralex1993/status/1570036707134676994

It's kind of a successor to query key factories.

[paul-sachs]

Ditto this for us. We're building a whole suite of tools around returning a single options object which seems to have some weird inference limitations with current types. Hopefully this'll remove those edge cases.

[dustinsgoodman]

rename useErrorBoundary

I agree ErrorBoundary is very much a React concept, but the use naming is fine as it's a configuration, not a function. I think if this was shouldThrowException or something else, it may be clearer. I wouldn't even consider throwError as an important flag to even consider and as you're expanding into other frameworks, I'm curious how this evolves.

[dustinsgoodman]

Also fwiw - it was really hard to find the docs on this flag searching the site. Took me 3-5 different searches to understand what it was doing. @TkDodo's blog was a better resource for understanding it.

[TkDodo]

useErrorBoundary still very much sounds like a hook to me 😅

Not sure what the difference is exactly between shouldThrowException and shouldThrowError ? JavaScript has no concept of exceptions - a runtime error produces an instance of the Error class, fetches produce a network error, and axios has AxiosError - a subclass of Error.

throwError would also go well with "make TError default to Error instead of unknown".

[dustinsgoodman]

useErrorBoundary still very much sounds like a hook to me 😅

Haha fair! 😂

Not sure what the difference is exactly between shouldThrowException and shouldThrowError ? JavaScript has no concept of exceptions - a runtime error produces an instance of the Error class, fetches produce a network error, and axios has AxiosError - a subclass of Error.

Thoughtless naming error over here. I think I'm really just trying to call out the prepending of the word should in place of use. throwError on its own isn't working IMO. I see that and my first thought is "so if this is true, it'll throw an error when I use it, why would I ever turn this on?" and then you get into the docs and the condition is clearer but I don't know if I would have bothered to look it up based on the name alone.

[TkDodo]

ah yeah, I missed that the extra should was added upfront. We can think about that. But it's such a word that you could to pretty much every boolean property:

• shouldSuspend instead of suspense
• shouldEnable instead of enabled
• shouldKeepPreviousData instead of keepPreviousData

so if this is true, it'll throw an error when I use it, why would I ever turn this on?

oh okay, I read it as: "so if this is true, it'll throw an error if I have an error"

but yeah, I can see shouldThrowError working here, too 👍

[dustinsgoodman]

ah yeah, I missed that the extra should was added upfront. We can think about that. But it's such a word that you could to pretty much every boolean property:

• shouldSuspend instead of suspense
• shouldEnable instead of enabled
• shouldKeepPreviousData instead of keepPreviousData

I wouldn't go that far with should_ but the idea of booleans being denoted use common syntaxes, e.g.

• enabled -> isEnabled
• suspense -> useSuspense (I know the "use" problem is here though)

Being clear that a config expects a boolean with the is_, should_ or similar prefixes feels right to me, but that's just like... my opinion man.

so if this is true, it'll throw an error when I use it, why would I ever turn this on?

oh okay, I read it as: "so if this is true, it'll throw an error if I have an error"

but yeah, I can see shouldThrowError working here, too 👍

Just saying - it doesn't have to be my suggestion but something that's clearer. To pitch some alternatives:

• useFrameworkErrors
• useJSErrors
• willThrowError (probably my favorite of these)

Trying to brainstorm the right term - I do not have the answer.

[ardeora]

Remove Overloads will make solid-query fly!

These are all awesome considerations for v5 🥳 I'm very excited for the Remove Overloads proposal. These would especially be very helpful in making the solid-query primitives more consistent and cleaner. Since solid primitives are instantiated once. Updates to options like queryKey needs to be wrapped inside a function to preserve the reactive properties. For example,

const [pageNo, setPageNo] = createSignal(1);
const query = createQuery(
   () => ['users', pageNo()], 
  fetcherFn
)

Also, if any property in the options object needs to be reactive. It again needs to be wrapped using the object getter syntax. One of the most commonly used enabled option would be made reactive like so

const queryOne = createQuery(...)

const queryTwo = createQuery(
   () => ['users', pageNo()], 
  fetcherFn,
  {
      get enabled() {
          return !!queryOne.data
      }
  }
)

These are some ugly workarounds we had to implement to make it work with the function overload API. Another issue with this implementation is that it causes inconsistencies with the query-core APIs. For example,

const [pageNo, setPageNo] = createSignal(1);

const queryClient = useQueryClient()
queryClient.prefetchQuery(
   ['users', pageNo()], // Here the query key is an array
   fetcherFn
)

const query = createQuery(
   () => ['users', pageNo()], // Here the query key is an array wrapped inside a function call
  fetcherFn
)

The new v5 proposal will solve all these issues since the new API would look something like this

const [pageNo, setPageNo] = createSignal(1);

const queryClient = useQueryClient()
queryClient.prefetchQuery(
   ['users', pageNo()], 
   fetcherFn
)

const queryOne = createQuery(...)

// 👇 ✅
const queryTwo = createQuery(() => ({
  queryKey: ['users', pageNo()] // Consistent with the `queryClient.prefetchQuery` queryKey
  queryFn: fetcherFn,
  enabled: !!queryOne.data // No confusing object getter syntax needed
}));

This will literally solve all the problems with the API and make solid-query so much nicer and cleaner to use! I'm super pumped for this proposal. Please let me know how I can help to make sure this proposal goes into production for the v5 release.

All the other changes look good to me 😄 Great job

[TkDodo]

That's great to hear 🎉

One slight correction, maybe I didn't emphasize this enough in the proposal: The overload removal does not only affect useQuery, but also the methods on the queryClient. So we will also have:

queryClient.prefetchQuery({
   queryKey: ['users', pageNo()], 
   queryFn: fetcherFn
)}

Basically, almost every function will just take one object. Exceptions are likely things like queryClient.getQueryData(key, updater) because we need to get data for a specific key.

[DamianOsipiuk]

👍 for that as well for vue-query. Same reactivity juggling we had to do to support all of those overloads :D

[TkDodo]

Update October 2nd:

I added two more points to the list:

• remove isDataEqual property on useQuery
• remove contextSharing

please take a look :)

[ecyrbe]

Context Sharing

So i'm a user of context sharing for microfrontends. Relying only on bundlers to share a common library is only one part of the equation.

It's all related to the order of context creation. With current context sharing, i don't have to pre instanciate context and pass it to all micro frontends. if i have two microfrontends that use react, they will share context (witchever one is instanciated first).

While if i have to instanciate a common context, i'll have to pass it manually to all microfrontends (even though at instanciation the host don't know if the microfrontend is using react and then instanciate context instance in the host even though i don't need it in the host or even don't need it in all microfrontends.
One worse thing if you deprecate context sharing is that i'll have to add react dependency to the host when it should really only be a bootstrapper for microfrontends.

This would really complexify microfrontends. Because i will not want to instanciate context in the host. So i will need to encapsulate context in a shared microfrontend or shared common library so that only microfrontends that need it will use it.

I would really prefer if this option stay like it is and is not deprecated

[ecyrbe]

• it's not desirable, but react needs to be used as a shared library (common single instance) and then context completely bugs because it's already instanciated
• react can't be used with different versions to work. You need to have a single common instance of react, else react bugs completely. Like i said, react need to be used as a single common instance.
• for keys, no issues, if they share the same cache and use the same keys i consider they are for the same request (i have key normalisation to evoid issues). It's pretty nice to have the same shared cache.

[TkDodo]

I see. Can you maybe comment on this?

• ContextSharing not working for different modules #2810 (comment)

[ecyrbe]

Is this issue for v4? I'm still on V3 at work. So i don't know if it's really broken on v4

[TkDodo]

there are no changes for this feature between v3 and v4 🤷

[ecyrbe]

I see. Can you maybe comment on this?

• ContextSharing not working for different modules #2810 (comment)

done here! Hope this second explanation clarify use cases for microfrontends.

[sergiidiak]

Thanks for all your hard work, and great ideas as always.
It'd be great to have an option for updating a cache when the query is successfully finished instead of writing boilerplaty code in onSuccess (usually depends on the query client that you also need to get from context). It'd drastically reduce the boilerplate code we write to update the cache with data from response, and would also separate this concern from onSuccess fn.
It could be something like

useQuery({
  queryKey,
  queryFn,
  cacheFn: <T>(data: TQueryFnData): [QueryKey, T][]
})

[sergiidiak]

Not necessarily a different cache entry.
This option could be used to update any entries including current query one if you provide tuple with the same query key and data to update in return value

[TkDodo]

but that's not really idiomatic. You'd want whatever is returned from the queryFn to land in the cache. You can do all sorts of transformations there after the actual fetch ...

[sergiidiak]

You're right...
I did not think about updating the same query cache initially. The primary use case for me was to update/set a different cache entry when e.g. I have a response with a list of items and I want to set every item of the list to the cache under its own query key.

(data) => data.map((listing) => [['listing', listing.id], listing]

or

(listing) => [['job', listing.job.id], listing.job]

[TkDodo]

what I usually do in those situations is to have detail queries pull that data in via initialData.

useQuery({
  queryKey: ['listing', id],
  queryFn: () => fetchListing(id),
  initialData: () => queryClient.getQueryData(['listings']).find(listing => listing.id === id)
})

kind of pulling data on-demand vs. pushing data down.

also, this only works well if the structure of list and detail endpoints are exactly the same.

[sergiidiak]

We also use this approach where we can though sometimes there could be multiple sources for the same "listing" that's why we, sometimes, have to push data down because 'detail' module doesn't always know in what context it is used (all because of our REST API source..). The proposal was more about simplifying the process of the push-down approach but this conversation convinced me that there should be no separate option for this.
Thank you for taking the time to read this and for valuable answers ;)

[rlesniak]

I have one, high-level dream - to make optimistic update of pagination easier.
Right now I am working on feature which consist page with pagination, and Server Sent Event. I am receiving data from this SSE and I need to insert/update data on this list. Because of a lot of cache entries (which are separate by { pageNum, pageSize }) makes it so much harder to update. I feel that I have spaghetti code in my hook... Is this even possible to simplify this in V5?

[TkDodo]

I'm not totally sure what you're trying to do / what the problem is, but I think it's the following:

• infinite queries have a special structure where we have an object at the top level that contains two entries: pages and pageParams.
• pages is what you're usually interested in, and it's an array because that's how fetches are chunked.
• Then, in each array, you have whatever is returned from your queryFn. That structure is known as the type InfiniteData:

query/packages/query-core/src/types.ts

Lines 46 to 49 in f715b30

	export interface InfiniteData<TData> {
	pages: TData[]
	pageParams: unknown[]
	}

Now if you also have filters of some kind, they should go into the queryKey, leaving you with more than one cache entry for infinite queries. For example:

['todo', 'list', { type: 'chore' }]
['todo', 'list', { type: 'fun' }]

let's assume each of them is an infinite query, and we now get an event that says: "todo number 5 is now done". We don't know if todo number 5 was chore or fun, so what we need to do is iterate over all the lists, find the entry with id 5 and update that one.

I understand that updating infinite data is a bit more boilerplate than updating normal data, especially in an immutable way. But it's not that bad. We can use setQueriesData to iterate over all matching keys, and then try to find our todo in it. If it doesn't exist, we can return undefined (or the previous data) to bail out of doing the update:

const updateTodo = (id: number, done: boolean) => {
  queryClient.setQueriesData<InfiniteData<Array<Todo>>>(['todo', 'list'], (prev) => {
    const containsTodo = prev?.pages.some(page => page.some(todo => todo.id === id))
    if (prev && containsTodo) {
      return {
        ...prev,
        pages: prev.pages.map(page =>
          page.map(todo => todo.id === id ? ({ ...todo, done }) : todo)
        )
      }
    }
    return undefined
  })
}

TypeScript playground

I'm sure there are a bunch of ways to make this more performant or in fewer iterations or more generic or so, but I wouldn't say this is so complex that it needs a drastically new api.

I would also consider updating the queryCache via setQueryData to be a somewhat advanced use-case. Most users will just invalidate and let the refetching take care of things. This is also what I would do even if there are websockets involved: https://tkdodo.eu/blog/using-web-sockets-with-react-query

[prateek3255]

We also had a similar problem of doing optimistic updates for infinite queries, and in our case the data to be modified was also deeply nested, so we relied on immer to optimistically update the data. It is a really weight library that provides an API to update immutable data in a very simple way.

[iway1]

in our codebase we just had a utility function for making these types of updates then you only have to write this mess once in a completely typesafe way, IE:

export default function updateInfiniteQueryItem<
    ItemType extends { id: string },
>({
    data,
    updateId,
    updater,
}: {
    data: InfiniteData<BasePaginatedOutput & { items: ItemType[] }>
    updateId: string
    updater: (item: ItemType) => ItemType
}): InfiniteData<BasePaginatedOutput & { items: ItemType[] }> {
    const newPages = [...data.pages]
    let pageIndex = 0
    for (const page of newPages) {
        const itemIndex = page.items.findIndex((e) => e.id == updateId)
        if (itemIndex !== -1) {
            // update
            const newPage = {
                ...page,
                items: [...page.items].map((e) =>
                    e.id == updateId ? updater(page.items[itemIndex]) : e,
                ),
            }
            newPages[pageIndex] = newPage
            break
        }
        pageIndex++
    }
    return {
        ...data,
        pages: newPages,
    }
}

export function deleteInfiniteQueryItem<ItemType extends { id: string }>({
    data,
    updateId,
}: {
    data: InfiniteData<BasePaginatedOutput & { items: ItemType[] }>
    updateId: string
}): InfiniteData<BasePaginatedOutput & { items: ItemType[] }> {
    const newPages = [...data.pages]
    let pageIndex = 0
    for (const page of newPages) {
        newPages[pageIndex].items = page.items.filter((e) => e.id !== updateId)
        pageIndex++
    }
    return {
        ...data,
        pages: newPages,
    }
}

This can be used for any infinite query in our whole code base (as long as the backend is returning the same structure from different end points.) This code is for updating a single item in an infinite query, but you could do something very similar for optimistically updating pages I'm sure (this just updates the data object without actually setting the query data, but really that's the only hard part of this)

[kaueDM]

About the cacheTime rename, what about something more "direct" instead of gcTime? I would suggest discardCacheAfter. You don't need to open the docs to understand what this property does.

It would be amazing a way to reuse select somehow when retrieving data from cache with getQueryData. In our current application we have some data renaming/filtering on our queries, but in some cases we need to access the data directly from the cache and to be usable we need to replicate the select function.

[TkDodo]

I would suggest discardCacheAfter.

The latest suggestion would be inactiveCacheTime (how long inactive queries are going to be cached) and I like that a lot because it's a) not a big change, b) quite descriptive and c) the inactive name is already what we use to describe those queries in the devtools and the query filters.

It would be amazing a way to reuse select somehow when retrieving data from cache with getQueryData

The problem here is that select is a per-observer option. That means you can do:

const useTodos = (select) => useQuery({ queryKey: ["todos"], queryFn: fetchTodos, select })

and call that in two different components with:

function FirstComponent() {
  const todoCount = useTodos(todos => todos.length)
}
function SecondComponent() {
  const firstTodo = useTodos(todos => todos[0])
}

they would both subscribe to a totally different "slice" of the query key, which makes them highly optimized. For example, the FirstComponent would not re-render if I update the first todo, because the count didn't change. The SecondComponent would not re-render if I add a todo because that doesn't influence the first todo.

That is what select is for, conceptually :). getQueryData will always give you what is in the cache directly. There is also no subscription involved (it just gets the data once), so optimizations are not necessary. That means, the best you can do is extract the selectors and share them:

const selectTodoSize = () => todos => todos.length
const size = selectTodoSize(queryClient.getQueryData(["todos"]))

[0commitment]

@TkDodo Use case for custom logger:

Run tests in development mode (NODE_ENV='development') but somehow? mute react-query logs so that they don't pollute test results for expected errors.

[TkDodo]

We won't be logging errors from failed queries anymore in v5. Those would be indeed annoying because you would see them when you test failed queries. The logger will be purely for things that you should address (like wrong query keys, invalid data returned from a queryFn, ...), so I think it's good that they show up during tests.

A good comparison would be the key warning react prints to the console, or the not wrapped in act() warning you'll see from testing-library.

[sbaechler]

The thing is that Axios actually does log errors for failed queries to the console. We are overriding the error logger in React Query with a null handler to stop this.

[TkDodo]

I don't think axios does this? React Query does it, and as I said, we plan to remove it.

[ericbiewener]

We won't be logging errors from failed queries anymore in v5

This is a key point you may want to elevate into the custom logger section in the main post of this thread. My team's use case is that we fail tests if any console.error calls are made. I came to this thread concerned that we'd need to sniff the stack trace or something on console.error logs to see if they emanated from failed queries and could thus be safely ignored. Glad to know that won't be the case 👍

[TkDodo]

My team's use case is that we fail tests if any console.error calls are made

This is actually one of the reasons why I want to introduce the logging behaviour. Logging failed queries yields to console.errors right now, so if you test failing queries you have to overwrite the logger. failing tests on console.error is a good practice imo because it fails your tests on react key warnings, or dom hydration warnings or similar things. So I want to make this easier, and there is no real advantage to logging failed queries, as this is not a developer error that you need to warn about. They are also visible in the network trace

[ianschmitz]

Thanks for the transparency on the roadmap! I have a question about isPending:

Pending with regards to Promises in JS implies that there is an instance of a promise, and it is yet to fulfill or reject. If i understand the current proposal correctly, isPending would be true for a useQuery instance that is set to disabled. Does that feel a little strange to anyone? In my naive mind if i didn't deeply read the docs my assumption would mean that pending means that the request is in flight, and we don't know the result yet.

Furthermore would this get confusing as we start to think about the future of the use hook in React that deals directly with promises?

I mention as the goal seemed to be to clear up confusion of the way things are represented currently, but i'm hoping we aren't introducing new confusion 😃

[TkDodo]

maybe we need a state machine?

we kind of have an internal state machine.

Not sure why? Why is there no disabled state in the first place?

There used to be an idle state in v3, but it had some problems:

1. you couldn't type-narrow data by excluding error and loading because there was always the 4th state even if you are not using enabled.
2. with the introduction of the fetchStatus for offline support, the idle status was an exception to all other states because it was the only state that didn't combine well with the fetchStatus. You can't be idle and paused or idle and fetching.
3. idle wasn't really a "state", as enabled is only an observer property that says: this instance will not fetch data by itself. It will still receive updates and even though you pass enabled:false, there are tons of other reasons why the query could go into success state, for example, by calling queryClient.setQueryData for that key.
   The important bit is: A query cannot be disabled :) A query is an entry in the queryCache, and it will always "be there" when you call useQuery.

waiting, initiating, parked, unavailable, initializing, preparing or blocked.

none of these communicate to me a state that means: "I am a query that doesn't have data". 🤷‍♂️

---

on the other hand, I'm still inclined to do the rename because the loading state means something different right now for a mutation (it really means fetching). It's confusing that loading means two different things, while success and error are streamlined.

[someone635]

@TkDodo Hi, has "blank" been proposed yet? isLoading = isBlank && isFetching seems pretty descriptive, short and without possible confusion (unlike empty or undefined).

And from the definition of a blank: "a space left to be filled in a document", there's even this idea that there is no data "yet".

[TkDodo]

we've settled for isPending

[tonyxiao]

we kind of have an internal state machine.

Let me know if I missed this in the docs, but would be great to have a table of all combinations of status and fetchStatus and the situation of when they occur plus recommended way to handle them in the UI.

[TkDodo]

not a table, but they are all described here: https://tanstack.com/query/v4/docs/react/guides/queries#query-basics

[Ephem]

Since it's a big subject on it's own and not all of it necessarily related to v5 (some can be done in minors), I posted a braindump on my current thinking around React SSR/Server Components over in this discussion. Some of the actionable things can probably be cross-posted here in the roadmap already, or do it as a umbrella issue thingy, and some we can copy in here when we've figured them out?

[wolverineks]

just my vote...
cacheTime -> inactiveCacheTime
staleTime -> activeCacheTime

[TkDodo]

I wouldn't want to name them both with the cacheTime postfix, because they do different things when they expire:

• when the inactiveCacheTime expires, data will be removed from the cache
• when the staleTime / activeCacheTime expires - nothing really happens and nothing is removed or refetched right away. Queries will be marked as stale, and they will be refetched at the next point in time determined by the heuristics.

[wolverineks]

ah, interesting. I was thinking they describe the state of the data more than an event.
active queries will remain in a "cached" state for ...
inactive queries will remain in a "cached" state for ...

[wolverineks]

although, stale describes the "after" and cache describes the "before". I still find that a bit dissimilar.

[wolverineks]

in that regard, gcTime actually makes more sense now

[arthurdenner]

@TkDodo, I noticed that while the plan is to have one signature for all methods and that's a good change IMO, the current ESLint rule only checks for queries (ref). Could the rule be extended to match the other methods too, e.g. useMutation?

PS: Sorry if many people get pinged with this comment

[arthurdenner]

I don't know the plans to launch the v5 date-wise but here is a bit more context: In my scenario, where we use micro-frontends and have many projects to update, even when codemods are available, it can take a while to update all related projects, so we try to stay ahead on major breaking changes and notify the teams as soon as possible.

Since the rule will be removed for v5, the effort is not necessary for me at least. We have other tools to ease the update, like patching the library itself to force/recommend an update today at runtime, I'll move forward with it. Thank you all!

[TkDodo]

Since the rule will be removed for v5, the effort is not necessary for me at least.

The thing is, if we have the eslint rule now and people are using it, it will tell them to upgrade to the new syntax now, because the syntax is already valid in v4 (just not as common because we didn't teach it). This will make upgrading easier when v5 comes out, because there's fewer things to do for you.

@Newbie012 if we can make it work for useMutation as well, that would be great ❤️

[Newbie012]

I raised a PR. Although, I'm not sure why Vercel keeps failing

[TkDodo]

vercel failure can be ignored. It's about preview deployment of the docs 🙈

[arthurdenner]

I've patched the library for now since modifying the parsers in the query-core.utils module allows me to detect and warn/log a non-object signature in almost all of the cases: prefetchQuery, invalidateQueries, etc.

And I reinforce that an ESLint rule is a much more friendly approach. The more it can be done that way, the better for sure.

[debater-coder]

Could some functionality that exists in community libraries such as react-query-kit be integrated into the core library? Or is it better to keep out separate? Regardless, I would love to see some more official support for this kind of functionality.

[Akash187]

@TkDodo I followed the instruction in the documentation yarn add @tanstack/react-query but it installed v4.24.4

[TkDodo]

v5 is not out yet. Latest is v4

[Akash187]

Can we mention that on docs because documentation is clearly deceptive?

[TkDodo]

please go ahead

[Akash187]

Hey @TkDodo My Ideas is to remove v5 option from the documentation. Saidly I didn't find code to update the select options. Hope you can update it or let me know the file to update.

Thanks

[devinrhode2]

Based on the open tickets seen on milestone/2 linked at the top..
It seems like v5 is "ready enough" if you aren't doing SSR:

I wonder if there are any open issues NOT added to this milestone, which would give most CSR folks pause?

(my team/project isn't using react query yet, so I'd rather not write new code which will get deprecated in a few months)

[TkDodo]

• we've just deprecated the callbacks on useQuery
• we might break some things slightly in useQueries

I don't want to go to beta without having an API that I think will stay stable

[devinrhode2]

Ok, sounds v5 is still in alpha? Use at your own risk?

[TkDodo]

v5 is currently at v5.0.0-alpha.18. We will break some things, and we don't have all codemods yet, but I think it's pretty good to try out, especially on a new side project.

[igortas]

@TkDodo with the new breaking change, removing onSuccess, onError for useQuery, how the select handler stays? If onSuccess getting out of sync, why select not... How I can adapt code, where I had select and onSuccess , now moving to useEffect probably...

// OLD
useQuery({
select: () => // ...some code,
onSuccess: () => // ...some code...
});

// NEW
useQuery({
select: () => // ...some code,
});

useEffect(() =>{
   if (isSuccess) {
   // ... some code
   }
}, [isSuccess])

[TkDodo]

select does something totally different. It's a data transformation, that is, on purpose, run for every observer, because it can literally create different results of your data. It also has to be pure, so we can run it on every render:

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

now, I can do:

const { data } = useQuery(todoOptions) 

and my data will be an Array of Todos, but I can also do:

const { data } = useQuery({
  ...todoOptions,
  select: todos => todos.length
})

in which case my data will be a number, or , I can do:

const { data } = useQuery({
  ...todoOptions,
  select: todos => todos[0]
})

in which case data will be a single todo (or undefined if there if todos is an empty array)

---

This transformation can run on every render, regardless of if we've just fetched data, or if we just read it from the cache, because it has no side-effect. There is no console.log or "show a toast" in here...

(note that if you want to optimize select, you can do that with useCallback. See: https://tkdodo.eu/blog/react-query-data-transformations#3-using-the-select-option)

---

It is also on purpose that you can have multiple components mounted simultaneously that use the same query, but have different select options specified. This is usually not the case with onSuccess - you'd expect it to run once (but it doesn't). So, I'm having a hard time understanding the comparison between select and onSuccess.

---

As to what you should use instead, that depends on what you were doing exactly. A lot of usages of onSuccess that I've seen were bugs in disguise where users thought it would only run once, and if I said "move it to an effect", the answer was often "but then it runs for each component, I don't want that", to which I then reply "you had the same issue before, you just didn't notice it".

So as far as I've seen so far, there are solutions to all problems that you're having where you thought you need onSuccess, but there is no definitive "just use an effect instead" answer. It depends. I've outlined some takes in the blopost: https://tkdodo.eu/blog/breaking-react-querys-api-on-purpose

[shijistar]

Rather than using useCallback for select performance optimization, it is more strongly recommended to make it into eslint's recommended rule and provide automatic code fixes. Because a large number of select usages are now anonymous arrow functions, resulting in repeated execution of select at each render, the default behavior has too much unnecessary performance loss.

It would be great to provide an eslint rule that hints at and automatically fixes this usage! Is it considered to be added in v5.0?

[romanslonov]

Hello everyone. Is it possible to somehow share data between vue-router and vue-query? My use case is: I need to fetch user profile and some other data from server to understand, can user go to some route or not. And I want to use all benefits of vue-query for that. Now we can use vue-query only inside vue components which is a problem, at least in my case.

So is it possible workaround? In features releases or maybe I missed something? Thanks.

[DavidVaness]

Did you find a solution?

[romanslonov]

Kind of. In last versions of vue-router you can inject context, so you can provide your queryClient and set cache data for that inside your router guards. @DavidVaness

[jonnylink]

I might've missed it, is there any prediction on when v5 will be officially released?

[TkDodo]

couple of months tops

[jonnylink]

Cool cool. Thanks for that. Love what you do!

[m4ttheweric]

The proposal for changing the loading/fetching flags sounds great. Having a simple isLoading flag that actually can be linked to a loading UI state sounds like a no brainer win. Looking forward to this release!

[TkDodo]

Yep, we have that in v5 already (currently in rc)

[karasavm]

Thanks for this new awesome version. Really like the new query status approach.

From migrating to v5 from v4 there is a missing case, that maybe is intentional.

On v4
I used to useQuery with suspense: true and useErrorBoundary: false. So, I am showing the loading skeletons on a Suspense fallback prop and the error handling is implemented inside the component that is using the useQuery with suspense.

NOW on v5
If I use the useSuspenseQuery I am not able to use the renamed useErrorBoundary (throwOnError), so I have to refactor in order to use ErrorBoundaries. Maybe the intention is on suspense queries to use ONLY ErrorBoundaries.???
I understand that, if you give the ability to throwOnError: false on a Suspense query the data will not always be defined.
What if it is not convenient to use ErrorBoundaries?

I would like to understand this intention :)

PS There is a misleading definition related to the above statement on useQuery docs, on throwOnError property, third bullet.
- Set this to false to disable suspense's default behavior of throwing errors to the error boundary.
This can not be happened according to v5
(https://tanstack.com/query/v5/docs/react/reference/useQuery)

[TkDodo]

Yes, that change is on purpose. Suspense is the idiomatic react approach to data loading. It comes with error boundaries for error handling. It's also what make sure that data is always defined, which is sometimes that a lot of people value when working with react-query.