xstate 5.25.1 → 5.27.0

package/dist/xstate.cjs.js

@@ -3,10 +3,10 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var actors_dist_xstateActors = require('../actors/dist/xstate-actors.cjs.js');
-var guards_dist_xstateGuards = require('./raise-577e4163.cjs.js');
-var StateMachine = require('./StateMachine-fee05db8.cjs.js');
-var assign = require('./assign-592716a8.cjs.js');
-var log = require('./log-9c9f917d.cjs.js');
+var guards_dist_xstateGuards = require('./raise-3a84be1f.cjs.js');
+var StateMachine = require('./StateMachine-e93afc18.cjs.js');
+var assign = require('./assign-e36553db.cjs.js');
+var log = require('./log-e54c2eff.cjs.js');
 require('../dev/dist/xstate-dev.cjs.js');
 
 /**
@@ -338,6 +338,95 @@ function initialTransition(logic, ...[input]) {
   return [nextSnapshot, executableActions];
 }
 
+/**
+ * Given a state `machine`, a `snapshot`, and an `event`, returns an array of
+ * microsteps, where each microstep is a tuple of `[snapshot, actions]`.
+ *
+ * This is a pure function that does not execute `actions`.
+ */
+function getMicrosteps(machine, snapshot, event) {
+  const actorScope = createInertActorScope(machine);
+  const {
+    microsteps
+  } = guards_dist_xstateGuards.macrostep(snapshot, event, actorScope, []);
+  return microsteps;
+}
+
+/**
+ * Given a state `machine` and optional `input`, returns an array of microsteps
+ * from the initial transition, where each microstep is a tuple of `[snapshot,
+ * actions]`.
+ *
+ * This is a pure function that does not execute `actions`.
+ */
+function getInitialMicrosteps(machine, ...[input]) {
+  const actorScope = createInertActorScope(machine);
+  const initEvent = guards_dist_xstateGuards.createInitEvent(input);
+  const internalQueue = [];
+  const preInitialSnapshot = machine._getPreInitialState(actorScope, initEvent, internalQueue);
+  const first = guards_dist_xstateGuards.initialMicrostep(machine.root, preInitialSnapshot, actorScope, initEvent, internalQueue);
+  const {
+    microsteps
+  } = guards_dist_xstateGuards.macrostep(first[0], initEvent, actorScope, internalQueue);
+  return [first, ...microsteps];
+}
+
+/**
+ * Gets all potential next transitions from the current state.
+ *
+ * Returns all transitions that are available from the current state, including:
+ *
+ * - All transitions from atomic states (leaf states in the current state
+ *   configuration)
+ * - All transitions from ancestor states (parent states that may handle events)
+ * - All guarded transitions (regardless of whether their guards would pass)
+ * - Always (eventless) transitions
+ * - After (delayed) transitions
+ *
+ * The order of transitions is deterministic:
+ *
+ * 1. Atomic states are processed in document order
+ * 2. For each atomic state, transitions are collected from the state itself first,
+ *    then its ancestors
+ * 3. Within each state node, transitions are in the order they appear in the state
+ *    definition
+ *
+ * @param state - The current machine snapshot
+ * @returns Array of transition definitions from the current state, in
+ *   deterministic order
+ */
+function getNextTransitions(state) {
+  const potentialTransitions = [];
+  const atomicStates = state._nodes.filter(guards_dist_xstateGuards.isAtomicStateNode);
+  const visited = new Set();
+
+  // Collect all transitions from atomic states and their ancestors
+  // Process atomic states in document order (as they appear in state._nodes)
+  for (const stateNode of atomicStates) {
+    // For each atomic state, process the state itself first, then its ancestors
+    // This ensures child state transitions come before parent state transitions
+    for (const s of [stateNode].concat(guards_dist_xstateGuards.getProperAncestors(stateNode, undefined))) {
+      if (visited.has(s.id)) {
+        continue;
+      }
+      visited.add(s.id);
+
+      // Get all transitions for each event type
+      // Include ALL transitions, even if the same event type appears in multiple state nodes
+      // This is important for guarded transitions - all are "potential" regardless of guard evaluation
+      for (const [, transitions] of s.transitions) {
+        potentialTransitions.push(...transitions);
+      }
+
+      // Also include always (eventless) transitions
+      if (s.always) {
+        potentialTransitions.push(...s.always);
+      }
+    }
+  }
+  return potentialTransitions;
+}
+
 const defaultWaitForOptions = {
   timeout: Infinity // much more than 10 seconds
 };
