Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/statelyai/xstate/llms.txt

Use this file to discover all available pages before exploring further.

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.

Build docs developers (and LLMs) love

Get started for freeTalk to us