react-use-async-action

A production-grade React hook for async actions with strong TypeScript inference, predictable state transitions, lifecycle-safe updates, and latest-call-wins behavior.

Features

• Typed execute(...args) API inferred from your async function
• idle, loading, success, and error status tracking
• reset() support for returning to the initial state
• Optional onSuccess, onError, and onSettled callbacks
• Optional immediate execution with initialArgs
• Protection against stale in-flight requests overwriting newer results
• Safe state updates when components unmount

Installation

npm install react-use-async-action

Usage

import { useAsyncAction } from "react-use-async-action";

async function fetchUser(id: number) {
  const response = await fetch(`/api/users/${id}`);

  if (!response.ok) {
    throw new Error("Failed to fetch user");
  }

  return response.json() as Promise<{ id: number; name: string }>;
}

export function UserButton() {
  const { execute, data, error, isLoading, reset, status } = useAsyncAction(
    fetchUser,
    {
      onError: (caughtError) => {
        console.error(caughtError);
      }
    }
  );

  return (
    <div>
      <button disabled={isLoading} onClick={() => void execute(1)}>
        {isLoading ? "Loading..." : "Load user"}
      </button>
      <button onClick={reset}>Reset</button>
      <p>Status: {status}</p>
      {error ? <p>Something went wrong.</p> : null}
      {data ? <p>{data.name}</p> : null}
    </div>
  );
}

API

useAsyncAction(asyncFunction, options?)

Returns:

• execute: Runs the async action and returns its result
• data: The latest successful result
• error: The latest thrown error
• status: One of idle, loading, success, or error
• isIdle, isLoading, isSuccess, hasError, hasLoaded
• reset: Resets the hook back to its initial state

Options:

• initialData: Seed state before the first execution
• immediate: Run automatically on mount
• initialArgs: Arguments used when immediate is enabled
• onSuccess: Called after a successful execution
• onError: Called after a failed execution
• onSettled: Called after either success or failure

Development

npm install
npm run typecheck
npm test
npm run build