async-resource

Create a scoped, abortable asynchronous resource with latest-result-wins state.


Package	`@vizejs/composable/async-resource`
Own the source	`vize lib pull composable:async-resource`
Runtime exports	`useAsyncResource`
Gzip budget	2048 B

Usage

import { useAsyncResource } from "@vizejs/composable/async-resource";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useAsyncResource`	async	experimental	safe	stable	caller, reactive-scope	web, server, worker, native, desktop, terminal	`AbortController`, `DOMException`	`tryOnScopeDispose`

API

`useAsyncResource`

Create a scoped, abortable asynchronous resource with latest-result-wins state. Every execution returns a discriminated result, so cancellation, supersession, loader failure, and successful undefined data stay distinct. When created inside an active reactive scope (and scope is enabled), the active execution is aborted when that scope stops; outside a scope, cancellation ownership stays with the caller. The execute promise never rejects — synchronous and asynchronous loader failures both settle into the "error" result. Safe during server rendering: no browser globals are read and abort reasons use the runtime-native DOMException.

function useAsyncResource<Data, Arguments extends readonly unknown[], Failure = unknown>( loader: (context: AsyncResourceContext, ...arguments_: Arguments) => Promise<Data>, options: UseAsyncResourceOptions<Data> = {}, ): AsyncResource<Data, Arguments, Failure>

Types

`AsyncResourceContext`

Context supplied to an asynchronous resource loader.

Member	Type	Description
`signal`	`AbortSignal`	Signal aborted by cancellation, reset, scope disposal, or a newer execution.

`UseAsyncResourceOptions`

Options for useAsyncResource.

Member	Type	Description
`initialData`?	`Data`	Initial data restored by `AsyncResource.reset`.
`cancelPrevious`?	`boolean`	Abort the active execution when a newer execution starts.
`keepData`?	`boolean`	Retain the current data while a new execution is pending.
`scope`?	`boolean`	Cancel an active execution when the current reactive scope is disposed.

`AsyncResource`

Reactive state and controls for an asynchronous loader.

Member	Type	Description
`data`	`Readonly<ShallowRef<Data \| undefined>>`	Data of the newest successful execution, retained according to `keepData`.
`error`	`Readonly<ShallowRef<Failure \| undefined>>`	Failure of the newest settled execution, cleared when a new one starts.
`status`	`Readonly<Ref<AsyncResourceStatus>>`	Current lifecycle status, driven only by the newest execution.
`pending`	`ComputedRef<boolean>`	Whether an execution is currently pending.
`execute`	`(...arguments_: Arguments) => Promise<AsyncResourceExecution<Data, Failure>>`	Run the loader. The returned promise never rejects: loader failures, cancellation, and supersession are reported as the discriminated result, and stale executions leave the reactive state untouched.
`cancel`	`(reason?: unknown) => boolean`	Abort the active execution and mark the resource cancelled.
`reset`	`() => void`	Cancel any active execution and restore the initial idle state.