use-async-machine

A hook for using an async state machine. The state machine this library implements looks like this (image generated with XState Visualizer):

Usage

This library exports a single hook to help you with asynchronous operations in your UI.

``jsx
import React from 'react'
import useAsync from 'use-async-machine'

function someAsyncTask() {
// Returns a promise
}

export default function App() {
const { data, error, isLoading, isError, dispatch } = useAsync(() => someAsyncTask())

React.useEffect(() => {
dispatch({ type: 'load' })
}, []) // 'dispatch' does not need to be included in dependency array

if (isLoading) {
return
}

if (isError) {
return
}

return


}
`

Use Cases

This library was created out of a need to generate and render a PDF document in the browser. useAsync is most useful for client-only asynchronous tasks such as this. If you need to interact with remote data sources, I recommend you try a data caching library such as react-query or use an SSR framework such as Remix.

API Reference

`javascript
const {
state,
data,
error,
context,
isIdle,
isLoading,
isError,
isSuccess,
dispatch,
} = useAsync(fn, {
onLoad,
onSuccess,
onError,
});
`

Options

- fn: (state: UseAsyncState) => Promise
- The asynchronous function to run on the load event.
- Receives the async state.
- Must return a promise that either resolves to data or throws an error.
- onLoad: (state: UseAsyncState) => unknown
- Function to be called when the state machine enters the loading state.
- Receives the async state
- Returns nothing
- onSuccess: (state: UseAsyncState) => unknown
- Function to be called when the state machine enters the success state.
- Receives the async state
- Returns nothing
- onError: (state: UseAsyncState) => unknown
- Function to be called when the state machine enters the error state.
- Receives the async state
- Returns nothing

Returns

- state: "idle" | "loading" | "success" | "error"
- Defaults to "idle"
- The state of the async function.
- data: TData
- Defaults to undefined
- The resolved data returned by fn
- error: TError
- Defaults to undefined
- If fn rejects with an error, it will be stored here
- context: TContext
- Defaults to undefined
- May be set by the "load" event with dispatch({ "type": "load", context })
- Useful if you want to pass additional context to fn
- isIdle: boolean
- Derived from state, true if and only if state === "idle"
- isLoading: boolean
- Derived from state, true if and only if state === "loading"
- isError: boolean
- Derived from state, true if and only if state === "error"
- isSuccess: boolean
- Derived from state, true if and only if state === "success"
- dispatch: React.Dispatch>
- Dispatch function returned from React.useReducer`
- Used to transition between async states.