Expose `queryHash` on `QueryFunctionContext` #9812

ElliotChong-MS · 2025-10-26T00:10:42Z

🎯 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 a new queryHash property in their execution context.
Documentation
- QueryFunctionContext docs updated to document the new queryHash field.
Tests
- Tests updated to assert that queryHash is included in the QueryFunctionContext across query flows.

* Initial plan * Add queryHash to QueryFunctionContext implementation and update tests Co-authored-by: ElliotChong-MS <[email protected]> * Add queryHash to QueryFunctionContext documentation and test Co-authored-by: ElliotChong-MS <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: ElliotChong-MS <[email protected]>

changeset-bot · 2025-10-26T00:10:46Z

🦋 Changeset detected

Latest commit: 079c7b1

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 · 2025-10-26T00:11:10Z

Walkthrough

Adds a new public property queryHash: string to QueryFunctionContext and propagates a precomputed query hash through query creation, execution, infinite pagination, and the persister; documentation and tests updated to assert the presence of queryHash.

Changes

Cohort / File(s)	Change Summary
Changelog & Release `.changeset/tiny-rabbits-tap.md`	Adds changelog entry for minor version bump and documents new public API `queryHash` on `QueryFunctionContext`.
Docs `docs/framework/react/guides/query-functions.md`	Documents the new `queryHash: string` property in `QueryFunctionContext`.
Core Types `packages/query-core/src/types.ts`, `packages/query-core/src/index.ts`	Adds `queryHash: string` to `QueryFunctionContext` (both conditional branches / exported interface).
Core Implementation `packages/query-core/src/query.ts`, `packages/query-core/src/infiniteQueryBehavior.ts`, `packages/query-core/src/utils.ts`	Compute/store `queryHash` on Query, include `queryHash` in the `QueryFunctionContext` passed to query functions; added `hashQueryKeyByOptions` utility and propagate `queryHash` for infinite pagination contexts.
Persister `packages/query-persist-client-core/src/__tests__/createPersister.test.ts`	Precompute `queryHash` earlier in persister setup and use it for `storageKey` / persister context.
Tests / Typings `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`, `packages/angular-query-experimental/src/__tests__/inject-query.test.ts`	Updated tests and d.ts test to assert `queryHash` is present on `QueryFunctionContext` and matches computed hash.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Creator as Query Creator
  participant Query as Query Instance
  participant Utils as hashQueryKeyByOptions
  participant Runner as Query Executor / QueryFn
  participant Persister as Persister

  Creator->>Utils: compute queryHash(queryKey, options)
  Utils-->>Creator: queryHash
  Creator->>Query: new Query(..., queryHash)
  Query->>Runner: execute(queryFnContext { queryKey, client, meta, signal, queryHash })
  Runner-->>Query: result

  Note right of Persister: Persister setup uses precomputed\nqueryHash for storageKey
  Creator->>Persister: setupPersister(context { queryHash, ... })
  Persister-->>Creator: persister ready

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Pay attention to consistent queryHash computation and use (utils vs inlined calls).
Verify QueryFunctionContext type changes apply to all conditional branches and exported declarations.
Inspect persister initialization ordering to ensure queryHash is computed before use in storageKey.
Confirm tests correctly assert the computed queryHash values and that no runtime behavior changed.

Possibly related PRs

fix(createQueryPersister): add option to change behavior of refetch after restore #9745 — touches persister implementation/tests in packages/query-persist-client-core; likely related due to overlapping changes around persister behavior and setup.

Suggested reviewers

arnoud-dv

Poem

🐰 I hashed the key beneath the moon,
Packed it in context, ready soon,
QueryFunction leaps with glee,
A tidy hash for you and me,
Hoppity-hop — results arrive in tune!

Pre-merge checks and finishing touches

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: exposing queryHash on QueryFunctionContext, which matches the primary objective of the pull request.
Description check	✅ Passed	The description follows the template structure with all required sections completed: changes explained with motivation, checklist items marked, and release impact documented with changeset confirmation.

✨ 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 29723ee and 079c7b1.

📒 Files selected for processing (2)

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

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

packages/query-core/src/query.ts

🧰 Additional context used

🧬 Code graph analysis (1)

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

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

hashQueryKeyByOptions (204-210)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

GitHub Check: Test
GitHub Check: Preview

🔇 Additional comments (2)

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

15-15: LGTM!

The import of hashQueryKeyByOptions is correctly added and used to validate the new queryHash property in the test assertion.

257-257: LGTM!

The assertion properly validates that the new queryHash property is present in the QueryFunctionContext and matches the expected computed hash value. This is the appropriate test to extend since it explicitly validates all context properties passed to the query function.

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

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

TkDodo · 2025-11-05T13:12:47Z

what do you need the queryHash for in here?

nx-cloud · 2025-11-05T13:13:12Z

View your CI Pipeline Execution ↗ for commit 079c7b1

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	✅ Succeeded	4m 27s	View ↗
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	1m 20s	View ↗

☁️ Nx Cloud last updated this comment at 2025-11-05 13:18:14 UTC

pkg-pr-new · 2025-11-05T13:15:27Z

More templates

@tanstack/angular-query-experimental

npm i https://pkg.pr.new/@tanstack/angular-query-experimental@9812

@tanstack/eslint-plugin-query

npm i https://pkg.pr.new/@tanstack/eslint-plugin-query@9812

@tanstack/query-async-storage-persister

npm i https://pkg.pr.new/@tanstack/query-async-storage-persister@9812

@tanstack/query-broadcast-client-experimental

npm i https://pkg.pr.new/@tanstack/query-broadcast-client-experimental@9812

@tanstack/query-core

