Stately

Utilities

Work with actors, snapshots and state values.

XState v6 is in beta

APIs and behavior may change before the stable release. Read the stable v5 docs.
UtilityPurpose
waitFor(actor, predicate)Wait for a matching snapshot.
toPromise(actor)Resolve with an actor's output.
initialTransition(logic, input?)Get [snapshot, actions] for the initial transition without starting an actor.
transition(logic, snapshot, event)Calculate [nextSnapshot, actions] for an event.
initialSystemTransition(systemLogic, options?)Initialize a pure system snapshot; experimental.
systemTransition(systemLogic, snapshot, actorPath, event)Settle macrosteps and messages in a system snapshot; experimental.
advanceSystemTime(systemLogic, snapshot, { time })Process system timers through an absolute deadline; experimental.
mapState(...)Map one state value to another value.
SimulatedClockControl time in tests.
const finalSnapshot = await waitFor(actor, (snapshot) =>
  snapshot.matches('complete')
);

Use initialTransition(...) and transition(...) for pure calculations. They do not start actors or run effects; the returned actions describe the effects that an actor would execute. Use SimulatedClock to test delays without waiting for real time.

For pure calculations across children, messages and timers, use the experimental system transition APIs. Each returns [snapshot, externalEffects] and completes macrosteps without running external effects.

For example, a route loader can calculate an initial view without starting a long-lived actor. A timeout test can advance a simulated clock to the retry state.

Utilities cheatsheet

await waitFor(actor, predicate);
await toPromise(actor);
const [initialSnapshot, initialActions] = initialTransition(logic, input);
const [nextSnapshot, actions] = transition(logic, snapshot, event);

On this page