feat(ensureQueryData): add 'revalidateIfStale' option

docs/reference/QueryClient.md

@@ -189,7 +189,8 @@ const data = await queryClient.ensureQueryData({ queryKey, queryFn })
 
 **Options**
 
-- The options for `ensureQueryData` are exactly the same as those of [`fetchQuery`](#queryclientfetchquery) except that `queryKey` is required.
+- The options for `ensureQueryData` are almost the same as those of [`fetchQuery`](#queryclientfetchquery) except that `queryKey` is required and that is has an extra optional option `revalidateIfStale`. When set `revalidateIfStale` to true the function will make sure the data will refetch in the background while still returning the data from the cache.
+
 
 **Returns**
 

packages/query-core/src/queryClient.ts

@@ -19,6 +19,7 @@ import type {
   DefaultError,
   DefaultOptions,
   DefaultedQueryObserverOptions,
+  EnsureQueryDataOptions,
   FetchInfiniteQueryOptions,
   FetchQueryOptions,
   InfiniteData,
@@ -130,13 +131,24 @@ export class QueryClient {
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
-    options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
+    options: EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey>,
   ): Promise<TData> {
     const cachedData = this.getQueryData<TData>(options.queryKey)
 
-    return cachedData !== undefined
-      ? Promise.resolve(cachedData)
-      : this.fetchQuery(options)
+    if (cachedData === undefined) return this.fetchQuery(options)
+    else {
+      const defaultedOptions = this.defaultQueryOptions(options)
+      const query = this.#queryCache.build(this, defaultedOptions)
+
+      if (
+        options.revalidateIfStale &&
+        query.isStaleByTime(defaultedOptions.staleTime)
+      ) {
+        void this.prefetchQuery(defaultedOptions)
+      }
+
+      return Promise.resolve(cachedData)
+    }
   }
 
   getQueriesData<TQueryFnData = unknown>(

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

@@ -450,6 +450,24 @@ describe('queryClient', () => {
         queryClient.ensureQueryData({ queryKey: [key], queryFn }),
       ).resolves.toEqual('data')
     })
+
+    test('should return the cached query data if the query is found and preFetchQuery in the background when revalidateIfStale is set', async () => {
+      const TIMEOUT = 10
+      const key = queryKey()
+      queryClient.setQueryData([key, 'id'], 'old')
+
+      const queryFn = () => new Promise((resolve) => {
+        setTimeout(() => resolve('new'), TIMEOUT)
+      })
+
+      await expect(
+        queryClient.ensureQueryData({ queryKey: [key, 'id'], queryFn, revalidateIfStale: true }),
+      ).resolves.toEqual('old')
+      await sleep(TIMEOUT + 10)
+      await expect(
+        queryClient.ensureQueryData({ queryKey: [key, 'id'], queryFn, revalidateIfStale: true }),
+      ).resolves.toEqual('new')
+    })
   })
 
   describe('getQueriesData', () => {

packages/query-core/src/types.ts

@@ -407,6 +407,23 @@ export interface FetchQueryOptions<
   staleTime?: number
 }
 
+export interface EnsureQueryDataOptions<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+  TPageParam = never,
+  > extends FetchQueryOptions<
+    TQueryFnData,
+    TError,
+    TData,
+    TQueryKey,
+    TPageParam
+  > {
+  revalidateIfStale?: boolean
+}
+
+
 type FetchInfiniteQueryPages<TQueryFnData = unknown, TPageParam = unknown> =
   | { pages?: never }
   | {