React API
Hooks exported by @omni-async/react.
useAction(handler, options?)
Creates an on-demand async action without retaining its resolved value.
Example:
const removeUser = useAction((id: string) => api.deleteUser(id));
await removeUser.trigger("42");
useAsync(handler, options)
Creates reactive state for an async handler with configurable concurrency and fallback data.
Example:
const save = useAsync((name: string) => api.saveProfile({ name }));
await save.trigger("Ada");
useFetch(handler, options?)
Runs an abortable fetch on mount and exposes controls for refetching or cancellation.
Example:
const profile = useFetch((signal) => fetchProfile({ signal }));
await profile.fetch();
useQuery(handler, options)
Creates a latest-request-wins query for data that may be refreshed on demand.
Example:
const users = useQuery(() => api.listUsers(), { initial: () => [] });
await users.trigger();
Shared result state
| Field | Type | Description |
|---|---|---|
data | Data | null | undefined | Most recently accepted data |
error | unknown | null | Most recently accepted error |
loading | boolean | Whether an accepted request is still running |
trigger | (...params: Params) => Promise<Data> | Starts the handler with typed parameters |
useAsync options
| Option | Default | Description |
|---|---|---|
initialData | null | Initial data and the value restored by the operation |
concurrency | "all" | Use "latest" to prevent older requests updating state |
dataOnError | Preserve | Produces replacement data after a rejected request |
isEqual | Fields | Suppresses updates when the previous and next states are equal |
onSuccess | — | Runs after an accepted successful update |
onError | — | Runs after an accepted error update |
The hook stores state in React. Current handlers and callbacks are retained through refs, and active work is invalidated when the component unmounts.
useQuery
useQuery uses "latest" concurrency. Its optional initial function supplies initial data. A
rejected request preserves the latest data and updates error.
useAction
useAction exposes error, loading, and trigger. The resolved value is returned by trigger
instead of being retained as component state.
useAction is an imperative async helper. It is separate from React 19's useActionState, which
manages previous state, queued actions, and form submissions. In an app whose framework supports
Server Functions, useAction can call an imported Server Function after hydration. Use React's
useActionState for form state or submissions that must work before hydration.
useFetch
useFetch calls fetch() on mount. Starting another fetch aborts the previous controller.
| Control | Description |
|---|---|
fetch() | Starts a request and returns its promise |
abort() | Aborts the current request, when one exists |