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

.changeset/branded-types-fix.md

@@ -0,0 +1,7 @@
+---
+"@tanstack/vue-query": patch
+---
+
+fix(vue-query): preserve branded types in MaybeRefDeep
+
+Branded types (e.g. `string & { __brand: 'PostId' }`) were being recursively mapped by `MaybeRefDeep`, causing TypeScript inference failures when used in `queryKey` tuples passed from `queryOptions` to `useQuery`. This fix adds a terminal branch to `MaybeRefDeep` so that branded types are preserved as-is instead of having their properties unwrapped.

packages/vue-query/src/__tests__/queryOptions.test-d.ts

@@ -332,4 +332,46 @@ describe('queryOptions', () => {
 
     expectTypeOf(options.queryKey).not.toBeUndefined()
   })
+
+  it('should work with branded queryKey', () => {
+    type PostId = string & { readonly __brand: 'PostId' }
+    const postId = '123' as PostId
+
+    const options = queryOptions({
+      queryKey: ['post', postId],
+      queryFn: () => Promise.resolve({ id: postId }),
+    })
+
+    expectTypeOf(options.queryKey).not.toBeUndefined()
+
+    const { data } = reactive(useQuery(options))
+    expectTypeOf(data).toEqualTypeOf<{ id: PostId } | undefined>()
+  })
+
+  it('should work with branded queryKey inside MaybeRefOrGetter', () => {
+    type PostId = string & { readonly __brand: 'PostId' }
+    const postId = '123' as PostId
+
+    const simpleOptions = queryOptions({
+      queryKey: ['post', postId],
+      queryFn: () => Promise.resolve({ id: postId }),
+    })
+    const { data: simpleData } = reactive(useQuery(simpleOptions))
+    expectTypeOf(simpleData).toEqualTypeOf<{ id: PostId } | undefined>()
+
+    const nestedOptions = queryOptions({
+      queryKey: ['post', { postId }],
+      queryFn: () => Promise.resolve({ id: postId }),
+    })
+    const { data: nestedData } = reactive(useQuery(nestedOptions))
+    expectTypeOf(nestedData).toEqualTypeOf<{ id: PostId } | undefined>()
+
+    const { data: inlineData } = reactive(
+      useQuery({
+        queryKey: ['post', { postId }],
+        queryFn: () => Promise.resolve({ id: postId }),
+      }),
+    )
+    expectTypeOf(inlineData).toEqualTypeOf<{ id: PostId } | undefined>()
+  })
 })

packages/vue-query/src/types.ts

@@ -31,11 +31,13 @@ export type MaybeRefOrGetter<T> = MaybeRef<T> | (() => T)
 export type MaybeRefDeep<T> = MaybeRef<
   T extends Function
     ? T
-    : T extends object
-      ? {
-          [Property in keyof T]: MaybeRefDeep<T[Property]>
-        }
-      : T
+    : T extends { __brand: infer _ }
+      ? T
+      : T extends object
+        ? {
+            [Property in keyof T]: MaybeRefDeep<T[Property]>
+          }
+        : T
 >
 
 export type NoUnknown<T> = Equal<unknown, T> extends true ? never : T