@tanstack/query-core 5.38.0 → 5.44.0

package/src/__tests__/hydration.test.tsx

@@ -1,4 +1,5 @@
 import { describe, expect, test, vi } from 'vitest'
+import { waitFor } from '@testing-library/react'
 import { QueryCache } from '../queryCache'
 import { dehydrate, hydrate } from '../hydration'
 import { MutationCache } from '../mutationCache'
@@ -174,6 +175,84 @@ describe('dehydration and rehydration', () => {
     hydrationClient.clear()
   })
 
+  test('should respect query defaultOptions specified on the QueryClient', async () => {
+    const queryCache = new QueryCache()
+    const queryClient = createQueryClient({
+      queryCache,
+      defaultOptions: {
+        dehydrate: { shouldDehydrateQuery: () => true },
+      },
+    })
+    await queryClient.prefetchQuery({
+      queryKey: ['string'],
+      retry: 0,
+      queryFn: () => Promise.reject(new Error('error')),
+    })
+    const dehydrated = dehydrate(queryClient)
+    expect(dehydrated.queries.length).toBe(1)
+    expect(dehydrated.queries[0]?.state.error).toStrictEqual(new Error('error'))
+    const stringified = JSON.stringify(dehydrated)
+    const parsed = JSON.parse(stringified)
+    const hydrationCache = new QueryCache()
+    const hydrationClient = createQueryClient({
+      queryCache: hydrationCache,
+      defaultOptions: { hydrate: { queries: { retry: 10 } } },
+    })
+    hydrate(hydrationClient, parsed, {
+      defaultOptions: { queries: { gcTime: 10 } },
+    })
+    expect(hydrationCache.find({ queryKey: ['string'] })?.options.retry).toBe(
+      10,
+    )
+    expect(hydrationCache.find({ queryKey: ['string'] })?.options.gcTime).toBe(
+      10,
+    )
+    queryClient.clear()
+    hydrationClient.clear()
+  })
+
+  test('should respect mutation defaultOptions specified on the QueryClient', async () => {
+    const mutationCache = new MutationCache()
+    const queryClient = createQueryClient({
+      mutationCache,
+      defaultOptions: {
+        dehydrate: {
+          shouldDehydrateMutation: (mutation) => mutation.state.data === 'done',
+        },
+      },
+    })
+    await executeMutation(
+      queryClient,
+      {
+        mutationKey: ['string'],
+        mutationFn: () => Promise.resolve('done'),
+      },
+      undefined,
+    )
+
+    const dehydrated = dehydrate(queryClient)
+    expect(dehydrated.mutations.length).toBe(1)
+    expect(dehydrated.mutations[0]?.state.data).toBe('done')
+    const stringified = JSON.stringify(dehydrated)
+    const parsed = JSON.parse(stringified)
+    const hydrationCache = new MutationCache()
+    const hydrationClient = createQueryClient({
+      mutationCache: hydrationCache,
+      defaultOptions: { hydrate: { mutations: { retry: 10 } } },
+    })
+    hydrate(hydrationClient, parsed, {
+      defaultOptions: { mutations: { gcTime: 10 } },
+    })
+    expect(
+      hydrationCache.find({ mutationKey: ['string'] })?.options.retry,
+    ).toBe(10)
+    expect(
+      hydrationCache.find({ mutationKey: ['string'] })?.options.gcTime,
+    ).toBe(10)
+    queryClient.clear()
+    hydrationClient.clear()
+  })
+
   test('should work with complex keys', async () => {
     const queryCache = new QueryCache()
     const queryClient = createQueryClient({ queryCache })
@@ -738,4 +817,95 @@ describe('dehydration and rehydration', () => {
 
     onlineMock.mockRestore()
   })
+
+  test('should dehydrate promises for pending queries', async () => {
+    const queryCache = new QueryCache()
+    const queryClient = createQueryClient({
+      queryCache,
+      defaultOptions: { dehydrate: { shouldDehydrateQuery: () => true } },
+    })
+    await queryClient.prefetchQuery({
+      queryKey: ['success'],
+      queryFn: () => fetchData('success'),
+    })
+
+    const promise = queryClient.prefetchQuery({
+      queryKey: ['pending'],
+      queryFn: () => fetchData('pending', 10),
+    })
+    const dehydrated = dehydrate(queryClient)
+
+    expect(dehydrated.queries[0]?.promise).toBeUndefined()
+    expect(dehydrated.queries[1]?.promise).toBeInstanceOf(Promise)
+
+    await promise
+    queryClient.clear()
+  })
+
+  test('should hydrate promises even without observers', async () => {
+    const queryCache = new QueryCache()
+    const queryClient = createQueryClient({
+      queryCache,
+      defaultOptions: { dehydrate: { shouldDehydrateQuery: () => true } },
+    })
+    await queryClient.prefetchQuery({
+      queryKey: ['success'],
+      queryFn: () => fetchData('success'),
+    })
+
+    void queryClient.prefetchQuery({
+      queryKey: ['pending'],
+      queryFn: () => fetchData('pending', 20),
+    })
+    const dehydrated = dehydrate(queryClient)
+    // no stringify/parse here because promises can't be serialized to json
+    // but nextJs still can do it
+
+    const hydrationCache = new QueryCache()
+    const hydrationClient = createQueryClient({
+      queryCache: hydrationCache,
+    })
+
+    hydrate(hydrationClient, dehydrated)
+
+    expect(hydrationCache.find({ queryKey: ['success'] })?.state.data).toBe(
+      'success',
+    )
+
+    expect(hydrationCache.find({ queryKey: ['pending'] })?.state).toMatchObject(
+      {
+        data: undefined,
+        dataUpdateCount: 0,
+        dataUpdatedAt: 0,
+        error: null,
+        errorUpdateCount: 0,
+        errorUpdatedAt: 0,
+        fetchFailureCount: 0,
+        fetchFailureReason: null,
+        fetchMeta: null,
+        fetchStatus: 'fetching',
+        isInvalidated: false,
+        status: 'pending',
+      },
+    )
+
+    await waitFor(() =>
+      expect(
+        hydrationCache.find({ queryKey: ['pending'] })?.state,
+      ).toMatchObject({
+        data: 'pending',
+        dataUpdateCount: 1,
+        dataUpdatedAt: expect.any(Number),
+        error: null,
+        errorUpdateCount: 0,
+        errorUpdatedAt: 0,
+        fetchFailureCount: 0,
+        fetchFailureReason: null,
+        fetchMeta: null,
+        fetchStatus: 'idle',
+        isInvalidated: false,
+        status: 'success',
+      }),
+    )
+  })
 })

