feat: queryOptions helper function (#5153)

* feat: queryOptions helper function

so that we can define and share options outside of useQuery, but still get the type inference

* docs: queryOptions

* docs: remove reference to onError

* docs: update migration guide

Author: TkDodo

docs/react/guides/migrating-to-v5.md

@@ -439,6 +439,10 @@ You can adjust the `maxPages` value according to the UX and refetching performan
 
 Note that the infinite list must be bi-directional, which requires both `getNextPageParam` and `getPreviousPageParam` to be defined.
 
+### Typesafe way to create Query Options
+
+See the [Typescript Docs](../typescript#typing-query-options) for more details.
+
 ### CreateStore
 
 We are now exposing a way to customize how queries are stored internally. Per default, a `Map` is used but, with the new `createStore` function, you can now use any data structure you want.

docs/react/typescript.md

@@ -140,6 +140,25 @@ const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
 
 [//]: # 'Materials'
 
+## Typing Query Options
+
+If you inline query options into `useQuery`, you'll get automatic type inference. However, you might want to extract the query options into a separate function to share them between `useQuery` and e.g. `prefetchQuery`. In that case, you'd lose type inference. To get it back, you can use `queryOptions` helper:
+
+```ts
+import { queryOptions } from '@tanstack/react-query'
+
+function groupOptions() {
+  return queryOptions({
+    queryKey: ['groups'],
+    queryFn: fetchGroups,
+    staleTime: 5 * 1000,
+  })
+}
+
+useQuery(groupOptions())
+queryClient.prefetchQuery(groupOptions())
+```
+
 ## Further Reading
 
 For tips and tricks around type inference, have a look at [React Query and TypeScript](../community/tkdodos-blog#6-react-query-and-typescript) from

packages/react-query/src/__tests__/useQuery.types.test.tsx

@@ -1,4 +1,4 @@
-import { useQuery } from '../useQuery'
+import { queryOptions, useQuery } from '../useQuery'
 import type { Expect, Equal } from './utils'
 import { doNotExecute } from './utils'
 
@@ -23,6 +23,26 @@ describe('initialData', () => {
       })
     })
 
+    it('TData should be defined when passed through queryOptions', () => {
+      doNotExecute(() => {
+        const options = queryOptions({
+          queryKey: ['key'],
+          queryFn: () => {
+            return {
+              wow: true,
+            }
+          },
+          initialData: {
+            wow: true,
+          },
+        })
+        const { data } = useQuery(options)
+
+        const result: Expect<Equal<{ wow: boolean }, typeof data>> = true
+        return result
+      })
+    })
+
     it('TData should always be defined when initialData is provided as a function which ALWAYS returns the data', () => {
       doNotExecute(() => {
         const { data } = useQuery({

packages/react-query/src/index.ts

@@ -7,7 +7,7 @@ export * from '@tanstack/query-core'
 export * from './types'
 export { useQueries } from './useQueries'
 export type { QueriesResults, QueriesOptions } from './useQueries'
-export { useQuery } from './useQuery'
+export { useQuery, queryOptions } from './useQuery'
 export {
   QueryClientContext,
   QueryClientProvider,

packages/react-query/src/useQuery.ts

@@ -8,6 +8,28 @@ import type {
 } from './types'
 import { useBaseQuery } from './useBaseQuery'
 
+export function queryOptions<
+  TQueryFnData = unknown,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
+
+export function queryOptions<
+  TQueryFnData = unknown,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>,
+): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>
+
+export function queryOptions(options: unknown) {
+  return options
+}
+
 // HOOK
 type UndefinedInitialDataOptions<
   TQueryFnData = unknown,