Proposal: Allow throttling invalidations

[todor-a]

In applications using mutations and server-sent events (SSE), a common pattern involves invalidating queries upon both successful mutations and SSE updates. This can lead to redundant refetches when a mutation triggers an SSE event shortly after, resulting in over-fetching.

Current Workarounds:

• Removing invalidation from onSuccess: Sacrifices immediate UI updates post-mutation.
• Throttling SSE handling: Not a TanStack Query-native solution and adds complexity.

Proposed Solution:

Introduce a throttle option to queryClient.invalidateQueries() to prevent rapid, redundant invalidations for the same query key.

API Suggestion:

await queryClient.invalidateQueries({ queryKey: ['foo'] }, { throttle: 1000 });

Benefits:

• Reduces over-fetching in scenarios with mutations and SSEs.
• Provides a TanStack Query-native solution for a common data synchronization problem.
• Offers a simple and declarative way to manage invalidation frequency.

Discussion Points:

• Specific implementation details of the throttling mechanism.
• Potential impact on existing applications.

Note: I'm aware that I might've missed a piece of the puzzle here and such an option (or an alternative way to do that) already exists. If this is the case, I would love to know how.

Note 2: I would be happy to work on this.

[TkDodo]

This can lead to redundant refetches when a mutation triggers an SSE event shortly after, resulting in over-fetching.

I don’t necessarily agree with this, as the first invalidation could’ve already read the state on the backend when the new event comes in, and it might then return outdated data.

That’s why calling invalidateQueries will, per default, abort the current refetch and trigger a new one when called. You can opt out of this by passing cancelRefetch: false to the options of invalidateQueries.

Other than that, have a look at TanStack Pacer, which offers throttling utilities to do this in user-land: https://tanstack.com/pacer/latest/docs/guides/throttling

But we will not build this into react-query.

[todor-a]

I did in fact go with pacer for the throttling implementation. Will experiment more with cancelRefetch as well. Thanks, Dominik.