@tanstack/query-core 5.47.0 → 5.49.0

package/src/__tests__/queryObserver.test.tsx

@@ -52,6 +52,173 @@ describe('queryObserver', () => {
     unsubscribe()
   })
 
+  describe('enabled is a callback that initially returns false', () => {
+    let observer: QueryObserver<string, Error, string, string, Array<string>>
+    let enabled: boolean
+    let count: number
+    let key: Array<string>
+
+    beforeEach(() => {
+      key = queryKey()
+      count = 0
+      enabled = false
+
+      observer = new QueryObserver(queryClient, {
+        queryKey: key,
+        staleTime: Infinity,
+        enabled: () => enabled,
+        queryFn: async () => {
+          await sleep(10)
+          count++
+          return 'data'
+        },
+      })
+    })
+
+    test('should not fetch on mount', () => {
+      const unsubscribe = observer.subscribe(vi.fn())
+
+      // Has not fetched and is not fetching since its disabled
+      expect(count).toBe(0)
+      expect(observer.getCurrentResult()).toMatchObject({
+        status: 'pending',
+        fetchStatus: 'idle',
+        data: undefined,
+      })
+
+      unsubscribe()
+    })
+
+    test('should not be re-fetched when invalidated with refetchType: all', async () => {
+      const unsubscribe = observer.subscribe(vi.fn())
+
+      queryClient.invalidateQueries({ queryKey: key, refetchType: 'all' })
+
+      //So we still expect it to not have fetched and not be fetching
+      expect(count).toBe(0)
+      expect(observer.getCurrentResult()).toMatchObject({
+        status: 'pending',
+        fetchStatus: 'idle',
+        data: undefined,
+      })
+      await waitFor(() => expect(count).toBe(0))
+
+      unsubscribe()
+    })
+
+    test('should still trigger a fetch when refetch is called', async () => {
+      const unsubscribe = observer.subscribe(vi.fn())
+
+      expect(enabled).toBe(false)
+
+      //Not the same with explicit refetch, this will override enabled and trigger a fetch anyway
+      observer.refetch()
+
+      expect(observer.getCurrentResult()).toMatchObject({
+        status: 'pending',
+        fetchStatus: 'fetching',
+        data: undefined,
+      })
+
+      await waitFor(() => expect(count).toBe(1))
+      expect(observer.getCurrentResult()).toMatchObject({
+        status: 'success',
+        fetchStatus: 'idle',
+        data: 'data',
+      })
+
+      unsubscribe()
+    })
+
+    test('should fetch if unsubscribed, then enabled returns true, and then re-subscribed', async () => {
+      let unsubscribe = observer.subscribe(vi.fn())
+      expect(observer.getCurrentResult()).toMatchObject({
+        status: 'pending',
+        fetchStatus: 'idle',
+        data: undefined,
+      })
+
+      unsubscribe()
+
+      enabled = true
+
+      unsubscribe = observer.subscribe(vi.fn())
+
+      expect(observer.getCurrentResult()).toMatchObject({
+        status: 'pending',
+        fetchStatus: 'fetching',
+        data: undefined,
+      })
+
+      await waitFor(() => expect(count).toBe(1))
+
+      unsubscribe()
+    })
+
+    test('should not be re-fetched if not subscribed to after enabled was toggled to true', async () => {
+      const unsubscribe = observer.subscribe(vi.fn())
+
+      // Toggle enabled
+      enabled = true
+
+      unsubscribe()
+
+      queryClient.invalidateQueries({ queryKey: key, refetchType: 'active' })
+
+      expect(observer.getCurrentResult()).toMatchObject({
+        status: 'pending',
+        fetchStatus: 'idle',
+        data: undefined,
+      })
+      expect(count).toBe(0)
+    })
+
+    test('should not be re-fetched if not subscribed to after enabled was toggled to true', async () => {
+      const unsubscribe = observer.subscribe(vi.fn())
+
+      // Toggle enabled
+      enabled = true
+
+      queryClient.invalidateQueries({ queryKey: key, refetchType: 'active' })
+
+      expect(observer.getCurrentResult()).toMatchObject({
+        status: 'pending',
+        fetchStatus: 'fetching',
+        data: undefined,
+      })
+      await waitFor(() => expect(count).toBe(1))
+
+      unsubscribe()
+    })
+
+    test('should handle that the enabled callback updates the return value', async () => {
+      const unsubscribe = observer.subscribe(vi.fn())
+
+      // Toggle enabled
+      enabled = true
+
+      queryClient.invalidateQueries({ queryKey: key, refetchType: 'inactive' })
+
+      //should not refetch since it was active and we only refetch inactive
+      await waitFor(() => expect(count).toBe(0))
+
+      queryClient.invalidateQueries({ queryKey: key, refetchType: 'active' })
+
+      //should refetch since it was active and we refetch active
+      await waitFor(() => expect(count).toBe(1))
+
+      // Toggle enabled
+      enabled = false
+
+      //should not refetch since it is not active and we only refetch active
+      queryClient.invalidateQueries({ queryKey: key, refetchType: 'active' })
+
+      await waitFor(() => expect(count).toBe(1))
+
+      unsubscribe()
+    })
+  })
+
   test('should be able to read latest data when re-subscribing (but not re-fetching)', async () => {
     const key = queryKey()
     let count = 0
@@ -429,6 +596,20 @@ describe('queryObserver', () => {
     expect(queryFn).toHaveBeenCalledTimes(0)
   })
 
+  test('should not trigger a fetch when subscribed and disabled by callback', async () => {
+    const key = queryKey()
+    const queryFn = vi.fn<Array<unknown>, string>().mockReturnValue('data')
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn,
+      enabled: () => false,
+    })
+    const unsubscribe = observer.subscribe(() => undefined)
+    await sleep(1)
+    unsubscribe()
+    expect(queryFn).toHaveBeenCalledTimes(0)
+  })
+
   test('should not trigger a fetch when not subscribed', async () => {
     const key = queryKey()
     const queryFn = vi.fn<Array<unknown>, string>().mockReturnValue('data')

package/src/focusManager.ts

@@ -17,7 +17,7 @@ export class FocusManager extends Subscribable<Listener> {
     super()
     this.#setup = (onFocus) => {
       // addEventListener does not exist in React Native, but window does
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      // eslint-disable-next-line ts/no-unnecessary-condition
       if (!isServer && window.addEventListener) {
         const listener = () => onFocus()
         // Listen to visibilitychange
@@ -78,7 +78,7 @@ export class FocusManager extends Subscribable<Listener> {
     }
 
     // document global can be unavailable in react native
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    // eslint-disable-next-line ts/no-unnecessary-condition
     return globalThis.document?.visibilityState !== 'hidden'
   }
 }

package/src/hydration.ts

@@ -13,15 +13,20 @@ import type { Query, QueryState } from './query'
 import type { Mutation, MutationState } from './mutation'
 
 // TYPES
+type TransformerFn = (data: any) => any
+function defaultTransformerFn(data: any): any {
+  return data
+}
 
 export interface DehydrateOptions {
+  serializeData?: TransformerFn
   shouldDehydrateMutation?: (mutation: Mutation) => boolean
   shouldDehydrateQuery?: (query: Query) => boolean
 }
 
 export interface HydrateOptions {
   defaultOptions?: {
-    transformPromise?: (promise: Promise<any>) => Promise<any>
+    deserializeData?: TransformerFn
     queries?: QueryOptions
     mutations?: MutationOptions<unknown, DefaultError, unknown, unknown>
   }
@@ -62,13 +67,21 @@ function dehydrateMutation(mutation: Mutation): DehydratedMutation {
 // consuming the de/rehydrated data, typically with useQuery on the client.
 // Sometimes it might make sense to prefetch data on the server and include
 // in the html-payload, but not consume it on the initial render.
-function dehydrateQuery(query: Query): DehydratedQuery {
+function dehydrateQuery(
+  query: Query,
+  serializeData: TransformerFn,
+): DehydratedQuery {
   return {
-    state: query.state,
+    state: {
+      ...query.state,
+      ...(query.state.data !== undefined && {
+        data: serializeData(query.state.data),
+      }),
+    },
     queryKey: query.queryKey,
     queryHash: query.queryHash,
     ...(query.state.status === 'pending' && {
-      promise: query.promise?.catch((error) => {
+      promise: query.promise?.then(serializeData).catch((error) => {
         if (process.env.NODE_ENV !== 'production') {
           console.error(
             `A query that was dehydrated as pending ended up rejecting. [${query.queryHash}]: ${error}; The error will be redacted in production builds`,
@@ -110,10 +123,17 @@ export function dehydrate(
     client.getDefaultOptions().dehydrate?.shouldDehydrateQuery ??
     defaultShouldDehydrateQuery
 
+  const serializeData =
+    options.serializeData ??
+    client.getDefaultOptions().dehydrate?.serializeData ??
+    defaultTransformerFn
+
   const queries = client
     .getQueryCache()
     .getAll()
-    .flatMap((query) => (filterQuery(query) ? [dehydrateQuery(query)] : []))
+    .flatMap((query) =>
+      filterQuery(query) ? [dehydrateQuery(query, serializeData)] : [],
+    )
 
   return { mutations, queries }
 }
@@ -129,10 +149,14 @@ export function hydrate(
 
   const mutationCache = client.getMutationCache()
   const queryCache = client.getQueryCache()
+  const deserializeData =
+    options?.defaultOptions?.deserializeData ??
+    client.getDefaultOptions().hydrate?.deserializeData ??
+    defaultTransformerFn
 
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  // eslint-disable-next-line ts/no-unnecessary-condition
   const mutations = (dehydratedState as DehydratedState).mutations || []
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  // eslint-disable-next-line ts/no-unnecessary-condition
   const queries = (dehydratedState as DehydratedState).queries || []
 
   mutations.forEach(({ state, ...mutationOptions }) => {
@@ -150,13 +174,19 @@ export function hydrate(
   queries.forEach(({ queryKey, state, queryHash, meta, promise }) => {
     let query = queryCache.get(queryHash)
 
+    const data =
+      state.data === undefined ? state.data : deserializeData(state.data)
+
     // Do not hydrate if an existing query exists with newer data
     if (query) {
       if (query.state.dataUpdatedAt < state.dataUpdatedAt) {
         // omit fetchStatus from dehydrated state
         // so that query stays in its current fetchStatus
-        const { fetchStatus: _ignored, ...dehydratedQueryState } = state
-        query.setState(dehydratedQueryState)
+        const { fetchStatus: _ignored, ...serializedState } = state
+        query.setState({
+          ...serializedState,
+          data,
+        })
       }
     } else {
       // Restore query
@@ -173,19 +203,16 @@ export function hydrate(
         // query being stuck in fetching state upon hydration
         {
           ...state,
+          data,
           fetchStatus: 'idle',
         },
       )
     }
 
     if (promise) {
-      const transformPromise =
-        client.getDefaultOptions().hydrate?.transformPromise
-
       // Note: `Promise.resolve` required cause
       // RSC transformed promises are not thenable
-      const initialPromise =
-        transformPromise?.(Promise.resolve(promise)) ?? promise
+      const initialPromise = Promise.resolve(promise).then(deserializeData)
 
       // this doesn't actually fetch - it just creates a retryer
       // which will re-use the passed `initialPromise`

package/src/onlineManager.ts

@@ -14,7 +14,7 @@ export class OnlineManager extends Subscribable<Listener> {
     super()
     this.#setup = (onOnline) => {
       // addEventListener does not exist in React Native, but window does
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      // eslint-disable-next-line ts/no-unnecessary-condition
       if (!isServer && window.addEventListener) {
         const onlineListener = () => onOnline(true)
         const offlineListener = () => onOnline(false)

package/src/query.ts

@@ -1,4 +1,10 @@
-import { ensureQueryFn, noop, replaceData, timeUntilStale } from './utils'
+import {
+  ensureQueryFn,
+  noop,
+  replaceData,
+  resolveEnabled,
+  timeUntilStale,
+} from './utils'
 import { notifyManager } from './notifyManager'
 import { canFetch, createRetryer, isCancelledError } from './retryer'
 import { Removable } from './removable'
@@ -244,7 +250,9 @@ export class Query<
   }
 
   isActive(): boolean {
-    return this.observers.some((observer) => observer.options.enabled !== false)
+    return this.observers.some(
+      (observer) => resolveEnabled(observer.options.enabled, this) !== false,
+    )
   }
 
   isDisabled(): boolean {

package/src/queryClient.ts

@@ -13,10 +13,10 @@ import { focusManager } from './focusManager'
 import { onlineManager } from './onlineManager'
 import { notifyManager } from './notifyManager'
 import { infiniteQueryBehavior } from './infiniteQueryBehavior'
-import type { DataTag, NoInfer, OmitKeyof } from './types'
 import type { QueryState } from './query'
 import type {
   CancelOptions,
+  DataTag,
   DefaultError,
   DefaultOptions,
   DefaultedQueryObserverOptions,
@@ -29,6 +29,8 @@ import type {
   MutationKey,
   MutationObserverOptions,
   MutationOptions,
+  NoInfer,
+  OmitKeyof,
   QueryClientConfig,
   QueryKey,
   QueryObserverOptions,

package/src/queryObserver.ts

@@ -3,6 +3,7 @@ import {
   isValidTimeout,
   noop,
   replaceData,
+  resolveEnabled,
   resolveStaleTime,
   shallowEqualObjects,
   timeUntilStale,
@@ -149,9 +150,14 @@ export class QueryObserver<
 
     if (
       this.options.enabled !== undefined &&
-      typeof this.options.enabled !== 'boolean'
+      typeof this.options.enabled !== 'boolean' &&
+      typeof this.options.enabled !== 'function' &&
+      typeof resolveEnabled(this.options.enabled, this.#currentQuery) !==
+        'boolean'
     ) {
-      throw new Error('Expected enabled to be a boolean')
+      throw new Error(
+        'Expected enabled to be a boolean or a callback that returns a boolean',
+      )
     }
 
     this.#updateQuery()
@@ -190,7 +196,8 @@ export class QueryObserver<
     if (
       mounted &&
       (this.#currentQuery !== prevQuery ||
-        this.options.enabled !== prevOptions.enabled ||
+        resolveEnabled(this.options.enabled, this.#currentQuery) !==
+          resolveEnabled(prevOptions.enabled, this.#currentQuery) ||
         resolveStaleTime(this.options.staleTime, this.#currentQuery) !==
           resolveStaleTime(prevOptions.staleTime, this.#currentQuery))
     ) {
@@ -203,7 +210,8 @@ export class QueryObserver<
     if (
       mounted &&
       (this.#currentQuery !== prevQuery ||
-        this.options.enabled !== prevOptions.enabled ||
+        resolveEnabled(this.options.enabled, this.#currentQuery) !==
+          resolveEnabled(prevOptions.enabled, this.#currentQuery) ||
         nextRefetchInterval !== this.#currentRefetchInterval)
     ) {
       this.#updateRefetchInterval(nextRefetchInterval)
@@ -377,7 +385,7 @@ export class QueryObserver<
 
     if (
       isServer ||
-      this.options.enabled === false ||
+      resolveEnabled(this.options.enabled, this.#currentQuery) === false ||
       !isValidTimeout(this.#currentRefetchInterval) ||
       this.#currentRefetchInterval === 0
     ) {
@@ -692,7 +700,7 @@ function shouldLoadOnMount(
   options: QueryObserverOptions<any, any, any, any>,
 ): boolean {
   return (
-    options.enabled !== false &&
+    resolveEnabled(options.enabled, query) !== false &&
     query.state.data === undefined &&
     !(query.state.status === 'error' && options.retryOnMount === false)
   )
@@ -716,7 +724,7 @@ function shouldFetchOn(
     (typeof options)['refetchOnWindowFocus'] &
     (typeof options)['refetchOnReconnect'],
 ) {
-  if (options.enabled !== false) {
+  if (resolveEnabled(options.enabled, query) !== false) {
     const value = typeof field === 'function' ? field(query) : field
 
     return value === 'always' || (value !== false && isStale(query, options))
@@ -731,7 +739,8 @@ function shouldFetchOptionally(
   prevOptions: QueryObserverOptions<any, any, any, any, any>,
 ): boolean {
   return (
-    (query !== prevQuery || prevOptions.enabled === false) &&
+    (query !== prevQuery ||
+      resolveEnabled(prevOptions.enabled, query) === false) &&
     (!options.suspense || query.state.status !== 'error') &&
     isStale(query, options)
   )
@@ -742,7 +751,7 @@ function isStale(
   options: QueryObserverOptions<any, any, any, any, any>,
 ): boolean {
   return (
-    options.enabled !== false &&
+    resolveEnabled(options.enabled, query) !== false &&
     query.isStaleByTime(resolveStaleTime(options.staleTime, query))
   )
 }

package/src/types.ts

@@ -54,6 +54,15 @@ export type StaleTime<
   TQueryKey extends QueryKey = QueryKey,
 > = number | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => number)
 
+export type Enabled<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> =
+  | boolean
+  | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => boolean)
+
 export type QueryPersister<
   T = unknown,
   TQueryKey extends QueryKey = QueryKey,
@@ -253,11 +262,12 @@ export interface QueryObserverOptions<
     'queryKey'
   > {
   /**
-   * Set this to `false` to disable automatic refetching when the query mounts or changes query keys.
+   * Set this to `false` or a function that returns `false` to disable automatic refetching when the query mounts or changes query keys.
    * To refetch the query, use the `refetch` method returned from the `useQuery` instance.
+   * Accepts a boolean or function that returns a boolean.
    * Defaults to `true`.
    */
-  enabled?: boolean
+  enabled?: Enabled<TQueryFnData, TError, TQueryData, TQueryKey>
   /**
    * The time in milliseconds after data is considered stale.
    * If set to `Infinity`, the data will never be considered stale.

package/src/utils.ts

@@ -1,5 +1,6 @@
 import type {
   DefaultError,
+  Enabled,
   FetchStatus,
   MutationKey,
   MutationStatus,
@@ -100,6 +101,18 @@ export function resolveStaleTime<
   return typeof staleTime === 'function' ? staleTime(query) : staleTime
 }
 
+export function resolveEnabled<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  enabled: undefined | Enabled<TQueryFnData, TError, TData, TQueryKey>,
+  query: Query<TQueryFnData, TError, TData, TQueryKey>,
+): boolean | undefined {
+  return typeof enabled === 'function' ? enabled(query) : enabled
+}
+
 export function matchQuery(
   filters: QueryFilters,
   query: Query<any, any, any, any>,