@@ -476,8 +565,11 @@ exports.sendTo = log.sendTo;
 exports.SimulatedClock = SimulatedClock;
 exports.assertEvent = assertEvent;
 exports.createMachine = createMachine;
+exports.getInitialMicrosteps = getInitialMicrosteps;
 exports.getInitialSnapshot = getInitialSnapshot;
+exports.getMicrosteps = getMicrosteps;
 exports.getNextSnapshot = getNextSnapshot;
+exports.getNextTransitions = getNextTransitions;
 exports.initialTransition = initialTransition;
 exports.setup = setup;
 exports.toPromise = toPromise;

package/dist/xstate.cjs.mjs

@@ -20,8 +20,11 @@ export {
   fromObservable,
   fromPromise,
   fromTransition,
+  getInitialMicrosteps,
   getInitialSnapshot,
+  getMicrosteps,
   getNextSnapshot,
+  getNextTransitions,
   getStateNodes,
   initialTransition,
   interpret,

package/dist/xstate.development.cjs.js

@@ -3,10 +3,10 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var actors_dist_xstateActors = require('../actors/dist/xstate-actors.development.cjs.js');
-var guards_dist_xstateGuards = require('./raise-ed7c6f3d.development.cjs.js');
-var StateMachine = require('./StateMachine-6d24a98f.development.cjs.js');
-var assign = require('./assign-577bb842.development.cjs.js');
-var log = require('./log-3827c227.development.cjs.js');
+var guards_dist_xstateGuards = require('./raise-ecea0c53.development.cjs.js');
+var StateMachine = require('./StateMachine-c3376229.development.cjs.js');
+var assign = require('./assign-8ef0e332.development.cjs.js');
+var log = require('./log-72d5ee02.development.cjs.js');
 require('../dev/dist/xstate-dev.development.cjs.js');
 
 /**
@@ -338,6 +338,95 @@ function initialTransition(logic, ...[input]) {
   return [nextSnapshot, executableActions];
 }
 
+/**
+ * Given a state `machine`, a `snapshot`, and an `event`, returns an array of
+ * microsteps, where each microstep is a tuple of `[snapshot, actions]`.
+ *
+ * This is a pure function that does not execute `actions`.
+ */
+function getMicrosteps(machine, snapshot, event) {
+  const actorScope = createInertActorScope(machine);
+  const {
+    microsteps
+  } = guards_dist_xstateGuards.macrostep(snapshot, event, actorScope, []);
+  return microsteps;
+}
+
+/**
+ * Given a state `machine` and optional `input`, returns an array of microsteps
+ * from the initial transition, where each microstep is a tuple of `[snapshot,
+ * actions]`.
+ *
+ * This is a pure function that does not execute `actions`.
+ */
+function getInitialMicrosteps(machine, ...[input]) {
+  const actorScope = createInertActorScope(machine);
+  const initEvent = guards_dist_xstateGuards.createInitEvent(input);
+  const internalQueue = [];
+  const preInitialSnapshot = machine._getPreInitialState(actorScope, initEvent, internalQueue);
+  const first = guards_dist_xstateGuards.initialMicrostep(machine.root, preInitialSnapshot, actorScope, initEvent, internalQueue);
+  const {
+    microsteps
+  } = guards_dist_xstateGuards.macrostep(first[0], initEvent, actorScope, internalQueue);
+  return [first, ...microsteps];
+}
+
+/**
+ * Gets all potential next transitions from the current state.
+ *
+ * Returns all transitions that are available from the current state, including:
+ *
+ * - All transitions from atomic states (leaf states in the current state
+ *   configuration)
+ * - All transitions from ancestor states (parent states that may handle events)
+ * - All guarded transitions (regardless of whether their guards would pass)
+ * - Always (eventless) transitions
+ * - After (delayed) transitions
+ *
+ * The order of transitions is deterministic:
+ *
+ * 1. Atomic states are processed in document order
+ * 2. For each atomic state, transitions are collected from the state itself first,
+ *    then its ancestors
+ * 3. Within each state node, transitions are in the order they appear in the state
+ *    definition
+ *
+ * @param state - The current machine snapshot
+ * @returns Array of transition definitions from the current state, in
+ *   deterministic order
+ */
+function getNextTransitions(state) {
+  const potentialTransitions = [];
+  const atomicStates = state._nodes.filter(guards_dist_xstateGuards.isAtomicStateNode);
+  const visited = new Set();
+
+  // Collect all transitions from atomic states and their ancestors
+  // Process atomic states in document order (as they appear in state._nodes)
+  for (const stateNode of atomicStates) {
+    // For each atomic state, process the state itself first, then its ancestors
+    // This ensures child state transitions come before parent state transitions
+    for (const s of [stateNode].concat(guards_dist_xstateGuards.getProperAncestors(stateNode, undefined))) {
+      if (visited.has(s.id)) {
+        continue;
+      }
+      visited.add(s.id);
+
+      // Get all transitions for each event type
+      // Include ALL transitions, even if the same event type appears in multiple state nodes
+      // This is important for guarded transitions - all are "potential" regardless of guard evaluation
+      for (const [, transitions] of s.transitions) {
+        potentialTransitions.push(...transitions);
+      }
+
+      // Also include always (eventless) transitions
+      if (s.always) {
+        potentialTransitions.push(...s.always);
+      }
+    }
+  }
+  return potentialTransitions;
+}
+
 const defaultWaitForOptions = {
   timeout: Infinity // much more than 10 seconds
 };
@@ -479,8 +568,11 @@ exports.sendTo = log.sendTo;
 exports.SimulatedClock = SimulatedClock;
 exports.assertEvent = assertEvent;
 exports.createMachine = createMachine;
+exports.getInitialMicrosteps = getInitialMicrosteps;
 exports.getInitialSnapshot = getInitialSnapshot;
+exports.getMicrosteps = getMicrosteps;
 exports.getNextSnapshot = getNextSnapshot;
+exports.getNextTransitions = getNextTransitions;
 exports.initialTransition = initialTransition;
 exports.setup = setup;
 exports.toPromise = toPromise;

package/dist/xstate.development.cjs.mjs

@@ -20,8 +20,11 @@ export {
   fromObservable,
   fromPromise,
   fromTransition,
+  getInitialMicrosteps,
   getInitialSnapshot,
+  getMicrosteps,
   getNextSnapshot,
+  getNextTransitions,
   getStateNodes,
   initialTransition,
   interpret,

package/dist/xstate.development.esm.js

@@ -1,12 +1,12 @@
 export { createEmptyActor, fromCallback, fromEventObservable, fromObservable, fromPromise, fromTransition } from '../actors/dist/xstate-actors.development.esm.js';
-import { m as matchesEventDescriptor, t as toArray, c as createActor, r as raise, a as cancel, s as stopChild, b as spawnChild } from './raise-13a60c49.development.esm.js';
-export { A as Actor, h as __unsafe_getAllOwnEventDescriptors, d as and, a as cancel, c as createActor, g as getStateNodes, i as interpret, f as isMachineSnapshot, j as matchesState, n as not, o as or, p as pathToStateValue, r as raise, b as spawnChild, e as stateIn, l as stop, s as stopChild, k as toObserver } from './raise-13a60c49.development.esm.js';
-import { S as StateMachine } from './StateMachine-d0e98d09.development.esm.js';
-export { S as StateMachine, a as StateNode } from './StateMachine-d0e98d09.development.esm.js';
-import { a as assign } from './assign-541a432d.development.esm.js';
-export { a as assign } from './assign-541a432d.development.esm.js';
-import { s as sendTo, l as log, e as enqueueActions, a as emit } from './log-b8ca474e.development.esm.js';
-export { S as SpecialTargets, a as emit, e as enqueueActions, f as forwardTo, l as log, b as sendParent, s as sendTo } from './log-b8ca474e.development.esm.js';
+import { m as matchesEventDescriptor, t as toArray, c as createActor, r as raise, a as cancel, s as stopChild, b as spawnChild, d as macrostep, e as createInitEvent, i as initialMicrostep, f as isAtomicStateNode, g as getProperAncestors } from './raise-a7794093.development.esm.js';
+export { A as Actor, q as __unsafe_getAllOwnEventDescriptors, j as and, a as cancel, c as createActor, p as getStateNodes, h as interpret, l as isMachineSnapshot, u as matchesState, n as not, o as or, v as pathToStateValue, r as raise, b as spawnChild, k as stateIn, x as stop, s as stopChild, w as toObserver } from './raise-a7794093.development.esm.js';
+import { S as StateMachine } from './StateMachine-93271b59.development.esm.js';
+export { S as StateMachine, a as StateNode } from './StateMachine-93271b59.development.esm.js';
+import { a as assign } from './assign-d5291869.development.esm.js';
+export { a as assign } from './assign-d5291869.development.esm.js';
+import { s as sendTo, l as log, e as enqueueActions, a as emit } from './log-7dbbb7c2.development.esm.js';
+export { S as SpecialTargets, a as emit, e as enqueueActions, f as forwardTo, l as log, b as sendParent, s as sendTo } from './log-7dbbb7c2.development.esm.js';
 import '../dev/dist/xstate-dev.development.esm.js';
 
 /**
@@ -338,6 +338,95 @@ function initialTransition(logic, ...[input]) {
   return [nextSnapshot, executableActions];
 }
 
+/**
+ * Given a state `machine`, a `snapshot`, and an `event`, returns an array of
+ * microsteps, where each microstep is a tuple of `[snapshot, actions]`.
+ *
+ * This is a pure function that does not execute `actions`.
+ */
+function getMicrosteps(machine, snapshot, event) {
+  const actorScope = createInertActorScope(machine);
+  const {
+    microsteps
+  } = macrostep(snapshot, event, actorScope, []);
+  return microsteps;
+}
+
+/**
+ * Given a state `machine` and optional `input`, returns an array of microsteps
+ * from the initial transition, where each microstep is a tuple of `[snapshot,
+ * actions]`.
+ *
+ * This is a pure function that does not execute `actions`.
+ */
+function getInitialMicrosteps(machine, ...[input]) {
+  const actorScope = createInertActorScope(machine);
+  const initEvent = createInitEvent(input);
+  const internalQueue = [];
+  const preInitialSnapshot = machine._getPreInitialState(actorScope, initEvent, internalQueue);
+  const first = initialMicrostep(machine.root, preInitialSnapshot, actorScope, initEvent, internalQueue);
+  const {
+    microsteps
+  } = macrostep(first[0], initEvent, actorScope, internalQueue);
+  return [first, ...microsteps];
+}
+
+/**
+ * Gets all potential next transitions from the current state.
+ *
+ * Returns all transitions that are available from the current state, including:
+ *
+ * - All transitions from atomic states (leaf states in the current state
+ *   configuration)
+ * - All transitions from ancestor states (parent states that may handle events)
+ * - All guarded transitions (regardless of whether their guards would pass)
+ * - Always (eventless) transitions
+ * - After (delayed) transitions
+ *
+ * The order of transitions is deterministic:
+ *
+ * 1. Atomic states are processed in document order
+ * 2. For each atomic state, transitions are collected from the state itself first,
+ *    then its ancestors
+ * 3. Within each state node, transitions are in the order they appear in the state
+ *    definition
+ *
+ * @param state - The current machine snapshot
+ * @returns Array of transition definitions from the current state, in
+ *   deterministic order
+ */
+function getNextTransitions(state) {
+  const potentialTransitions = [];
+  const atomicStates = state._nodes.filter(isAtomicStateNode);
+  const visited = new Set();
+
+  // Collect all transitions from atomic states and their ancestors
+  // Process atomic states in document order (as they appear in state._nodes)
+  for (const stateNode of atomicStates) {
+    // For each atomic state, process the state itself first, then its ancestors
+    // This ensures child state transitions come before parent state transitions
+    for (const s of [stateNode].concat(getProperAncestors(stateNode, undefined))) {
+      if (visited.has(s.id)) {
+        continue;
+      }
+      visited.add(s.id);
+
+      // Get all transitions for each event type
+      // Include ALL transitions, even if the same event type appears in multiple state nodes
+      // This is important for guarded transitions - all are "potential" regardless of guard evaluation
+      for (const [, transitions] of s.transitions) {
+        potentialTransitions.push(...transitions);
+      }
+
+      // Also include always (eventless) transitions
+      if (s.always) {
+        potentialTransitions.push(...s.always);
+      }
+    }
+  }
+  return potentialTransitions;
+}
+
 const defaultWaitForOptions = {
   timeout: Infinity // much more than 10 seconds
 };
@@ -442,4 +531,4 @@ function waitFor(actorRef, predicate, options) {
   });
 }
 
