Add full types to useMutation's returned callback

query-old/docs/api/created-api/hooks.md

@@ -68,7 +68,7 @@ type UseQueryResult<T> = {
   isLoading: false; // Query is currently loading for the first time. No data yet.
   isFetching: false; // Query is currently fetching, but might have data from an earlier request.
   isSuccess: false; // Query has data from a successful load.
-  isError: false; // Query is currently in "error" state.
+  isError: false; // Query is currently in an "error" state.
 
   refetch: () => void; // A function to force refetch the query
 };
@@ -91,18 +91,39 @@ The query arg is used as a cache key. Changing the query arg will tell the hook
 #### Signature
 
 ```ts
-type MutationHook = () => [
-  (
-    arg: any
-  ) => {
-    unwrap: () => Promise<ResultTypeFrom<D>>;
-  },
-  MutationSubState<D> & RequestStatusFlags
-];
+type UseMutation<Definition> = () => [UseMutationTrigger<Definition>, UseMutationResult<Definition>];
+
+type UseMutationTrigger<Definition> = (
+  arg: ArgTypeFrom<Definition>
+) => Promise<{ data: ResultTypeFrom<Definition> }> & {
+  arg: {
+    endpointName: string; // The name of the given endpoint for the mutation
+    originalArgs: ArgTypeFrom<Definition>; // Arguments passed to the mutation
+    track?: boolean; // Whether the mutation is being tracked in the store
+    startedTimeStamp: number; // Timestamp for when the mutation was initiated
+  };
+  requestId: string; // A string generated by RTK Query
+  abort: () => void; // A method to cancel the mutation promise
+  unwrap: () => Promise<ResultTypeFrom<Definition>>; // A method to unwrap the mutation call and provide the raw response/error
+  unsubscribe: () => void; // A method to manually unsubscribe from the mutation call
+};
+
+type UseMutationResult<Definition> = {
+  data?: ResultTypeFrom<Definition>; // Returned result if present
+  endpointName?: string; // The name of the given endpoint for the mutation
+  error?: any; // Error result if present
+  fulfilledTimestamp?: number; // Timestamp for when the mutation was completed
+  isError: boolean; // Mutation is currently in an "error" state
+  isLoading: boolean; // Mutation has been fired and is awaiting a response
+  isSuccess: boolean; // Mutation has data from a successful call
+  isUninitialized: boolean; // Mutation has not been fired yet
+  originalArgs?: ArgTypeFrom<Definition>; // Arguments passed to the latest mutation call
+  startedTimeStamp?: number; // Timestamp for when the latest mutation was initiated
+};
 ```
 
 - **Returns**: a tuple containing:
-  - `trigger`: a function that triggers an update to the data based on the provided argument
+  - `trigger`: a function that triggers an update to the data based on the provided argument. The trigger function returns a promise with the properties shown above that may be used to handle the behaviour of the promise.
   - `mutationState`: a query status object containing the current loading state and metadata about the request
 
 #### Description

src/createAsyncThunk.ts

@@ -144,7 +144,7 @@ export type AsyncThunkPayloadCreator<
  * A ThunkAction created by `createAsyncThunk`.
  * Dispatching it returns a Promise for either a
  * fulfilled or rejected action.
- * Also, the returned value contains a `abort()` method
+ * Also, the returned value contains an `abort()` method
  * that allows the asyncAction to be cancelled from the outside.
  *
  * @public

src/query/core/buildInitiate.ts

@@ -11,12 +11,13 @@ import {
   AsyncThunk,
   ThunkAction,
   unwrapResult,
+  SerializedError,
 } from '@reduxjs/toolkit'
 import { QuerySubState, SubscriptionOptions } from './apiState'
 import { InternalSerializeQueryArgs } from '../defaultSerializeQueryArgs'
 import { Api } from '../apiTypes'
 import { ApiEndpointQuery } from './module'
