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 (e.g., branded strings) inside queryKey tuples passed through queryOptions and useQuery.
Tests
- Added TypeScript declaration tests covering branded values directly in queryKey tuples and nested inside objects.

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

Run ID: 0accd6b5-bdef-4ed7-a457-a5b50519163a

📥 Commits

Reviewing files that changed from the base of the PR and between df73bb9 and af629b6.

📒 Files selected for processing (1)

.changeset/branded-types-fix.md

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

.changeset/branded-types-fix.md

📝 Walkthrough

Walkthrough

This PR updates MaybeRefDeep so branded types remain unchanged during recursive mapping, preventing inference errors when branded values appear in queryKey tuples passed from queryOptions to useQuery. Type tests cover tuple and object-wrapped branded values, and a patch changeset documents the fix.

Changes

Branded queryKey inference

Layer / File(s)	Summary
MaybeRefDeep branded-type handling `packages/vue-query/src/types.ts`	Adds a `__brand` conditional branch that preserves branded types before recursive object mapping.
Type inference validation `packages/vue-query/src/__tests__/queryOptions.test-d.ts`	Tests branded values in direct and object-wrapped `queryKey` tuples, including `queryOptions` passed to `useQuery`, while preserving the inferred data type.
Release metadata `.changeset/branded-types-fix.md`	Adds a patch changeset for `@tanstack/vue-query` describing the branded-type fix.

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

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: preserving branded types in MaybeRefDeep for vue-query.
Description check	✅ Passed	The description matches the template and includes changes, checklist items, and release impact details.
Linked Issues check	✅ Passed	The code and tests address `#9920` by preserving branded queryKey types so queryOptions results work with useQuery.
Out of Scope Changes check	✅ Passed	The changeset and type tests are directly related to the branded type fix and do not add unrelated scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ 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 df73bb9

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

☁️ Nx Cloud last updated this comment at 2026-04-25 04:59:09 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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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 1 commit 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

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