fix(vue-query): preserve discriminated union narrowing in UseBaseQueryReturnType (#9244)

Make the mapped type explicitly distributive over each variant of
QueryObserverResult, and lock in the narrowing patterns that work
without reactive() (direct data.value !== undefined check) versus
those that require reactive() (narrowing via isSuccess / status).

Fixes #9244

Generated by Claude Code
Vibe coded by ousamabenyounes

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ousamabenyounes

.changeset/vue-query-narrow-result-type.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/vue-query': patch
+---
+
+fix(vue-query): preserve discriminated union narrowing in `UseBaseQueryReturnType`
+
+Make the mapped type explicitly distributive over each variant of `QueryObserverResult`, and document the narrowing patterns that work without `reactive()` (direct `data.value !== undefined` checks) versus those that require `reactive()` (narrowing via `isSuccess`/`status`). Adds type-test coverage for the issue scenario.

docs/framework/vue/typescript.md

@@ -68,6 +68,8 @@ if (isSuccess) {
 
 [typescript playground](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBAbzgVwM4FMCKz1QJ5wC+cAZlBCHAOQACMAhgHaoMDGA1gPQBuOAtAEcc+KgFgAUKEixEcKOnqsYwbuiKlylKr3RUA3BImsIzeEgAm9BgBo4wVAGVkrVulSp1AXjkKlK9AAUaFjCeAEA2lQwbjBUALq2AQCUcJ4AfHAACpr26AB08qgQADaqAQCsSVWGkiRwAfZOLm6oKQgScJ1wlgwSnJydAHoA-BKEEkA)
 
+> **Note:** Wrapping `useQuery(...)` in `reactive(...)` is required to narrow `data` from a discriminator like `isSuccess` or `status`. Destructuring directly from `useQuery(...)` produces independent refs, and TypeScript cannot propagate narrowing across separate refs — `if (isSuccess.value)` will not narrow `data.value` from `T | undefined` to `T`. If you cannot use `reactive()`, narrow the value ref directly with `if (data.value !== undefined)`.
+
 [//]: # 'TypeNarrowing'
 [//]: # 'TypingError'
 

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

@@ -2,6 +2,7 @@ import { 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 { Ref } from 'vue-demi'
 import type { OmitKeyof, UseQueryOptions } from '..'
 
 describe('useQuery', () => {
@@ -268,6 +269,75 @@ describe('useQuery', () => {
     })
   })
 
+  // Regression coverage for #9244 — narrowing across the discriminated
+  // result union from useQuery() under the patterns users actually write.
+  describe('issue #9244 — narrowing without reactive()', () => {
+    it('useQuery() return preserves the discriminated union (no reactive())', () => {
+      const key = queryKey()
+
+      const query = useQuery({
+        queryKey: key,
+        queryFn: () => sleep(0).then(() => 'Some data'),
+      })
+
+      // Whole-result narrowing requires reactive() because the discriminator
+      // sits inside `Ref<boolean>`. The `data` ref itself is still a
+      // discriminated union of `Ref<string> | Ref<undefined>` (matches the
+      // shape documented in docs/framework/vue/typescript.md).
+      expectTypeOf(query.data).toEqualTypeOf<Ref<string> | Ref<undefined>>()
+    })
+
+    it('data.value narrows after a direct undefined check', () => {
+      const key = queryKey()
+
+      const { data } = useQuery({
+        queryKey: key,
+        queryFn: () => sleep(0).then(() => 'Some data'),
+      })
+
+      // This is the recommended pattern when `reactive()` is not used:
+      // narrow on `.value !== undefined` rather than relying on `isSuccess`.
+      if (data.value !== undefined) {
+        expectTypeOf(data.value).toEqualTypeOf<string>()
+        expectTypeOf(data).toEqualTypeOf<Ref<string>>()
+      }
+    })
+
+    it('reactive() preserves narrowing across destructured properties', () => {
+      const key = queryKey()
+
+      // Destructuring directly from `useQuery()` (without `reactive()`)
+      // breaks cross-property narrowing because each ref is independent —
+      // wrapping in `reactive()` flattens the refs and keeps the
+      // discriminated union linkage.
+      const { data, isSuccess } = reactive(
+        useQuery({
+          queryKey: key,
+          queryFn: () => sleep(0).then(() => 'Some data'),
+        }),
+      )
+
+      if (isSuccess) {
+        expectTypeOf(data).toEqualTypeOf<string>()
+      }
+    })
+
+    it('reactive() narrows on status discriminator', () => {
+      const key = queryKey()
+
+      const { data, status } = reactive(
+        useQuery({
+          queryKey: key,
+          queryFn: () => sleep(0).then(() => 'Some data'),
+        }),
+      )
+
+      if (status === 'success') {
+        expectTypeOf(data).toEqualTypeOf<string>()
+      }
+    })
+  })
+
   describe('accept ref options', () => {
     it('should accept ref options', () => {
       const options = ref({

packages/vue-query/src/useBaseQuery.ts

@@ -24,20 +24,29 @@ import type { UseQueryOptions } from './useQuery'
 import type { UseInfiniteQueryOptions } from './useInfiniteQuery'
 import type { MaybeRefOrGetter } from './types'
 
+// Distributive over `TResult` so each member of the discriminated union
+// (success / pending / error / placeholder / refetch-error / loading-error)
+// produces its own ref-mapped object, instead of collapsing into a single
+// `{ data: Ref<TData | undefined>, ... }`. This preserves narrowing through
+// `reactive()` and direct property access on the un-destructured result.
+// See packages/vue-query/src/__tests__/useQuery.test-d.ts for the contracts
+// this preserves (and the destructure-without-reactive limitation).
 export type UseBaseQueryReturnType<
   TData,
   TError,
   TResult = QueryObserverResult<TData, TError>,
-> = {
-  [K in keyof TResult]: K extends
-    | 'fetchNextPage'
-    | 'fetchPreviousPage'
-    | 'refetch'
-    ? TResult[K]
-    : Ref<Readonly<TResult>[K]>
-} & {
-  suspense: () => Promise<TResult>
-}
+> = TResult extends unknown
+  ? {
+      [K in keyof TResult]: K extends
+        | 'fetchNextPage'
+        | 'fetchPreviousPage'
+        | 'refetch'
+        ? TResult[K]
+        : Ref<Readonly<TResult>[K]>
+    } & {
+      suspense: () => Promise<QueryObserverResult<TData, TError>>
+    }
+  : never
 
 type UseQueryOptionsGeneric<
   TQueryFnData,