Adding event-based invalidation support

[jimmycallin]

Hello!

We have quite a few useQuery and useInfiniteQuery wrappers, that we over the years have managed to move more and more logic into react-query's queryOptions and infiniteQueryOptions, which has been great since we have been able to reuse these for both dynamic useQueries, as well as prefetching from the router's loader.

There is one part of these wrappers we haven't been able to integrate, and that is our query invalidation logic. We listen to webhook events for update events to various entities, and in case an update matches the rendered entity, we invalidate the query.

Essentially, our hooks look like this now:

function getEntityQuery(entityId) {
   return queryOptions(...)
}


function useEntity(entityId) {
    const query = useQuery(getEntityQuery(entityId));
   const queryClient = useQueryClient();
   const invalidate = useCallback(() => queryClient.invalidateQueries({ queryKey: query.queryKey }), [queryClient.invalidateQueries, query.queryKey]);
   const matchFn = useCallback((entity) => entity.id === entityId, [entityId]);
   // useUpdateEvent runs matchFn on each incoming webhook event, and onMatch if matchFn returns true
   useUpdateEvent({ matchFn, onMatch: invalidate });
   return query;
}

This works overall pretty well for us - we can fetch entities in a common way, and automatically have them invalidated as update events matching the entity are passed.

What I would love to have is to have the event invalidation more tightly integrated into react-query. There are a few reasons for me wanting this:

• I would love for us to completely lose the useEntity wrapper, and have each component call getEntityQuery directly, and passing it into useQuery, useSuspenseQuery, useQueries, useInfiniteQuery, queryClient.ensureQueryData, etc, without having to create new hooks for each scenario. As long as I care about data invalidation on webhook events, I can't come up with a good way to do this.
• Fine-grained invalidation of useQueries would be quite useful, by being able to allow each queryOption object define its own invalidation logic
• I see a potential to have this integrated with tanstack router in a pretty cool way, where we can invalidate routes. Something like:

export const Route = createFileRoute('/entity/$entityId')({
  loader: ({ context: { queryClient, route }, params: { entityId } }) => {
    return queryClient.ensureQueryData(getEntityQuery({ entityId, onInvalidate: (queryKey) => route.invalidate())
  },
  component: EntityComponent,
})

The way I imagine supporting this is through a new invalidationManager, that works close to how the other managers work. Something like:

import { invalidationManager } from "@tanstack/react-query";
webhooksService.subscribe((event) => invalidationManager.send(event));

which then enables us to for each query define the same match fn as I'm doing in my useUpdateEvent hook, but as part of the queryOptions:

function getEntityQuery(entityId) {
   return queryOptions({..., onBeforeInvalidate: (event) => event.id === entityId})
}

I can also see this being useful to add to the QueryClient, to have a centralized place to add invalidation logic.

Thanks for reading, curious to hear what you think!

[tannerlinsley]

@TkDodo We've brushed on this topic in the past. Where you you stand on stuff like this now?

[TkDodo]

invalidationManager could work, but adding callbacks like onBeforeInvalidate to queries is the opposite of where we’ve been moving towards lately.

I also don’t fully understand what the invalidationManager can do that a global event listener cannot?

webhooksService.subscribe((event) => {
  queryClient.invalidateQueries({ queryKey: event.queryKey })
});

[jimmycallin]

So I've been thinking about your alternative of a global event listener.

If I understand you correctly, webhooksService need to somehow be able to build a queryKey based on the payload of the event. This can certainly work in my provided use case in the original post, and I was almost happy to throw out the entire idea. But when I looked at our invalidation logic a bit closer, I noticed a use case where we invalidate queries based on the result of the query payload.

So my previous example looks a bit less simplified like this:

function useEntity({entityId, entityType, matchFn}) {
   // same as before
   ... 
   // notice the added context here, which is then passed as an argument to the matchFn
   useUpdateEvent({ matchFn, onMatch: invalidate, context: { data: query?.data } });
   return query;
}

If a query where to return the assignee of a particular task, I would like a matchFn that invalidates the query in certain cases an assignee gets updated:

function matchFn({ payload, context: { data } }) {
   return payload.entityType === "user" && data.assignee.entityId === payload.entityId;
}
const { data: task } = useSuspenseQuery(getEntityQuery({entityId: "123", entityType: "task", matchFn}))
return task.assignee;

I'm not entirely sure how to model this with a global event listener. An onBeforeInvalidate callback with the context of its current query would work perfectly for this, but I understand your sentiment that you are moving away from these types of APIs. I'm for alternative solutions, of course, but I can't figure it out myself at the moment.

EDIT: I just noticed that invalidateQueries can take a predicate argument, and in one way that would resolve this issue I believe? But I'm unsure about how to figure out colocation of the query and its invalidation logic - what I like about my suggested approach is that if I'm rendering the component everything will automatically work, and if I'm removing the component I don't have to worry about additional unused logic elsewhere.

[TkDodo]

webhooksService need to somehow be able to build a queryKey based on the payload of the event.

yes

I'm not entirely sure how to model this with a global event listener.

the event listener can also grab data from the cache:

webhooksService.subscribe((event) => {
  const data = queryClient.getQueryData(event.queryKey)
  if (payload.entityType === "user" && data.assignee.entityId === payload.entityId) {
    queryClient.invalidateQueries({ queryKey: event.queryKey })
  }
});

the predicate would also work of course:

webhooksService.subscribe((event) => {
  queryClient.invalidateQueries({
    queryKey: event.queryKey,
    predicate: query => payload.entityType === "user" && query.state.data.assignee.entityId === payload.entityId
  })
});

But I'm unsure about how to figure out colocation of the query and its invalidation logic

that’s a good point. the callback would solve it, I can think about it. Until then, you can make your own callback with meta. Something like:

useQuery({
  queryKey,
  queryFn,
  meta: {
    onBeforeInvalidate: (query) => ...
  }
}

webhooksService.subscribe((event) => {
  queryClient.invalidateQueries({
    queryKey: event.queryKey,
    predicate: query => query.meta?.onBeforeInvalidate(query)
  })
});

[jimmycallin]

I just read about the tRPC query integration, which looks really cool! But they mention there is no primitive from them to integrate their subscription hook https://trpc.io/docs/client/tanstack-react-query/usage#subscriptionOptions

This feels to me like a related use case, that could be worth exploring alongside this particular idea.