use-async-function v1.0.3
useAsyncFunction
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
oryarn add use-async-function
Use
import useAsyncFunction, { State } from 'use-async-function';
const myAsyncFunction = async (): Promise<void> => {
await one();
await two();
return 'three';
};
function MyComponent() {
const dispatch = useAsyncFunction(myAsyncFunction);
if (!dispatch.state) {
dispatch();
}
if (dispatch.state === State.Fulfilled) {
return <div>The response was {dispatch.value}.</div>;
}
if (dispatch.state === State.Rejected) {
return <div>An error occurred: {dispatch.error}</div>;
}
// Pending and uninitiated.
return <Loading />;
}
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, the second
parameter of the useAsyncFunction
hook is the options object.
useAsyncFunction(Function, Reducer)
If you are using an 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 and an
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.
// 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 <div>Admin loaded with {dispatch.admin.value}.</div>;
}
}
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 via GitHub's Sponsors Program.