RFC: create subscriptions for query

[MrFlashAccount]

Hello everyone,

I would like to express my gratitude for this exceptional library. It is undoubtedly a crucial component of contemporary architecture.

The Problem

We are currently developing an IDE that must be capable of displaying thousands of elements simultaneously and efficiently updating them. To achieve this, we have integrated react-query, suspense, and selectors. However, we have encountered performance limitations that require our attention. Notably, approximately 80% of the mounting time is allocated to react-query subscriptions. Additionally, creating a subscription necessitates the transmission of superfluous data (from the perspective of nested components) to recreate queryFn and queryKey. This process introduces complexity into testing, necessitating the mocking of unnecessary components.

The performance issues associated with subscriptions have been discussed in detail in this thread: https://x.com/MrFlashAccount/status/1857881760110952926.

Several attempts have been made by @TkDodo to address these performance concerns, but the proposed solutions potentially involve breaking changes.

For reference, please see the following links:

• Feature/stale time on query #8313
• Feature/stale time on query attempt 2 #8360

Proposed Solution

To address the performance concerns, we propose introducing a new field named subscription to the query object. This lightweight wrapper will eliminate stale time checks, garbage collection, and other query-related operations, leaving only subscription-related options (such as select).

The query-related options are not needed, because subscription exist only when useQuery exist.

We will also introduce a new hook called useSubscription that accepts a subscription property and returns the relevant data.

For demonstration purposes, we have provided an example using zustand and @tanstack/react-query: https://codesandbox.io/p/devbox/react-query-subscription-q75dpg. Please note that this example serves as a demonstration and should be adapted to address various edge cases.

Usage of the API: https://codesandbox.io/p/devbox/react-query-subscription-q75dpg?file=/src/App.tsx:51,2

Potential API could look like:

  // Defining a query. the `useQuery` returns a `subscription` field
  // that is bounded to this query.
  // subscription has a stable reference and doesn't change if we change a queryFn or queryKey.
  const { promise, subscription } = useQuery({
    queryKey: [props.q],
    queryFn: ({ queryKey: [q] }) => {
      return fetchData(q);
    },
  });

  // Somewhere down in the components tree:
  // call the `useSubscription` hook and pass
  // subscription with subscription-related options,
  // like `select`: 
  const itemName = useSubscription({
    subscription,
    select: (data) => data.find((item) => item.id === id).name,
  });

Things to address:

• Support for use API in React (should it extend the Usable interface? Should it be just a promise?)

Implementation details

No idea ATM as I'm not deeply familiar with query internals.

[TkDodo]

Thanks for proposing this. What you are basically proposing is an observer that only watches a cache entry, but can never actually fill it. That requires this observer to be created further down the component tree than another one that has a valid queryFn.

We’ve thought about a useQueryState hook before that does this. The problem here is that imo, it creates an implicit coupling between the component that initiates the query and the component that only reads the query state.

Usually, components with useQuery are independent. You can move them around your component tree rather freely and they will “just work”, because they will either initiate the fetch themselves, or they will read from the cache and potentially trigger a background refetch. A useQueryState hook would basically always return data as undefined unless a parent has put data into the cache, so the component might work in one component sub-tree, but stops working when moved to a different sub-tree.

Your subscription proposal is a good way to side-step that problem. Given that a subscription can only be created by useQuery, you need a parent to pass down that subscription via props or context, so this coupling becomes more explicit, which is good.

Perf wise, it yields another problem though: One an update comes in, the component that has useQuery will certainly re-render, so the whole tree, including all useSubscription sub-components, will re-render. You would have to break that chain somehow with memoizing child components. Passing notifyOnChangeProps: [] to the parent useQuery can work, in which case the useQuery would only be the one that creates the subscription for children. I would rather see this as a separate hook that creates a subscription and nothing else.

Another problem is that you might not want a useQuery at all - data could be prefetched in route loaders with an imperative method. If you’re doing that, you can’t use useSubscription at all, because you have no subscription created by useQuery. We could have hooks like usePrefetchQuery and imperative functions like prefetchQuery also return a subscription to pass down - this would fix the re-render issue (as those aren’t observers at all).

---

All in all, I think there are too many “ifs” here for us to provide this functionality out of the box right now. What you can do is implement a useQueryState function yourself by subscribing to the query cache directly. I think we export everything that you’d need for that.

As a similar example, have a look at the useMutationState hook:

https://github.com/TanStack/query/blob/8fe90104c6fce9654539e006bd739074e15ae70f/packages/react-query/src/useMutationState.ts

It subscribes to the mutation cache and uses useSyncExternalStore, refs and structural sharing (replaceEquaLDeep) + a select API to allow subscribing to parts of a mutation without having an active observer. We made this for mutations because they are fundamentally different than queries, and without that, there is no way to read data of a mutation in another component.

For queries, we always said “just useQuery again”, but if mounting an observer is too much overhead on your end, this would potentially be a suitable replacement.

If this works well for you, and we find a good way to create subscriptions, we might add this in the future internally. I currently like the idea of usePrefetchQuery or other imperative prefetch methods to create a subscription, however, it goes a bit agains the core functionality of react query of being a “data synchronization tool”. If you only do prefetching + useQueryState, you’d have zero observers and thus would never get a refetch to sync your data with the backend.

