fix(vue-query): preserve branded types in MaybeRefDeep by byungsker · Pull Request #10573 · TanStack/query

byungsker · 2026-04-25T04:55:04Z

🎯 Changes

This PR fixes a TypeScript type inference issue where branded types (e.g. string & { __brand: 'PostId' }) in queryKey tuples cause TS2769 errors when passed from queryOptions to useQuery.

The root cause was MaybeRefDeep<T> recursively mapping branded types as objects, which destroyed the branded type information needed for DataTag-based overload resolution.

The fix adds a terminal branch to MaybeRefDeep: T extends { __brand: infer _ } ? T, so branded types pass through unchanged.

Two type-test cases were added to validate the fix.

Fixes #9920

✅ 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

Bug Fixes
- Fixed TypeScript inference issues when using branded types, such as branded strings, inside queryKey tuples passed through queryOptions and useQuery.
- Preserved branded primitive types during deep reactive type mapping, including branded values nested in objects and references.
- Improved type accuracy for query results involving branded identifiers.
Tests
- Added TypeScript declaration tests covering direct and nested branded values, query options, reactive references, and inferred query results.

coderabbitai · 2026-04-25T04:55:16Z

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: e4c9878e-6fbb-46a8-ae7b-a342a32ca370

📥 Commits

Reviewing files that changed from the base of the PR and between 2215bb0 and e261806.

📒 Files selected for processing (3)

.changeset/branded-types-fix.md
packages/vue-query/src/__tests__/queryOptions.test-d.ts
packages/vue-query/src/types.ts

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

packages/vue-query/src/types.ts
.changeset/branded-types-fix.md
packages/vue-query/src/tests/queryOptions.test-d.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

Walkthrough

This PR updates MaybeRefDeep to preserve branded primitive types during recursive mapping. Type tests cover branded values in direct and nested queryKey tuples. A patch changeset documents the fix.

Changes

Branded queryKey inference

Layer / File(s)	Summary
Branded type handling and validation `packages/vue-query/src/types.ts`, `packages/vue-query/src/__tests__/queryOptions.test-d.ts`	`MaybeRefDeep` now returns primitive types unchanged. Type tests verify branded values through direct, nested, inline, and `queryOptions`-based `useQuery` usage.
Release metadata `.changeset/branded-types-fix.md`	Adds a patch changeset for `@tanstack/vue-query` describing the branded-type inference fix.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to e2618

This localized TypeScript change preserves branded types in Vue Query options and adds coverage for the affected inference cases; no actionable merge-blocking risk remains beyond normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the Vue Query fix for preserving branded types in MaybeRefDeep.
Description check	✅ Passed	The description explains the bug, root cause, fix, tests, checklist status, release impact, and linked issue.
Linked Issues check	✅ Passed	The changes fix the branded queryKey inference error in useQuery and add type tests for helper, nested, and ref-containing cases required by issue [`#9920`].
Out of Scope Changes check	✅ Passed	The implementation, type tests, and changeset are directly related to the branded queryKey inference fix and issue [`#9920`].
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2 files. (1 skipped: 1 unsupported.)

✨ 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

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

nx-cloud · 2026-04-25T04:55:34Z

🤖 Nx Cloud AI Fix Eligible

An automatically generated fix could have helped fix failing tasks for this run, but Self-healing CI is disabled for this workspace. Visit workspace settings to enable it and get automatic fixes in future runs.

_{To disable these notifications, a workspace admin can disable them in workspace settings.}

View your CI Pipeline Execution ↗ for commit e261806

Command	Status	Duration	Result
`nx affected --targets=test:sherif,test:knip,tes...`	❌ Failed	2m 23s	View ↗
`nx run-many --target=build --exclude=examples/*...`	❌ Failed	32s	View ↗

☁️ Nx Cloud last updated this comment at 2026-08-22 14:22:06 UTC

pkg-pr-new · 2026-04-25T04:56:34Z

More templates

@tanstack/angular-query-experimental

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

@tanstack/eslint-plugin-query

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

@tanstack/preact-query

npm i https://pkg.pr.new/@tanstack/preact-query@10573

@tanstack/preact-query-devtools

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

