Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/charlesstover/use-async-function
A React hook for integrating asynchronous function state into React function component state.
https://github.com/charlesstover/use-async-function
javascript js npm npm-module npm-package npmjs react react-hook react-hooks reactjs ts typescript
Last synced: about 1 month ago
JSON representation
A React hook for integrating asynchronous function state into React function component state.
- Host: GitHub
- URL: https://github.com/charlesstover/use-async-function
- Owner: CharlesStover
- License: mit
- Archived: true
- Created: 2019-09-15T05:18:45.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2020-12-12T18:46:08.000Z (almost 4 years ago)
- Last Synced: 2024-09-28T15:20:11.784Z (about 1 month ago)
- Topics: javascript, js, npm, npm-module, npm-package, npmjs, react, react-hook, react-hooks, reactjs, ts, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/use-async-function
- Size: 1.01 MB
- Stars: 15
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# useAsyncFunction [](https://twitter.com/intent/tweet?text=useAsyncFunction%20integrates%20your%20asynchronous%20function%20state%20with%20a%20React%20component's%20local%20state.&url=https://github.com/CharlesStover/use-async-function&via=CharlesStover&hashtags=react,reactjs,javascript,typescript,webdev,webdevelopment) [](https://www.npmjs.com/package/use-async-function) [](https://www.npmjs.com/package/use-async-function) [](https://www.npmjs.com/package/use-async-function) [](https://travis-ci.com/CharlesStover/use-async-function/)
`useAsyncFunction` is a React hook that integrates an asynchronous function's
state with a React function component's state. This automates the process of
re-rendering the React function component as the asynchronous function's state
changes between pending, resolved, and rejected.
## Install
- `npm i use-async-function` or
- `yarn add use-async-function`
## Use
```javascript
import useAsyncFunction, { State } from 'use-async-function';
const myAsyncFunction = async (): Promise => {
await one();
await two();
return 'three';
};
function MyComponent() {
const dispatch = useAsyncFunction(myAsyncFunction);
if (!dispatch.state) {
dispatch();
}
if (dispatch.state === State.Fulfilled) {
return
The response was {dispatch.value}.;
}
if (dispatch.state === State.Rejected) {
return
An error occurred: {dispatch.error};
}
// Pending and uninitiated.
return ;
}
```
## Parameters
### useAsyncFunction(Function)
The first parameter of the `useAsyncFunction` hook is the asynchronous function
itself.
### useAsyncFunction(Function, Options)
If you are not using an [identity reducer](#identity-reducer), the second
parameter of the `useAsyncFunction` hook is the [options](#options) object.
### useAsyncFunction(Function, Reducer)
If you are using an [identity reducer](#identity-reducer), the second parameter
of the `useAsyncFunction` hook is the identity reducer.
### useAsyncFunction(Function, Reducer, Options)
If you are using both an [identity reducer](#identity-reducer) and an
[options](#options) object, the identity reducer is the second parameter of the
`useAsyncFunction` hook, and the options object is the third parameter of the
`useAsyncFunction` hook.
## Identity Reducer
An identity reducer allows you to track multiple calls to the same asynchronous
function. This is particularly useful when tracking API calls, where each call's
fulfillment, pending, and rejection states are unique.
An identity reducer takes the call's arguments as its arguments and returns a
string unique to that call.
```javascript
// Asynchronously fetch a user's data by their username.
function fetchUser({ username }) {
return fetch(`/users/${username}`);
}
// Uniquely identify an asynchronous function call by the username.
function idByUsername({ username }) {
return username;
}
function MyComponent() {
const dispatch = useAsyncFunction(fetchUser, idByUsername);
// We can determine if this call has been made by the presence of a property
// with the call's ID.
if (!dispatch.admin) {
dispatch({ username: 'admin' });
return null;
}
if (!dispatch.bob) {
dispatch({ username: 'bob' });
return null;
}
// The state of the call is stored on the property with the call's ID.
if (dispatch.admin.state === State.Fulfilled) {
return
Admin loaded with {dispatch.admin.value}.;
}
}
```
## Options
### throwError
**Default:** `false`
**Type:** `boolean`
If `true`, the asynchronous function will throw any encountered errors,
requiring a `.catch` block.
If `false`, the asynchronous function will swallow any errors. The component
will rerender, and the `error` property of the async function will be set to the
caught error.
## Sponsor 💗
If you are a fan of this project, you may
[become a sponsor](https://github.com/sponsors/CharlesStover)
via GitHub's Sponsors Program.