Expose queryHash on QueryFunctionContext

[ElliotChong-MS]

🎯 Changes

This PR exposes queryHash on QueryFunctionContext so query functions have first-class access to the canonical identifier of the query without recomputing the hash or performing an expensive lookup in the QueryCache. This is an additive, backward-compatible enhancement.

Discussion Item: #9811

✅ 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).

Summary by CodeRabbit

• New Features

  • Query functions now receive queryHash in their context, eliminating the need to compute or import the query hash externally.

• Documentation

  • Updated QueryFunctionContext documentation to include the new queryHash property.

• Tests

  • Updated tests to verify queryHash is properly included in QueryFunctionContext across all query operations.

[changeset-bot]

🦋 Changeset detected

Latest commit: 29723ee

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 19 packages

Name	Type
@tanstack/query-core	Minor
@tanstack/angular-query-experimental	Patch
@tanstack/query-async-storage-persister	Patch
@tanstack/query-broadcast-client-experimental	Patch
@tanstack/query-persist-client-core	Patch
@tanstack/query-sync-storage-persister	Patch
@tanstack/react-query	Patch
@tanstack/solid-query	Patch
@tanstack/svelte-query	Patch
@tanstack/vue-query	Patch
@tanstack/angular-query-persist-client	Patch
@tanstack/react-query-persist-client	Patch
@tanstack/solid-query-persist-client	Patch
@tanstack/svelte-query-persist-client	Patch
@tanstack/react-query-devtools	Patch
@tanstack/react-query-next-experimental	Patch
@tanstack/solid-query-devtools	Patch
@tanstack/svelte-query-devtools	Patch
@tanstack/vue-query-devtools	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Walkthrough

Introduces queryHash as a new public property in QueryFunctionContext, enabling query functions direct access to precomputed query hashes. Implementation updates core types, query execution, infinite query behavior, and persister client, with corresponding documentation and test coverage across all affected packages.

Changes

Cohort / File(s)	Change Summary
Changelog & Configuration .changeset/tiny-rabbits-tap.md	Documents minor version bump for @tanstack/query-core with new public API: queryHash added to QueryFunctionContext
Documentation docs/framework/react/guides/query-functions.md	Updated QueryFunctionContext documentation to describe the new queryHash: string property
Core Type Definition packages/query-core/src/types.ts	Added queryHash: string property to QueryFunctionContext interface in both conditional type branches
Core Implementation packages/query-core/src/query.ts, packages/query-core/src/infiniteQueryBehavior.ts	Populates queryHash in QueryFunctionContext objects during query execution and infinite query pagination
Persister Client packages/query-persist-client-core/src/__tests__/createPersister.test.ts	Precomputes queryHash in context initialization for use in storageKey generation and persister operations
Test Updates packages/angular-query-experimental/src/__tests__/inject-query.test.ts, packages/query-core/src/__tests__/query.test.tsx, packages/query-core/src/__tests__/infiniteQueryBehavior.test.tsx, packages/query-core/src/__tests__/queryClient.test-d.tsx	Updated test assertions to verify queryHash property is included in QueryFunctionContext passed to query functions

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Verify queryHash computation is consistent across all code paths (query.ts, infiniteQueryBehavior.ts, persister client)
• Ensure test assertions in all packages comprehensively validate the new queryHash property
• Confirm type definition changes propagate correctly through both conditional branches of QueryFunctionContext
• Check that persister client initialization properly sequences queryHash computation before use in storageKey

Suggested reviewers

• arnoud-dv

Poem

🐰 A hash so true, now in your hand,
No need to compute across the land,
QueryFunctionContext hops with pride,
With queryHash bundled inside,
Your queries bloom, efficient and grand!

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "Expose queryHash on QueryFunctionContext" is concise, clear, and directly reflects the primary change in the changeset. The title accurately summarizes what the PR accomplishes—adding queryHash as a new property accessible through QueryFunctionContext—which aligns with the extensive changes across test files, type definitions, and implementation files that all contribute to this feature. A teammate reviewing the git history would immediately understand the purpose of this PR.
Description Check	✅ Passed	The pull request description follows the repository's template structure completely, including all required sections: the 🎯 Changes section explains the feature and its motivation with reference to discussion #9811, the ✅ Checklist section confirms both that the contributing guide was followed and tests were run locally (both marked as completed), and the 🚀 Release Impact section correctly indicates that a changeset was generated since this affects published code. The description provides sufficient context about the additive, backward-compatible nature of the enhancement.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 38b4008 and 29723ee.

📒 Files selected for processing (10)

• .changeset/tiny-rabbits-tap.md (1 hunks)
• docs/framework/react/guides/query-functions.md (1 hunks)
• packages/angular-query-experimental/src/__tests__/inject-query.test.ts (1 hunks)
• packages/query-core/src/__tests__/infiniteQueryBehavior.test.tsx (10 hunks)
• packages/query-core/src/__tests__/query.test.tsx (1 hunks)
• packages/query-core/src/__tests__/queryClient.test-d.tsx (1 hunks)
• packages/query-core/src/infiniteQueryBehavior.ts (2 hunks)
• packages/query-core/src/query.ts (1 hunks)
• packages/query-core/src/types.ts (2 hunks)
• packages/query-persist-client-core/src/__tests__/createPersister.test.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (3)

packages/query-core/src/__tests__/query.test.tsx (1)

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

• hashQueryKeyByOptions (204-210)

packages/query-persist-client-core/src/__tests__/createPersister.test.ts (1)

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

• hashKey (29-29)

packages/query-core/src/__tests__/infiniteQueryBehavior.test.tsx (1)

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

• hashQueryKeyByOptions (204-210)

🔇 Additional comments (4)

packages/query-core/src/__tests__/infiniteQueryBehavior.test.tsx (2)

4-4: LGTM!

The import is correctly added and consistently used throughout the test file to verify the new queryHash field.

---

84-311: Excellent test coverage for the new queryHash field!

The test expectations are consistently updated across all query execution scenarios (initial fetch, pagination, refetch, and cancellation) to verify that queryHash is correctly populated in the QueryFunctionContext. The use of hashQueryKeyByOptions(key) ensures the expected value matches the implementation.

packages/query-core/src/infiniteQueryBehavior.ts (2)

57-71: Correct implementation of queryHash in query function context!

The queryHash is properly propagated from query.queryHash into the QueryFunctionContext created for each page fetch, making it available to the query function without recomputation.

---

116-129: Correct propagation of queryHash to persister options!

The queryHash is properly included in the persister options, ensuring that persisters have access to the canonical query identifier for storage/caching operations. This maintains consistency with the query function context.

---

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