diff --git a/packages/toolkit/src/query/core/apiState.ts b/packages/toolkit/src/query/core/apiState.ts index cdf6831d2b..4a2a664ab4 100644 --- a/packages/toolkit/src/query/core/apiState.ts +++ b/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). diff --git a/packages/toolkit/src/query/react/buildHooks.ts b/packages/toolkit/src/query/react/buildHooks.ts index aee59a3d9e..879851a533 100644 --- a/packages/toolkit/src/query/react/buildHooks.ts +++ b/packages/toolkit/src/query/react/buildHooks.ts @@ -357,6 +357,9 @@ export type TypedUseQueryState< QueryDefinition > +/** + * @internal + */ export type UseQueryStateOptions< D extends QueryDefinition, R extends Record, @@ -427,6 +430,79 @@ export type UseQueryStateOptions< selectFromResult?: QueryStateSelector } +/** + * 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 + * #### __Create a `useQuery` hook with default options__ + * + * ```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({ + * query: () => 'posts', + * }), + * }), + * }) + * + * const { useGetPostsQuery } = api + * + * export const useGetPostsQueryWithDefaults = < + * SelectedResult extends Record, + * >( + * overrideOptions: TypedUseQueryStateOptions< + * Post[], + * void, + * ReturnType, + * 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 = UseQueryStateDefaultResult< + QueryDefinition + >, +> = UseQueryStateOptions< + QueryDefinition, + SelectedResult +> + export type UseQueryStateResult< _ extends QueryDefinition, R, diff --git a/packages/toolkit/src/query/react/index.ts b/packages/toolkit/src/query/react/index.ts index 9708412874..8f4ae07f84 100644 --- a/packages/toolkit/src/query/react/index.ts +++ b/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 } diff --git a/packages/toolkit/src/query/tests/unionTypes.test-d.ts b/packages/toolkit/src/query/tests/unionTypes.test-d.ts index 1c5768d24a..6426556428 100644 --- a/packages/toolkit/src/query/tests/unionTypes.test-d.ts +++ b/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 + >().toMatchTypeOf< + Parameters[1] + >() + + expectTypeOf< + UseQueryStateOptions< + QueryDefinition, + { x: boolean } + > + >().toEqualTypeOf< + TypedUseQueryStateOptions + >() + }) + test('useQuerySubscription', () => { expectTypeOf< TypedUseQuerySubscription