feat(query-core): forward caller-provided meta into the invalidate action payload

[maastrich]

Summary

Implements the proposal from discussion #10539.

• Adds meta?: QueryMeta to InvalidateOptions (second arg of invalidateQueries)
• Threads it through query.invalidate(meta) into the dispatched InvalidateAction
• Makes event.action.meta available in queryCache.subscribe for structured observability and echo-suppression

Usage

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

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

Notes

• Fully additive — meta is optional and defaults to undefined. No existing call site is affected.
• options.meta is distinct from filters.meta (which filters queries by their meta).
• The existing isInvalidated guard is preserved: if a query is already invalidated, the dispatch is skipped and the meta from subsequent calls is silently dropped. This is consistent with current behavior and can be revisited separately.
• query-broadcast-client-experimental does not broadcast invalidate actions today, so no changes are needed there.

Checklist

• Core implementation (query.ts, queryClient.ts, types.ts)
• Test in queryClient.test.tsx
• Reference docs updated (docs/reference/QueryClient.md)
• Guide updated (docs/framework/react/guides/query-invalidation.md) — other framework guides mirror it via ref:
• Changeset (minor for @tanstack/query-core)

Closes discussion: #10539

Summary by CodeRabbit

• New Features

  • Invalidation now accepts a meta option that is forwarded with invalidation events so subscribers can observe the source/context.

• Documentation

  • Added guide and reference examples showing how to pass and read meta during invalidation and clarifying it differs from filter metadata.

• Tests

  • Added tests verifying that meta is propagated through invalidation events.

[coderabbitai]

📝 Walkthrough

Walkthrough

invalidateQueries can accept an optional meta in its options which is forwarded into the internal invalidate action payload; queryCache.subscribe listeners can read this value via event.action.meta. Changes touch types, Query/QueryClient logic, a test, docs, and a changeset.

Changes

Cohort / File(s)	Summary
Types & Query class packages/query-core/src/types.ts, packages/query-core/src/query.ts	Add meta?: QueryMeta to InvalidateOptions. Change Query.invalidate() signature to invalidate(meta?: QueryMeta) and include meta on the dispatched invalidate action payload.
QueryClient behavior packages/query-core/src/queryClient.ts	QueryClient.invalidateQueries() forwards options.meta into query.invalidate(options.meta) for matched queries; meta is omitted when calling refetchQueries.
Tests packages/query-core/src/__tests__/queryClient.test.tsx	New test asserting that calling invalidateQueries with options.meta causes a single queryCache updated event with an invalidate action whose event.action.meta equals the provided meta.
Docs & Changeset .changeset/invalidate-queries-meta.md, docs/framework/react/guides/query-invalidation.md, docs/reference/QueryClient.md	Add changeset and documentation describing options.meta for invalidateQueries, how it propagates into invalidate action payloads, and distinction from filters.meta.

Sequence Diagram(s)

sequenceDiagram
    participant Client as Client
    participant QC as QueryClient
    participant Q as Query
    participant Sub as Subscriber

    Client->>QC: invalidateQueries(filters, { meta })
    QC->>Q: invalidate(meta)
    Q->>Sub: emit updated (action: { type: "invalidate", meta: meta })
    Sub-->>Client: read event.action.meta

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I nudged a meta into the invalidate trail,

so listeners sniff who wagged the tail.
A tiny packet, a quiet clue,
hops through cache so watchers view. 🥕

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: forwarding a caller-provided meta field into the invalidate action payload, which is the core feature implemented across all modified files.
Description check	✅ Passed	The description comprehensively covers changes, motivation, usage examples, and important notes. It addresses all template sections with clear information about the implementation, testing, documentation, and changeset work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/query-core/src/queryClient.ts (1)

297-311: ⚠️ Potential issue | 🟠 Major

Strip meta before forwarding options to refetchQueries.