npm i https://pkg.pr.new/@tanstack/query-core@9812

@tanstack/query-devtools

npm i https://pkg.pr.new/@tanstack/query-devtools@9812

@tanstack/query-persist-client-core

npm i https://pkg.pr.new/@tanstack/query-persist-client-core@9812

@tanstack/query-sync-storage-persister

npm i https://pkg.pr.new/@tanstack/query-sync-storage-persister@9812

@tanstack/react-query

npm i https://pkg.pr.new/@tanstack/react-query@9812

@tanstack/react-query-devtools

npm i https://pkg.pr.new/@tanstack/react-query-devtools@9812

@tanstack/react-query-next-experimental

npm i https://pkg.pr.new/@tanstack/react-query-next-experimental@9812

@tanstack/react-query-persist-client

npm i https://pkg.pr.new/@tanstack/react-query-persist-client@9812

@tanstack/solid-query

npm i https://pkg.pr.new/@tanstack/solid-query@9812

@tanstack/solid-query-devtools

npm i https://pkg.pr.new/@tanstack/solid-query-devtools@9812

@tanstack/solid-query-persist-client

npm i https://pkg.pr.new/@tanstack/solid-query-persist-client@9812

@tanstack/svelte-query

npm i https://pkg.pr.new/@tanstack/svelte-query@9812

@tanstack/svelte-query-devtools

npm i https://pkg.pr.new/@tanstack/svelte-query-devtools@9812

@tanstack/svelte-query-persist-client

npm i https://pkg.pr.new/@tanstack/svelte-query-persist-client@9812

@tanstack/vue-query

npm i https://pkg.pr.new/@tanstack/vue-query@9812

@tanstack/vue-query-devtools

npm i https://pkg.pr.new/@tanstack/vue-query-devtools@9812

commit: 079c7b1

codecov · 2025-11-05T13:19:05Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 59.78%. Comparing base (a5fca0e) to head (079c7b1).

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #9812       +/-   ##
===========================================
+ Coverage   45.75%   59.78%   +14.02%     
===========================================
  Files         200      129       -71     
  Lines        8408     5622     -2786     
  Branches     1929     1533      -396     
===========================================
- Hits         3847     3361      -486     
+ Misses       4113     1956     -2157     
+ Partials      448      305      -143

Components	Coverage Δ
@tanstack/angular-query-experimental	`93.85% <ø> (ø)`
@tanstack/eslint-plugin-query	`∅ <ø> (∅)`
@tanstack/query-async-storage-persister	`43.85% <ø> (ø)`
@tanstack/query-broadcast-client-experimental	`24.39% <ø> (ø)`
@tanstack/query-codemods	`∅ <ø> (∅)`
@tanstack/query-core	`97.38% <ø> (ø)`
@tanstack/query-devtools	`3.48% <ø> (ø)`
@tanstack/query-persist-client-core	`80.00% <ø> (ø)`
@tanstack/query-sync-storage-persister	`84.61% <ø> (ø)`
@tanstack/query-test-utils	`∅ <ø> (∅)`
@tanstack/react-query	`96.01% <ø> (ø)`
@tanstack/react-query-devtools	`10.00% <ø> (ø)`
@tanstack/react-query-next-experimental	`∅ <ø> (∅)`
@tanstack/react-query-persist-client	`100.00% <ø> (ø)`
@tanstack/solid-query	`77.81% <ø> (ø)`
@tanstack/solid-query-devtools	`61.90% <ø> (ø)`
@tanstack/solid-query-persist-client	`100.00% <ø> (ø)`
@tanstack/svelte-query	`∅ <ø> (∅)`
@tanstack/svelte-query-devtools	`∅ <ø> (∅)`
@tanstack/svelte-query-persist-client	`∅ <ø> (∅)`
@tanstack/vue-query	`71.10% <ø> (ø)`
@tanstack/vue-query-devtools	`∅ <ø> (∅)`

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

ElliotChong-MS and others added 4 commits October 24, 2025 18:57

Add queryHash property to query types

c1cbf7e

Add changeset

2e2bef4

Fix test expectations for queryHash in QueryFunctionContext

29723ee

github-actions bot added documentation Improvements or additions to documentation package: query-core package: query-persist-client-core package: angular-query-experimental labels Oct 26, 2025

Merge branch 'main' into patch-1

079c7b1

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Expose `queryHash` on `QueryFunctionContext` #9812

Expose `queryHash` on `QueryFunctionContext` #9812

ElliotChong-MS commented Oct 26, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Oct 26, 2025 •

edited

Loading

Uh oh!

coderabbitai bot commented Oct 26, 2025 •

edited

Loading

Uh oh!

TkDodo commented Nov 5, 2025

Uh oh!

nx-cloud bot commented Nov 5, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Nov 5, 2025

Uh oh!

codecov bot commented Nov 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Expose queryHash on QueryFunctionContext #9812

Are you sure you want to change the base?

Expose queryHash on QueryFunctionContext #9812

Conversation

ElliotChong-MS commented Oct 26, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Oct 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai bot commented Oct 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Pre-merge checks and finishing touches

Uh oh!

TkDodo commented Nov 5, 2025

Uh oh!

nx-cloud bot commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Nov 5, 2025

Uh oh!

codecov bot commented Nov 5, 2025

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Expose `queryHash` on `QueryFunctionContext` #9812

Expose `queryHash` on `QueryFunctionContext` #9812

ElliotChong-MS commented Oct 26, 2025 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Oct 26, 2025 •

edited

Loading

coderabbitai bot commented Oct 26, 2025 •

edited

Loading

nx-cloud bot commented Nov 5, 2025 •

edited

Loading