useMutation hook for React and React Native. Tailored for thorough response handling.
npm install react-mutationuseMutation hook for React and React Native. Tailored for thorough response handling.
``bash`
yarn add react-mutationor
npm i --save react-mutation
tsx
const Button = () => {
const [mutate, { isLoading, error, reset }] = useMutation(({ name }) => {
return Promise.resolve(Hello ${name}!)
}, {
chainSettle: x => x.catch(catchAllError)
}) return (
)
}
`Features
- Designed for comprehensive error handling
- Compatible with React Native
- Supports async/await
- Built with TypescriptWhy use
react-mutation?
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.
API
useMutation(mutationFn, config?)
> useMutation(mutationFn: (variables: TVariables) => Promise, config?: MutationParamConfig): MutationReturn$3
- 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$3
> { onMutate, chainSettle }####
onMutate: (variables: TVariables) => void
- Called immediately after mutate function is called
- This can be used for optimistic updates
#### chainSettle: (chain: Promise, variables: TVariables) => Promise
- Will be chained AFTER local
- Normally only used to .catch
- Example usage: chainSettle: (chain) => chain.catch(e => console.error(e))> Return
$3
or equals to`ts
MutationReturn = [
MutationReturnFunction,
MutationReturnConfig
]
`$3
- Call this function to execute the request
- variables will be passed to mutationFn
- Example usage:
`ts
const [mutate] = useMutation(...)
mutate(variables)
`####
chain?: (chain: Promise, variables: TVariables) => Promise
- Will be chained AFTER query and BEFORE "global"
- Example usage:
`ts
mutate(variables,
chain => chain.then(x => console.log(x))
)
`
#### overrideConfig?: MutationParamConfig
- Refer to the config above
- If passed, this will be used instead of the value in config (per config key)$3
- isLoading: true if mutation is being executed, otherwise false
- error: error object from .catch. null if no error
- reset: function to reset error back to null. Eg: reset()More Examples
Standard error handling
This will call the error and log it, then let it be handled by catchAllErrorapi.ts
`ts
export default () => {
return useMutation(({ name }) => {
return Promise.reject()
}, {
chainSettle: x => x.catch(catchAllError)
})
}
`
component.tsx
`tsx
import useApi from './api.ts'const Button = () => {
const [mutate] = useApi()
return (
)
}
`Show loading/error state & reset
api.ts
`ts
export default () => {
return useMutation(({ name }) => {
return new Promise((resolve, reject) => setTimeout(resolve(name), 1000))
})
}
`
component.tsx
`tsx
import useApi from './api.ts'const Button = () => {
const [mutate, { isLoading, error, reset }] = useApi()
return (
<>
{isLoading.toString()}
{error?.toString() ?? "null"}
>
)
}
`Optimistic Updates
`ts
export default () => {
return useMutation(({ name }) => {
return new Promise((resolve, reject) => setTimeout(resolve(name), 1000))
}, {
onMutate: (variables) => {
const { name } = variables
// Update cache
}
})
}
`Guides
Use with Typescript
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
Chaining mutations
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:
`tsx
const Button = () => {
const [mutate] = useMutation(({ name }) => {
return Promise.resolve(Hello ${name}!)
})
const [mutate2] = useMutation(({ name }) => {
return Promise.resolve(Hello, my name is ${name}!)
}) return (
)
}
`
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.
Async / Await
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
`ts
export default () => {
return useMutation(({ name }) => {
return new Promise((resolve, reject) => setTimeout(resolve(name), 1000))
})
}
`
component.tsx
`tsx
import useApi from './api.ts'const Button = () => {
const [mutate, { isLoading, error, reset }] = useApi()
return (
<>
{isLoading.toString()}
{error?.toString() ?? "null"}
return res
}
)
}}>
Call Mutate
>
)
}
``Big thanks to react-query where a big part of our API is based from.