Merge pull request #4604 from aryaemami59/export-UseQueryStateOptions

Add the `TypedUseQueryStateOptions` helper type

Author: EskiMojo14

packages/toolkit/src/query/core/apiState.ts

@@ -78,6 +78,9 @@ export function getRequestStatusFlags(status: QueryStatus): RequestStatusFlags {
   } as any
 }
 
+/**
+ * @public
+ */
 export type SubscriptionOptions = {
   /**
    * How frequently to automatically re-fetch data (in milliseconds). Defaults to `0` (off).

packages/toolkit/src/query/react/buildHooks.ts

@@ -357,6 +357,9 @@ export type TypedUseQueryState<
   QueryDefinition<QueryArg, BaseQuery, string, ResultType, string>
 >
 
+/**
+ * @internal
+ */
 export type UseQueryStateOptions<
   D extends QueryDefinition<any, any, any, any>,
   R extends Record<string, any>,
@@ -427,6 +430,79 @@ export type UseQueryStateOptions<
   selectFromResult?: QueryStateSelector<R, D>
 }
 
+/**
+ * Provides a way to define a "pre-typed" version of
+ * {@linkcode UseQueryStateOptions} with specific options for a given query.
+ * This is particularly useful for setting default query behaviors such as
+ * refetching strategies, which can be overridden as needed.
+ *
+ * @example
+ * <caption>#### __Create a `useQuery` hook with default options__</caption>
+ *
+ * ```ts
+ * import type {
+ *   SubscriptionOptions,
+ *   TypedUseQueryStateOptions,
+ * } from '@reduxjs/toolkit/query/react'
+ * import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
+ *
+ * type Post = {
+ *   id: number
+ *   name: string
+ * }
+ *
+ * const api = createApi({
+ *   baseQuery: fetchBaseQuery({ baseUrl: '/' }),
+ *   tagTypes: ['Post'],
+ *   endpoints: (build) => ({
+ *     getPosts: build.query<Post[], void>({
+ *       query: () => 'posts',
+ *     }),
+ *   }),
+ * })
+ *
+ * const { useGetPostsQuery } = api
+ *
+ * export const useGetPostsQueryWithDefaults = <
+ *   SelectedResult extends Record<string, any>,
+ * >(
+ *   overrideOptions: TypedUseQueryStateOptions<
+ *     Post[],
+ *     void,
+ *     ReturnType<typeof fetchBaseQuery>,
+ *     SelectedResult
+ *   > &
+ *     SubscriptionOptions,
+ * ) =>
+ *   useGetPostsQuery(undefined, {
+ *     // Insert default options here
+ *
+ *     refetchOnMountOrArgChange: true,
+ *     refetchOnFocus: true,
+ *     ...overrideOptions,
+ *   })
+ * ```
+ *
+ * @template ResultType - The type of the result `data` returned by the query.
+ * @template QueryArg - The type of the argument passed into the query.
+ * @template BaseQuery - The type of the base query function being used.
+ * @template SelectedResult - The type of the selected result returned by the __`selectFromResult`__ function.
+ *
+ * @since 2.7.8
+ * @public
+ */
+export type TypedUseQueryStateOptions<
+  ResultType,
+  QueryArg,
+  BaseQuery extends BaseQueryFn,
+  SelectedResult extends Record<string, any> = UseQueryStateDefaultResult<
+    QueryDefinition<QueryArg, BaseQuery, string, ResultType, string>
+  >,
+> = UseQueryStateOptions<
+  QueryDefinition<QueryArg, BaseQuery, string, ResultType, string>,
+  SelectedResult
+>
+
 export type UseQueryStateResult<
   _ extends QueryDefinition<any, any, any, any>,
   R,

packages/toolkit/src/query/react/index.ts

@@ -26,6 +26,7 @@ export type {
   TypedUseQuery,
   TypedUseQuerySubscription,
   TypedUseLazyQuerySubscription,
+  TypedUseQueryStateOptions,
 } from './buildHooks'
 export { UNINITIALIZED_VALUE } from './constants'
 export { createApi, reactHooksModule, reactHooksModuleName }

packages/toolkit/src/query/tests/unionTypes.test-d.ts

@@ -1,6 +1,8 @@
+import type { UseQueryStateOptions } from '@internal/query/react/buildHooks'
 import type { SerializedError } from '@reduxjs/toolkit'
 import type {
   FetchBaseQueryError,
+  QueryDefinition,
   TypedUseMutationResult,
   TypedUseQueryHookResult,
   TypedUseQueryState,
@@ -13,6 +15,7 @@ import type {
   TypedMutationTrigger,
   TypedUseQuerySubscription,
   TypedUseQuery,
+  TypedUseQueryStateOptions,
 } from '@reduxjs/toolkit/query/react'
 import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
 
@@ -776,6 +779,23 @@ describe('"Typed" helper types', () => {
     >().toEqualTypeOf(result)
   })
 
+  test('useQueryState options', () => {
+    expectTypeOf<
+      TypedUseQueryStateOptions<string, void, typeof baseQuery>
+    >().toMatchTypeOf<
+      Parameters<typeof api.endpoints.getTest.useQueryState>[1]
+    >()
+
+    expectTypeOf<
+      UseQueryStateOptions<
+        QueryDefinition<void, typeof baseQuery, string, string>,
+        { x: boolean }
+      >
+    >().toEqualTypeOf<
+      TypedUseQueryStateOptions<string, void, typeof baseQuery, { x: boolean }>
+    >()
+  })
+
   test('useQuerySubscription', () => {
     expectTypeOf<
       TypedUseQuerySubscription<string, void, typeof baseQuery>