docs(mutations): describe difference between using callbacks in useMu… (#3274)

* docs(mutations): describe difference between using callbacks in useMutation and .mutate

* Text corrections

Co-authored-by: Dominik Dorfmeister <[email protected]>

* add subheader

* update consecutive mutations case to better describe ordering of mutation calls and fulfillment

Co-authored-by: Dominik Dorfmeister <[email protected]>

Author: zrwsk

docs/src/pages/guides/mutations.md

@@ -179,6 +179,28 @@ mutate(todo, {
 })
 ```
 
+### Consecutive mutations
+There is a slight difference in handling `onSuccess`, `onError` and `onSettled` callbacks when it comes to consecutive mutations. When passed to the `mutate` function, they will be fired up only _once_ and only if the component is still mounted.  This is due to the fact that mutation observer is removed and resubscribed every time when the `mutate` function is called. On the contrary, `useMutation` handlers execute for each `mutate` call.
+
+> Be aware that most likely, `mutationFn` passed to `useMutation` is ansynchronous. In that case, the order in which mutations are fulfilled may differ from the order of `mutate` function calls.
+
+```js
+useMutation(addTodo, {
+  onSuccess: (data, error, variables, context) => {
+    // Will be called 3 times
+  },
+})
+
+['Todo 1', 'Todo 2', 'Todo 3'].forEach((todo) => {
+  mutate(todo, {
+    onSuccess: (data, error, variables, context) => {
+      // Will execute only once, for the last mutation (Todo 3),
+      // regardles which mutation resolves first 
+    },
+  })
+})
+
+```
 ## Promises
 
 Use `mutateAsync` instead of `mutate` to get a promise which will resolve on success or throw on an error. This can for example be used to compose side effects.