From 95afcc631dd2c33592bfb07c0aad95c3ddeb2863 Mon Sep 17 00:00:00 2001 From: Arya Emami Date: Wed, 4 Sep 2024 01:07:03 -0500 Subject: [PATCH 1/6] Mark the `SubscriptionOptions` type with an `@public` JSDoc tag --- packages/toolkit/src/query/core/apiState.ts | 3 +++ 1 file changed, 3 insertions(+) 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). From c8fa4bfb7c4d575b7ac6fd9364f3c5d51477b1e1 Mon Sep 17 00:00:00 2001 From: Arya Emami Date: Wed, 11 Sep 2024 15:23:06 -0500 Subject: [PATCH 2/6] Mark `UseQueryStateOptions` with the `@internal` JSDoc tag --- packages/toolkit/src/query/react/buildHooks.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/toolkit/src/query/react/buildHooks.ts b/packages/toolkit/src/query/react/buildHooks.ts index aee59a3d9e..f3855b7bd0 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, From fe940f050c1e04b14a0a0e8d057a7e0c3f25f3a5 Mon Sep 17 00:00:00 2001 From: Arya Emami Date: Wed, 11 Sep 2024 15:33:08 -0500 Subject: [PATCH 3/6] Add `TypedUseQueryStateOptions` helper type --- .../toolkit/src/query/react/buildHooks.ts | 24 +++++++++++++++++++ packages/toolkit/src/query/react/index.ts | 1 + 2 files changed, 25 insertions(+) diff --git a/packages/toolkit/src/query/react/buildHooks.ts b/packages/toolkit/src/query/react/buildHooks.ts index f3855b7bd0..4197e41cdc 100644 --- a/packages/toolkit/src/query/react/buildHooks.ts +++ b/packages/toolkit/src/query/react/buildHooks.ts @@ -430,6 +430,30 @@ export type UseQueryStateOptions< selectFromResult?: QueryStateSelector } +/** + * Allows you to define a "pre-typed" version of + * {@linkcode UseQueryStateOptions} for a specific query. + * + * @template ResultType - The type of the data returned by the query. + * @template QueryArg - The type of the argument passed to the query. + * @template BaseQuery - The type of the base query function used by the query. + * @template SelectedResult - The type of the selected result returned by __`selectFromResult`__. + * + * @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 } From 4a3290acf4e84e2654bcce31454d9c6f86fcc40c Mon Sep 17 00:00:00 2001 From: Arya Emami Date: Wed, 11 Sep 2024 15:33:29 -0500 Subject: [PATCH 4/6] Add type tests for `TypedUseQueryStateOptions` --- .../src/query/tests/unionTypes.test-d.ts | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) 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 From 67be6370abb8d496678857343c3fdc65963d89bc Mon Sep 17 00:00:00 2001 From: Arya Emami Date: Wed, 11 Sep 2024 16:30:32 -0500 Subject: [PATCH 5/6] Improve on JSDocs of `TypedUseQueryStateOptions` --- packages/toolkit/src/query/react/buildHooks.ts | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/packages/toolkit/src/query/react/buildHooks.ts b/packages/toolkit/src/query/react/buildHooks.ts index 4197e41cdc..26870d4ea2 100644 --- a/packages/toolkit/src/query/react/buildHooks.ts +++ b/packages/toolkit/src/query/react/buildHooks.ts @@ -431,13 +431,16 @@ export type UseQueryStateOptions< } /** - * Allows you to define a "pre-typed" version of - * {@linkcode UseQueryStateOptions} for a specific query. + * 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. * - * @template ResultType - The type of the data returned by the query. - * @template QueryArg - The type of the argument passed to the query. - * @template BaseQuery - The type of the base query function used by the query. - * @template SelectedResult - The type of the selected result returned by __`selectFromResult`__. + * + * @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 From c42acfa4851450051a9347c9c33c597cb4498556 Mon Sep 17 00:00:00 2001 From: Arya Emami Date: Wed, 11 Sep 2024 16:30:49 -0500 Subject: [PATCH 6/6] Add example for `TypedUseQueryStateOptions` --- .../toolkit/src/query/react/buildHooks.ts | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/packages/toolkit/src/query/react/buildHooks.ts b/packages/toolkit/src/query/react/buildHooks.ts index 26870d4ea2..879851a533 100644 --- a/packages/toolkit/src/query/react/buildHooks.ts +++ b/packages/toolkit/src/query/react/buildHooks.ts @@ -436,6 +436,52 @@ export type UseQueryStateOptions< * 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.