Split the TypedOnQueryStarted type into 2 separate types

Author: aryaemami59

packages/toolkit/src/query/core/buildMiddleware/index.ts

@@ -35,7 +35,8 @@ export type {
   MutationLifecycleApi,
   QueryLifecycleApi,
   ReferenceQueryLifecycle,
-  TypedOnQueryStarted,
+  TypedOnQueryStartedForMutationEndpoints,
+  TypedOnQueryStartedForQueryEndpoints,
 } from './queryLifecycle'
 export type { SubscriptionSelectors } from './types'
 

packages/toolkit/src/query/core/buildMiddleware/queryLifecycle.ts

@@ -116,45 +116,6 @@ export type QueryLifecycleQueryExtraOptions<
   ): Promise<void> | void
 }
 
-/**
- * @since 2.4.0
- * @public
- */
-export type TypedOnQueryStarted<
-  ResultType,
-  QueryArg,
-  BaseQuery extends BaseQueryFn,
-  ReducerPath extends string = string,
-  DefinitionType extends 'query' | 'mutation' = 'query' | 'mutation',
-> = 'query' | 'mutation' extends DefinitionType
-  ? QueryLifecycleMutationExtraOptions<
-      ResultType,
-      QueryArg,
-      BaseQuery,
-      ReducerPath
-    >['onQueryStarted'] &
-      QueryLifecycleQueryExtraOptions<
-        ResultType,
-        QueryArg,
-        BaseQuery,
-        ReducerPath
-      >['onQueryStarted']
-  : 'query' extends DefinitionType
-    ? QueryLifecycleQueryExtraOptions<
-        ResultType,
-        QueryArg,
-        BaseQuery,
-        ReducerPath
-      >['onQueryStarted']
-    : 'mutation' extends DefinitionType
-      ? QueryLifecycleMutationExtraOptions<
-          ResultType,
-          QueryArg,
-          BaseQuery,
-          ReducerPath
-        >['onQueryStarted']
-      : never
-
 export type QueryLifecycleMutationExtraOptions<
   ResultType,
   QueryArg,
@@ -231,6 +192,212 @@ export type MutationLifecycleApi<
 > = MutationBaseLifecycleApi<QueryArg, BaseQuery, ResultType, ReducerPath> &
   QueryLifecyclePromises<ResultType, BaseQuery>
 