Also note that without observers, a query is not considered “active”, as a direct cache subscription is not a subscription to a query per se. So you have to be aware of potential garbage collection, too.

[MrFlashAccount]

Thank you for your detailed response.
I wholeheartedly support your perspective, and my proposal is merely my vision for addressing this issue. However, I would like to address some of your statements:

We have considered a useQueryState hook that accomplishes this task. The primary concern with this approach is, in my opinion, that it establishes an implicit dependency between the component initiating the query and the component solely responsible for reading the query state.

This was initially our architectural consideration. We intended to subscribe to errors, data, and loading states, but we refrained from employing passive listeners for fetching operations. Unfortunately, this approach resulted in more complications than solutions. Consequently, we abandoned this approach.

From a performance standpoint, this approach also presents a challenge. Upon an update, the component using useQuery will inevitably re-render, causing the entire tree, including all useSubscription sub-components, to re-render. To mitigate this issue, we would need to break the re-rendering chain somehow through memoization of child components. Passing notifyOnChangeProps: [] to the parent useQuery can effectively achieve this, as it would only create the subscription for the children. However, I prefer to envision this as a separate hook that solely creates the subscription, without any additional responsibilities.

This is a valid question when considering the broader ecosystem. The default behavior should be “no memoization” and “no compiler.” The useQuery with subscription does not imply that the result of the useQuery will not be utilized. The approach remains unchanged: we fetch data only when necessary. The subscription serves as an advanced technique, primarily beneficial for 5% of potential developers. Given that we focus on optimizing the most performance-critical components, these developers tend to be more proficient in memoization techniques. Therefore, my perspective is that most developers will not utilize this feature, while others will significantly benefit from it. I believe it is quite similar to exposing promises or refetch, isn’t it?

I do not fully comprehend your point regarding a separate hook. How would it differ from useQuery? One of the primary advantages of returning a subscription property is to provide query management through useQuery. An explicit subscription guarantees that the data will not be collected.

Another issue is that you may not require a useQuery at all. Data could be prefetched in route loaders using an imperative method. If you are doing that, you cannot use useSubscription because you have no subscription created by useQuery. We could implement hooks like usePrefetchQuery and imperative functions like prefetchQuery that also return a subscription to pass down, which would resolve the re-render issue (as these are not observers).

I do not perceive this as a problem. Neither ensureQueryData nor prefetchData are subscriptions. They fire only once and return only promises. This API is imperative, unlike the useQuery hook. Therefore, I view it as intended.

In summary, we are internally considering using a combination of @tanstack/react-query and zustand. The codesanbox above is a minimal implementation of our solution that we are testing internally (it is not yet public). We prefer to extend the useQuery, useQueries, useSuspenseQuery, and useSuspenseQueries hooks (although this would be tedious), but we have concerns that this may cause significant issues when we decide to update the library.

A custom hook may be a solution, but it will not guarantee the connection between a mounted query and a consumer.

Ideally, we would like to see this as a built-in feature in the future, if feasible.

Would you like to test this approach with us? We can implement it on our side, test it in a portion of our application, and share the results with you. Then, we can iterate over and compare the potential gains with additional work and determine if it is worthwhile.

[TkDodo]

Unfortunately, this approach resulted in more complications than solutions. Consequently, we abandoned this approach.

👍

The subscription serves as an advanced technique, primarily beneficial for 5% of potential developers. Given that we focus on optimizing the most performance-critical components, these developers tend to be more proficient in memoization techniques.

That’s definitely a reasonable assumption. What I want to avoid is widen the api surface and increase our code base (including bundle size) for something that won’t be requested much, especially if it can be built in user-land, too.

The question is: can it be built in user-land? Subscribing to the cache directly is not the same as creating an observer. The biggest difference is that cache subscriptions are not tied to a single query - they listen to everything happening in the whole cache. Yes, it can be filtered down to events and query keys/hashes, but the query will still not be seen as “active” by us, leading to the garbage collection problem.

Maybe sub-classing a QueryObserver would be possible on your end, as this is what we do for InfiniteQueries as well, but I think many observer features are baked into the base class as private functions that can’t be overwritten.

I do not perceive this as a problem. Neither ensureQueryData nor prefetchData are subscriptions. They fire only once and return only promises. This API is imperative, unlike the useQuery hook. Therefore, I view it as intended.

That’s fair. My thoughts were about using an imperative prefetching, getting a subscription back and then only using the light-weight option, but as you mentioned - you’d still want a useQuery at the top that’s fully tied to the query lifecycle.

In summary, we are internally considering using a combination of @tanstack/react-query and zustand

I think this is similar to what I’ve written about with React Query and React Context. Context doesn’t allow selectors, but zustand does, so if you do this on purpose, I think it’s fine.

Ideally, we would like to see this as a built-in feature in the future, if feasible.

I don’t see an “easy” way to achieve that, but let me think about it some more. Maybe refactoring the QueryObserver and allowing a more light-weight sub-classing, combined with exposing our useBaseQuery hook that wants an observer passed can work, but I’m really not sure 😅