State Utilities

Internal utilities for working with state nodes and transitions

The stateUtils module contains a collection of internal utility functions used by XState for managing state nodes, transitions, and state values. These utilities are primarily used internally by the XState library.

State Node Utilities

getStateNodes

Returns the state nodes represented by the current state value.

function getStateNodes(
  stateNode: AnyStateNode,
  stateValue: StateValue
): Array<AnyStateNode>

stateNode · AnyStateNode · required

The parent state node to search within.

stateValue · StateValue · required

The state value (string or object) representing the current state.

returns · Array<AnyStateNode>

An array of state nodes that correspond to the given state value.

getStateNodeByPath

Returns the relative state node from the given statePath, or throws an error if not found.

function getStateNodeByPath(
  stateNode: AnyStateNode,
  statePath: string | string[]
): AnyStateNode

stateNode · AnyStateNode · required

The starting state node.

statePath · string | string[] · required

The string or string array relative path to the target state node. Can use state IDs (strings starting with #).

returns · AnyStateNode

The state node at the specified path.

getStateValue

Computes the state value from a root node and a collection of state nodes.

function getStateValue(
  rootNode: AnyStateNode,
  stateNodes: Iterable<AnyStateNode>
): StateValue

rootNode · AnyStateNode · required

The root state node of the machine.

stateNodes · Iterable<AnyStateNode> · required

The collection of active state nodes.

returns · StateValue

The computed state value (string for atomic states, object for compound/parallel states).

resolveStateValue

Resolves a partial state value with its full representation in the state node’s machine.

function resolveStateValue(
  rootNode: AnyStateNode,
  stateValue: StateValue
): StateValue

rootNode · AnyStateNode · required

The root state node of the machine.

stateValue · StateValue · required

The partial state value to resolve.

returns · StateValue

The fully resolved state value.

Transition Utilities

formatTransition

Formats a transition config into a complete transition definition.

function formatTransition(
  stateNode: AnyStateNode,
  descriptor: string,
  transitionConfig: AnyTransitionConfig
): AnyTransitionDefinition

stateNode · AnyStateNode · required

The source state node.

descriptor · string · required

The event descriptor for this transition.

transitionConfig · AnyTransitionConfig · required

The raw transition configuration.

returns · AnyTransitionDefinition

A fully formatted transition definition with resolved targets and guards.

transitionNode

Determines the enabled transitions for a state node given a state value and event.

function transitionNode<TContext extends MachineContext, TEvent extends EventObject>(
  stateNode: AnyStateNode,
  stateValue: StateValue,
  snapshot: MachineSnapshot<TContext, TEvent, ...>,
  event: TEvent
): Array<TransitionDefinition<TContext, TEvent>> | undefined

stateNode · AnyStateNode · required

The state node to get transitions from.

stateValue · StateValue · required

The current state value.

snapshot · MachineSnapshot · required

The current machine snapshot.

event · EventObject · required

The event that may trigger transitions.

returns · Array<TransitionDefinition> | undefined

An array of enabled transitions, or undefined if no transitions are enabled.

getCandidates

Returns candidate transitions for a given event type on a state node.

function getCandidates<TEvent extends EventObject>(
  stateNode: StateNode<any, TEvent>,
  receivedEventType: TEvent['type']
): Array<TransitionDefinition<any, TEvent>>

stateNode · StateNode · required

The state node to get candidates from.

receivedEventType · string · required

The type of the received event.

returns · Array<TransitionDefinition>

An array of candidate transitions that match the event type.

State Checking Utilities

isInFinalState

Checks if a state node is in a final state.

function isInFinalState(
  stateNodeSet: Set<AnyStateNode>,
  stateNode: AnyStateNode
): boolean

stateNodeSet · Set<AnyStateNode> · required

The set of currently active state nodes.

stateNode · AnyStateNode · required

The state node to check.

returns · boolean

true if the state node is in a final state:

• For compound states: if a direct child final state is active
• For parallel states: if all child regions are in final states
• For atomic states: if the state itself is a final state

isAtomicStateNode

Checks if a state node is atomic (has no child states).

function isAtomicStateNode(stateNode: StateNode<any, any>): boolean

stateNode · StateNode · required

The state node to check.

returns · boolean

true if the state node type is 'atomic' or 'final'.

getProperAncestors

Returns all proper ancestors of a state node up to (but not including) a target ancestor.

function getProperAncestors(
  stateNode: AnyStateNode,
  toStateNode: AnyStateNode | undefined
): Array<AnyStateNode>

stateNode · AnyStateNode · required

The starting state node.

toStateNode · AnyStateNode | undefined · required

The ancestor to stop at (not included in results). If undefined, returns all ancestors.

returns · Array<AnyStateNode>

An array of ancestor state nodes, from immediate parent to the generation before toStateNode.

Transition Processing

macrostep

Performs a macrostep, which processes an event and executes all resulting microsteps until a stable state is reached.

function macrostep(
  snapshot: AnyMachineSnapshot,
  event: EventObject,
  actorScope: AnyActorScope,
  internalQueue: AnyEventObject[]
): {
  snapshot: AnyMachineSnapshot;
  microsteps: Microstep[];
}

snapshot · AnyMachineSnapshot · required

The current machine snapshot.

event · EventObject · required

The event to process.

actorScope · AnyActorScope · required

The actor scope containing execution context.

internalQueue · AnyEventObject[] · required

Queue for internally raised events.

returns · { snapshot: AnyMachineSnapshot; microsteps: Microstep[] }

An object containing the resulting snapshot and an array of microsteps that were executed.

Notes

These utilities are primarily intended for internal use by XState. The APIs may change between minor versions. Use the public XState APIs when possible.

Many of these utilities are used during state machine initialization and transition processing. They implement core algorithms from the SCXML specification.

If you need to work with state nodes or analyze machine structure, consider using the public inspection APIs like machine.transition() or the @xstate/inspect package.