React Async

React Async is a library providing React components and hooks for declarative promise resolution and data fetching. It allows you to handle every state of an asynchronous process (loading, error, success) without making assumptions about your data shape or request type. It is compatible with fetch, Axios, GraphQL, and works in both React and React Native environments.

Key features include:

• Multiple patterns: Choose between Render Props, Context-based helper components, or the useAsync and useFetch hooks.
• Metadata: Provides convenient properties like isPending, startedAt, and finishedAt.
• Actions: Provides cancel and reload actions.
• Lifecycle hooks: Supports onResolve, onReject, and onCancel callbacks.
• Advanced capabilities: Supports abortable fetch (via AbortController), optimistic updates (via setData), and server-side rendering (via initialValue).
• Automation: Automatic re-run using watch or watchFn props.
• Experimental Support: Includes experimental Suspense support.

While promiseFn is used for automatic data fetching on render, deferFn is used for asynchronous actions that must be triggered manually (e.g., submitting a form).

To use deferFn:

1. Define a function that returns a Promise. This function receives three arguments: args (an array of arguments passed to run), props, and signal (an AbortSignal).
2. Pass this function to the deferFn option in useAsync.
3. Call the run function returned by useAsync to trigger the action. You can pass any number of arguments to run, which will appear in the args array inside your deferFn.

This pattern is ideal for POST requests, deletions, or any action that should not happen automatically when a component mounts.

import React, { useState } from "react"
import { useAsync } from "react-async"

// The deferFn receives (args, props, { signal })
const subscribe = ([email], props, { signal }) =>
  fetch("/newsletter", { method: "POST", body: JSON.stringify({ email }), signal })

const NewsletterForm = () => {
  // deferFn is NOT automatically invoked on render
  const { isPending, error, run } = useAsync({ deferFn: subscribe })
  const [email, setEmail] = useState("")

  const handleSubmit = event => {
    event.preventDefault()
    // Triggering the action manually with run()
    run(email)
  }

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" value={email} onChange={event => setEmail(event.target.value)} />
      <button type="submit" disabled={isPending}>
        Subscribe
      </button>
      {error && <p>{error.message}</p>}
    </form>
  )
}

React Async provides helper components to improve the readability of render functions by handling conditional rendering based on the async state.

Using with useAsync hook

When using the useAsync hook, you must pass the returned state object to the helper components.

Using as compounds to <Async>

When used inside an <Async> component, these helpers act as compound components. They automatically access the state via React Context, so you do not need to pass the state prop manually.

Available Helpers:

• IfPending / Async.Pending: Renders when the operation is in progress.
• IfFulfilled / Async.Fulfilled: Renders when the operation succeeds (provides data to children).
• IfRejected / Async.Rejected: Renders when the operation fails (provides error to children).

// Pattern 1: With useAsync hook
import { useAsync, IfPending, IfFulfilled, IfRejected } from "react-async"

const MyComponent = () => {
  const state = useAsync({ promiseFn: loadPlayer, playerId: 1 })
  return (
    <>
      <IfPending state={state}>Loading...</IfPending>
      <IfRejected state={state}>{error => `Something went wrong: ${error.message}`}</IfRejected>
      <IfFulfilled state={state}>
        {data => (
          <div>
            <strong>Player data:</strong>
            <pre>{JSON.stringify(data, null, 2)}</pre>
          </div>
        )}
      </IfFulfilled>
    </>
  )
}

// Pattern 2: As compounds to <Async>
import Async from "react-async"

const MyComponent = () => (
  <Async promiseFn={loadPlayer} playerId={1}>
    <Async.Pending>Loading...</Async.Pending>
    <Async.Fulfilled>
      {data => (
        <div>
          <strong>Player data:</strong>
          <pre>{JSON.stringify(data, null, 2)}</pre>
        </div>
      )}
    </Async.Fulfilled>
    <Async.Rejected>{error => `Something went wrong: ${error.message}`}</Async.Rejected>
  </Async>
)

To keep components clean, you can separate logic from presentation by creating 'logic-only' components. These components use the useAsync hook to manage async state but do not render UI themselves. Instead, they use the [render props] pattern to pass the async state (including isPending, data, and error) down to a child function that handles the actual rendering.

This approach is useful for creating reusable logic wrappers that can be used across different parts of your application with different UI implementations.

import React from "react"
import { useAsync } from "react-async"

const fetchPerson = async ({ id }, { signal }) => {
  const response = await fetch(`https://swapi.co/api/people/${id}/`, { signal })
  if (!response.ok) throw new Error(response.statusText)
  return response.json()
}

const Person = ({ id }) => {
  const state = useAsync({ promiseFn: fetchPerson, id })
  return children(state)
}

const App = () => {
  return (
    <Person id={1}>
      {({ isPending, data, error }) => {
        if (isPending) return "Loading..."
        if (error) return <ErrorMessage {...error} />
        if (data) return <Greeting {...data} />
        return null
      }}
    </Person>
  )
}