fix(vue-query): widen 'SkipToken' to 'symbol' and align 'queryOptions'/'infiniteQueryOptions' input

.changeset/vue-query-skiptoken-getter-typecheck.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/vue-query': minor
+---
+
+fix(vue-query): widen 'SkipToken' to 'symbol' and align 'queryOptions'/'infiniteQueryOptions' input

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

@@ -1,20 +1,30 @@
 import { assertType, describe, expectTypeOf, it } from 'vitest'
-import { dataTagSymbol } from '@tanstack/query-core'
-import { reactive } from 'vue-demi'
+import { dataTagSymbol, skipToken } from '@tanstack/query-core'
+import { computed, reactive, ref } from 'vue-demi'
 import { queryKey } from '@tanstack/query-test-utils'
 import { infiniteQueryOptions } from '../infiniteQueryOptions'
 import { QueryClient } from '../queryClient'
 import { useInfiniteQuery } from '../useInfiniteQuery'
-import type { InfiniteData } from '@tanstack/query-core'
+import type { InfiniteData, QueryKeyWithDataTag } from '@tanstack/query-core'
+import type { InfiniteQueryOptions } from '../infiniteQueryOptions'
 
 // Regression test for exported infiniteQueryOptions inference under declaration emit.
 // TypeScript should be able to name the return type without expanding the
 // internal data tag symbols into the consumer's .d.ts output.
