@hyperfrontend/state-machine/async-operation

async-operation

State-tracking wrapper for a single asynchronous process.

AsyncOperation is the runtime object that owns the state of one async process: not-started, in-progress, paused, done, failed, retrying, etc. It dispatches the actions in /actions against the reducer and exposes selectors so consumers can query the process state without importing the reducer directly. AsyncProcess is the data shape held inside the operation, useful when the operation is composed into larger structures or persisted. Reach for the higher-level /coordinated-async-operation when several related async processes need to be orchestrated together.

API Reference§

◇ Classes

§class

AsyncOperation

Manages the lifecycle of an asynchronous operation with start, cancel, and pause capabilities.

Constructor

§new AsyncOperation(process: AsyncProcess)

Wraps a process so its progress can be observed as state-machine events.
Nothing runs until start is called.

Parameters

Name	Type	Description
§process	`AsyncProcess`	The asynchronous work to manage; its returned promise decides success or failure

Methods

§readonly cancel(): void

Dispatches the cancel action, which leaves the state halted and no longer in progress.
The promise returned by the process is not interrupted: the work keeps running, and whatever it settles with is still dispatched afterwards. Cancellation is a state the operation's observers see, not a signal the process receives.

§readonly on(event: Event, handler: (event: Event, current: DerivedState, previous: DerivedState) => void): void

Registers a handler for one of the operation's lifecycle events.

Parameters

Name	Type	Description
§event	`Event`	Which state transition to listen for, one of the `event` constants
§handler	`(event: Event, current: DerivedState, previous: DerivedState) => void`	Called with the event name, the state after the transition and the state before it

§readonly pause(): void

Dispatches the pause action, which marks the state halted while still in progress.
As with cancel, the process itself is not suspended; only the observable state changes.

§readonly start(): Promise<void>

Runs the process once, dispatching the start action before it and success or fail after.
A rejection is caught and reported as a failure carrying the thrown value, so the returned promise never rejects. Calling start again runs the process again, and the events describe the rerun as a retry or a restart depending on how the previous run ended.

Returns

Promise<void>

Resolves once the process has settled and its outcome has been dispatched

Example

Starting an async operation

const operation = new AsyncOperation(async () => {
  await fetchData()
})
operation.start()

View source →

◆ Types

§type

AsyncProcess

Async process function type that returns a Promise.

type AsyncProcess = () => Promise<void>

View source →