Feature/query options

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,