-import { BaseQueryResult } from '../baseQueryTypes'
+import { BaseQueryError } from '../baseQueryTypes'
 
 declare module './module' {
   export interface ApiEndpointQuery<
@@ -79,18 +80,98 @@ type StartMutationActionCreator<
 export type MutationActionCreatorResult<
   D extends MutationDefinition<any, any, any, any>
 > = Promise<
-  ReturnType<
-    BaseQueryResult<
-      D extends MutationDefinition<any, infer BaseQuery, any, any>
-        ? BaseQuery
-        : never
-    >
-  >
+  | { data: ResultTypeFrom<D> }
+  | {
+      error:
+        | BaseQueryError<
+            D extends MutationDefinition<any, infer BaseQuery, any, any>
+              ? BaseQuery
+              : never
+          >
+        | SerializedError
+    }
 > & {
-  arg: QueryArgFrom<D>
+  /** @internal */
+  arg: {
+    /**
+     * The name of the given endpoint for the mutation
+     */
+    endpointName: string
+    /**
+     * The original arguments supplied to the mutation call
+     */
+    originalArgs: QueryArgFrom<D>
+    /**
+     * Whether the mutation is being tracked in the store.
+     */
+    track?: boolean
+    /**
+     * Timestamp for when the mutation was initiated
+     */
+    startedTimeStamp: number
+  }
+  /**
+   * A unique string generated for the request sequence
+   */
   requestId: string
+  /**
+   * A method to cancel the mutation promise. Note that this is not intended to prevent the mutation
+   * that was fired off from reaching the server, but only to assist in handling the response.
+   *
+   * Calling `abort()` prior to the promise resolving will make it throw with an error like:
+   * `{ name: 'AbortError', message: 'Aborted' }`
+   *
+   * @example
+   * ```ts
+   * const [updateUser] = useUpdateUserMutation();
+   *
+   * useEffect(() => {
+   *   const promise = updateUser(id);
+   *   promise
+   *     .unwrap()
+   *     .catch((err) => {
+   *       if (err.name === 'AbortError') return;
+   *       // else handle the unexpected error
+   *     })
+   *
+   *   return () => {
+   *     promise.abort();
+   *   }
+   * }, [id, updateUser])
+   * ```
+   */
   abort(): void
+  /**
+   * Unwraps a mutation call to provide the raw response/error.
+   *
+   * @remarks
+   * If you need to access the error or success payload immediately after a mutation, you can chain .unwrap().
+   *
+   * @example
+   * ```ts
+   * // codeblock-meta title="Using .unwrap"
+   * addPost({ id: 1, name: 'Example' })
+   *   .unwrap()
+   *   .then((payload) => console.log('fulfilled', payload))
+   *   .catch((error) => console.error('rejected', error));
+   * ```
+   *
+   * @example
+   * ```ts
+   * // codeblock-meta title="Using .unwrap with async await"
+   * try {
+   *   const payload = await addPost({ id: 1, name: 'Example' }).unwrap();
+   *   console.log('fulfilled', payload)
+   * } catch (error) {
+   *   console.error('rejected', error);
+   * }
+   * ```
+   */
   unwrap(): Promise<ResultTypeFrom<D>>
+  /**
+   * A method to manually unsubscribe from the mutation call, meaning it will be removed from cache after the usual caching grace period.
+   The value returned by the hook will reset to `isUninitialized` afterwards.
+   */
   unsubscribe(): void
 }
 

src/query/react/buildHooks.ts

@@ -321,37 +321,7 @@ export type UseMutation<D extends MutationDefinition<any, any, any, any>> = <
 >(
   options?: UseMutationStateOptions<D, R>
 ) => [
-  (
-    arg: QueryArgFrom<D>
-  ) => {
-    /**
-     * Unwraps a mutation call to provide the raw response/error.
-     *
-     * @remarks
-     * If you need to access the error or success payload immediately after a mutation, you can chain .unwrap().
-     *
-     * @example
-     * ```ts
-     * // codeblock-meta title="Using .unwrap"
-     * addPost({ id: 1, name: 'Example' })
-     *   .unwrap()
-     *   .then((payload) => console.log('fulfilled', payload))
-     *   .catch((error) => console.error('rejected', error));
-     * ```
-     *
-     * @example
-     * ```ts
-     * // codeblock-meta title="Using .unwrap with async await"
-     * try {
-     *   const payload = await addPost({ id: 1, name: 'Example' }).unwrap();
-     *   console.log('fulfilled', payload)
-     * } catch (error) {
-     *   console.error('rejected', error);
-     * }
-     * ```
-     */
-    unwrap: () => Promise<ResultTypeFrom<D>>
-  },
+  (arg: QueryArgFrom<D>) => MutationActionCreatorResult<D>,
   UseMutationStateResult<D, R>
 ]
 

src/query/tests/buildHooks.test.tsx

@@ -6,6 +6,7 @@ import { rest } from 'msw'
 import {
   actionsReducer,
   expectExactType,
+  expectType,
   matchSequence,
   setupApiStore,
   useRenderCounter,
@@ -14,6 +15,7 @@ import {
 import { server } from './mocks/server'
 import { AnyAction } from 'redux'
 import { SubscriptionOptions } from '../core/apiState'
+import { SerializedError } from '../../createAsyncThunk'
 
 // Just setup a temporary in-memory counter for tests that `getIncrementedAmount`.
 // This can be used to test how many renders happen due to data changes or
@@ -26,6 +28,16 @@ const api = createApi({
     if (arg?.body && 'amount' in arg.body) {
       amount += 1
     }
+
+    if (arg?.body && 'forceError' in arg.body) {
+      return {
+        error: {
+          status: 500,
+          data: null,
+        },
+      }
+    }
+
     return {
       data: arg?.body
         ? { ...arg.body, ...(amount ? { amount } : {}) }
@@ -44,7 +56,7 @@ const api = createApi({
         },
       }),
     }),
-    updateUser: build.mutation<any, { name: string }>({
+    updateUser: build.mutation<{ name: string }, { name: string }>({
       query: (update) => ({ body: update }),
     }),
     getError: build.query({
@@ -804,6 +816,84 @@ describe('hooks tests', () => {
         )
       )
     })
+
+    test('useMutation hook callback returns various properties to handle the result', async () => {
+      function User() {
+        const [updateUser] = api.endpoints.updateUser.useMutation()
+        const [successMsg, setSuccessMsg] = React.useState('')
+        const [errMsg, setErrMsg] = React.useState('')
+        const [isAborted, setIsAborted] = React.useState(false)
+
+        const handleClick = async () => {
+          const res = updateUser({ name: 'Banana' })
+
+          // no-op simply for clearer type assertions
+          res.then((result) => {
+            // currently passing with a false positive, because error is getting typed as `any`
+            expectExactType<
+              | {
+                  error: { status: number; data: unknown } | SerializedError
+                }
+              | {
+                  data: {
+                    name: string
+                  }
+                }
+              // @ts-expect-error TEMPORARY ONLY - suppressed for codesandbox build
+            >(result)
+          })
+
+          expectType<{
+            endpointName: string
+            originalArgs: { name: string }
+            track?: boolean
+            startedTimeStamp: number
+          }>(res.arg)
+          expectType<string>(res.requestId)
+          expectType<() => void>(res.abort)
+          expectType<() => Promise<{ name: string }>>(res.unwrap)
+          expectType<() => void>(res.unsubscribe)
+
+          // abort the mutation immediately to force an error
+          res.abort()
+          res
+            .unwrap()
+            .then((result) => {
+              expectType<{ name: string }>(result)
+              setSuccessMsg(`Successfully updated user ${result.name}`)
+            })
+            .catch((err) => {
+              setErrMsg(
+                `An error has occurred updating user ${res.arg.originalArgs.name}`
+              )
+              if (err.name === 'AbortError') {
+                setIsAborted(true)
+              }
+            })
+        }
+
+        return (
+          <div>
+            <button onClick={handleClick}>Update User and abort</button>
+            <div>{successMsg}</div>
+            <div>{errMsg}</div>
+            <div>{isAborted ? 'Request was aborted' : ''}</div>
+          </div>
+        )
+      }
+
+      render(<User />, { wrapper: storeRef.wrapper })
+      expect(screen.queryByText(/An error has occurred/i)).toBeNull()
+      expect(screen.queryByText(/Successfully updated user/i)).toBeNull()
+      expect(screen.queryByText('Request was aborted')).toBeNull()
+
+      fireEvent.click(
+        screen.getByRole('button', { name: 'Update User and abort' })
+      )
+      await screen.findByText('An error has occurred updating user Banana')
+      expect(screen.queryByText(/Successfully updated user/i)).toBeNull()
+      screen.getByText('Request was aborted')
+    })
   })
 
   describe('usePrefetch', () => {

src/query/tests/queryFn.test.tsx

@@ -247,7 +247,7 @@ describe('queryFn base implementation tests', () => {
     {
       const thunk = mutationWithNeither.initiate('mutationWithNeither')
       const result = await store.dispatch(thunk)
-      expect(result.error).toEqual(
+      expect((result as any).error).toEqual(
         expect.objectContaining({
           message: 'endpointDefinition.queryFn is not a function',
         })