package/src/__tests__/queryObserver.test.tsx

@@ -910,4 +910,30 @@ describe('queryObserver', () => {
     const result = observer.getCurrentResult()
     expect(result.isStale).toBe(false)
   })
+
+  test('should allow staleTime as a function', async () => {
+    const key = queryKey()
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn: async () => {
+        await sleep(5)
+        return {
+          data: 'data',
+          staleTime: 20,
+        }
+      },
+      staleTime: (query) => query.state.data?.staleTime ?? 0,
+    })
+    const results: Array<QueryObserverResult<unknown>> = []
+    const unsubscribe = observer.subscribe((x) => {
+      if (x.data) {
+        results.push(x)
+      }
+    })
+
+    await waitFor(() => expect(results[0]?.isStale).toBe(false))
+    await waitFor(() => expect(results[1]?.isStale).toBe(true))
+
+    unsubscribe()
+  })
 })

package/src/hydration.ts

@@ -37,6 +37,7 @@ interface DehydratedQuery {
   queryHash: string
   queryKey: QueryKey
   state: QueryState
+  promise?: Promise<unknown>
   meta?: QueryMeta
 }
 
@@ -65,6 +66,16 @@ function dehydrateQuery(query: Query): DehydratedQuery {
     state: query.state,
     queryKey: query.queryKey,
     queryHash: query.queryHash,
+    ...(query.state.status === 'pending' && {
+      promise: query.promise?.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`,
+          )
+        }
+        return Promise.reject(new Error('redacted'))
+      }),
+    }),
     ...(query.meta && { meta: query.meta }),
   }
 }
@@ -82,7 +93,9 @@ export function dehydrate(
   options: DehydrateOptions = {},
 ): DehydratedState {
   const filterMutation =
-    options.shouldDehydrateMutation ?? defaultShouldDehydrateMutation
+    options.shouldDehydrateMutation ??
+    client.getDefaultOptions().dehydrate?.shouldDehydrateMutation ??
+    defaultShouldDehydrateMutation
 
   const mutations = client
     .getMutationCache()
@@ -92,7 +105,9 @@ export function dehydrate(
     )
 
   const filterQuery =
-    options.shouldDehydrateQuery ?? defaultShouldDehydrateQuery
+    options.shouldDehydrateQuery ??
+    client.getDefaultOptions().dehydrate?.shouldDehydrateQuery ??
+    defaultShouldDehydrateQuery
 
   const queries = client
     .getQueryCache()
@@ -123,6 +138,7 @@ export function hydrate(
     mutationCache.build(
       client,
       {
+        ...client.getDefaultOptions().hydrate?.mutations,
         ...options?.defaultOptions?.mutations,
         ...mutationOptions,
       },
@@ -130,8 +146,8 @@ export function hydrate(
     )
   })
 
-  queries.forEach(({ queryKey, state, queryHash, meta }) => {
-    const query = queryCache.get(queryHash)
+  queries.forEach(({ queryKey, state, queryHash, meta, promise }) => {
+    let query = queryCache.get(queryHash)
 
     // Do not hydrate if an existing query exists with newer data
     if (query) {
@@ -141,24 +157,30 @@ export function hydrate(
         const { fetchStatus: _ignored, ...dehydratedQueryState } = state
         query.setState(dehydratedQueryState)
       }
-      return
+    } else {
+      // Restore query
+      query = queryCache.build(
+        client,
+        {
+          ...client.getDefaultOptions().hydrate?.queries,
+          ...options?.defaultOptions?.queries,
+          queryKey,
+          queryHash,
+          meta,
+        },
+        // Reset fetch status to idle to avoid
+        // query being stuck in fetching state upon hydration
+        {
+          ...state,
+          fetchStatus: 'idle',
+        },
+      )
     }
 
-    // Restore query
-    queryCache.build(
-      client,
-      {
-        ...options?.defaultOptions?.queries,
-        queryKey,
-        queryHash,
-        meta,
-      },
-      // Reset fetch status to idle to avoid
-      // query being stuck in fetching state upon hydration
-      {
-        ...state,
-        fetchStatus: 'idle',
-      },
-    )
+    if (promise) {
+      // this doesn't actually fetch - it just creates a retryer
+      // which will re-use the passed `initialPromise`
+      void query.fetch(undefined, { initialPromise: promise })
+    }
   })
 }

package/src/infiniteQueryBehavior.ts

@@ -1,4 +1,4 @@
-import { addToEnd, addToStart, skipToken } from './utils'
+import { addToEnd, addToStart, ensureQueryFn } from './utils'
 import type { QueryBehavior } from './query'
 import type {
   InfiniteData,
@@ -37,22 +37,7 @@ export function infiniteQueryBehavior<TQueryFnData, TError, TData, TPageParam>(
           })
         }
 
-        // Get query function
-        const queryFn =
-          context.options.queryFn && context.options.queryFn !== skipToken
-            ? context.options.queryFn
-            : () => {
-                if (process.env.NODE_ENV !== 'production') {
-                  if (context.options.queryFn === skipToken) {
-                    console.error(
-                      `Attempted to invoke queryFn when set to skipToken. This is likely a configuration error. Query hash: '${context.options.queryHash}'`,
-                    )
-                  }
-                }
-                return Promise.reject(
-                  new Error(`Missing queryFn: '${context.options.queryHash}'`),
-                )
-              }
+        const queryFn = ensureQueryFn(context.options, context.fetchOptions)
 
         // Create function to fetch a page
         const fetchPage = async (

package/src/query.ts

@@ -1,4 +1,4 @@
-import { noop, replaceData, skipToken, timeUntilStale } from './utils'
+import { ensureQueryFn, noop, replaceData, timeUntilStale } from './utils'
 import { notifyManager } from './notifyManager'
 import { canFetch, createRetryer, isCancelledError } from './retryer'
 import { Removable } from './removable'
@@ -8,6 +8,7 @@ import type {
   FetchStatus,
   InitialDataFunction,
   OmitKeyof,
+  QueryFunction,
   QueryFunctionContext,
   QueryKey,
   QueryMeta,
@@ -82,9 +83,10 @@ export interface FetchMeta {
   fetchMore?: { direction: FetchDirection }
 }
 
-export interface FetchOptions {
+export interface FetchOptions<TData = unknown> {
   cancelRefetch?: boolean
   meta?: FetchMeta
+  initialPromise?: Promise<TData>
 }
 
 interface FailedAction<TError> {
@@ -182,6 +184,10 @@ export class Query<
     return this.options.meta
   }
 
+  get promise(): Promise<TData> | undefined {
+    return this.#retryer?.promise
+  }
+
   setOptions(
     options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,
   ): void {
@@ -330,7 +336,7 @@ export class Query<
 
   fetch(
     options?: QueryOptions<TQueryFnData, TError, TData, TQueryKey>,
-    fetchOptions?: FetchOptions,
+    fetchOptions?: FetchOptions<TQueryFnData>,
   ): Promise<TData> {
     if (this.state.fetchStatus !== 'idle') {
       if (this.state.data !== undefined && fetchOptions?.cancelRefetch) {
@@ -368,15 +374,6 @@ export class Query<
 
     const abortController = new AbortController()
 
-    // Create query function context
-    const queryFnContext: OmitKeyof<
-      QueryFunctionContext<TQueryKey>,
-      'signal'
-    > = {
-      queryKey: this.queryKey,
-      meta: this.meta,
-    }
-
     // Adds an enumerable signal property to the object that
     // which sets abortSignalConsumed to true when the signal
     // is read.
@@ -390,36 +387,31 @@ export class Query<
       })
     }
 
-    addSignalProperty(queryFnContext)
-
     // Create fetch function
     const fetchFn = () => {
-      if (process.env.NODE_ENV !== 'production') {
-        if (this.options.queryFn === skipToken) {
-          console.error(
-            `Attempted to invoke queryFn when set to skipToken. This is likely a configuration error. Query hash: '${this.options.queryHash}'`,
-          )
-        }
+      const queryFn = ensureQueryFn(this.options, fetchOptions)
+
+      // Create query function context
+      const queryFnContext: OmitKeyof<
+        QueryFunctionContext<TQueryKey>,
+        'signal'
+      > = {
+        queryKey: this.queryKey,
+        meta: this.meta,
       }
 
-      if (!this.options.queryFn || this.options.queryFn === skipToken) {
-        return Promise.reject(
-          new Error(`Missing queryFn: '${this.options.queryHash}'`),
-        )
-      }
+      addSignalProperty(queryFnContext)
 
       this.#abortSignalConsumed = false
       if (this.options.persister) {
         return this.options.persister(
-          this.options.queryFn,
+          queryFn as QueryFunction<any>,
           queryFnContext as QueryFunctionContext<TQueryKey>,
           this as unknown as Query,
         )
       }
 
-      return this.options.queryFn(
-        queryFnContext as QueryFunctionContext<TQueryKey>,
-      )
+      return queryFn(queryFnContext as QueryFunctionContext<TQueryKey>)
     }
 
     // Trigger behavior hook
@@ -483,6 +475,9 @@ export class Query<
 
     // Try to fetch the data
     this.#retryer = createRetryer({
+      initialPromise: fetchOptions?.initialPromise as
+        | Promise<TData>
+        | undefined,
       fn: context.fetchFn as () => Promise<TData>,
       abort: abortController.abort.bind(abortController),
       onSuccess: (data) => {

package/src/queryCache.ts

@@ -97,7 +97,12 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     this.#queries = new Map<string, Query>()
   }
 
-  build<TQueryFnData, TError, TData, TQueryKey extends QueryKey>(
+  build<
+    TQueryFnData = unknown,
+    TError = DefaultError,
+    TData = TQueryFnData,
+    TQueryKey extends QueryKey = QueryKey,
+  >(
     client: QueryClient,
     options: WithRequired<
       QueryOptions<TQueryFnData, TError, TData, TQueryKey>,

package/src/queryClient.ts

@@ -4,6 +4,7 @@ import {
   hashQueryKeyByOptions,
   noop,
   partialMatchKey,
+  resolveStaleTime,
   skipToken,
 } from './utils'
 import { QueryCache } from './queryCache'
@@ -142,7 +143,7 @@ export class QueryClient {
 
       if (
         options.revalidateIfStale &&
-        query.isStaleByTime(defaultedOptions.staleTime)
+        query.isStaleByTime(resolveStaleTime(defaultedOptions.staleTime, query))
       ) {
         void this.prefetchQuery(defaultedOptions)
       }
@@ -343,7 +344,9 @@ export class QueryClient {
 
     const query = this.#queryCache.build(this, defaultedOptions)
 
-    return query.isStaleByTime(defaultedOptions.staleTime)
+    return query.isStaleByTime(
+      resolveStaleTime(defaultedOptions.staleTime, query),
+    )
       ? query.fetch(defaultedOptions)
       : Promise.resolve(query.state.data as TData)
   }

package/src/queryObserver.ts

@@ -3,6 +3,7 @@ import {
   isValidTimeout,
   noop,
   replaceData,
+  resolveStaleTime,
   shallowEqualObjects,
   timeUntilStale,
 } from './utils'
@@ -190,7 +191,8 @@ export class QueryObserver<
       mounted &&
       (this.#currentQuery !== prevQuery ||
         this.options.enabled !== prevOptions.enabled ||
-        this.options.staleTime !== prevOptions.staleTime)
+        resolveStaleTime(this.options.staleTime, this.#currentQuery) !==
+          resolveStaleTime(prevOptions.staleTime, this.#currentQuery))
     ) {
       this.#updateStaleTimeout()
     }
@@ -318,7 +320,7 @@ export class QueryObserver<
   }
 
   #executeFetch(
-    fetchOptions?: ObserverFetchOptions,
+    fetchOptions?: Omit<ObserverFetchOptions, 'initialPromise'>,
   ): Promise<TQueryData | undefined> {
     // Make sure we reference the latest query as the current one might have been removed
     this.#updateQuery()
@@ -338,19 +340,16 @@ export class QueryObserver<
 
   #updateStaleTimeout(): void {
     this.#clearStaleTimeout()
+    const staleTime = resolveStaleTime(
+      this.options.staleTime,
+      this.#currentQuery,
+    )
 
-    if (
-      isServer ||
-      this.#currentResult.isStale ||
-      !isValidTimeout(this.options.staleTime)
-    ) {
+    if (isServer || this.#currentResult.isStale || !isValidTimeout(staleTime)) {
       return
     }
 
-    const time = timeUntilStale(
-      this.#currentResult.dataUpdatedAt,
-      this.options.staleTime,
-    )
+    const time = timeUntilStale(this.#currentResult.dataUpdatedAt, staleTime)
 
     // The timeout is sometimes triggered 1 ms before the stale time expiration.
     // To mitigate this issue we always add 1 ms to the timeout.
@@ -742,7 +741,10 @@ function isStale(
   query: Query<any, any, any, any>,
   options: QueryObserverOptions<any, any, any, any, any>,
 ): boolean {
-  return options.enabled !== false && query.isStaleByTime(options.staleTime)
+  return (
+    options.enabled !== false &&
+    query.isStaleByTime(resolveStaleTime(options.staleTime, query))
+  )
 }
 
 // this function would decide if we will update the observer's 'current'

package/src/retryer.ts

@@ -7,6 +7,7 @@ import type { CancelOptions, DefaultError, NetworkMode } from './types'
 
 interface RetryerConfig<TData = unknown, TError = DefaultError> {
   fn: () => TData | Promise<TData>
+  initialPromise?: Promise<TData>
   abort?: () => void
   onError?: (error: TError) => void
   onSuccess?: (data: TData) => void
@@ -146,9 +147,13 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
 
     let promiseOrValue: any
 
+    // we can re-use config.initialPromise on the first call of run()
+    const initialPromise =
+      failureCount === 0 ? config.initialPromise : undefined
+
     // Execute query
     try {
-      promiseOrValue = config.fn()
+      promiseOrValue = initialPromise ?? config.fn()
     } catch (error) {
       promiseOrValue = Promise.reject(error)
     }

package/src/types.ts

@@ -1,5 +1,6 @@
 /* istanbul ignore file */
 
+import type { DehydrateOptions, HydrateOptions } from './hydration'
 import type { MutationState } from './mutation'
 import type { FetchDirection, Query, QueryBehavior } from './query'
 import type { RetryDelayValue, RetryValue } from './retryer'
@@ -46,6 +47,13 @@ export type QueryFunction<
   TPageParam = never,
 > = (context: QueryFunctionContext<TQueryKey, TPageParam>) => T | Promise<T>
 
+export type StaleTime<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = number | ((query: Query<TQueryFnData, TError, TData, TQueryKey>) => number)
+
 export type QueryPersister<
   T = unknown,
   TQueryKey extends QueryKey = QueryKey,
@@ -253,8 +261,9 @@ export interface QueryObserverOptions<
   /**
    * The time in milliseconds after data is considered stale.
    * If set to `Infinity`, the data will never be considered stale.
+   * If set to a function, the function will be executed with the query to compute a `staleTime`.
    */
-  staleTime?: number
+  staleTime?: StaleTime<TQueryFnData, TError, TQueryData, TQueryKey>
   /**
    * If set to a number, the query will continuously refetch at this frequency in milliseconds.
    * If set to a function, the function will be executed with the latest data and query to compute a frequency
@@ -426,7 +435,7 @@ export interface FetchQueryOptions<
    * The time in milliseconds after data is considered stale.
    * If the data is fresh it will be returned from the cache.
    */
-  staleTime?: number
+  staleTime?: StaleTime<TQueryFnData, TError, TData, TQueryKey>
 }
 
 export interface EnsureQueryDataOptions<
@@ -1119,6 +1128,8 @@ export interface DefaultOptions<TError = DefaultError> {
     'suspense' | 'queryKey'
   >
   mutations?: MutationObserverOptions<unknown, TError, unknown, unknown>
+  hydrate?: HydrateOptions['defaultOptions']
+  dehydrate?: DehydrateOptions
 }
 
 export interface CancelOptions {