options.meta is intended for the invalidate action, but the full options object is also passed into refetchQueries. That leaks the same object into query.fetch(..., fetchOptions), where fetchOptions.meta is interpreted as fetch metadata and can update fetchMeta / fetch events with invalidation metadata.

Proposed fix

   ): Promise<void> {
     return notifyManager.batch(() => {
+      const { meta, ...refetchOptions } = options
+
       this.#queryCache.findAll(filters).forEach((query) => {
-        query.invalidate(options.meta)
+        query.invalidate(meta)
       })

       if (filters?.refetchType === 'none') {
         return Promise.resolve()
       }
@@
           ...filters,
           type: filters?.refetchType ?? filters?.type ?? 'active',
         },
-        options,
+        refetchOptions,
       )
     })
   }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/query-core/src/queryClient.ts` around lines 297 - 311, The
invalidate loop correctly uses options.meta but you must avoid forwarding that
same meta into refetchQueries; when calling this.refetchQueries(...) strip out
meta from the options passed (e.g., clone options then delete or omit
options.meta) so invalidate receives meta but the refetch call receives options
without meta; locate the call to notifyManager.batch ->
this.#queryCache.findAll(...).forEach(query => query.invalidate(options.meta))
and change the refetchQueries invocation to pass a copy of options with meta
removed before spreading into the second argument.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@packages/query-core/src/queryClient.ts`:
- Around line 297-311: The invalidate loop correctly uses options.meta but you
must avoid forwarding that same meta into refetchQueries; when calling
this.refetchQueries(...) strip out meta from the options passed (e.g., clone
options then delete or omit options.meta) so invalidate receives meta but the
refetch call receives options without meta; locate the call to
notifyManager.batch -> this.#queryCache.findAll(...).forEach(query =>
query.invalidate(options.meta)) and change the refetchQueries invocation to pass
a copy of options with meta removed before spreading into the second argument.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6a2f6275-2903-4509-b84a-b2a7e73fffc8

📥 Commits

Reviewing files that changed from the base of the PR and between 646f04e and 848c49e.

📒 Files selected for processing (7)

• .changeset/invalidate-queries-meta.md
• docs/framework/react/guides/query-invalidation.md
• docs/reference/QueryClient.md
• packages/query-core/src/__tests__/queryClient.test.tsx
• packages/query-core/src/query.ts
• packages/query-core/src/queryClient.ts
• packages/query-core/src/types.ts

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/query-core/src/query.ts`:
- Around line 392-396: The current invalidate method drops caller-supplied meta
when state.isInvalidated is true because it skips dispatch; change
invalidate(meta?: QueryMeta) to always emit a dispatch carrying meta so
subscribers can observe every call — either always call this.#dispatch({ type:
'invalidate', meta }) (and let reducers ignore no-op state changes) or dispatch
a distinct action (e.g., type: 'invalidateMeta') when state.isInvalidated is
already true; update any action handlers/listeners that consume type
'invalidate' to handle the no-op case or handle the new 'invalidateMeta' action
so meta is propagated to subscribers without altering state.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 51a91876-d9d5-4132-9d3f-6dcda6257543

📥 Commits

Reviewing files that changed from the base of the PR and between 76550ee and 3cfeb2e.

📒 Files selected for processing (7)

• .changeset/invalidate-queries-meta.md
• docs/framework/react/guides/query-invalidation.md
• docs/reference/QueryClient.md
• packages/query-core/src/__tests__/queryClient.test.tsx
• packages/query-core/src/query.ts
• packages/query-core/src/queryClient.ts
• packages/query-core/src/types.ts

✅ Files skipped from review due to trivial changes (3)

• .changeset/invalidate-queries-meta.md
• docs/reference/QueryClient.md
• docs/framework/react/guides/query-invalidation.md

🚧 Files skipped from review as they are similar to previous changes (3)

• packages/query-core/src/queryClient.ts
• packages/query-core/src/types.ts
• packages/query-core/src/tests/queryClient.test.tsx