@tanstack/query-core 5.87.4 → 5.89.0

package/src/mutation.ts

@@ -3,6 +3,7 @@ import { Removable } from './removable'
 import { createRetryer } from './retryer'
 import type {
   DefaultError,
+  MutationFunctionContext,
   MutationMeta,
   MutationOptions,
   MutationStatus,
@@ -10,23 +11,25 @@ import type {
 import type { MutationCache } from './mutationCache'
 import type { MutationObserver } from './mutationObserver'
 import type { Retryer } from './retryer'
+import type { QueryClient } from './queryClient'
 
 // TYPES
 
-interface MutationConfig<TData, TError, TVariables, TContext> {
+interface MutationConfig<TData, TError, TVariables, TOnMutateResult> {
+  client: QueryClient
   mutationId: number
   mutationCache: MutationCache
-  options: MutationOptions<TData, TError, TVariables, TContext>
-  state?: MutationState<TData, TError, TVariables, TContext>
+  options: MutationOptions<TData, TError, TVariables, TOnMutateResult>
+  state?: MutationState<TData, TError, TVariables, TOnMutateResult>
 }
 
 export interface MutationState<
   TData = unknown,
   TError = DefaultError,
   TVariables = unknown,
-  TContext = unknown,
+  TOnMutateResult = unknown,
 > {
-  context: TContext | undefined
+  context: TOnMutateResult | undefined
   data: TData | undefined
   error: TError | null
   failureCount: number
@@ -43,11 +46,11 @@ interface FailedAction<TError> {
   error: TError | null
 }
 
-interface PendingAction<TVariables, TContext> {
+interface PendingAction<TVariables, TOnMutateResult> {
   type: 'pending'
   isPaused: boolean
   variables?: TVariables
-  context?: TContext
+  context?: TOnMutateResult
 }
 
 interface SuccessAction<TData> {
@@ -68,11 +71,11 @@ interface ContinueAction {
   type: 'continue'
 }
 
-export type Action<TData, TError, TVariables, TContext> =
+export type Action<TData, TError, TVariables, TOnMutateResult> =
   | ContinueAction
   | ErrorAction<TError>
   | FailedAction<TError>
-  | PendingAction<TVariables, TContext>
+  | PendingAction<TVariables, TOnMutateResult>
   | PauseAction
   | SuccessAction<TData>
 
@@ -82,19 +85,25 @@ export class Mutation<
   TData = unknown,
   TError = DefaultError,
   TVariables = unknown,
-  TContext = unknown,
+  TOnMutateResult = unknown,
 > extends Removable {
-  state: MutationState<TData, TError, TVariables, TContext>
-  options!: MutationOptions<TData, TError, TVariables, TContext>
+  state: MutationState<TData, TError, TVariables, TOnMutateResult>
+  options!: MutationOptions<TData, TError, TVariables, TOnMutateResult>
   readonly mutationId: number
 
-  #observers: Array<MutationObserver<TData, TError, TVariables, TContext>>
+  #client: QueryClient
+  #observers: Array<
+    MutationObserver<TData, TError, TVariables, TOnMutateResult>
+  >
   #mutationCache: MutationCache
   #retryer?: Retryer<TData>
 
-  constructor(config: MutationConfig<TData, TError, TVariables, TContext>) {
+  constructor(
+    config: MutationConfig<TData, TError, TVariables, TOnMutateResult>,
+  ) {
     super()
 
+    this.#client = config.client
     this.mutationId = config.mutationId
     this.#mutationCache = config.mutationCache
     this.#observers = []
@@ -105,7 +114,7 @@ export class Mutation<
   }
 
   setOptions(
-    options: MutationOptions<TData, TError, TVariables, TContext>,
+    options: MutationOptions<TData, TError, TVariables, TOnMutateResult>,
   ): void {
     this.options = options
 
@@ -166,12 +175,19 @@ export class Mutation<
       this.#dispatch({ type: 'continue' })
     }
 
+    const mutationFnContext = {
+      client: this.#client,
+      meta: this.options.meta,
+      mutationKey: this.options.mutationKey,
+    } satisfies MutationFunctionContext
+
     this.#retryer = createRetryer({
       fn: () => {
         if (!this.options.mutationFn) {
           return Promise.reject(new Error('No mutationFn found'))
         }
-        return this.options.mutationFn(variables)
+
+        return this.options.mutationFn(variables, mutationFnContext)
       },
       onFail: (failureCount, error) => {
         this.#dispatch({ type: 'failed', failureCount, error })
@@ -199,8 +215,12 @@ export class Mutation<
         await this.#mutationCache.config.onMutate?.(
           variables,
           this as Mutation<unknown, unknown, unknown, unknown>,
+          mutationFnContext,
+        )
+        const context = await this.options.onMutate?.(
+          variables,
+          mutationFnContext,
         )
-        const context = await this.options.onMutate?.(variables)
         if (context !== this.state.context) {
           this.#dispatch({
             type: 'pending',
@@ -218,9 +238,15 @@ export class Mutation<
         variables,
         this.state.context,
         this as Mutation<unknown, unknown, unknown, unknown>,
+        mutationFnContext,
       )
 
-      await this.options.onSuccess?.(data, variables, this.state.context!)
+      await this.options.onSuccess?.(
+        data,
+        variables,
+        this.state.context,
+        mutationFnContext,
+      )
 
       // Notify cache callback
       await this.#mutationCache.config.onSettled?.(
@@ -229,9 +255,16 @@ export class Mutation<
         this.state.variables,
         this.state.context,
         this as Mutation<unknown, unknown, unknown, unknown>,
+        mutationFnContext,
       )
 
-      await this.options.onSettled?.(data, null, variables, this.state.context)
+      await this.options.onSettled?.(
+        data,
+        null,
+        variables,
+        this.state.context,
+        mutationFnContext,
+      )
 
       this.#dispatch({ type: 'success', data })
       return data
@@ -243,12 +276,14 @@ export class Mutation<
           variables,
           this.state.context,
           this as Mutation<unknown, unknown, unknown, unknown>,
+          mutationFnContext,
         )
 
         await this.options.onError?.(
           error as TError,
           variables,
           this.state.context,
+          mutationFnContext,
         )
 
         // Notify cache callback
@@ -258,6 +293,7 @@ export class Mutation<
           this.state.variables,
           this.state.context,
           this as Mutation<unknown, unknown, unknown, unknown>,
+          mutationFnContext,
         )
 
         await this.options.onSettled?.(
@@ -265,6 +301,7 @@ export class Mutation<
           error as TError,
           variables,
           this.state.context,
+          mutationFnContext,
         )
         throw error
       } finally {
@@ -275,10 +312,10 @@ export class Mutation<
     }
   }
 
-  #dispatch(action: Action<TData, TError, TVariables, TContext>): void {
+  #dispatch(action: Action<TData, TError, TVariables, TOnMutateResult>): void {
     const reducer = (
-      state: MutationState<TData, TError, TVariables, TContext>,
-    ): MutationState<TData, TError, TVariables, TContext> => {
+      state: MutationState<TData, TError, TVariables, TOnMutateResult>,
+    ): MutationState<TData, TError, TVariables, TOnMutateResult> => {
       switch (action.type) {
         case 'failed':
           return {
@@ -350,8 +387,8 @@ export function getDefaultState<
   TData,
   TError,
   TVariables,
-  TContext,
->(): MutationState<TData, TError, TVariables, TContext> {
+  TOnMutateResult,
+>(): MutationState<TData, TError, TVariables, TOnMutateResult> {
   return {
     context: undefined,
     data: undefined,

package/src/mutationCache.ts

@@ -3,7 +3,12 @@ import { Mutation } from './mutation'
 import { matchMutation, noop } from './utils'
 import { Subscribable } from './subscribable'
 import type { MutationObserver } from './mutationObserver'
-import type { DefaultError, MutationOptions, NotifyEvent } from './types'
+import type {
+  DefaultError,
+  MutationFunctionContext,
+  MutationOptions,
+  NotifyEvent,
+} from './types'
 import type { QueryClient } from './queryClient'
 import type { Action, MutationState } from './mutation'
 import type { MutationFilters } from './utils'
@@ -14,25 +19,29 @@ interface MutationCacheConfig {
   onError?: (
     error: DefaultError,
     variables: unknown,
-    context: unknown,
+    onMutateResult: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
+    context: MutationFunctionContext,
   ) => Promise<unknown> | unknown
   onSuccess?: (
     data: unknown,
     variables: unknown,
-    context: unknown,
+    onMutateResult: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
+    context: MutationFunctionContext,
   ) => Promise<unknown> | unknown
   onMutate?: (
     variables: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
+    context: MutationFunctionContext,
   ) => Promise<unknown> | unknown
   onSettled?: (
     data: unknown | undefined,
     error: DefaultError | null,
     variables: unknown,
-    context: unknown,
+    onMutateResult: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
+    context: MutationFunctionContext,
   ) => Promise<unknown> | unknown
 }
 
@@ -93,12 +102,13 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     this.#mutationId = 0
   }
 
-  build<TData, TError, TVariables, TContext>(
+  build<TData, TError, TVariables, TOnMutateResult>(
     client: QueryClient,
-    options: MutationOptions<TData, TError, TVariables, TContext>,
-    state?: MutationState<TData, TError, TVariables, TContext>,
-  ): Mutation<TData, TError, TVariables, TContext> {
+    options: MutationOptions<TData, TError, TVariables, TOnMutateResult>,
+    state?: MutationState<TData, TError, TVariables, TOnMutateResult>,
+  ): Mutation<TData, TError, TVariables, TOnMutateResult> {
     const mutation = new Mutation({
+      client,
       mutationCache: this,
       mutationId: ++this.#mutationId,
       options: client.defaultMutationOptions(options),
@@ -195,15 +205,15 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     TData = unknown,
     TError = DefaultError,
     TVariables = any,
-    TContext = unknown,
+    TOnMutateResult = unknown,
   >(
     filters: MutationFilters,
-  ): Mutation<TData, TError, TVariables, TContext> | undefined {
+  ): Mutation<TData, TError, TVariables, TOnMutateResult> | undefined {
     const defaultedFilters = { exact: true, ...filters }
 
     return this.getAll().find((mutation) =>
       matchMutation(defaultedFilters, mutation),
-    ) as Mutation<TData, TError, TVariables, TContext> | undefined
+    ) as Mutation<TData, TError, TVariables, TOnMutateResult> | undefined
   }
 
   findAll(filters: MutationFilters = {}): Array<Mutation> {

package/src/mutationObserver.ts

@@ -6,6 +6,7 @@ import type { QueryClient } from './queryClient'
 import type {
   DefaultError,
   MutateOptions,
+  MutationFunctionContext,
   MutationObserverOptions,
   MutationObserverResult,
 } from './types'
@@ -13,8 +14,8 @@ import type { Action, Mutation } from './mutation'
 
 // TYPES
 
-type MutationObserverListener<TData, TError, TVariables, TContext> = (
-  result: MutationObserverResult<TData, TError, TVariables, TContext>,
+type MutationObserverListener<TData, TError, TVariables, TOnMutateResult> = (
+  result: MutationObserverResult<TData, TError, TVariables, TOnMutateResult>,
 ) => void
 
 // CLASS
@@ -23,21 +24,30 @@ export class MutationObserver<
   TData = unknown,
   TError = DefaultError,
   TVariables = void,
-  TContext = unknown,
+  TOnMutateResult = unknown,
 > extends Subscribable<
-  MutationObserverListener<TData, TError, TVariables, TContext>
+  MutationObserverListener<TData, TError, TVariables, TOnMutateResult>
 > {
-  options!: MutationObserverOptions<TData, TError, TVariables, TContext>
+  options!: MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>
 
   #client: QueryClient
-  #currentResult: MutationObserverResult<TData, TError, TVariables, TContext> =
-    undefined!
-  #currentMutation?: Mutation<TData, TError, TVariables, TContext>
-  #mutateOptions?: MutateOptions<TData, TError, TVariables, TContext>
+  #currentResult: MutationObserverResult<
+    TData,
+    TError,
+    TVariables,
+    TOnMutateResult
+  > = undefined!
+  #currentMutation?: Mutation<TData, TError, TVariables, TOnMutateResult>
+  #mutateOptions?: MutateOptions<TData, TError, TVariables, TOnMutateResult>
 
   constructor(
     client: QueryClient,
-    options: MutationObserverOptions<TData, TError, TVariables, TContext>,
+    options: MutationObserverOptions<
+      TData,
+      TError,
+      TVariables,
+      TOnMutateResult
+    >,
   ) {
     super()
 
@@ -53,10 +63,15 @@ export class MutationObserver<
   }
 
   setOptions(
-    options: MutationObserverOptions<TData, TError, TVariables, TContext>,
+    options: MutationObserverOptions<
+      TData,
+      TError,
+      TVariables,
+      TOnMutateResult
+    >,
   ) {
     const prevOptions = this.options as
-      | MutationObserverOptions<TData, TError, TVariables, TContext>
+      | MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>
       | undefined
     this.options = this.#client.defaultMutationOptions(options)
     if (!shallowEqualObjects(this.options, prevOptions)) {
@@ -84,7 +99,9 @@ export class MutationObserver<
     }
   }
 
-  onMutationUpdate(action: Action<TData, TError, TVariables, TContext>): void {
+  onMutationUpdate(
+    action: Action<TData, TError, TVariables, TOnMutateResult>,
+  ): void {
     this.#updateResult()
 
     this.#notify(action)
@@ -94,7 +111,7 @@ export class MutationObserver<
     TData,
     TError,
     TVariables,
-    TContext
+    TOnMutateResult
   > {
     return this.#currentResult
   }
@@ -110,7 +127,7 @@ export class MutationObserver<
 
   mutate(
     variables: TVariables,
-    options?: MutateOptions<TData, TError, TVariables, TContext>,
+    options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>,
   ): Promise<TData> {
     this.#mutateOptions = options
 
@@ -128,7 +145,7 @@ export class MutationObserver<
   #updateResult(): void {
     const state =
       this.#currentMutation?.state ??
-      getDefaultState<TData, TError, TVariables, TContext>()
+      getDefaultState<TData, TError, TVariables, TOnMutateResult>()
 
     this.#currentResult = {
       ...state,
@@ -138,25 +155,48 @@ export class MutationObserver<
       isIdle: state.status === 'idle',
       mutate: this.mutate,
       reset: this.reset,
-    } as MutationObserverResult<TData, TError, TVariables, TContext>
+    } as MutationObserverResult<TData, TError, TVariables, TOnMutateResult>
   }
 
-  #notify(action?: Action<TData, TError, TVariables, TContext>): void {
+  #notify(action?: Action<TData, TError, TVariables, TOnMutateResult>): void {
     notifyManager.batch(() => {
       // First trigger the mutate callbacks
       if (this.#mutateOptions && this.hasListeners()) {
         const variables = this.#currentResult.variables!
-        const context = this.#currentResult.context
+        const onMutateResult = this.#currentResult.context
+
+        const context = {
+          client: this.#client,
+          meta: this.options.meta,
+          mutationKey: this.options.mutationKey,
+        } satisfies MutationFunctionContext
 
         if (action?.type === 'success') {
-          this.#mutateOptions.onSuccess?.(action.data, variables, context!)
-          this.#mutateOptions.onSettled?.(action.data, null, variables, context)
+          this.#mutateOptions.onSuccess?.(
+            action.data,
+            variables,
+            onMutateResult,
+            context,
+          )
+          this.#mutateOptions.onSettled?.(
+            action.data,
+            null,
+            variables,
+            onMutateResult,
+            context,
+          )
         } else if (action?.type === 'error') {
-          this.#mutateOptions.onError?.(action.error, variables, context)
+          this.#mutateOptions.onError?.(
+            action.error,
+            variables,
+            onMutateResult,
+            context,
+          )
           this.#mutateOptions.onSettled?.(
             undefined,
             action.error,
             variables,
+            onMutateResult,
             context,
           )
         }

package/src/queryClient.ts

@@ -512,11 +512,11 @@ export class QueryClient {
     TData = unknown,
     TError = DefaultError,
     TVariables = void,
-    TContext = unknown,
+    TOnMutateResult = unknown,
   >(
     mutationKey: MutationKey,
     options: OmitKeyof<
-      MutationObserverOptions<TData, TError, TVariables, TContext>,
+      MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>,
       'mutationKey'
     >,
   ): void {