notifyOnChangeProps to also accept a callback

[paulobmarcos]

Hey TanStack team!

First of all, thank you for your amazing work with the TanStack/query 🚀

Problem

With notifyOnChangeProps we can make a component only re-render if any of the listed properties change. This is very useful and we can completely stop all re-renders if needed with an empty array [].

We have a use case where we want to completely disable re-renders that would come from data fetching when components go into an "hidden"/"sleep" state.

This is achievable by setting component state and use that as a condition to pass in a different notifyOnChangeProps value.

Basic Example:

const useSharedDataHook = (options) =>
  useQuery({
    queryKey: ['myExampleKey'],
    queryFn: async () => {
      const response = await fetch(
        'https://api.github.com/repos/tannerlinsley/react-query'
      );
      return response.json();
    },
    ...options,
  });

const MyExampleComponent = () => {
  const [hidden, setHidden] = useState(false);
  const { dataUpdatedAt } = useSharedDataHook({
    notifyOnChangeProps: hidden ? [] : undefined,
  });

  const toggleHidden = () => setHidden((h) => !h);

  return (
    <>
      <div>DataUpdatedAt: {dataUpdatedAt}</div>
      <button onClick={toggleHidden}>Toggle Hidden</button>
    </>
  );
};

So, if any other component uses the same queryKey to update the data, the component won't re-render.

However, this still requires one extra re-render to change the notifyOnChangeProps value and we have a use case where the extra re-render could be considered expensive.

Proposal

The notifyOnChangeProps would be extended to also accept a callback. The return type of this callback would be string[] | "all".

This way, we could change the return value of notifyOnChangeProps without an extra re-render.

Basic Example:

const MyExampleComponent = () => {
  const hiddenRef = useRef(false);

  const notifyOnChangeProps = useCallback(() => {
    return hiddenRef.current ? [] : undefined;
  }, []);

  const { dataUpdatedAt } = useSharedDataHook({ notifyOnChangeProps });

  const toggleHidden = () => {
    hiddenRef.current = !hiddenRef.current;
  };

  return (
    <>
      <div>DataUpdatedAt: {dataUpdatedAt}</div>
      <button onClick={toggleHidden}>Toggle Hidden</button>
    </>
  );
};

Unknowns

I'm still unsure if there would be any side-effects by opting for a callback instead.

From the example above, the only probable side-effect I'm able to think of is that the data wouldn't be immediately up to date if the component stopped being hidden, probably requiring a manual "refetch" or wait for another data fetch.

[TkDodo]

I think the react way would be to unmount the component if it's going to be "hidden"

[TkDodo]

ah okay got it. Sooo, there is another thing that actually stops subscriptions:

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

Lines 62 to 72 in 457723f

	const unsubscribe = isRestoring
	? () => undefined
	: observer.subscribe(notifyManager.batchCalls(onStoreChange))
	// Update result to make sure we did not miss any query updates
	// between creating the observer and subscribing to it.
	observer.updateResult()
	return unsubscribe
	},
	[observer, isRestoring],

If we are in restoring state, components render, but are not subscribed to the QueryCache. When can we be restoring ? Well, we have our own Provider for that that has a boolean value:

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

Lines 4 to 7 in ba7fc56

	const IsRestoringContext = React.createContext(false)
	export const useIsRestoring = () => React.useContext(IsRestoringContext)
	export const IsRestoringProvider = IsRestoringContext.Provider

We currently only use this context to signal that we are restoring from our persist plugins:

query/packages/react-query-persist-client/src/PersistQueryClientProvider.tsx

Line 54 in a6186e5

<IsRestoringProvider value={isRestoring}>{children}</IsRestoringProvider>

The Provider and the hook are exported, so what you could try is:

• render this Provider on your screen
• provide it true when you want to unsubscribe
• set it back to false when you want to subscribe

It's not what we have intended the provider for, at least according to the name, but if unsubscribing from queries while keeping data rendered on the screen is a real use-case, I'd rather push this as a solution rather than the notifyOnChangeProps, given that it works for you.

If that's the case, I could consider a re-name in v5 (because you are not restoring anything here).

[ferrannp]

Mmm I see @TkDodo, the problem with that though (again) is that we need to trigger a re-render of the screen (or the wrapper that wraps the screen) to change the value for the provider, correct? And that will happen when navigating in RN, and anything that happens while navigating will drop frames. Is there a way we could do something like this:

const {subscribeToQuery, unsubscribeToQuery} = useQuery(...)

useFocusEffect(useCallback(() => {
  subscribeToQuery();
  return () => {
     unsubscribeToQuery();
  };
},[subscribeToQuery, unsubscribeToQuery])

While still using useQuery and without forcing any extra re-renders?

This would give us tremendous amount of control over the subscriptions without causing performance issues in RN.

[TkDodo]

okay, back to notifyOnChangeProps it is :)

Is there a way we could do something like this:

This is pretty much what useQuery does under the hood. You could create your own custom hook that also creates a QueryObserver and then subscribes / unsubscribes in useFocusEffect instead of useSyncExternalStore. QueryObserver is the primitive from query-core that has subscribe / unsubscribe methods

[ferrannp]

Yup. We were thinking though how to contribute so we do not have to maintain our own hooks. I was thinking if you would be ok to have a useQuery.native.tsso, basically the react-native packager would pick that (and web will use the normal useQuery.ts). Then, we could have some arg like unsubscribeOnBlur (maybe even others like unsubscribeOnBackground - we can thing of all those) and for example, if you pass unsubscribeOnBlur and you do not have react-navigation installed, you would see a warning (in web, that prop would be ignored). But I was wondering if changing useQuery like creating a useQuery.native would be enough or if we would need to touch other hooks too?

[TkDodo]

so this would mean we'd need a copy of every hook with a .native.ts extensions, where we go away from subscribing in useSyncExternalStore and switch towards useFocusEffect. I'm not sure I like that too much from a) the maintenance effort and b) react concurrent features really need us to useSyncExternalStore or we risk tearing.

I think the notifyOnChangeProps function is still the best move

[paulobmarcos]

Hey @TkDodo! I have a branch ready and would like to open a PR.

However I might not have permissions to push to a branch. What is the best away to do so? 🙏

[TkDodo]

create a fork, create a branch there and then create a PR from your fork to our repo :)

[paulobmarcos]

Thank you so much @TkDodo for merging the PR: #5734

---

A few more questions that could further improve this experience.

We tried this approach, since it's now live, and we hit what I described here: #5588 (reply in thread)

Whenever a fetch happens, if a component is not listening to any prop changes it could end up with "outdated" data.
Here is an example on React Native:
https://github.com/TanStack/query/assets/11398440/61d80168-ef5f-4973-911f-848ab1eb2ade

To fix this, we could call refetch again to get the latest data whenever a screen is visible again. However, calling refetch usually triggers another API call.

So how could we get a screen/component to re-render/get the latest data from cache?

• A new method returned by useQuery?
  • A forceUpdate method?
• A new refetch option?
  • A preferCache option?
    • This option could check if there is something on cache, and if there is, return that instead.

What are your thoughts @TkDodo?

Thank you once again for all you support! 🙇

[ferrannp]

I would vote for options two.

refetch({preferCache: true})

^ in this case, if there is data in the cache, force a re-render (to get the data) but do not perform a request. If we pass preferCache: true but for some reason there is no cache, perform the request.

[TkDodo]

if you only need to trigger a re-render, please do that with react state.

[pedrosimao]

Seems like a simple enough solution indeed...
Great PR btw!