feat(query-core): include current query as a placeholder data functio…

[mkljczk]

…n param

🎯 Changes

current query is now provided to placeholder data function. I tried to explain my use case in the test, basically I want to provide a placeholder data function globally, where it previously didn't have access to query key so it was quite useless for me.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

[coderabbitai]

📝 Walkthrough

Walkthrough

The changes extend the placeholderData function signature across @tanstack/query-core to include a third currentQuery parameter, allowing placeholder data functions to access the current query object. This involves type definition updates, implementation changes, documentation revisions for React and Solid frameworks, and a new test case verifying the behavior.

Changes

Cohort / File(s)	Summary
Changeset Entry .changeset/long-bars-lay.md	Adds minor version bump entry for @tanstack/query-core documenting the new placeholderData feature.
Type Definitions packages/query-core/src/types.ts	Updates PlaceholderDataFunction signature to include a non-optional currentQuery: Query<...> parameter as the third argument.
Implementation packages/query-core/src/queryObserver.ts	Modifies QueryObserver.createResult to pass the current query as a third argument when invoking placeholderData callback functions.
Documentation docs/framework/react/reference/useQuery.md, docs/framework/solid/reference/useQuery.md	Updates placeholderData function type signatures in both framework references to reflect the new third currentQuery parameter.
Tests packages/query-core/src/__tests__/queryObserver.test.tsx	Adds unit test verifying that placeholderData functions receive the current query object when invoked through QueryObserver.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

A whisker-twitch of joy! The placeholder now sees,
The query's own reflection, its current core with ease.
Three parameters dance where once there were but two,
A rabbit's small refactor makes the data flow shine true. 🐰✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main feature: adding the current query as a placeholder data function parameter.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The PR description includes a clear explanation of changes, follows the template structure, and confirms a changeset was generated for this published code change.

_{✏️ 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 (2)

docs/framework/react/reference/useQuery.md (1)

158-162: ⚠️ Potential issue | 🟡 Minor

Documentation is incomplete for the new currentQuery parameter.

The signature on line 158 correctly includes currentQuery: Query, but the description on line 162 only mentions the first two arguments. Consider updating the description to explain the third argument:

- If you provide a function for `placeholderData`, as a first argument you will receive previously watched query data if available, and the second argument will be the complete previousQuery instance.
+ If you provide a function for `placeholderData`, as a first argument you will receive previously watched query data if available, the second argument will be the complete previousQuery instance, and the third argument will be the current query instance.

🤖 Prompt for AI Agents

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

In `@docs/framework/react/reference/useQuery.md` around lines 158 - 162, The doc
text for the placeholderData function signature is missing a description of the
third parameter; update the paragraph describing placeholderData (the entry for
placeholderData: TData | (previousValue: TData | undefined, previousQuery: Query
| undefined, currentQuery: Query) => TData) to explicitly document the third
argument named currentQuery: explain that when a function is provided it
receives (1) previous watched query data (or undefined), (2) the previous Query
instance (or undefined), and (3) the current Query instance that is about to be
observed so callers can inspect its key/options to compute placeholder data
accordingly; mention that currentQuery is the live Query object for the pending
observation.

docs/framework/solid/reference/useQuery.md (1)

207-211: ⚠️ Potential issue | 🟡 Minor

Documentation is incomplete for the new currentQuery parameter.

Same issue as the React documentation: the signature includes currentQuery: Query, but the description only explains the first two arguments. Consider updating:

- If you provide a function for `placeholderData`, as a first argument you will receive previously watched query data if available, and the second argument will be the complete previousQuery instance.
+ If you provide a function for `placeholderData`, as a first argument you will receive previously watched query data if available, the second argument will be the complete previousQuery instance, and the third argument will be the current query instance.

🤖 Prompt for AI Agents

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

In `@docs/framework/solid/reference/useQuery.md` around lines 207 - 211, The docs
for placeholderData are missing an explanation of the third parameter; update
the placeholderData signature description (for placeholderData: TData |
(previousValue: TData | undefined, previousQuery: Query | undefined,
currentQuery: Query) => TData) to document the currentQuery parameter: explain
that when placeholderData is a function it receives (1) the previously watched
query data (previousValue), (2) the previous Query instance (previousQuery) and
(3) the current Query instance (currentQuery) representing the query that is
about to be observed, and clarify how currentQuery can be used to derive
placeholder values based on the new query context and that placeholderData is
not persisted to the cache; reference the placeholderData signature and the
Query type in the description.

🤖 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 `@docs/framework/react/reference/useQuery.md`:
- Around line 158-162: The doc text for the placeholderData function signature
is missing a description of the third parameter; update the paragraph describing
placeholderData (the entry for placeholderData: TData | (previousValue: TData |
undefined, previousQuery: Query | undefined, currentQuery: Query) => TData) to
explicitly document the third argument named currentQuery: explain that when a
function is provided it receives (1) previous watched query data (or undefined),
(2) the previous Query instance (or undefined), and (3) the current Query
instance that is about to be observed so callers can inspect its key/options to
compute placeholder data accordingly; mention that currentQuery is the live
Query object for the pending observation.

In `@docs/framework/solid/reference/useQuery.md`:
- Around line 207-211: The docs for placeholderData are missing an explanation
of the third parameter; update the placeholderData signature description (for
placeholderData: TData | (previousValue: TData | undefined, previousQuery: Query
| undefined, currentQuery: Query) => TData) to document the currentQuery
parameter: explain that when placeholderData is a function it receives (1) the
previously watched query data (previousValue), (2) the previous Query instance
(previousQuery) and (3) the current Query instance (currentQuery) representing
the query that is about to be observed, and clarify how currentQuery can be used
to derive placeholder values based on the new query context and that
placeholderData is not persisted to the cache; reference the placeholderData
signature and the Query type in the description.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a6d47998-c6bc-486f-afb3-ba61cc96a1f1

📥 Commits

Reviewing files that changed from the base of the PR and between 2e26f14 and 3ddf800.

📒 Files selected for processing (6)

• .changeset/long-bars-lay.md
• docs/framework/react/reference/useQuery.md
• docs/framework/solid/reference/useQuery.md
• packages/query-core/src/__tests__/queryObserver.test.tsx
• packages/query-core/src/queryObserver.ts
• packages/query-core/src/types.ts