@tanstack/preact-query-persist-client

npm i https://pkg.pr.new/@tanstack/preact-query-persist-client@10573

@tanstack/query-async-storage-persister

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

@tanstack/query-broadcast-client-experimental

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

@tanstack/query-core

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

@tanstack/query-devtools

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

@tanstack/query-persist-client-core

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

@tanstack/query-sync-storage-persister

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

@tanstack/react-query

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

@tanstack/react-query-devtools

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

@tanstack/react-query-next-experimental

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

@tanstack/react-query-persist-client

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

@tanstack/solid-query

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

@tanstack/solid-query-devtools

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

@tanstack/solid-query-persist-client

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

@tanstack/svelte-query

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

@tanstack/svelte-query-devtools

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

@tanstack/svelte-query-persist-client

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

@tanstack/vue-query

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

@tanstack/vue-query-devtools

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

commit: df73bb9

Branded types (string & { __brand: string }) were being recursively mapped by MaybeRefDeep, causing type inference failures when used in queryKey tuples passed from queryOptions to useQuery. Fixes TanStack#9920

peterbud · 2026-08-21T18:23:35Z

Hi @byungsker , I quickly looked at this and the fix preserves branded primitive types, but it also treats any object with a __brand property as a terminal value. That regresses deep ref support for valid structured query keys such as { __brand: 'post', postId: ref('123') }, where postId is no longer accepted. I know it might be a rare case, but still...

I think narrowing the terminal condition to branded primitive intersections (T extends Primitive), or use a brand detection approach that does not exempt normal objects from recursive unwrapping would be a better solution. Also adding a regression type test for an object containing both __brand and a nested ref would be beneficial.

byungsker · 2026-08-22T14:12:50Z

Good catch. The __brand check matched regular objects, so nested refs could be left untouched.

I changed it to T extends Primitive and added a type test for an object with __brand and a nested ref. The type tests pass. I'll push the fix.

coderabbitai · 2026-08-22T14:18:27Z

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.

github-actions Bot added the package: vue-query label Apr 25, 2026

KIM-DONGJU mentioned this pull request May 20, 2026

Branded queryKey in queryOptions causes TS error (TS2769) in useQuery #9920

Open

fix(vue-query): preserve branded types in MaybeRefDeep

af629b6

Branded types (string & { __brand: string }) were being recursively mapped by MaybeRefDeep, causing type inference failures when used in queryKey tuples passed from queryOptions to useQuery. Fixes TanStack#9920

byungsker force-pushed the fix/vue-query-options-querykey branch from df73bb9 to af629b6 Compare July 22, 2026 01:44

TkDodo mentioned this pull request Aug 22, 2026

fix(vue-query): stop MaybeRefDeep stripping branded queryKey types (#9920) #11252

Closed

fix(vue-query): narrow branded type handling

7d972a0

Merge branch 'main' into fix/vue-query-options-querykey

e261806

Navigation Menu

Uh oh!

Uh oh!

fix(vue-query): preserve branded types in MaybeRefDeep - #10573

fix(vue-query): preserve branded types in MaybeRefDeep#10573
byungsker wants to merge 3 commits into
TanStack:mainfrom
byungsker:fix/vue-query-options-querykey

byungsker commented Apr 25, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Apr 25, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

nx-cloud Bot commented Apr 25, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Apr 25, 2026 •

edited

Loading

Uh oh!

peterbud commented Aug 21, 2026

Uh oh!

byungsker commented Aug 22, 2026

Uh oh!

coderabbitai Bot commented Aug 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

byungsker commented Apr 25, 2026 • 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!

coderabbitai Bot commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

nx-cloud Bot commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Nx Cloud AI Fix Eligible

Uh oh!

pkg-pr-new Bot commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

peterbud commented Aug 21, 2026

Uh oh!

byungsker commented Aug 22, 2026

Uh oh!

coderabbitai Bot commented Aug 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

byungsker commented Apr 25, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Apr 25, 2026 •

edited

Loading

nx-cloud Bot commented Apr 25, 2026 •

edited

Loading

pkg-pr-new Bot commented Apr 25, 2026 •

edited

Loading