Feature: forward caller-provided meta into the invalidate action payload in queryCache.subscribe

[maastrich]

Problem

queryCache.subscribe exposes what happened to the cache — but never why or from where. When an { type: 'updated', action: { type: 'invalidate' } } event fires, all caller context has been discarded. Every subscriber sees the same opaque signal regardless of what triggered the invalidation.

This makes it impossible to build composable cache observers without external bookkeeping.

Proposed API

Add an optional meta field to the second argument of invalidateQueries — distinct from filters.meta, which already means "filter queries by their meta":

queryClient.invalidateQueries(
  { queryKey: ['orders'] },
  { meta: { source: 'websocket', traceId: 'abc123' } }
)

The value would flow through to the action seen in queryCache.subscribe:

queryCache.subscribe((event) => {
  if (event.type === 'updated' && event.action.type === 'invalidate') {
    console.log(event.action.meta) // { source: 'websocket', traceId: 'abc123' }
  }
})

Use Cases

1. Observability and structured logging

Applications that log cache activity today can only record that a query was invalidated — not what caused it. With meta, a single cache subscriber can produce structured logs attributing each invalidation to a mutation, a WebSocket event, a polling tick, or a user action, without any out-of-band coordination.

queryCache.subscribe((event) => {
  if (event.type === 'updated' && event.action.type === 'invalidate') {
    analytics.track('cache.invalidated', {
      queryKey: event.query.queryKey,
      ...event.action.meta,
    })
  }
})

2. Real-time sync — suppressing echoes

When invalidations are broadcast across tabs or clients (BroadcastChannel, WebSocket, MQTT), a subscriber that re-broadcasts cache events must distinguish locally-originated invalidations from remotely-received ones. Without meta on the action, there is no clean way to make that distinction at the subscriber — the two cases are indistinguishable from the event alone.

Backwards Compatibility

Fully additive. meta is optional and defaults to undefined. The InvalidateAction shape becomes { type: 'invalidate', meta?: QueryMeta }. No existing call site or subscriber is affected.

Implementation

Thread options.meta from invalidateQueries into query.invalidate(meta) and dispatch { type: 'invalidate', meta }. The same pattern could be extended to resetQueries and refetchQueries in a follow-up.

[maastrich]

Implementation submitted in #10540.

[TkDodo]

A query generally doesn’t have information about what triggered the fetch, we don’t store that. Adding this to invaldiateQueries only is weird. Adding it everywhere (including refetch returned from useQuery or all the other ways we have to fetch, like fetchNextPage in infinite queries), or even the auto-fetching we do with refetchOnWindowFocus becomes a lot.

Listening to the low-level query events is a pretty advanced use-case so I’m not willing to add that much to the lib just for this case, sorry. The events we emit are primarily for the devtools, but it’s great that you find them useful as well.

Also, meta data still has to be attached manually, at which point you can just make your own abstraction around invalidateQueries that does the logging.

You’re also mixing up a bunch of things, like:

distinct from filters.meta, which already means "filter queries by their meta"

This feels hallucinated, as filters.meta just doesn’t exist.

I’m gonna close the PR for those reasons.