Feature/scoped mutations

docs/framework/react/guides/mutations.md

@@ -267,7 +267,7 @@ try {
 
 ## Retry
 
-By default TanStack Query will not retry a mutation on error, but it is possible with the `retry` option:
+By default, TanStack Query will not retry a mutation on error, but it is possible with the `retry` option:
 
 [//]: # 'Example9'
 
@@ -390,6 +390,23 @@ We also have an extensive [offline example](../examples/offline) that covers bot
 
 [//]: # 'Materials'
 
+## Mutation Scopes
+
+Per default, all mutations run in parallel - even if you invoke `.mutate()` of the same mutation multiple times. Mutations can be given a `scope` with an `id` to avoid that. All mutations with the same `scope.id` will run in serial, which means when they are triggered, they will start in `isPaused: true` state if there is already a mutation for that scope in progress. They will be put into a queue and will automatically resume once their time in the queue has come.
+
+[//]: # 'ExampleScopes'
+
+```tsx
+const mutation = useMutation({
+  mutationFn: addTodo,
+  scope: {
+    id: 'todo',
+  },
+})
+```
+
+[//]: # 'ExampleScopes'
+
 ## Further reading
 
 For more information about mutations, have a look at [#12: Mastering Mutations in React Query](../tkdodos-blog#12-mastering-mutations-in-react-query) from

docs/framework/react/reference/useMutation.md

@@ -23,6 +23,7 @@ const {
 } = useMutation({
   mutationFn,
   gcTime,
+  meta,
   mutationKey,
   networkMode,
   onError,
@@ -31,8 +32,8 @@ const {
   onSuccess,
   retry,
   retryDelay,
+  scope,
   throwOnError,
-  meta,
 })
 
 mutate(variables, {
@@ -85,6 +86,10 @@ mutate(variables, {
   - This function receives a `retryAttempt` integer and the actual Error and returns the delay to apply before the next attempt in milliseconds.
   - A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff.
   - A function like `attempt => attempt * 1000` applies linear backoff.
+- `scope: { id: string }`
+  - Optional
+  - Defaults to a unique id (so that all mutations run in parallel)
+  - Mutations with the same scope id will run in serial
 - `throwOnError: undefined | boolean | (error: TError) => boolean`
   - Defaults to the global query config's `throwOnError` value, which is `undefined`
   - Set this to `true` if you want mutation errors to be thrown in the render phase and propagate to the nearest error boundary

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

@@ -704,4 +704,38 @@ describe('dehydration and rehydration', () => {
       hydrationCache.find({ queryKey: ['string'] })?.state.fetchStatus,
     ).toBe('idle')
   })
+
+  test('should dehydrate and hydrate mutation scopes', async () => {
+    const queryClient = createQueryClient()
+    const onlineMock = mockOnlineManagerIsOnline(false)
+
+    void executeMutation(
+      queryClient,
+      {
+        mutationKey: ['mutation'],
+        mutationFn: async () => {
+          return 'mutation'
+        },
+        scope: {
+          id: 'scope',
+        },
+      },
+      'vars',
+    )
+
+    const dehydrated = dehydrate(queryClient)
+    expect(dehydrated.mutations[0]?.scope?.id).toBe('scope')
+    const stringified = JSON.stringify(dehydrated)
+
+    // ---
+    const parsed = JSON.parse(stringified)
+    const hydrationCache = new MutationCache()
+    const hydrationClient = createQueryClient({ mutationCache: hydrationCache })
+
+    hydrate(hydrationClient, parsed)
+
+    expect(dehydrated.mutations[0]?.scope?.id).toBe('scope')
+
+    onlineMock.mockRestore()
+  })
 })

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

@@ -409,4 +409,195 @@ describe('mutations', () => {
 
     expect(onSuccess).toHaveBeenCalledWith(2)
   })
+
+  describe('scoped mutations', () => {
+    test('mutations in the same scope should run in serial', async () => {
+      const key1 = queryKey()
+      const key2 = queryKey()
+
+      const results: Array<string> = []
+
+      const execute1 = executeMutation(
+        queryClient,
+        {
+          mutationKey: key1,
+          scope: {
+            id: 'scope',
+          },
+          mutationFn: async () => {
+            results.push('start-A')
+            await sleep(10)
+            results.push('finish-A')
+            return 'a'
+          },
+        },
+        'vars1',
+      )
+
+      expect(
+        queryClient.getMutationCache().find({ mutationKey: key1 })?.state,
+      ).toMatchObject({
+        status: 'pending',
+        isPaused: false,
+      })
+
+      const execute2 = executeMutation(
+        queryClient,
+        {
+          mutationKey: key2,
+          scope: {
+            id: 'scope',
+          },
+          mutationFn: async () => {
+            results.push('start-B')
+            await sleep(10)
+            results.push('finish-B')
+            return 'b'
+          },
+        },
+        'vars2',
+      )
+
+      expect(
+        queryClient.getMutationCache().find({ mutationKey: key2 })?.state,
+      ).toMatchObject({
+        status: 'pending',
+        isPaused: true,
+      })
+
+      await Promise.all([execute1, execute2])
+
+      expect(results).toStrictEqual([
+        'start-A',
+        'finish-A',
+        'start-B',
+        'finish-B',
+      ])
+    })
+  })
+
+  test('mutations without scope should run in parallel', async () => {
+    const key1 = queryKey()
+    const key2 = queryKey()
+
+    const results: Array<string> = []
+
+    const execute1 = executeMutation(
+      queryClient,
+      {
+        mutationKey: key1,
+        mutationFn: async () => {
+          results.push('start-A')
+          await sleep(10)
+          results.push('finish-A')
+          return 'a'
+        },
+      },
+      'vars1',
+    )
+
+    const execute2 = executeMutation(
+      queryClient,
+      {
+        mutationKey: key2,
+        mutationFn: async () => {
+          results.push('start-B')
+          await sleep(10)
+          results.push('finish-B')
+          return 'b'
+        },
+      },
+      'vars2',
+    )
+
+    await Promise.all([execute1, execute2])
+
+    expect(results).toStrictEqual([
+      'start-A',
+      'start-B',
+      'finish-A',
+      'finish-B',
+    ])
+  })
+
+  test('each scope should run should run in parallel, serial within scope', async () => {
+    const results: Array<string> = []
+
+    const execute1 = executeMutation(
+      queryClient,
+      {
+        scope: {
+          id: '1',
+        },
+        mutationFn: async () => {
+          results.push('start-A1')
+          await sleep(10)
+          results.push('finish-A1')
+          return 'a'
+        },
+      },
+      'vars1',
+    )
+
+    const execute2 = executeMutation(
+      queryClient,
+      {
+        scope: {
+          id: '1',
+        },
+        mutationFn: async () => {
+          results.push('start-B1')
+          await sleep(10)
+          results.push('finish-B1')
+          return 'b'
+        },
+      },
+      'vars2',
+    )
+
+    const execute3 = executeMutation(
+      queryClient,
+      {
+        scope: {
+          id: '2',
+        },
+        mutationFn: async () => {
+          results.push('start-A2')
+          await sleep(10)
+          results.push('finish-A2')
+          return 'a'
+        },
+      },
+      'vars1',
+    )
+
+    const execute4 = executeMutation(
+      queryClient,
+      {
+        scope: {
+          id: '2',
+        },
+        mutationFn: async () => {
+          results.push('start-B2')
+          await sleep(10)
+          results.push('finish-B2')
+          return 'b'
+        },
+      },
+      'vars2',
+    )
+
+    await Promise.all([execute1, execute2, execute3, execute4])
+
+    expect(results).toStrictEqual([
+      'start-A1',
+      'start-A2',
+      'finish-A1',
+      'start-B1',
+      'finish-A2',
+      'start-B2',
+      'finish-B1',
+      'finish-B2',
+    ])
+  })
 })