feature: useMutation onSuccess, onError, onSettled now have access to…

… variables (#274)

README.md

@@ -1075,6 +1075,11 @@ Mutations without variables are not that useful, so let's add some variables to
 To pass `variables` to your `mutate` function, call `mutate` with an object.
 
 ```js
+
+// Notice how the fetcher function receives an object containing
+// all possible variables
+const createTodo = ({title}) => { /* trigger an http request */ }
+
 const CreateTodo = () => {
   const [title, setTitle] = useState('')
   const [mutate] = useMutation(createTodo)
@@ -1267,6 +1272,23 @@ mutate(
 const { status, data, error } = useQuery(['todo', { id: 5 }], fetchTodoByID)
 ```
 
+
+You might want to tight the `onSuccess` logic into a reusable mutation, for that you can
+create a custom hook like this:
+
+```js
+
+const useMutateTodo = () => {
+  return useMutate(editTodo, {
+    // Notice the second argument is the variables object that the `mutate` function receives
+    onSuccess: (data, variables) => {
+      queryCache.setQueryData(['todo', { id: variables.id }], data)
+    },
+  })
+}
+
+```
+
 ## Resetting Mutation State
 
 It's sometimes the case that you need to clear the `error` or `data` of a mutation request. To do this, you can use the `reset` function to handle this:
@@ -2041,15 +2063,16 @@ const promise = mutate(variables, {
 - `mutationFn: Function(variables) => Promise`
   - **Required**
   - A function that performs an asynchronous task and returns a promise.
-- `onSuccess: Function(data) => Promise | undefined`
+  - `variables` is an object that `mutate` will pass to your `mutationFn`
+- `onSuccess: Function(data, variables) => Promise | undefined`
   - Optional
   - This function will fire when the mutation is successful and will be passed the mutation's result.
   - If a promise is returned, it will be awaited and resolved before proceeding
-- `onError: Function(err) => Promise | undefined`
+- `onError: Function(err, variables) => Promise | undefined`
   - Optional
   - This function will fire if the mutation encounters an error and will be passed the error.
   - If a promise is returned, it will be awaited and resolved before proceeding
-- `onSettled: Function(data, error) => Promise | undefined`
+- `onSettled: Function(data, error, variables) => Promise | undefined`
   - Optional
   - This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error
   - If a promise is returned, it will be awaited and resolved before proceeding

src/useMutation.js

@@ -79,8 +79,8 @@ export function useMutation(mutationFn, config = {}) {
 
       try {
         const data = await getMutationFn()(variables)
-        await resolvedOptions.onSuccess(data)
-        await resolvedOptions.onSettled(data, null)
+        await resolvedOptions.onSuccess(data, variables)
+        await resolvedOptions.onSettled(data, null, variables)
 
         if (latestMutationRef.current === mutationId) {
           dispatch({ type: actionResolve, data })
@@ -89,8 +89,8 @@ export function useMutation(mutationFn, config = {}) {
         return data
       } catch (error) {
         Console.error(error)
-        await resolvedOptions.onError(error)
-        await resolvedOptions.onSettled(undefined, error)
+        await resolvedOptions.onError(error, variables)
+        await resolvedOptions.onSettled(undefined, error, variables)
 
         if (latestMutationRef.current === mutationId) {
           dispatch({ type: actionReject, error })