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 operation is memoized from its structural options. Current handlers and callbacks are retained through refs, and active work is aborted when the component unmounts.
useQuery
useQuery uses "latest" concurrency. Its optional initial function supplies initial data and is
called again to produce fallback data after an error.
useAction
useAction exposes error, loading, and trigger. The resolved value is returned by trigger
instead of being retained as component state.
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 |