-export { SimulatedClock, assertEvent, createMachine, getInitialSnapshot, getNextSnapshot, initialTransition, setup, toPromise, transition, waitFor };
+export { SimulatedClock, assertEvent, createMachine, getInitialMicrosteps, getInitialSnapshot, getMicrosteps, getNextSnapshot, getNextTransitions, initialTransition, setup, toPromise, transition, waitFor };

package/dist/xstate.esm.js

@@ -1,12 +1,12 @@
 export { createEmptyActor, fromCallback, fromEventObservable, fromObservable, fromPromise, fromTransition } from '../actors/dist/xstate-actors.esm.js';
-import { m as matchesEventDescriptor, t as toArray, c as createActor, r as raise, a as cancel, s as stopChild, b as spawnChild } from './raise-f5c7cb5b.esm.js';
-export { A as Actor, h as __unsafe_getAllOwnEventDescriptors, d as and, a as cancel, c as createActor, g as getStateNodes, i as interpret, f as isMachineSnapshot, j as matchesState, n as not, o as or, p as pathToStateValue, r as raise, b as spawnChild, e as stateIn, l as stop, s as stopChild, k as toObserver } from './raise-f5c7cb5b.esm.js';
-import { S as StateMachine } from './StateMachine-6c48f805.esm.js';
-export { S as StateMachine, a as StateNode } from './StateMachine-6c48f805.esm.js';
-import { a as assign } from './assign-37a2fc1e.esm.js';
-export { a as assign } from './assign-37a2fc1e.esm.js';
-import { s as sendTo, l as log, e as enqueueActions, a as emit } from './log-ce14fc9a.esm.js';
-export { S as SpecialTargets, a as emit, e as enqueueActions, f as forwardTo, l as log, b as sendParent, s as sendTo } from './log-ce14fc9a.esm.js';
+import { m as matchesEventDescriptor, t as toArray, c as createActor, r as raise, a as cancel, s as stopChild, b as spawnChild, d as macrostep, e as createInitEvent, i as initialMicrostep, f as isAtomicStateNode, g as getProperAncestors } from './raise-e5d81555.esm.js';
+export { A as Actor, q as __unsafe_getAllOwnEventDescriptors, j as and, a as cancel, c as createActor, p as getStateNodes, h as interpret, l as isMachineSnapshot, u as matchesState, n as not, o as or, v as pathToStateValue, r as raise, b as spawnChild, k as stateIn, x as stop, s as stopChild, w as toObserver } from './raise-e5d81555.esm.js';
+import { S as StateMachine } from './StateMachine-a4db5a91.esm.js';
+export { S as StateMachine, a as StateNode } from './StateMachine-a4db5a91.esm.js';
+import { a as assign } from './assign-227b928a.esm.js';
+export { a as assign } from './assign-227b928a.esm.js';
+import { s as sendTo, l as log, e as enqueueActions, a as emit } from './log-fa76d888.esm.js';
+export { S as SpecialTargets, a as emit, e as enqueueActions, f as forwardTo, l as log, b as sendParent, s as sendTo } from './log-fa76d888.esm.js';
 import '../dev/dist/xstate-dev.esm.js';
 
 /**
@@ -338,6 +338,95 @@ function initialTransition(logic, ...[input]) {
   return [nextSnapshot, executableActions];
 }
 
+/**
+ * Given a state `machine`, a `snapshot`, and an `event`, returns an array of
+ * microsteps, where each microstep is a tuple of `[snapshot, actions]`.
+ *
+ * This is a pure function that does not execute `actions`.
+ */
+function getMicrosteps(machine, snapshot, event) {
+  const actorScope = createInertActorScope(machine);
+  const {
+    microsteps
+  } = macrostep(snapshot, event, actorScope, []);
+  return microsteps;
+}
+
+/**
+ * Given a state `machine` and optional `input`, returns an array of microsteps
+ * from the initial transition, where each microstep is a tuple of `[snapshot,
+ * actions]`.
+ *
+ * This is a pure function that does not execute `actions`.
+ */
+function getInitialMicrosteps(machine, ...[input]) {
+  const actorScope = createInertActorScope(machine);
+  const initEvent = createInitEvent(input);
+  const internalQueue = [];
+  const preInitialSnapshot = machine._getPreInitialState(actorScope, initEvent, internalQueue);
+  const first = initialMicrostep(machine.root, preInitialSnapshot, actorScope, initEvent, internalQueue);
+  const {
+    microsteps
+  } = macrostep(first[0], initEvent, actorScope, internalQueue);
+  return [first, ...microsteps];
+}
+
+/**
+ * Gets all potential next transitions from the current state.
+ *
+ * Returns all transitions that are available from the current state, including:
+ *
+ * - All transitions from atomic states (leaf states in the current state
+ *   configuration)
+ * - All transitions from ancestor states (parent states that may handle events)
+ * - All guarded transitions (regardless of whether their guards would pass)
+ * - Always (eventless) transitions
+ * - After (delayed) transitions
+ *
+ * The order of transitions is deterministic:
+ *
+ * 1. Atomic states are processed in document order
+ * 2. For each atomic state, transitions are collected from the state itself first,
+ *    then its ancestors
+ * 3. Within each state node, transitions are in the order they appear in the state
+ *    definition
+ *
+ * @param state - The current machine snapshot
+ * @returns Array of transition definitions from the current state, in
+ *   deterministic order
+ */
+function getNextTransitions(state) {
+  const potentialTransitions = [];
+  const atomicStates = state._nodes.filter(isAtomicStateNode);
+  const visited = new Set();
+
+  // Collect all transitions from atomic states and their ancestors
+  // Process atomic states in document order (as they appear in state._nodes)
+  for (const stateNode of atomicStates) {
+    // For each atomic state, process the state itself first, then its ancestors
+    // This ensures child state transitions come before parent state transitions
+    for (const s of [stateNode].concat(getProperAncestors(stateNode, undefined))) {
+      if (visited.has(s.id)) {
+        continue;
+      }
+      visited.add(s.id);
+
+      // Get all transitions for each event type
+      // Include ALL transitions, even if the same event type appears in multiple state nodes
+      // This is important for guarded transitions - all are "potential" regardless of guard evaluation
+      for (const [, transitions] of s.transitions) {
+        potentialTransitions.push(...transitions);
+      }
+
+      // Also include always (eventless) transitions
+      if (s.always) {
+        potentialTransitions.push(...s.always);
+      }
+    }
+  }
+  return potentialTransitions;
+}
+
 const defaultWaitForOptions = {
   timeout: Infinity // much more than 10 seconds
 };
@@ -439,4 +528,4 @@ function waitFor(actorRef, predicate, options) {
   });
 }
 
-export { SimulatedClock, assertEvent, createMachine, getInitialSnapshot, getNextSnapshot, initialTransition, setup, toPromise, transition, waitFor };
+export { SimulatedClock, assertEvent, createMachine, getInitialMicrosteps, getInitialSnapshot, getMicrosteps, getNextSnapshot, getNextTransitions, initialTransition, setup, toPromise, transition, waitFor };