From 25f32fb42418c34b938b3480cf0360746fb677b3 Mon Sep 17 00:00:00 2001
From: Ousama Ben Younes <benyounes.ousama@gmail.com>
Date: Sat, 25 Apr 2026 22:40:23 +0000
Subject: [PATCH 1/2] fix(vue-query): preserve TQueryKey inference with generic
 params (#8199)

The mapped UseQueryOptions type wrapped queryKey in
MaybeRefDeep<DeepUnwrapRef<TQueryKey>>. The recursive DeepUnwrapRef on a
generic TQueryKey is opaque to TS's homomorphic mapped type inference,
so TQueryKey collapsed to its default (QueryKey) when useQuery was
called from a composable that propagates a generic into the queryKey.

For the queryKey property only, drop DeepUnwrapRef and use a single-
level MaybeRef<TQueryKey> wrap. Inference now binds TQueryKey to the
supplied queryKey shape; queryFn still receives DeepUnwrapRef<TQueryKey>
via the existing mapping for non-queryKey properties.

Co-Authored-By: Ora Studio <noreply@oratelecom.net>
---
 .../vue-query-generic-querykey-inference.md   |  5 ++++
 .../src/__tests__/useQuery.test-d.ts          | 23 ++++++++++++++-
 packages/vue-query/src/useQuery.ts            | 28 +++++++++++++------
 3 files changed, 46 insertions(+), 10 deletions(-)
 create mode 100644 .changeset/vue-query-generic-querykey-inference.md

diff --git a/.changeset/vue-query-generic-querykey-inference.md b/.changeset/vue-query-generic-querykey-inference.md
new file mode 100644
index 00000000000..5a24b50f6c6
--- /dev/null
+++ b/.changeset/vue-query-generic-querykey-inference.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/vue-query': patch
+---
+
+fix(vue-query): preserve `TQueryKey` inference when wrapping `useQuery` in a composable with a generic param
diff --git a/packages/vue-query/src/__tests__/useQuery.test-d.ts b/packages/vue-query/src/__tests__/useQuery.test-d.ts
index be9013e222b..56c92c15426 100644
--- a/packages/vue-query/src/__tests__/useQuery.test-d.ts
+++ b/packages/vue-query/src/__tests__/useQuery.test-d.ts
@@ -1,4 +1,4 @@
-import { describe, expectTypeOf, it } from 'vitest'
+import { assertType, describe, expectTypeOf, it } from 'vitest'
 import { computed, reactive, ref } from 'vue-demi'
 import { queryKey, sleep } from '@tanstack/query-test-utils'
 import { queryOptions, useQuery } from '..'
@@ -152,6 +152,27 @@ describe('useQuery', () => {
     })
   })
 
+  describe('generic queryKey inference (#8199)', () => {
+    it('should not error when wrapping useQuery in a composable that propagates a generic type to the queryKey', () => {
+      const basket = { fruit: 'apple', vegetable: 'broccoli' } as const
+
+      function getBasket<T extends 'fruit' | 'vegetable'>(type: T) {
+        return basket[type]
+      }
+
+      function useBasket<T extends 'fruit' | 'vegetable'>(type: T) {
+        return useQuery({
+          queryKey: ['basket', type] as const,
+          queryFn({ queryKey: [, t] }) {
+            return getBasket(t)
+          },
+        })
+      }
+
+      assertType(useBasket('fruit'))
+    })
+  })
+
   describe('custom composable', () => {
     it('should allow custom composable using UseQueryOptions', () => {
       const key = queryKey()
diff --git a/packages/vue-query/src/useQuery.ts b/packages/vue-query/src/useQuery.ts
index 116e91baefe..bab7f7119e7 100644
--- a/packages/vue-query/src/useQuery.ts
+++ b/packages/vue-query/src/useQuery.ts
@@ -42,15 +42,25 @@ export type UseQueryOptions<
               TQueryData,
               DeepUnwrapRef<TQueryKey>
             >)
-      : MaybeRefDeep<
-          QueryObserverOptions<
-            TQueryFnData,
-            TError,
-            TData,
-            TQueryData,
-            DeepUnwrapRef<TQueryKey>
-          >[Property]
-        >
+      : Property extends 'queryKey'
+        ? MaybeRef<
+            QueryObserverOptions<
+              TQueryFnData,
+              TError,
+              TData,
+              TQueryData,
+              TQueryKey
+            >[Property]
+          >
+        : MaybeRefDeep<
+            QueryObserverOptions<
+              TQueryFnData,
+              TError,
+              TData,
+              TQueryData,
+              DeepUnwrapRef<TQueryKey>
+            >[Property]
+          >
   } & ShallowOption
 >
 

From beb9b81cc2fe3703cabebded8234f40025e72696 Mon Sep 17 00:00:00 2001
From: Ousama Ben Younes <benyounes.ousama@gmail.com>
Date: Sat, 25 Apr 2026 23:04:46 +0000
Subject: [PATCH 2/2] test(vue-query): strengthen #8199 regression assertion
 with explicit TData

Per CodeRabbit feedback: bare assertType(useBasket('fruit')) only verified
the call compiled, which would still pass under the old buggy behavior
(TQueryKey collapsing to QueryKey, TData inferred as unknown). Lock the
regression by asserting the propagated TData explicitly.
---
 packages/vue-query/src/__tests__/useQuery.test-d.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/vue-query/src/__tests__/useQuery.test-d.ts b/packages/vue-query/src/__tests__/useQuery.test-d.ts
index 56c92c15426..7bb8cd8407b 100644
--- a/packages/vue-query/src/__tests__/useQuery.test-d.ts
+++ b/packages/vue-query/src/__tests__/useQuery.test-d.ts
@@ -2,7 +2,7 @@ import { assertType, describe, expectTypeOf, it } from 'vitest'
 import { computed, reactive, ref } from 'vue-demi'
 import { queryKey, sleep } from '@tanstack/query-test-utils'
 import { queryOptions, useQuery } from '..'
-import type { OmitKeyof, UseQueryOptions } from '..'
+import type { OmitKeyof, UseQueryOptions, UseQueryReturnType } from '..'
 
 describe('useQuery', () => {
   describe('Config object overload', () => {
@@ -169,7 +169,9 @@ describe('useQuery', () => {
         })
       }
 
-      assertType(useBasket('fruit'))
+      assertType<UseQueryReturnType<'apple' | 'broccoli', Error>>(
+        useBasket('fruit'),
+      )
     })
   })