-export const exportedInfiniteQueryOptions = infiniteQueryOptions({
-  queryKey: ['invalid'],
-  getNextPageParam: () => 1,
-  initialPageParam: 1,
-})
+export const exportedInfiniteQueryOptions: InfiniteQueryOptions<
+  unknown,
+  Error,
+  InfiniteData<unknown>,
+  Array<string>,
+  number
+> & {
+  initialData?: undefined
+} & QueryKeyWithDataTag<Array<string>, InfiniteData<unknown>, Error> =
+  infiniteQueryOptions({
+    queryKey: ['invalid'],
+    getNextPageParam: () => 1,
+    initialPageParam: 1,
+  })
 
 describe('infiniteQueryOptions', () => {
   it('should not allow excess properties', () => {
@@ -30,6 +40,66 @@ describe('infiniteQueryOptions', () => {
       }),
     )
   })
+  it('should allow a bare reactive getter for the whole queryKey array', () => {
+    const id = ref(1)
+
+    const options = infiniteQueryOptions({
+      queryKey: () => ['post', id.value] as const,
+      queryFn: () => Promise.resolve('data'),
+      getNextPageParam: () => 1,
+      initialPageParam: 1,
+    })
+
+    expectTypeOf(options.queryKey).not.toBeUndefined()
+  })
+  it('should allow computed ref as enabled property', () => {
+    const enabled = computed(() => true)
+
+    const options = infiniteQueryOptions({
+      queryKey: queryKey(),
+      queryFn: () => Promise.resolve(1),
+      getNextPageParam: () => 1,
+      initialPageParam: 1,
+      enabled,
+    })
+
+    expectTypeOf(options.queryKey).not.toBeUndefined()
+  })
+  it('should allow ref as enabled property', () => {
+    const enabled = ref(true)
+
+    const options = infiniteQueryOptions({
+      queryKey: queryKey(),
+      queryFn: () => Promise.resolve(1),
+      getNextPageParam: () => 1,
+      initialPageParam: 1,
+      enabled,
+    })
+
+    expectTypeOf(options.queryKey).not.toBeUndefined()
+  })
+  it('should allow getter function as enabled property', () => {
+    const options = infiniteQueryOptions({
+      queryKey: queryKey(),
+      queryFn: () => Promise.resolve(1),
+      getNextPageParam: () => 1,
+      initialPageParam: 1,
+      enabled: () => true,
+    })
+
+    expectTypeOf(options.queryKey).not.toBeUndefined()
+  })
+  it('should allow a plain callback as enabled property', () => {
+    const options = infiniteQueryOptions({
+      queryKey: queryKey(),
+      queryFn: () => Promise.resolve(1),
+      getNextPageParam: () => 1,
+      initialPageParam: 1,
+      enabled: (query) => query.state.data === undefined,
+    })
+
+    expectTypeOf(options.queryKey).not.toBeUndefined()
+  })
   it('should infer types for callbacks', () => {
     const key = queryKey()
     infiniteQueryOptions({
@@ -162,4 +232,59 @@ describe('infiniteQueryOptions', () => {
       InfiniteData<string, unknown> | undefined
     >()
   })
+
+  it('should allow a computed queryFn resolving to skipToken', () => {
+    const id = ref<string | null>('1')
+
+    const options = infiniteQueryOptions({
+      queryKey: computed(() => ['foo', id.value]),
+      queryFn: computed(() =>
+        id.value
+          ? ({ pageParam }: { pageParam: number }) =>
+              Promise.resolve({ id: id.value, pageParam })
+          : skipToken,
+      ),
+      getNextPageParam: () => 1,
+      initialPageParam: 1,
+    })
+
+    const { data } = reactive(useInfiniteQuery(options))
+
+    expectTypeOf(data).toEqualTypeOf<
+      InfiniteData<{ id: string | null; pageParam: number }> | undefined
+    >()
+  })
+
+  it('should reject a ref for an option other than enabled/queryKey/queryFn', () => {
+    // Unlike `useInfiniteQuery`, `infiniteQueryOptions` only tracks `enabled`/`queryKey`/`queryFn` reactively —
+    // every other option (`staleTime` here) stays a plain value. This is deliberate: the returned object is
+    // shared with plain APIs like `queryClient.infiniteQuery`, so a `ref` slipping into an arbitrary option
+    // would make the declared (plain) type lie about the actual (reactive) value.
+    assertType(
+      infiniteQueryOptions({
+        queryKey: queryKey(),
+        queryFn: ({ pageParam }: { pageParam: number }) =>
+          Promise.resolve(pageParam),
+        getNextPageParam: () => 1,
+        initialPageParam: 1,
+        // @ts-expect-error staleTime must be a plain value, not a ref
+        staleTime: ref(1000),
+      }),
+    )
+  })
+
+  it('should reject the whole options object wrapped in a ref', () => {
+    assertType(
+      infiniteQueryOptions(
+        // @ts-expect-error infiniteQueryOptions only accepts a plain object, not a ref
+        ref({
+          queryKey: queryKey(),
+          queryFn: ({ pageParam }: { pageParam: number }) =>
+            Promise.resolve(pageParam),
+          getNextPageParam: () => 1,
+          initialPageParam: 1,
+        }),
+      ),
+    )
+  })
 })

packages/vue-query/src/__tests__/queryClient.test.ts

@@ -470,8 +470,8 @@ describe('QueryCache', () => {
 
       const options = infiniteQueryOptions({
         queryKey: queryKeyRef,
-        initialPageParam: ref(0),
-        getNextPageParam: ref(getNextPageParam),
+        initialPageParam: 0,
+        getNextPageParam,
       })
 
       queryClient.infiniteQuery({

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

@@ -1,6 +1,6 @@
 import { assertType, describe, expectTypeOf, it } from 'vitest'
 import { computed, reactive, ref } from 'vue-demi'
-import { dataTagSymbol } from '@tanstack/query-core'
+import { dataTagSymbol, skipToken } from '@tanstack/query-core'
 import { queryKey } from '@tanstack/query-test-utils'
 import { QueryClient } from '../queryClient'
 import { queryOptions } from '../queryOptions'
@@ -362,4 +362,64 @@ describe('queryOptions', () => {
 
     expectTypeOf(options.queryKey).not.toBeUndefined()
   })
+
+  it('should narrow data to a defined type for a computed queryFn resolving to skipToken', () => {
+    const id = ref<string | null>('1')
+
+    const options = queryOptions({
+      queryKey: computed(() => ['foo', id.value]),
+      queryFn: computed(() =>
+        id.value ? () => Promise.resolve({ id: '1' }) : skipToken,
+      ),
+    })
+
+    const { data } = reactive(useQuery(options))
+
+    expectTypeOf(data).toEqualTypeOf<{ id: string } | undefined>()
+  })
+
+  it('should reject a ref for an option other than enabled/queryKey/queryFn', () => {
+    // Unlike `useQuery`, `queryOptions` only tracks `enabled`/`queryKey`/`queryFn` reactively — every other
+    // option (`staleTime` here) stays a plain value. This is deliberate: the returned object is shared with
+    // plain APIs like `queryClient.fetchQuery`, so a `ref` slipping into an arbitrary option would make the
+    // declared (plain) type lie about the actual (reactive) value.
+    assertType(
+      queryOptions({
+        // The directive sits on `queryKey`, not `staleTime`: overload resolution fails on the whole
+        // object literal and TypeScript reports it at the first property.
+        // @ts-expect-error staleTime must be a plain value, not a ref
+        queryKey: queryKey(),
+        queryFn: () => Promise.resolve(5),
+        staleTime: ref(1000),
+      }),
+    )
+  })
+
+  it('should reject the whole options object wrapped in a ref', () => {
+    assertType(
+      queryOptions(
+        // @ts-expect-error queryOptions only accepts a plain object or a getter for the whole object, not a ref
+        ref({
+          queryKey: queryKey(),
+          queryFn: () => Promise.resolve(5),
+        }),
+      ),
+    )
+  })
+
+  it('should narrow data to a defined type for a conditional skipToken inside a whole-options getter', () => {
+    const id = ref<string | null>('1')
+
+    const options = queryOptions(() => {
+      const current = id.value
+      return {
+        queryKey: ['foo', current],
+        queryFn: current ? () => Promise.resolve({ id: current }) : skipToken,
+      }
+    })
+
+    const { data } = reactive(useQuery(options))
+
+    expectTypeOf(data).toEqualTypeOf<{ id: string } | undefined>()
+  })
 })

packages/vue-query/src/__tests__/useInfiniteQuery.test-d.tsx

@@ -1,5 +1,6 @@
 import { assertType, describe, expectTypeOf, it } from 'vitest'
 import { computed, reactive, ref } from 'vue-demi'
+import { skipToken } from '@tanstack/query-core'
 import { queryKey, sleep } from '@tanstack/query-test-utils'
 import { useInfiniteQuery } from '../useInfiniteQuery'
 import { infiniteQueryOptions } from '../infiniteQueryOptions'
@@ -103,6 +104,31 @@ describe('Discriminated union return type', () => {
     }
   })
 
+  it('should accept a computed queryFn resolving to skipToken', () => {
+    const key = queryKey()
+    const id = ref<string | null>('1')
+
+    // The resulting `data` type can't be asserted here: `vue-tsc`'s language-service plugin (unlike `tsc` or
+    // vitest's own typecheck) fails to resolve `TQueryFnData` through this inference path, leaking the
+    // unresolved type parameter into `query.data`'s type. Runtime skip/refetch behavior is covered in
+    // `useInfiniteQuery.test.ts`.
+    assertType(
+      reactive(
+        useInfiniteQuery({
+          queryKey: key,
+          queryFn: computed(() =>
+            id.value
+              ? ({ pageParam }: { pageParam: number }) =>
+                  sleep(0).then(() => 'data on page ' + pageParam)
+              : skipToken,
+          ),
+          getNextPageParam: () => undefined,
+          initialPageParam: 0,
+        }),
+      ),
+    )
+  })
+
   it('should accept computed options using infiniteQueryOptions', () => {
     const key = queryKey()
     const options = computed(() =>
@@ -138,12 +164,10 @@ describe('Discriminated union return type', () => {
 })
 
 describe('queryKey reactivity rules', () => {
-  it('should reject a bare reactive getter for the whole queryKey array', () => {
+  it('should accept a bare reactive getter for the whole queryKey array', () => {
     const id = ref(1)
     assertType(
       useInfiniteQuery({
-        // @ts-expect-error when passed directly to useInfiniteQuery, queryKey cannot be a bare
-        // reactive getter for the whole array (queryOptions() allows this)
         queryKey: () => ['post', id.value],
         queryFn: () => sleep(0).then(() => 'Some data'),
         getNextPageParam: () => undefined,

packages/vue-query/src/__tests__/useInfiniteQuery.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { ref } from 'vue-demi'
+import { computed, ref } from 'vue-demi'
+import { skipToken } from '@tanstack/query-core'
 import { queryKey, sleep } from '@tanstack/query-test-utils'
 import { useInfiniteQuery } from '../useInfiniteQuery'
 import { infiniteQueryOptions } from '../infiniteQueryOptions'
@@ -129,4 +130,60 @@ describe('useInfiniteQuery', () => {
     expect(hasNextPage.value).toBe(false)
     expect(isFetching.value).toBe(false)
   })
+
+  it('should skip the query while a computed queryFn resolves to skipToken, and run it once defined', async () => {
+    const key = queryKey()
+    const id = ref<string | null>(null)
+    const fetchFn = vi.fn(({ pageParam }: { pageParam: number }) =>
+      sleep(10).then(() => 'data on page ' + pageParam),
+    )
+
+    const { data, status } = useInfiniteQuery({
+      queryKey: key,
+      queryFn: computed(() => (id.value ? fetchFn : skipToken)),
+      initialPageParam: 0,
+      getNextPageParam: () => 12,
+    })
+
+    await vi.advanceTimersByTimeAsync(10)
+
+    expect(fetchFn).not.toHaveBeenCalled()
+    expect(status.value).toStrictEqual('pending')
+
+    id.value = '1'
+
+    await vi.advanceTimersByTimeAsync(10)
+
+    expect(fetchFn).toHaveBeenCalledTimes(1)
+    expect(status.value).toStrictEqual('success')
+    expect(data.value).toStrictEqual({
+      pageParams: [0],
+      pages: ['data on page 0'],
+    })
+  })
+
+  describe('queryKey reactivity rules', () => {
+    it('should refetch when a bare reactive getter for the whole queryKey array changes', async () => {
+      const key = queryKey()
+      const id = ref(1)
+      const fetchFn = vi.fn(() => sleep(10).then(() => 'Some data'))
+
+      useInfiniteQuery({
+        queryKey: () => [...key, id.value],
+        queryFn: fetchFn,
+        initialPageParam: 0,
+        getNextPageParam: () => undefined,
+      })
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(fetchFn).toHaveBeenCalledTimes(1)
+
+      id.value = 2
+
+      await vi.advanceTimersByTimeAsync(10)
+
+      expect(fetchFn).toHaveBeenCalledTimes(2)
+    })
+  })
 })