use-async-state

Reactive state for an async producer.


Package	`@vizejs/composable/use-async-state`
Own the source	`vize lib pull composable:use-async-state`
Runtime exports	`useAsyncState`
Gzip budget	768 B

Usage

import { useAsyncState } from "@vizejs/composable/use-async-state";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useAsyncState`	async	experimental	safe	stable	none	web, server, worker, native, desktop, terminal	—	—

API

`useAsyncState`

Reactive state for an async producer. Tracks the result, loading, readiness, and error of the newest execution; out-of-order completions of older executions are ignored, so the state always reflects the latest request. The typing is arity-aware: producers with parameters require { immediate: false } and execute keeps their parameter tuple. On the server an immediate execution starts but is not awaited, so both sides render the initial state with isLoading: true.

function useAsyncState<Data, Initial>( producer: () => Promise<Data>, initial: Initial, options?: UseAsyncStateOptions<Data>, ): AsyncState<Data, Initial, []>

const { state, isLoading, execute } = useAsyncState((id: string) => fetchUser(id), null, {
  immediate: false,
});
await execute("u-1");

`useAsyncState`

function useAsyncState<Data, Initial, Parameters extends readonly unknown[]>( producer: (...args: Parameters) => Promise<Data>, initial: Initial, options: UseAsyncStateOptions<Data> & { readonly immediate: false }, ): AsyncState<Data, Initial, Parameters>

`useAsyncState`

function useAsyncState( producer: (...args: readonly unknown[]) => Promise<unknown>, initial: unknown, options: UseAsyncStateOptions<unknown> = {}, ): AsyncState<unknown, unknown, readonly unknown[]>

Types

`UseAsyncStateOptions`

Options for useAsyncState.

Member	Type	Description
`immediate`?	`boolean`	Execute once right away. Only available for producers without parameters; pass `false` to run a producer that takes arguments through `AsyncState.execute`.
`resetOnExecute`?	`boolean`	Restore the initial state at the start of every execution.
`throwError`?	`boolean`	Re-throw failures from `execute` in addition to storing them.
`onError`?	`(error: unknown) => void`	Called with every failure of the newest execution.
`onSuccess`?	`(data: Data) => void`	Called with every successful result of the newest execution.

`AsyncState`

Reactive state and controls returned by useAsyncState.

Member	Type	Description
`state`	`Readonly<ShallowRef<Data \| Initial>>`	Newest result, or the initial state.
`isReady`	`Readonly<ShallowRef<boolean>>`	Whether at least one execution succeeded.
`isLoading`	`Readonly<ShallowRef<boolean>>`	Whether an execution is in flight.
`error`	`Readonly<ShallowRef<unknown>>`	Failure of the newest execution, cleared when a new one starts.
`execute`	`(...args: Parameters) => Promise<Data \| Initial>`	Run the producer. Only the newest execution may update the state.