throw error if enabled: true/skiptoken and no cached data

Author: DogPawHat

packages/query-core/src/__tests__/queryClient.test-d.tsx

@@ -1,5 +1,6 @@
 import { assertType, describe, expectTypeOf, it } from 'vitest'
 import { QueryClient } from '../queryClient'
+import { skipToken } from '../utils'
 import type { MutationFilters, QueryFilters, Updater } from '../utils'
 import type { Mutation } from '../mutation'
 import type { Query, QueryState } from '../query'
@@ -236,6 +237,37 @@ describe('query', () => {
 
     expectTypeOf(options).toEqualTypeOf<Promise<number>>()
   })
+
+  it('should infer select type with skipToken queryFn', () => {
+    const options = new QueryClient().query({
+      queryKey: ['key'],
+      queryFn: skipToken,
+      select: (data: string) => data.length,
+    })
+
+    expectTypeOf(options).toEqualTypeOf<Promise<number>>()
+  })
+
+  it('should infer select type with skipToken queryFn and enabled false', () => {
+    const options = new QueryClient().query({
+      queryKey: ['key'],
+      queryFn: skipToken,
+      enabled: false,
+      select: (data: string) => data.length,
+    })
+
+    expectTypeOf(options).toEqualTypeOf<Promise<number>>()
+  })
+
+  it('should infer select type with skipToken queryFn and enabled true', () => {
+    const options = new QueryClient().query({
+      queryKey: ['key'],
+      enabled: false,
+      select: (data: string) => data.length,
+    })
+
+    expectTypeOf(options).toEqualTypeOf<Promise<number>>()
+  })
 })
 
 describe('infiniteQuery', () => {

packages/query-core/src/__tests__/queryClient.test.tsx

@@ -978,6 +978,123 @@ describe('queryClient', () => {
       expect(second).toBe(first)
     })
 
+    test('should throw when disabled and no cached data exists', async () => {
+      const key = queryKey()
+      const queryFn = vi.fn(() => Promise.resolve('data'))
+
+      await expect(
+        queryClient.query({
+          queryKey: key,
+          queryFn,
+          enabled: false,
+        }),
+      ).rejects.toThrowError()
+
+      expect(queryFn).not.toHaveBeenCalled()
+    })
+
+    test('should return cached data when disabled and apply select', async () => {
+      const key = queryKey()
+      const queryFn = vi.fn(() => Promise.resolve('fetched-data'))
+
+      queryClient.setQueryData(key, 'cached-data')
+
+      const result = await queryClient.query({
+        queryKey: key,
+        queryFn,
+        enabled: false,
+        staleTime: 0,
+        select: (data) => `${data}-selected`,
+      })
+
+      expect(result).toBe('cached-data-selected')
+      expect(queryFn).not.toHaveBeenCalled()
+    })
+
+    test('should throw when skipToken is provided and no cached data exists', async () => {
+      const key = queryKey()
+      const select = vi.fn((data: unknown) => (data as string).length)
+
+      await expect(
+        queryClient.query({
+          queryKey: key,
+          queryFn: skipToken,
+          select,
+        }),
+      ).rejects.toThrowError()
+
+      expect(select).not.toHaveBeenCalled()
+    })
+
+    test('should return cached data when skipToken is provided', async () => {
+      const key = queryKey()
+
+      queryClient.setQueryData(key, 'cached-data')
+
+      const result = await queryClient.query({
+        queryKey: key,
+        queryFn: skipToken,
+        select: (data: unknown) => (data as string).length,
+      })
+
+      expect(result).toBe('cached-data'.length)
+    })
+
+    test('should return cached data when skipToken and enabled false are both provided', async () => {
+      const key = queryKey()
+
+      queryClient.setQueryData(key, { value: 'cached-data' })
+
+      const result = await queryClient.query({
+        queryKey: key,
+        queryFn: skipToken,
+        enabled: false,
+        select: (data: { value: string }) => data.value.toUpperCase(),
+      })
+
+      expect(result).toBe('CACHED-DATA')
+    })
+
+    test('should throw when enabled resolves true and skipToken are provided with no cached data', async () => {
+      await expect(
+        queryClient.query({
+          queryKey: queryKey(),
+          queryFn: skipToken,
+          enabled: true,
+        }),
+      ).rejects.toThrowError()
+    })
+
+    test('should return cached data when enabled resolves false and skipToken are provided', async () => {
+      const key1 = queryKey()
+      queryClient.setQueryData(key1, { value: 'cached-data' })
+
+      const booleanDisabledResult = await queryClient.query({
+        queryKey: key1,
+        queryFn: skipToken,
+        enabled: false,
+        select: (data: { value: string }) => data.value.length,
+      })
+
+      expect(booleanDisabledResult).toBe('cached-data'.length)
+    })
+
+    test('should return cached data when enabled callback returns false even if queryFn would return different data', async () => {
+      const key = queryKey()
+      const queryFn = vi.fn(() => Promise.resolve('fetched-data'))
+
+      queryClient.setQueryData(key, 'cached-data')
+
+      const result = await queryClient.query({
+        queryKey: key,
+        queryFn,
+        enabled: () => false,
+      })
+
+      expect(result).toBe('cached-data')
+      expect(queryFn).not.toHaveBeenCalled()
+    })
+
     test('should read from cache with static staleTime even if invalidated', async () => {
       const key = queryKey()
 

packages/query-core/src/queryClient.ts

@@ -4,6 +4,7 @@ import {
   hashQueryKeyByOptions,
   noop,
   partialMatchKey,
+  resolveEnabled,
   resolveStaleTime,
   skipToken,
 } from './utils'
@@ -365,6 +366,25 @@ export class QueryClient {
     }
 
     const query = this.#queryCache.build(this, defaultedOptions)
+    const isEnabled = resolveEnabled(defaultedOptions.enabled, query) !== false
+
+    if (!isEnabled) {
+      const queryData = query.state.data
+
+      if (queryData === undefined) {
+        throw new Error(
+          `Missing query data for disabled query. Query hash: '${query.queryHash}'`,
+        )
+      }
+
+      const select = defaultedOptions.select
+
+      if (select) {
+        return select(queryData)
+      }
+
+      return queryData as unknown as TData
+    }
 
     const isStale = query.isStaleByTime(
       resolveStaleTime(defaultedOptions.staleTime, query),

packages/query-core/src/types.ts

@@ -502,6 +502,11 @@ export interface QueryExecuteOptions<
   'queryKey'
 > {
   initialPageParam?: never
+  /**
+   * Set this to `false` or a function that returns `false` to disable fetching.
+   * If cached data exists, it will be returned.
+   */
+  enabled?: Enabled<TQueryFnData, TError, TQueryData, TQueryKey>
   select?: (data: TQueryData) => TData
   /**
    * The time in milliseconds after data is considered stale.