feat: add scope deprecate context on mutation state

Author: joshuaellis

packages/query-core/src/__tests__/mutations.test.tsx

@@ -64,6 +64,7 @@ describe('mutations', () => {
 
     expect(mutation.getCurrentResult()).toEqual({
       context: undefined,
+      scope: undefined,
       data: undefined,
       error: null,
       failureCount: 0,
@@ -92,6 +93,7 @@ describe('mutations', () => {
 
     expect(states[0]).toEqual({
       context: undefined,
+      scope: undefined,
       data: undefined,
       error: null,
       failureCount: 0,
@@ -112,6 +114,7 @@ describe('mutations', () => {
 
     expect(states[1]).toEqual({
       context: 'todo',
+      scope: 'todo',
       data: undefined,
       error: null,
       failureCount: 0,
@@ -132,6 +135,7 @@ describe('mutations', () => {
 
     expect(states[2]).toEqual({
       context: 'todo',
+      scope: 'todo',
       data: 'todo',
       error: null,
       failureCount: 0,
@@ -170,6 +174,7 @@ describe('mutations', () => {
 
     expect(states[0]).toEqual({
       context: undefined,
+      scope: undefined,
       data: undefined,
       error: null,
       failureCount: 0,
@@ -190,6 +195,7 @@ describe('mutations', () => {
 
     expect(states[1]).toEqual({
       context: 'todo',
+      scope: 'todo',
       data: undefined,
       error: null,
       failureCount: 0,
@@ -210,6 +216,7 @@ describe('mutations', () => {
 
     expect(states[2]).toEqual({
       context: 'todo',
+      scope: 'todo',
       data: undefined,
       error: null,
       failureCount: 1,
@@ -230,6 +237,7 @@ describe('mutations', () => {
 
     expect(states[3]).toEqual({
       context: 'todo',
+      scope: 'todo',
       data: undefined,
       error: new Error('err'),
       failureCount: 2,
@@ -270,6 +278,7 @@ describe('mutations', () => {
         },
         {
           context: 'todo',
+          scope: 'todo',
           data: undefined,
           error: null,
           failureCount: 1,
@@ -283,6 +292,7 @@ describe('mutations', () => {
 
     expect(mutation.state).toEqual({
       context: 'todo',
+      scope: 'todo',
       data: undefined,
       error: null,
       failureCount: 1,
@@ -298,6 +308,7 @@ describe('mutations', () => {
     // check that the mutation is correctly resumed
     expect(mutation.state).toEqual({
       context: 'todo',
+      scope: 'todo',
       data: undefined,
       error: null,
       failureCount: 1,
@@ -312,6 +323,7 @@ describe('mutations', () => {
 
     expect(mutation.state).toEqual({
       context: 'todo',
+      scope: 'todo',
       data: 'todo',
       error: null,
       failureCount: 0,

packages/query-core/src/mutation.ts

@@ -29,7 +29,11 @@ export interface MutationState<
   TVariables = unknown,
   TScope = unknown,
 > {
+  /**
+   * @deprecated This will be removed in the next major version. Use the `scope` property instead.
+   */
   context: TScope | undefined
+  scope: TScope | undefined
   data: TData | undefined
   error: TError | null
   failureCount: number
@@ -50,7 +54,7 @@ interface PendingAction<TVariables, TScope> {
   type: 'pending'
   isPaused: boolean
   variables?: TVariables
-  context?: TScope
+  scope?: TScope
 }
 
 interface SuccessAction<TData> {
@@ -212,14 +216,14 @@ export class Mutation<
           variables,
           this as Mutation<unknown, unknown, unknown, unknown>,
         )
-        const context = await this.options.onMutate?.(
+        const scope = await this.options.onMutate?.(
           variables,
           mutationFnContext,
         )
-        if (context !== this.state.context) {
+        if (scope !== this.state.scope) {
           this.#dispatch({
             type: 'pending',
-            context,
+            scope,
             variables,
             isPaused,
           })
@@ -231,22 +235,22 @@ export class Mutation<
       await this.#mutationCache.config.onSuccess?.(
         data,
         variables,
-        this.state.context,
+        this.state.scope,
         this as Mutation<unknown, unknown, unknown, unknown>,
       )
 
-      await this.options.onSuccess?.(data, variables, this.state.context!)
+      await this.options.onSuccess?.(data, variables, this.state.scope!)
 
       // Notify cache callback
       await this.#mutationCache.config.onSettled?.(
         data,
         null,
         this.state.variables,
-        this.state.context,
+        this.state.scope,
         this as Mutation<unknown, unknown, unknown, unknown>,
       )
 
-      await this.options.onSettled?.(data, null, variables, this.state.context)
+      await this.options.onSettled?.(data, null, variables, this.state.scope)
 
       this.#dispatch({ type: 'success', data })
       return data
@@ -256,30 +260,30 @@ export class Mutation<
         await this.#mutationCache.config.onError?.(
           error as any,
           variables,
-          this.state.context,
+          this.state.scope,
           this as Mutation<unknown, unknown, unknown, unknown>,
         )
 
         await this.options.onError?.(
           error as TError,
           variables,
-          this.state.context,
+          this.state.scope,
         )
 
         // Notify cache callback
         await this.#mutationCache.config.onSettled?.(
           undefined,
           error as any,
           this.state.variables,
-          this.state.context,
+          this.state.scope,
           this as Mutation<unknown, unknown, unknown, unknown>,
         )
 
         await this.options.onSettled?.(
           undefined,
           error as TError,
           variables,
-          this.state.context,
+          this.state.scope,
         )
         throw error
       } finally {
@@ -314,7 +318,8 @@ export class Mutation<
         case 'pending':
           return {
             ...state,
-            context: action.context,
+            context: action.scope,
+            scope: action.scope,
             data: undefined,
             failureCount: 0,
             failureReason: null,
@@ -369,6 +374,7 @@ export function getDefaultState<
 >(): MutationState<TData, TError, TVariables, TScope> {
   return {
     context: undefined,
+    scope: undefined,
     data: undefined,
     error: null,
     failureCount: 0,

packages/query-core/src/mutationObserver.ts

@@ -146,18 +146,18 @@ export class MutationObserver<
       // First trigger the mutate callbacks
       if (this.#mutateOptions && this.hasListeners()) {
         const variables = this.#currentResult.variables!
-        const context = this.#currentResult.context
+        const scope = this.#currentResult.scope
 
         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, scope!)
+          this.#mutateOptions.onSettled?.(action.data, null, variables, scope)
         } else if (action?.type === 'error') {
-          this.#mutateOptions.onError?.(action.error, variables, context)
+          this.#mutateOptions.onError?.(action.error, variables, scope)
           this.#mutateOptions.onSettled?.(
             undefined,
             action.error,
             variables,
-            context,
+            scope,
           )
         }
       }

packages/query-devtools/src/Devtools.tsx

@@ -2427,7 +2427,7 @@ const MutationDetails = () => {
           <Explorer
             label="Context"
             defaultExpanded={['Context']}
-            value={activeMutation()!.state.context}
+            value={activeMutation()!.state.scope}
           />
         </div>
         <div class={cx(styles().detailsHeader, 'tsqd-query-details-header')}>