useMutation
hook for React and React Native. Tailored for thorough response handling.
yarn add react-mutation
# or
npm i --save react-mutation
const Button = () => {
const [mutate, { isLoading, error, reset }] = useMutation(({ name }) => {
return Promise.resolve(`Hello ${name}!`)
}, {
chainSettle: x => x.catch(catchAllError)
})
return (
<button onClick={() => {
mutate({ name: "World" }, (chain) =>
chain.then((returnedString) => {
// On success
console.log(returnedString)
}).catch((e) => {
// On error
console.error(e)
})
)
}}>
Call Mutate
</button>
)
}
- Designed for comprehensive error handling
- Compatible with React Native
- Supports async/await
- Built with Typescript
We expose isLoading
and error
in the hook level allowing us to show appropriate status to user.
react-mutation
also allows great control over handling mutation responses. This library was built mainly for better error handling. We allow then
and catch
(or async/await try
& catch
) on all stages of the mutation.
These are:
- Initial request
- Locally when the mutate function is called
- "Globally" when the hook is first defined
Consider the following graph:
This library is tailored to allow promise chaining on various stages of the response. A standard flow could look like:
- Query - Calling edit profile API request
- Local - Handling alert if success. Catches validation error and alerting user.
- Global - Catches unexpected error, logging it to the cloud.
I don't recommend returning/throwing an error past "global" unless you know what you're doing. Eg: Catch using error boundary.
useMutation<TResult = any, TVariables = any>(mutationFn: (variables: TVariables) => Promise, config?: MutationParamConfig): MutationReturn<TResult, TVariables>
- Required
- A function that returns a promise. This is your main mutate function
variables
is an object that will be passed when you call the mutate function
{ onMutate, chainSettle }
- Called immediately after mutate function is called
- This can be used for optimistic updates
- Will be chained AFTER local
- Normally only used to
.catch
- Example usage:
chainSettle: (chain) => chain.catch(e => console.error(e))
or equals to
MutationReturn<TResult, TVariables> = [
MutationReturnFunction<TResult, TVariables>,
MutationReturnConfig
]
- Call this function to execute the request
variables
will be passed tomutationFn
- Example usage:
const [mutate] = useMutation(...)
mutate(variables)
- Will be chained AFTER query and BEFORE "global"
- Example usage:
mutate(variables,
chain => chain.then(x => console.log(x))
)
- Refer to the config above
- If passed, this will be used instead of the value in config (per config key)
isLoading
:true
if mutation is being executed, otherwisefalse
error
: error object from.catch
.null
if no errorreset
: function to reset error back to null. Eg:reset()
This will call the error and log it, then let it be handled by catchAllError
api.ts
export default () => {
return useMutation(({ name }) => {
return Promise.reject()
}, {
chainSettle: x => x.catch(catchAllError)
})
}
component.tsx
import useApi from './api.ts'
const Button = () => {
const [mutate] = useApi()
return (
<button onClick={() => {
mutate({ name: "World" }, (chain) =>
chain.catch((e) => {
// On error
// This will be called first
console.error(e)
throw e
})
)
}}>
Call Mutate
</button>
)
}
api.ts
export default () => {
return useMutation(({ name }) => {
return new Promise((resolve, reject) => setTimeout(resolve(name), 1000))
})
}
component.tsx
import useApi from './api.ts'
const Button = () => {
const [mutate, { isLoading, error, reset }] = useApi()
return (
<>
{isLoading.toString()}
{error?.toString() ?? "null"}
<button onClick={() => {
mutate({ name: "World" })
}}>
Call Mutate
</button>
<button onClick={() => reset()}>Reset</button>
</>
)
}
export default () => {
return useMutation(({ name }) => {
return new Promise((resolve, reject) => setTimeout(resolve(name), 1000))
}, {
onMutate: (variables) => {
const { name } = variables
// Update cache
}
})
}
react-mutation
is built using TS. You should be able to use it without doing anything.
Refer to src/types.ts for most of the types we use., so you don't have to do anything to use
Sometimes, we'll want to chain mutations together. When one failed, then the rest shouldn't continue. Here's an example of how you might do this:
const Button = () => {
const [mutate] = useMutation(({ name }) => {
return Promise.resolve(`Hello ${name}!`)
})
const [mutate2] = useMutation(({ name }) => {
return Promise.resolve(`Hello, my name is ${name}!`)
})
return (
<button onClick={async () => {
try {
await mutate({ name: "World" })
await mutate2({ name: "Adam" })
}
catch(e) {
alert("Mutate failed!")
}
}}>
Call Mutate
</button>
)
}
Notice that for this, we catch the error in a different way that normal. Usually we pass a chain function on the second parameter. Using await outside means that this is handled after the "global" handler. We let the error overflow and handle it ourself.
If you are using a catch-all error handling on the global level, then this wouldn't work. Since the error won't be thrown, an error in any of the mutate
won't stop the rest from executing.
For this, we can override the global chain by passing additional config when we call mutate. I also recommend having a default error handling function that you can easily trigger whether to propegate the error or not.
Since we're just dealing with Promise, we can use async/await wherever we want. The only downside is it could be confusing which part of the promise are we dealing with.
api.ts
export default () => {
return useMutation(({ name }) => {
return new Promise((resolve, reject) => setTimeout(resolve(name), 1000))
})
}
component.tsx
import useApi from './api.ts'
const Button = () => {
const [mutate, { isLoading, error, reset }] = useApi()
return (
<>
{isLoading.toString()}
{error?.toString() ?? "null"}
<button onClick={() => {
mutate(
{ name: "World" },
async chain => {
console.log("This is called before request is run")
const res = await chain
console.log("This is called after request is run (Same as after .then)")
return res
}
)
}}>
Call Mutate
</button>
<button onClick={() => reset()}>Reset</button>
</>
)
}
Any contributions are welcomed. Create an issue/PR and I'll have a look at it as soon as possible. I'd love to see use cases and problems when using this.
- Docs could be better/clearer
- We could tighten the types, especially promise error types
- More examples
- Add tests
Big thanks to react-query where a big part of our API is based from.