@tanstack/react-query 4.40.1 → 4.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-query",
-  "version": "4.40.1",
+  "version": "4.41.0",
   "description": "Hooks for managing, caching and syncing asynchronous and remote data in React",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -51,7 +51,7 @@
   },
   "dependencies": {
     "use-sync-external-store": "^1.2.0",
-    "@tanstack/query-core": "4.40.0"
+    "@tanstack/query-core": "4.41.0"
   },
   "peerDependencies": {
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0",

package/src/__tests__/infiniteQueryOptions.test.tsx

@@ -0,0 +1,13 @@
+import { infiniteQueryOptions } from '../infiniteQueryOptions'
+
+describe('infiniteQueryOptions', () => {
+  it('should return the object received as a parameter without any modification.', () => {
+    const object = {
+      queryKey: ['key'],
+      queryFn: () => Promise.resolve(5),
+      getNextPageParam: () => null,
+    } as const
+
+    expect(infiniteQueryOptions(object)).toStrictEqual(object)
+  })
+})

package/src/__tests__/infiniteQueryOptions.types.test.tsx

@@ -0,0 +1,111 @@
+import { expectTypeOf } from 'expect-type'
+import {
+  type InfiniteData,
+  type UseInfiniteQueryResult,
+  useInfiniteQuery,
+  useQueryClient,
+} from '@tanstack/react-query'
+
+import { useSuspenseInfiniteQuery } from '../useSuspenseInfiniteQuery'
+import { infiniteQueryOptions } from '../infiniteQueryOptions'
+import { doNotExecute } from './utils'
+import type {
+  DefinedUseInfiniteQueryResult,
+  UseSuspenseInfiniteQueryResult,
+} from '../types'
+
+const infiniteQuery = {
+  options: () =>
+    infiniteQueryOptions({
+      queryKey: ['key', 1] as const,
+      queryFn: () => Promise.resolve({ field: 'success' }),
+    }),
+  optionsWithInitialData: () =>
+    infiniteQueryOptions({
+      queryKey: ['key', 2] as const,
+      queryFn: () => Promise.resolve({ field: 'success' }),
+      initialData: () => ({ pageParams: [], pages: [{ field: 'success' }] }),
+    }),
+}
+
+describe('infiniteQueryOptions', () => {
+  it('should be used with useInfiniteQuery', () => {
+    doNotExecute(() => {
+      expectTypeOf(useInfiniteQuery(infiniteQuery.options())).toEqualTypeOf<
+        UseInfiniteQueryResult<{ field: string }>
+      >()
+
+      expectTypeOf(
+        useInfiniteQuery({
+          ...infiniteQuery.options(),
+          select: (data) => ({
+            pages: data.pages.map(({ field }) => field),
+            pageParams: data.pageParams,
+          }),
+        }),
+      ).toEqualTypeOf<UseInfiniteQueryResult<string>>()
+
+      expectTypeOf(
+        useInfiniteQuery(infiniteQuery.optionsWithInitialData()),
+      ).toEqualTypeOf<DefinedUseInfiniteQueryResult<{ field: string }>>()
+
+      expectTypeOf(
+        useInfiniteQuery({
+          ...infiniteQuery.optionsWithInitialData(),
+          select: (data) => ({
+            pages: data.pages.map(({ field }) => field),
+            pageParams: data.pageParams,
+          }),
+        }),
+      ).toEqualTypeOf<DefinedUseInfiniteQueryResult<string>>()
+
+      expectTypeOf(
+        useInfiniteQuery({
+          queryKey: ['key', 2] as const,
+          queryFn: () => Promise.resolve({ field: 'success' }),
+          initialData: () => ({
+            pages: [{ field: 'success' }],
+            pageParams: [],
+          }),
+          select: (data) => ({
+            pages: data.pages.map(({ field }) => field),
+            pageParams: data.pageParams,
+          }),
+        }),
+      ).toEqualTypeOf<DefinedUseInfiniteQueryResult<string>>()
+    })
+  })
+  it('should be used with useSuspenseInfiniteQuery', () => {
+    doNotExecute(() => {
+      expectTypeOf(
+        useSuspenseInfiniteQuery(infiniteQuery.options()),
+      ).toEqualTypeOf<UseSuspenseInfiniteQueryResult<{ field: string }>>()
+
+      expectTypeOf(
+        useSuspenseInfiniteQuery({
+          ...infiniteQuery.options(),
+          select: (data) => ({
+            pages: data.pages.map(({ field }) => field),
+            pageParams: data.pageParams,
+          }),
+        }),
+      ).toEqualTypeOf<UseSuspenseInfiniteQueryResult<string>>()
+    })
+  })
+  it('should be used with useQueryClient', () => {
+    doNotExecute(async () => {
+      const queryClient = useQueryClient()
+
+      queryClient.invalidateQueries(infiniteQuery.options())
+      queryClient.resetQueries(infiniteQuery.options())
+      queryClient.removeQueries(infiniteQuery.options())
+      queryClient.cancelQueries(infiniteQuery.options())
+      queryClient.prefetchQuery(infiniteQuery.options())
+      queryClient.refetchQueries(infiniteQuery.options())
+
+      expectTypeOf(
+        await queryClient.fetchQuery(infiniteQuery.options()),
+      ).toEqualTypeOf<InfiniteData<{ field: string }>>()
+    })
+  })
+})

package/src/__tests__/queryOptions.types.test.tsx

@@ -19,13 +19,14 @@ const queryFn = () => Promise.resolve({ field: 'success' })
 describe('queryOptions', () => {
   it('should be used with useQuery', () => {
     doNotExecute(() => {
-      const dd = useQuery(
-        queryOptions({
-          queryKey,
-          queryFn,
-        }),
-      )
-      expectTypeOf(dd).toEqualTypeOf<UseQueryResult<{ field: string }>>()
+      expectTypeOf(
+        useQuery(
+          queryOptions({
+            queryKey,
+            queryFn,
+          }),
+        ),
+      ).toEqualTypeOf<UseQueryResult<{ field: string }>>()
       expectTypeOf(
         useQuery({
           ...queryOptions({

package/src/__tests__/suspense.test.tsx

@@ -1238,3 +1238,233 @@ describe('useQueries with suspense', () => {
     expect(results).toEqual(['1', '2', 'loading'])
   })
 })
+
+describe('cacheTime minimum enforcement with suspense', () => {
+  const queryClient = createQueryClient()
+
+  it('should not cause infinite re-renders with synchronous query function and cacheTime: 0', async () => {
+    const key = queryKey()
+    let renderCount = 0
+    let queryFnCallCount = 0
+    const maxChecks = 20
+
+    function Page() {
+      renderCount++
+
+      if (renderCount > maxChecks) {
+        throw new Error(`Infinite loop detected! Renders: ${renderCount}`)
+      }
+
+      const result = useQuery(
+        key,
+        () => {
+          queryFnCallCount++
+          return 42
+        },
+        {
+          cacheTime: 0,
+          suspense: true,
+        },
+      )
+
+      return <div>data: {result.data}</div>
+    }
+
+    const rendered = renderWithClient(
+      queryClient,
+      <React.Suspense fallback="loading">
+        <Page />
+      </React.Suspense>,
+    )
+
+    await waitFor(() => rendered.getByText('data: 42'))
+
+    expect(renderCount).toBeLessThan(5)
+    expect(queryFnCallCount).toBe(1)
+    expect(rendered.queryByText('data: 42')).not.toBeNull()
+    expect(rendered.queryByText('loading')).toBeNull()
+  })
+
+  describe('boundary value tests', () => {
+    test.each([
+      [0, 1000],
+      [1, 1000],
+      [999, 1000],
+      [1000, 1000],
+      [2000, 2000],
+    ])(
+      'cacheTime %i should be adjusted to %i with suspense',
+      async (input, expected) => {
+        const key = queryKey()
+
+        function Page() {
+          const result = useQuery(key, () => 42, {
+            suspense: true,
+            cacheTime: input,
+          })
+          return <div>data: {result.data}</div>
+        }
+
+        const rendered = renderWithClient(
+          queryClient,
+          <React.Suspense fallback="loading">
+            <Page />
+          </React.Suspense>,
+        )
+
+        await waitFor(() => rendered.getByText('data: 42'))
+
+        const query = queryClient.getQueryCache().find(key)
+        const options = query?.options
+        expect(options?.cacheTime).toBe(expected)
+      },
+    )
+  })
+
+  it('should preserve user cacheTime when >= 1000ms', async () => {
+    const key = queryKey()
+    const userCacheTime = 5000
+
+    function Page() {
+      useQuery(key, () => 'test', {
+        suspense: true,
+        cacheTime: userCacheTime,
+      })
+      return <div>rendered</div>
+    }
+
+    renderWithClient(
+      queryClient,
+      <React.Suspense fallback="loading">
+        <Page />
+      </React.Suspense>,
+    )
+
+    await waitFor(() => {
+      const query = queryClient.getQueryCache().find(key)
+      const options = query?.options
+      expect(options?.cacheTime).toBe(userCacheTime)
+    })
+  })
+
+  it('should handle async queries with adjusted cacheTime', async () => {
+    const key = queryKey()
+    let renderCount = 0
+
+    function Page() {
+      renderCount++
+      const result = useQuery(
+        key,
+        async () => {
+          await sleep(10)
+          return 'async-result'
+        },
+        {
+          suspense: true,
+          cacheTime: 0,
+        },
+      )
+      return <div>data: {result.data}</div>
+    }
+
+    const rendered = renderWithClient(
+      queryClient,
+      <React.Suspense fallback="loading">
+        <Page />
+      </React.Suspense>,
+    )
+
+    await waitFor(() => rendered.getByText('data: async-result'))
+    expect(renderCount).toBeLessThan(5)
+  })
+
+  describe('staleTime and cacheTime relationship', () => {
+    it('should handle when both need adjustment', async () => {
+      const key = queryKey()
+
+      function Page() {
+        useQuery(key, () => 42, {
+          suspense: true,
+          cacheTime: 0,
+          staleTime: undefined,
+        })
+        return <div>rendered</div>
+      }
+
+      renderWithClient(
+        queryClient,
+        <React.Suspense fallback="loading">
+          <Page />
+        </React.Suspense>,
+      )
+
+      await waitFor(() => {
+        const query = queryClient.getQueryCache().find(key)
+        const options = query?.options as any
+        expect(options?.cacheTime).toBe(1000)
+        expect(options?.staleTime).toBe(1000)
+      })
+    })
+
+    it('should maintain staleTime < cacheTime invariant', async () => {
+      const key = queryKey()
+
+      function Page() {
+        useQuery(key, () => 42, {
+          suspense: true,
+          cacheTime: 500,
+          staleTime: 2000,
+        })
+        return <div>rendered</div>
+      }
+
+      renderWithClient(
+        queryClient,
+        <React.Suspense fallback="loading">
+          <Page />
+        </React.Suspense>,
+      )
+
+      await waitFor(() => {
+        const query = queryClient.getQueryCache().find(key)
+        const options = query?.options as any
+        expect(options?.cacheTime).toBe(1000)
+        expect(options?.staleTime).toBe(2000)
+      })
+    })
+  })
+
+  it('should fix synchronous query with cacheTime 0 infinite loop', async () => {
+    const key = queryKey()
+    let renderCount = 0
+    let queryFnCallCount = 0
+
+    function Page() {
+      renderCount++
+      const result = useQuery(
+        key,
+        () => {
+          queryFnCallCount++
+          return 42
+        },
+        {
+          suspense: true,
+          cacheTime: 0,
+        },
+      )
+      return <div>data: {result.data}</div>
+    }
+
+    const rendered = renderWithClient(
+      queryClient,
+      <React.Suspense fallback="loading">
+        <Page />
+      </React.Suspense>,
+    )
+
+    await waitFor(() => rendered.getByText('data: 42'))
+
+    expect(renderCount).toBeLessThan(5)
+    expect(queryFnCallCount).toBe(1)
+  })
+})

package/src/__tests__/useSuspenseInfiniteQuery.types.test.tsx

@@ -0,0 +1,115 @@
+import { expectTypeOf } from 'expect-type'
+import { infiniteQueryOptions, useSuspenseInfiniteQuery } from '..'
+import { doNotExecute, sleep } from './utils'
+import type { UseSuspenseInfiniteQueryResult } from '..'
+
+import type { InfiniteData } from '@tanstack/react-query'
+
+const queryKey = ['key'] as const
+const queryFn = () => sleep(10).then(() => ({ text: 'response' }))
+
+describe('useSuspenseInfiniteQuery', () => {
+  it('type check', () => {
+    doNotExecute(() => {
+      // @ts-expect-error no arg
+      useSuspenseInfiniteQuery()
+
+      useSuspenseInfiniteQuery({
+        queryKey,
+        queryFn,
+        // @ts-expect-error no suspense
+        suspense: boolean,
+      })
+      useSuspenseInfiniteQuery({
+        queryKey,
+        queryFn,
+        // @ts-expect-error no useErrorBoundary
+        useErrorBoundary: boolean,
+      })
+      useSuspenseInfiniteQuery({
+        queryKey,
+        queryFn,
+        // @ts-expect-error no enabled
+        enabled: boolean,
+      })
+      useSuspenseInfiniteQuery({
+        queryKey,
+        queryFn,
+        // @ts-expect-error no placeholderData
+        placeholderData: 'placeholder',
+      })
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      useSuspenseInfiniteQuery({
+        queryKey,
+        queryFn,
+        // @ts-expect-error no isPlaceholderData
+      }).isPlaceholderData
+      useSuspenseInfiniteQuery({
+        queryKey,
+        queryFn,
+        //@ts-expect-error no networkMode
+        networkMode: 'always',
+      })
+
+      const infiniteQuery = useSuspenseInfiniteQuery({ queryKey, queryFn })
+      expectTypeOf(infiniteQuery).toEqualTypeOf<
+        UseSuspenseInfiniteQueryResult<{ text: string }>
+      >()
+      expectTypeOf(infiniteQuery.data).toEqualTypeOf<
+        InfiniteData<{ text: string }>
+      >()
+      expectTypeOf(infiniteQuery.status).toEqualTypeOf<'error' | 'success'>()
+
+      const selectedInfiniteQuery = useSuspenseInfiniteQuery({
+        queryKey,
+        queryFn,
+        select: (data) => ({
+          pages: data.pages.map(({ text }) => text),
+          pageParams: data.pageParams,
+        }),
+      })
+      expectTypeOf(selectedInfiniteQuery).toEqualTypeOf<
+        UseSuspenseInfiniteQueryResult<string>
+      >()
+      expectTypeOf(selectedInfiniteQuery.data).toEqualTypeOf<
+        InfiniteData<string>
+      >()
+      expectTypeOf(selectedInfiniteQuery.status).toEqualTypeOf<
+        'error' | 'success'
+      >()
+
+      const options = infiniteQueryOptions({
+        queryKey,
+        queryFn,
+      })
+
+      const infiniteQueryWithOptions = useSuspenseInfiniteQuery(options)
+      expectTypeOf(infiniteQueryWithOptions).toEqualTypeOf<
+        UseSuspenseInfiniteQueryResult<{ text: string }>
+      >()
+      expectTypeOf(infiniteQueryWithOptions.data).toEqualTypeOf<
+        InfiniteData<{ text: string }>
+      >()
+      expectTypeOf(infiniteQueryWithOptions.status).toEqualTypeOf<
+        'error' | 'success'
+      >()
+
+      const selectedInfiniteQueryWithOptions = useSuspenseInfiniteQuery({
+        ...options,
+        select: (data) => ({
+          pages: data.pages.map(({ text }) => text),
+          pageParams: data.pageParams,
+        }),
+      })
+      expectTypeOf(selectedInfiniteQueryWithOptions).toEqualTypeOf<
+        UseSuspenseInfiniteQueryResult<string>
+      >()
+      expectTypeOf(selectedInfiniteQueryWithOptions.data).toEqualTypeOf<
+        InfiniteData<string>
+      >()
+      expectTypeOf(selectedInfiniteQueryWithOptions.status).toEqualTypeOf<
+        'error' | 'success'
+      >()
+    })
+  })
+})

package/src/index.ts

@@ -12,6 +12,7 @@ export { useQueries } from './useQueries'
 export type { QueriesResults, QueriesOptions } from './useQueries'
 export { useQuery } from './useQuery'
 export { useSuspenseQuery } from './useSuspenseQuery'
+export { useSuspenseInfiniteQuery } from './useSuspenseInfiniteQuery'
 export { useSuspenseQueries } from './useSuspenseQueries'
 export type {
   SuspenseQueriesResults,
@@ -22,6 +23,11 @@ export type {
   DefinedInitialDataOptions,
   UndefinedInitialDataOptions,
 } from './queryOptions'
+export { infiniteQueryOptions } from './infiniteQueryOptions'
+export type {
+  DefinedInitialDataInfiniteOptions,
+  UndefinedInitialDataInfiniteOptions,
+} from './infiniteQueryOptions'
 export {
   defaultContext,
   QueryClientProvider,

package/src/infiniteQueryOptions.ts

@@ -0,0 +1,95 @@
+import type { UseInfiniteQueryOptions } from './types'
+import type {
+  InfiniteData,
+  NonUndefinedGuard,
+  OmitKeyof,
+  QueryKey,
+  WithRequired,
+} from '@tanstack/query-core'
+
+type UseInfiniteQueryOptionsOmitted<
+  TQueryFnData = unknown,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = OmitKeyof<
+  UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryFnData, TQueryKey>,
+  'onSuccess' | 'onError' | 'onSettled' | 'refetchInterval'
+>
+
+type ProhibitedInfiniteQueryOptionsKeyInV5 = keyof Pick<
+  UseInfiniteQueryOptionsOmitted,
+  'useErrorBoundary' | 'suspense'
+>
+
+export type UndefinedInitialDataInfiniteOptions<
+  TQueryFnData,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = UseInfiniteQueryOptionsOmitted<TQueryFnData, TError, TData, TQueryKey> & {
+  initialData?: undefined
+}
+
+export type DefinedInitialDataInfiniteOptions<
+  TQueryFnData,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = UseInfiniteQueryOptionsOmitted<TQueryFnData, TError, TData, TQueryKey> & {
+  initialData:
+    | NonUndefinedGuard<InfiniteData<TQueryFnData>>
+    | (() => NonUndefinedGuard<InfiniteData<TQueryFnData>>)
+    | undefined
+}
+
+export function infiniteQueryOptions<
+  TQueryFnData,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: WithRequired<
+    OmitKeyof<
+      DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey>,
+      ProhibitedInfiniteQueryOptionsKeyInV5
+    >,
+    'queryKey'
+  >,
+): WithRequired<
+  OmitKeyof<
+    DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey>,
+    ProhibitedInfiniteQueryOptionsKeyInV5
+  >,
+  'queryKey'
+>
+
+export function infiniteQueryOptions<
+  TQueryFnData,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: WithRequired<
+    OmitKeyof<
+      UndefinedInitialDataInfiniteOptions<
+        TQueryFnData,
+        TError,
+        TData,
+        TQueryKey
+      >,
+      ProhibitedInfiniteQueryOptionsKeyInV5
+    >,
+    'queryKey'
+  >,
+): WithRequired<
+  OmitKeyof<
+    UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey>,
+    ProhibitedInfiniteQueryOptionsKeyInV5
+  >,
+  'queryKey'
+>
+
+export function infiniteQueryOptions(options: unknown) {
+  return options
+}

package/src/queryOptions.ts

@@ -59,7 +59,10 @@ export function queryOptions<
     'queryKey'
   >,
 ): WithRequired<
-  DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+  OmitKeyof<
+    DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+    ProhibitedQueryOptionsKeyInV5
+  >,
   'queryKey'
 >
 
@@ -77,7 +80,10 @@ export function queryOptions<
     'queryKey'
   >,
 ): WithRequired<
-  UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+  OmitKeyof<
+    UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+    ProhibitedQueryOptionsKeyInV5
+  >,
   'queryKey'
 >
 

package/src/suspense.ts

@@ -4,6 +4,13 @@ import type { QueryErrorResetBoundaryValue } from './QueryErrorResetBoundary'
 import type { QueryObserverResult } from '@tanstack/query-core'
 import type { QueryKey } from '@tanstack/query-core'
 
+/**
+ * Ensures minimum staleTime and cacheTime values when suspense is enabled.
+ * Despite the name, this function guards both staleTime and cacheTime to prevent
+ * infinite re-render loops with synchronous queries.
+ *
+ * @deprecated in v5 - replaced by ensureSuspenseTimers
+ */
 export const ensureStaleTime = (
   defaultedOptions: DefaultedQueryObserverOptions<any, any, any, any, any>,
 ) => {
@@ -13,6 +20,10 @@ export const ensureStaleTime = (
     if (typeof defaultedOptions.staleTime !== 'number') {
       defaultedOptions.staleTime = 1000
     }
+
+    if (typeof defaultedOptions.cacheTime === 'number') {
+      defaultedOptions.cacheTime = Math.max(defaultedOptions.cacheTime, 1000)
+    }
   }
 }