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

.changeset/fix-branded-types-mayberefdeep.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/vue-query': patch
+---
+
+fix(vue-query): preserve branded types in `MaybeRefDeep` so branded `queryKey`s (e.g. `string & { __brand }`) pass through `queryOptions` into `useQuery` without a TS2769 overload error

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

@@ -362,4 +362,64 @@ 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 inlineData = reactive(
+      useQuery({
+        queryKey: ['post', postId],
+        queryFn: () => Promise.resolve({ id: postId }),
+      }),
+    )
+
+    expectTypeOf(inlineData.data).toEqualTypeOf<{ id: PostId } | undefined>()
+  })
+
+  it('should still tag the queryKey with the queryFn result when it contains branded types', () => {
+    type PostId = string & { readonly __brand: 'PostId' }
+    const postId = '123' as PostId
+
+    const { queryKey: tagged } = queryOptions({
+      queryKey: ['post', { postId }],
+      queryFn: () => Promise.resolve({ id: postId }),
+    })
+
+    expectTypeOf(tagged[dataTagSymbol]).toEqualTypeOf<{ id: PostId }>()
+  })
 })

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