feat(query-core): pass a context object to the placeholderData function

[RodolfoSilva]

placeholderData functions now receive a third argument holding the client, the queryKey and the meta of the Query, matching the QueryFunctionContext that queryFn already gets.

This lets a queryOptions factory seed from the cache without being handed a QueryClient, which previously had to be threaded through components, prefetch calls, route loaders and tests.

export const blogPostOptions = (blogPostId: string) =>
  queryOptions({
    queryKey: ['blogPost', blogPostId],
    queryFn: () => fetchBlogPost(blogPostId),
    placeholderData: (_previousData, _previousQuery, { client }) =>
      client.getQueryData(['blogPosts'])?.find((post) => post.id === blogPostId),
  })

meta and queryKey come from the observer's own options rather than from the Query, so two observers on the same key with different meta each see their own.

Existing two argument placeholderData functions keep working.

Implements the proposal from #11140.

Summary by CodeRabbit

• New Features

  • placeholderData callbacks now receive context containing the query client, query key, and metadata.
  • Improved query-key type inference across Angular, React, Preact, Solid, and Svelte integrations.
  • Placeholder data can now be selected from related cached query results.

• Documentation

  • Added framework-specific examples and updated useQuery and useQueries references with the new callback context.

• Tests

  • Added coverage for context contents, metadata, cache access, type inference, and compatibility with previous-data behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5b5f3044-6d33-4c60-b580-c71932b9dda1

📥 Commits

Reviewing files that changed from the base of the PR and between 46d7f02 and eac654d.

📒 Files selected for processing (17)

• .changeset/placeholder-data-context.md
• docs/framework/angular/guides/placeholder-query-data.md
• docs/framework/react/guides/placeholder-query-data.md
• docs/framework/react/reference/useQueries.md
• docs/framework/react/reference/useQuery.md
• docs/framework/solid/reference/useQuery.md
• packages/angular-query-experimental/src/inject-queries.ts
• packages/preact-query/src/useQueries.ts
• packages/query-core/src/__tests__/queryObserver.test-d.tsx
• packages/query-core/src/__tests__/queryObserver.test.tsx
• packages/query-core/src/queryObserver.ts
• packages/query-core/src/types.ts
• packages/react-query/src/__tests__/useQueries.test-d.tsx
• packages/react-query/src/__tests__/useQuery.test.tsx
• packages/react-query/src/useQueries.ts
• packages/solid-query/src/useQueries.ts
• packages/svelte-query/src/createQueries.svelte.ts

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

• docs/framework/solid/reference/useQuery.md
• packages/angular-query-experimental/src/inject-queries.ts
• docs/framework/react/reference/useQueries.md
• docs/framework/react/reference/useQuery.md
• packages/react-query/src/tests/useQueries.test-d.tsx
• packages/query-core/src/tests/queryObserver.test-d.tsx
• docs/framework/react/guides/placeholder-query-data.md
• packages/solid-query/src/useQueries.ts
• .changeset/placeholder-data-context.md
• docs/framework/angular/guides/placeholder-query-data.md
• packages/svelte-query/src/createQueries.svelte.ts
• packages/query-core/src/types.ts
• packages/query-core/src/queryObserver.ts
• packages/preact-query/src/useQueries.ts
• packages/query-core/src/tests/queryObserver.test.tsx
• packages/react-query/src/useQueries.ts
• packages/react-query/src/tests/useQuery.test.tsx

---

📝 Walkthrough

Walkthrough

placeholderData callbacks now receive a PlaceholderDataContext with the query client, query key, and metadata. Core runtime behavior, framework typings, tests, documentation, and release metadata were updated.

Changes

Placeholder data context

Layer / File(s)	Summary
Core context contract and runtime packages/query-core/src/types.ts, packages/query-core/src/queryObserver.ts, packages/query-core/src/__tests__/*	Added PlaceholderDataContext, updated callback types, passed context during observer execution, and added runtime and type coverage.
Framework query typings and validation packages/{angular-query-experimental,preact-query,react-query,solid-query,svelte-query}/src/*	Preserved query-key types in framework placeholder-data callbacks and added React type and behavior tests.
Documentation and release metadata docs/framework/{angular,react,solid}/**, .changeset/placeholder-data-context.md	Documented context usage and recorded minor releases for six Query packages.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant QueryObserver
  participant placeholderData
  participant QueryClient
  QueryObserver->>placeholderData: invoke with previous data, previous query, and context
  placeholderData->>QueryClient: read cached query data
  QueryClient-->>placeholderData: return cached data
  placeholderData-->>QueryObserver: return placeholder data

Loading

Possibly related PRs

• TanStack/query#11011: Both changes modify QueryObserver placeholder-data behavior and tests.

Suggested reviewers: sukvvon

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the change and motivation but omits the required Changes, Checklist, and Release Impact sections.	Add the required template sections and complete the checklist and release-impact information, including the changeset and test status.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary change: adding a context object to placeholderData callbacks.
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.

✨ 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.}

[coderabbitai]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.