A React hook for gracefully resolving, cancelling, and handling errors for async functions
and promises. These hooks also clean up any lingering promises when your component unmounts
by cancelling them.
## Quick Start
[Check out the example on CodeSandbox](https://codesandbox.io/s/react-hookasync-example-kdghe)
```jsx harmony
import {useAsync, useAsyncEffect} from '@react-hook/async'
// Example using a manual invocation
const CallbackResolver = () => {
const [{status, cancel, error, value}, call] = useAsync(() => {
return new Promise((resolve) => setTimeout(() => resolve('Loaded'), 3000))
})
switch (status) {
case 'loading':
return (
Loading...
)
case 'cancelled':
return (
Cancelled.
)
case 'error':
return `Error: ${error}`
case 'success':
return value || 'Success!'
default:
return
}
}
// Example using a useEffect invocation
const EffectResolver = () => {
const [curr, setCurr] = useState(0)
// Will load each time counter changes
const {status, cancel, error, value} = useAsyncEffect(() => {
return new Promise((resolve) =>
setTimeout(() => resolve(`Loaded ${curr}`), 3000)
)
}, [curr])
switch (status) {
case 'loading':
return (
Loading...
)
case 'cancelled':
return (
Cancelled.
)
case 'error':
return `Error: ${error}`
case 'success':
return (
{value}
)
default:
return null
}
}
```
## API
### useAsync(asyncCallback)
```ts
export const useAsync = <
ValueType extends any = any,
ErrorType extends any = Error,
Args extends any[] = any[]
>(
asyncCallback: (...args: Args) => Promise
): [AsyncState, AsyncCallback]
```
#### Arguments
| Argument | Type | Default | Required? | Description |
| ------------- | --------------------------------------- | ----------- | --------- | ----------------------------------------------------- |
| asyncCallback | `(...args: Args) => Promise` | `undefined` | Yes | An async function or function that returns a promise. |
#### Returns [[`AsyncState`](#asyncstate), [`AsyncCallback`](#asynccallback)]
---
### AsyncState
```ts
export interface AsyncState {
// 'idle' | 'loading' | 'success' | 'error' | 'cancelled'
status: AsyncStatus
// The return value of your async callback or promise. This value is persisted until there
// is another successful promise resolution. That means you when you're in an 'error', 'loading',
// or 'cancelled' state, you'll still have the most recent successful value here. This is useful
// because the status property should be dictating what you're doing in your UI and there are
// cases where you won't want to lose the current value.
value?: ValueType
// The error object from any exceptions encountered inside the async function
// or the value of the promise rejection.
error?: ErrorType
// Cancels the promise
cancel: () => void
}
```
### AsyncCallback
```ts
export interface AsyncCallback {
(...args: Args): void
cancel: () => void
}
```
---
### useAsyncEffect(asyncCallback, dependencies)
```ts
export const useAsyncEffect = <
ValueType extends any = any,
ErrorType extends any = Error
>(
asyncCallback: () => Promise,
dependencies?: React.DependencyList
): AsyncState
```
This hook will invoke a callback each time its dependencies array changes.
#### Arguments
| Argument | Type | Default | Required? | Description |
| ------------- | -------------------------- | ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- |
| asyncCallback | `() => Promise` | `undefined` | Yes | An async function or function that returns a promise. |
| dependencies | `any[]` | `undefined` | No | Values or state that your callback depends on. This works the same as the dependencies array of `useEffect`, `useCallback`, etc. |
#### Returns [`AsyncState`](#asyncstate)
## LICENSE
MIT