+/**
+ * Provides a way to define a strongly-typed version of
+ * {@linkcode QueryLifecycleQueryExtraOptions.onQueryStarted | onQueryStarted}
+ * for a specific query.
+ *
+ * @example
+ * <caption>#### __Create and reuse a strongly-typed `onQueryStarted` function__</caption>
+ *
+ * ```ts
+ * import type { TypedOnQueryStartedForQueryEndpoints } from '@reduxjs/toolkit/query'
+ * import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query'
+ *
+ * type Post = {
+ *   id: number
+ *   title: string
+ *   userId: number
+ * }
+ *
+ * type PostsApiResponse = {
+ *   posts: Post[]
+ *   total: number
+ *   skip: number
+ *   limit: number
+ * }
+ *
+ * type QueryArgument = number | undefined
+ *
+ * type BaseQueryFunction = ReturnType<typeof fetchBaseQuery>
+ *
+ * const baseApiSlice = createApi({
+ *   baseQuery: fetchBaseQuery({ baseUrl: 'https://dummyjson.com' }),
+ *   reducerPath: 'postsApi',
+ *   tagTypes: ['Posts'],
+ *   endpoints: (builder) => ({
+ *     getPosts: builder.query<PostsApiResponse, void>({
+ *       query: () => `/posts`,
+ *     }),
+ *
+ *     getPostById: builder.query<Post, QueryArgument>({
+ *       query: (postId) => `/posts/${postId}`,
+ *     }),
+ *   }),
+ * })
+ *
+ * const updatePostOnFulfilled: TypedOnQueryStartedForQueryEndpoints<
+ *   PostsApiResponse,
+ *   QueryArgument,
+ *   BaseQueryFunction,
+ *   'postsApi'
+ * > = async (queryArgument, { dispatch, queryFulfilled }) => {
+ *   const result = await queryFulfilled
+ *
+ *   const { posts } = result.data
+ *
+ *   // Pre-fill the individual post entries with the results
+ *   // from the list endpoint query
+ *   dispatch(
+ *     baseApiSlice.util.upsertQueryEntries(
+ *       posts.map((post) => ({
+ *         endpointName: 'getPostById',
+ *         arg: post.id,
+ *         value: post,
+ *       })),
+ *     ),
+ *   )
+ * }
+ *
+ * export const extendedApiSlice = baseApiSlice.injectEndpoints({
+ *   endpoints: (builder) => ({
+ *     getPostsByUserId: builder.query<PostsApiResponse, QueryArgument>({
+ *       query: (userId) => `/posts/user/${userId}`,
+ *
+ *       onQueryStarted: updatePostOnFulfilled,
+ *     }),
+ *   }),
+ * })
+ * ```
+ *
+ * @template ResultType - The type of the result `data` returned by the query.
+ * @template QueryArgumentType - The type of the argument passed into the query.
+ * @template BaseQueryFunctionType - The type of the base query function being used.
+ * @template ReducerPath - The type representing the `reducerPath` for the API slice.
+ *
+ * @since 2.4.0
+ * @public
+ */
+export type TypedOnQueryStartedForQueryEndpoints<
+  ResultType,
+  QueryArgumentType,
+  BaseQueryFunctionType extends BaseQueryFn,
+  ReducerPath extends string = string,
+> = QueryLifecycleQueryExtraOptions<
+  ResultType,
+  QueryArgumentType,
+  BaseQueryFunctionType,
+  ReducerPath
+>['onQueryStarted']
+
+/**
+ * Provides a way to define a strongly-typed version of
+ * {@linkcode QueryLifecycleMutationExtraOptions.onQueryStarted | onQueryStarted}
+ * for a specific mutation.
+ *
+ * @example
+ * <caption>#### __Create and reuse a strongly-typed `onQueryStarted` function__</caption>
+ *
+ * ```ts
+ * import type { TypedOnQueryStartedForMutationEndpoints } from '@reduxjs/toolkit/query'
+ * import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query'
+ *
+ * type Post = {
+ *   id: number
+ *   title: string
+ *   userId: number
+ * }
+ *
+ * type PostsApiResponse = {
+ *   posts: Post[]
+ *   total: number
+ *   skip: number
+ *   limit: number
+ * }
+ *
+ * type QueryArgument = Pick<Post, 'id'> & Partial<Post>
+ *
+ * type BaseQueryFunction = ReturnType<typeof fetchBaseQuery>
+ *
+ * const baseApiSlice = createApi({
+ *   baseQuery: fetchBaseQuery({ baseUrl: 'https://dummyjson.com' }),
+ *   reducerPath: 'postsApi',
+ *   tagTypes: ['Posts'],
+ *   endpoints: (builder) => ({
+ *     getPosts: builder.query<PostsApiResponse, void>({
+ *       query: () => `/posts`,
+ *     }),
+ *
+ *     getPostById: builder.query<Post, number>({
+ *       query: (postId) => `/posts/${postId}`,
+ *     }),
+ *   }),
+ * })
+ *
+ * const updatePostOnFulfilled: TypedOnQueryStartedForMutationEndpoints<
+ *   Post,
+ *   QueryArgument,
+ *   BaseQueryFunction,
+ *   'postsApi'
+ * > = async ({ id, ...patch }, { dispatch, queryFulfilled }) => {
+ *   const patchCollection = dispatch(
+ *     baseApiSlice.util.updateQueryData('getPostById', id, (draftPost) => {
+ *       Object.assign(draftPost, patch)
+ *     }),
+ *   )
+ *
+ *   try {
+ *     await queryFulfilled
+ *   } catch {
+ *     patchCollection.undo()
+ *   }
+ * }
+ *
+ * export const extendedApiSlice = baseApiSlice.injectEndpoints({
+ *   endpoints: (builder) => ({
+ *     addPost: builder.mutation<Post, Omit<QueryArgument, 'id'>>({
+ *       query: (body) => ({
+ *         url: `posts/add`,
+ *         method: 'POST',
+ *         body,
+ *       }),
+ *
+ *       onQueryStarted: updatePostOnFulfilled,
+ *     }),
+ *
+ *     updatePost: builder.mutation<Post, QueryArgument>({
+ *       query: ({ id, ...patch }) => ({
+ *         url: `post/${id}`,
+ *         method: 'PATCH',
+ *         body: patch,
+ *       }),
+ *
+ *       onQueryStarted: updatePostOnFulfilled,
+ *     }),
+ *   }),
+ * })
+ * ```
+ *
+ * @template ResultType - The type of the result `data` returned by the query.
+ * @template QueryArgumentType - The type of the argument passed into the query.
+ * @template BaseQueryFunctionType - The type of the base query function being used.
+ * @template ReducerPath - The type representing the `reducerPath` for the API slice.
+ *
+ * @since 2.4.0
+ * @public
+ */
+export type TypedOnQueryStartedForMutationEndpoints<
+  ResultType,
+  QueryArgumentType,
+  BaseQueryFunctionType extends BaseQueryFn,
+  ReducerPath extends string = string,
+> = QueryLifecycleMutationExtraOptions<
+  ResultType,
+  QueryArgumentType,
+  BaseQueryFunctionType,
+  ReducerPath
+>['onQueryStarted']
+
 export const buildQueryLifecycleHandler: InternalHandlerBuilder = ({
   api,
   context,

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

@@ -24,7 +24,8 @@ export type {
   QueryCacheLifecycleApi,
   QueryLifecycleApi,
   SubscriptionSelectors,
-  TypedOnQueryStarted,
+  TypedOnQueryStartedForMutationEndpoints,
+  TypedOnQueryStartedForQueryEndpoints,
 } from './buildMiddleware/index'
 export { skipToken } from './buildSelectors'
 export type {

packages/toolkit/src/query/index.ts

@@ -69,7 +69,10 @@ export { buildCreateApi } from './createApi'
 export { _NEVER, fakeBaseQuery } from './fakeBaseQuery'
 export { copyWithStructuralSharing } from './utils/copyWithStructuralSharing'
 export { createApi, coreModule, coreModuleName } from './core/index'
-export type { TypedOnQueryStarted } from './core/index'
+export type {
+  TypedOnQueryStartedForMutationEndpoints,
+  TypedOnQueryStartedForQueryEndpoints,
+} from './core/index'
 export type {
   ApiEndpointMutation,
   ApiEndpointQuery,