xstate 5.4.0 → 5.5.0

package/dist/xstate.development.cjs.js

@@ -3,8 +3,8 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var actors_dist_xstateActors = require('../actors/dist/xstate-actors.development.cjs.js');
-var guards_dist_xstateGuards = require('./raise-e3ff3de1.development.cjs.js');
-var log = require('./log-cd3d7c14.development.cjs.js');
+var guards_dist_xstateGuards = require('./raise-7af39710.development.cjs.js');
+var log = require('./log-da322832.development.cjs.js');
 require('../dev/dist/xstate-dev.development.cjs.js');
 
 class SimulatedClock {
@@ -207,6 +207,8 @@ class StateNode {
     this.output = this.type === 'final' || !this.parent ? this.config.output : undefined;
     this.tags = guards_dist_xstateGuards.toArray(config.tags).slice();
   }
+
+  /** @internal */
   _initialize() {
     this.transitions = guards_dist_xstateGuards.formatTransitions(this);
     if (this.config.always) {
@@ -258,6 +260,8 @@ class StateNode {
       tags: this.tags
     };
   }
+
+  /** @internal */
   toJSON() {
     return this.definition;
   }
@@ -314,6 +318,8 @@ class StateNode {
   get initial() {
     return memo(this, 'initial', () => guards_dist_xstateGuards.formatInitialTransition(this, this.config.initial));
   }
+
+  /** @internal */
   next(snapshot, event) {
     const eventType = event.type;
     const actions = [];
@@ -389,13 +395,17 @@ class StateMachine {
      */
     this.version = void 0;
     this.implementations = void 0;
+    /** @internal */
     this.__xstatenode = true;
+    /** @internal */
     this.idMap = new Map();
     this.root = void 0;
     this.id = void 0;
     this.states = void 0;
     this.events = void 0;
-    /** @deprecated an internal property acting as a "phantom" type, not meant to be used at runtime */
+    /**
+     * @deprecated an internal property that was acting as a "phantom" type, it's not used by anything right now but it's kept around for compatibility reasons
+     **/
     this.__TResolvedTypesMeta = void 0;
     this.id = config.id || '(machine)';
     this.implementations = {
@@ -584,7 +594,7 @@ class StateMachine {
       }
       const actorRef = guards_dist_xstateGuards.createActor(logic, {
         id: actorId,
-        parent: _actorScope?.self,
+        parent: _actorScope.self,
         syncSnapshot: actorData.syncSnapshot,
         snapshot: childState,
         src,
@@ -696,10 +706,100 @@ function waitFor(actorRef, predicate, options) {
 // this is not 100% accurate since we can't make parallel regions required in the result
 // `TTestValue` doesn't encode this information anyhow for us to be able to do that
 // this is fine for most practical use cases anyway though
+/**
+ * Creates a state machine (statechart) with the given configuration.
+ *
+ * The state machine represents the pure logic of a state machine actor.
+ * 
+ * @param config The state machine configuration.
+ * @param options DEPRECATED: use `setup({ ... })` or `machine.provide({ ... })` to provide machine implementations instead.
+ * 
+ * @example
+  ```ts
+  import { createMachine } from 'xstate';
+
+  const lightMachine = createMachine({
+    id: 'light',
+    initial: 'green',
+    states: {
+      green: {
+        on: {
+          TIMER: { target: 'yellow' }
+        }
+      },
+      yellow: {
+        on: {
+          TIMER: { target: 'red' }
+        }
+      },
+      red: {
+        on: {
+          TIMER: { target: 'green' }
+        }
+      }
+    }
+  });
+
+  const lightActor = createActor(lightMachine);
+  lightActor.start();
+
+  lightActor.send({ type: 'TIMER' });
+  ```
+ */
 function createMachine(config, implementations) {
   return new StateMachine(config, implementations);
 }
 
+/** @internal */
+function createInertActorScope(actorLogic) {
+  const self = guards_dist_xstateGuards.createActor(actorLogic);
+  const inertActorScope = {
+    self,
+    defer: () => {},
+    id: '',
+    logger: () => {},
+    sessionId: '',
+    stopChild: () => {},
+    system: self.system
+  };
+  return inertActorScope;
+}
+
+/**
+ * Determines the next snapshot for the given `actorLogic` based on
+ * the given `snapshot` and `event`.
+ *
+ * If the `snapshot` is `undefined`, the initial snapshot of the
+ * `actorLogic` is used.
+ *
+ * @example
+  ```ts
+  import { getNextSnapshot } from 'xstate';
+  import { trafficLightMachine } from './trafficLightMachine.ts';
+
+  const nextSnapshot = getNextSnapshot(
+    trafficLightMachine, // actor logic
+    undefined, // snapshot (or initial state if undefined)
+    { type: 'TIMER' }); // event object
+
+  console.log(nextSnapshot.value);
+  // => 'yellow'
+
+  const nextSnapshot2 = getNextSnapshot(
+    trafficLightMachine, // actor logic
+    nextSnapshot, // snapshot
+    { type: 'TIMER' }); // event object
+
+  console.log(nextSnapshot2.value);
+  // =>'red'
+  ```
+ */
+function getNextSnapshot(actorLogic, snapshot, event) {
+  const inertActorScope = createInertActorScope(actorLogic);
+  inertActorScope.self._snapshot = snapshot;
+  return actorLogic.transition(snapshot, event, inertActorScope);
+}
+
 // at the moment we allow extra actors - ones that are not specified by `children`
 // this could be reconsidered in the future
 function setup({
@@ -817,6 +917,7 @@ exports.StateMachine = StateMachine;
 exports.StateNode = StateNode;
 exports.assertEvent = assertEvent;
 exports.createMachine = createMachine;
+exports.getNextSnapshot = getNextSnapshot;
 exports.setup = setup;
 exports.toPromise = toPromise;
 exports.waitFor = waitFor;

package/dist/xstate.development.cjs.mjs

@@ -19,6 +19,7 @@ export {
   fromObservable,
   fromPromise,
   fromTransition,
+  getNextSnapshot,
   getStateNodes,
   interpret,
   isMachineSnapshot,

package/dist/xstate.development.esm.js

@@ -1,8 +1,8 @@
 export { createEmptyActor, fromCallback, fromEventObservable, fromObservable, fromPromise, fromTransition } from '../actors/dist/xstate-actors.development.esm.js';
-import { S as STATE_DELIMITER, m as mapValues, t as toArray, f as formatTransitions, a as toTransitionConfigArray, b as formatTransition, N as NULL_EVENT, e as evaluateGuard, c as createInvokeId, g as getDelayedTransitions, d as formatInitialTransition, h as getCandidates, r as resolveStateValue, i as getAllStateNodes, j as getStateNodes, k as createMachineSnapshot, l as isInFinalState, n as macrostep, o as transitionNode, p as resolveActionsAndContext, q as createInitEvent, s as microstep, u as getInitialStateNodes, v as isStateId, w as getStateNodeByPath, x as getPersistedSnapshot, y as resolveReferencedActor, z as createActor, $ as $$ACTOR_TYPE } from './raise-0fc3a80c.development.esm.js';
-export { A as Actor, H as __unsafe_getAllOwnEventDescriptors, D as and, L as cancel, z as createActor, j as getStateNodes, B as interpret, C as isMachineSnapshot, I as matchesState, E as not, F as or, J as pathToStateValue, M as raise, O as spawnChild, G as stateIn, P as stop, Q as stopChild, K as toObserver } from './raise-0fc3a80c.development.esm.js';
-import { a as assign } from './log-580765a2.development.esm.js';
-export { S as SpecialTargets, a as assign, e as enqueueActions, f as forwardTo, l as log, s as sendParent, b as sendTo } from './log-580765a2.development.esm.js';
+import { S as STATE_DELIMITER, m as mapValues, t as toArray, f as formatTransitions, a as toTransitionConfigArray, b as formatTransition, N as NULL_EVENT, e as evaluateGuard, c as createInvokeId, g as getDelayedTransitions, d as formatInitialTransition, h as getCandidates, r as resolveStateValue, i as getAllStateNodes, j as getStateNodes, k as createMachineSnapshot, l as isInFinalState, n as macrostep, o as transitionNode, p as resolveActionsAndContext, q as createInitEvent, s as microstep, u as getInitialStateNodes, v as isStateId, w as getStateNodeByPath, x as getPersistedSnapshot, y as resolveReferencedActor, z as createActor, $ as $$ACTOR_TYPE } from './raise-8da27ebb.development.esm.js';
+export { A as Actor, H as __unsafe_getAllOwnEventDescriptors, D as and, L as cancel, z as createActor, j as getStateNodes, B as interpret, C as isMachineSnapshot, I as matchesState, E as not, F as or, J as pathToStateValue, M as raise, O as spawnChild, G as stateIn, P as stop, Q as stopChild, K as toObserver } from './raise-8da27ebb.development.esm.js';
+import { a as assign } from './log-285f62db.development.esm.js';
+export { S as SpecialTargets, a as assign, e as enqueueActions, f as forwardTo, l as log, s as sendParent, b as sendTo } from './log-285f62db.development.esm.js';
 import '../dev/dist/xstate-dev.development.esm.js';
 
 class SimulatedClock {
@@ -205,6 +205,8 @@ class StateNode {
     this.output = this.type === 'final' || !this.parent ? this.config.output : undefined;
     this.tags = toArray(config.tags).slice();
   }
+
+  /** @internal */
   _initialize() {
     this.transitions = formatTransitions(this);
     if (this.config.always) {
@@ -256,6 +258,8 @@ class StateNode {
       tags: this.tags
     };
   }
+
+  /** @internal */
   toJSON() {
     return this.definition;
   }
@@ -312,6 +316,8 @@ class StateNode {
   get initial() {
     return memo(this, 'initial', () => formatInitialTransition(this, this.config.initial));
   }
+
+  /** @internal */
   next(snapshot, event) {
     const eventType = event.type;
     const actions = [];
@@ -387,13 +393,17 @@ class StateMachine {
      */
     this.version = void 0;
     this.implementations = void 0;
+    /** @internal */
     this.__xstatenode = true;
+    /** @internal */
     this.idMap = new Map();
     this.root = void 0;
     this.id = void 0;
     this.states = void 0;
     this.events = void 0;
-    /** @deprecated an internal property acting as a "phantom" type, not meant to be used at runtime */
+    /**
+     * @deprecated an internal property that was acting as a "phantom" type, it's not used by anything right now but it's kept around for compatibility reasons
+     **/
     this.__TResolvedTypesMeta = void 0;
     this.id = config.id || '(machine)';
     this.implementations = {
@@ -582,7 +592,7 @@ class StateMachine {
       }
       const actorRef = createActor(logic, {
         id: actorId,
-        parent: _actorScope?.self,
+        parent: _actorScope.self,
         syncSnapshot: actorData.syncSnapshot,
         snapshot: childState,
         src,
@@ -694,10 +704,100 @@ function waitFor(actorRef, predicate, options) {
 // this is not 100% accurate since we can't make parallel regions required in the result
 // `TTestValue` doesn't encode this information anyhow for us to be able to do that
 // this is fine for most practical use cases anyway though
+/**
+ * Creates a state machine (statechart) with the given configuration.
+ *
+ * The state machine represents the pure logic of a state machine actor.
+ * 
+ * @param config The state machine configuration.
+ * @param options DEPRECATED: use `setup({ ... })` or `machine.provide({ ... })` to provide machine implementations instead.
+ * 
+ * @example
+  ```ts
+  import { createMachine } from 'xstate';
+
+  const lightMachine = createMachine({
+    id: 'light',
+    initial: 'green',
+    states: {
+      green: {
+        on: {
+          TIMER: { target: 'yellow' }
+        }
+      },
+      yellow: {
+        on: {
+          TIMER: { target: 'red' }
+        }
+      },
+      red: {
+        on: {
+          TIMER: { target: 'green' }
+        }
+      }
+    }
+  });
+
+  const lightActor = createActor(lightMachine);
+  lightActor.start();
+
+  lightActor.send({ type: 'TIMER' });
+  ```
+ */
 function createMachine(config, implementations) {
   return new StateMachine(config, implementations);
 }
 
+/** @internal */
+function createInertActorScope(actorLogic) {
+  const self = createActor(actorLogic);
+  const inertActorScope = {
+    self,
+    defer: () => {},
+    id: '',
+    logger: () => {},
+    sessionId: '',
+    stopChild: () => {},
+    system: self.system
+  };
+  return inertActorScope;
+}
+
+/**
+ * Determines the next snapshot for the given `actorLogic` based on
+ * the given `snapshot` and `event`.
+ *
+ * If the `snapshot` is `undefined`, the initial snapshot of the
+ * `actorLogic` is used.
+ *
+ * @example
+  ```ts
+  import { getNextSnapshot } from 'xstate';
+  import { trafficLightMachine } from './trafficLightMachine.ts';
+
+  const nextSnapshot = getNextSnapshot(
+    trafficLightMachine, // actor logic
+    undefined, // snapshot (or initial state if undefined)
+    { type: 'TIMER' }); // event object
+
+  console.log(nextSnapshot.value);
+  // => 'yellow'
+
+  const nextSnapshot2 = getNextSnapshot(
+    trafficLightMachine, // actor logic
+    nextSnapshot, // snapshot
+    { type: 'TIMER' }); // event object
+
+  console.log(nextSnapshot2.value);
+  // =>'red'
+  ```
+ */
+function getNextSnapshot(actorLogic, snapshot, event) {
+  const inertActorScope = createInertActorScope(actorLogic);
+  inertActorScope.self._snapshot = snapshot;
+  return actorLogic.transition(snapshot, event, inertActorScope);
+}
+
 // at the moment we allow extra actors - ones that are not specified by `children`
 // this could be reconsidered in the future
 function setup({
@@ -779,4 +879,4 @@ function assertEvent(event, type) {
   }
 }
 
-export { SimulatedClock, StateMachine, StateNode, assertEvent, createMachine, setup, toPromise, waitFor };
+export { SimulatedClock, StateMachine, StateNode, assertEvent, createMachine, getNextSnapshot, setup, toPromise, waitFor };

package/dist/xstate.esm.js

@@ -1,8 +1,8 @@
 export { createEmptyActor, fromCallback, fromEventObservable, fromObservable, fromPromise, fromTransition } from '../actors/dist/xstate-actors.esm.js';
-import { S as STATE_DELIMITER, m as mapValues, t as toArray, f as formatTransitions, a as toTransitionConfigArray, b as formatTransition, N as NULL_EVENT, e as evaluateGuard, c as createInvokeId, g as getDelayedTransitions, d as formatInitialTransition, h as getCandidates, r as resolveStateValue, i as getAllStateNodes, j as getStateNodes, k as createMachineSnapshot, l as isInFinalState, n as macrostep, o as transitionNode, p as resolveActionsAndContext, q as createInitEvent, s as microstep, u as getInitialStateNodes, v as isStateId, w as getStateNodeByPath, x as getPersistedSnapshot, y as resolveReferencedActor, z as createActor, $ as $$ACTOR_TYPE } from './raise-7df513e7.esm.js';
-export { A as Actor, H as __unsafe_getAllOwnEventDescriptors, D as and, L as cancel, z as createActor, j as getStateNodes, B as interpret, C as isMachineSnapshot, I as matchesState, E as not, F as or, J as pathToStateValue, M as raise, O as spawnChild, G as stateIn, P as stop, Q as stopChild, K as toObserver } from './raise-7df513e7.esm.js';
-import { a as assign } from './log-e870aec8.esm.js';
-export { S as SpecialTargets, a as assign, e as enqueueActions, f as forwardTo, l as log, s as sendParent, b as sendTo } from './log-e870aec8.esm.js';
+import { S as STATE_DELIMITER, m as mapValues, t as toArray, f as formatTransitions, a as toTransitionConfigArray, b as formatTransition, N as NULL_EVENT, e as evaluateGuard, c as createInvokeId, g as getDelayedTransitions, d as formatInitialTransition, h as getCandidates, r as resolveStateValue, i as getAllStateNodes, j as getStateNodes, k as createMachineSnapshot, l as isInFinalState, n as macrostep, o as transitionNode, p as resolveActionsAndContext, q as createInitEvent, s as microstep, u as getInitialStateNodes, v as isStateId, w as getStateNodeByPath, x as getPersistedSnapshot, y as resolveReferencedActor, z as createActor, $ as $$ACTOR_TYPE } from './raise-0e64ee6e.esm.js';
+export { A as Actor, H as __unsafe_getAllOwnEventDescriptors, D as and, L as cancel, z as createActor, j as getStateNodes, B as interpret, C as isMachineSnapshot, I as matchesState, E as not, F as or, J as pathToStateValue, M as raise, O as spawnChild, G as stateIn, P as stop, Q as stopChild, K as toObserver } from './raise-0e64ee6e.esm.js';
+import { a as assign } from './log-22b3587f.esm.js';
+export { S as SpecialTargets, a as assign, e as enqueueActions, f as forwardTo, l as log, s as sendParent, b as sendTo } from './log-22b3587f.esm.js';
 import '../dev/dist/xstate-dev.esm.js';
 
 class SimulatedClock {
@@ -205,6 +205,8 @@ class StateNode {
     this.output = this.type === 'final' || !this.parent ? this.config.output : undefined;
     this.tags = toArray(config.tags).slice();
   }
+
+  /** @internal */
   _initialize() {
     this.transitions = formatTransitions(this);
     if (this.config.always) {
@@ -256,6 +258,8 @@ class StateNode {
       tags: this.tags
     };
   }
+
+  /** @internal */
   toJSON() {
     return this.definition;
   }
@@ -312,6 +316,8 @@ class StateNode {
   get initial() {
     return memo(this, 'initial', () => formatInitialTransition(this, this.config.initial));
   }
+
+  /** @internal */
   next(snapshot, event) {
     const eventType = event.type;
     const actions = [];
@@ -387,13 +393,17 @@ class StateMachine {
      */
     this.version = void 0;
     this.implementations = void 0;
+    /** @internal */
     this.__xstatenode = true;
+    /** @internal */
     this.idMap = new Map();
     this.root = void 0;
     this.id = void 0;
     this.states = void 0;
     this.events = void 0;
-    /** @deprecated an internal property acting as a "phantom" type, not meant to be used at runtime */
+    /**
+     * @deprecated an internal property that was acting as a "phantom" type, it's not used by anything right now but it's kept around for compatibility reasons
+     **/
     this.__TResolvedTypesMeta = void 0;
     this.id = config.id || '(machine)';
     this.implementations = {
@@ -579,7 +589,7 @@ class StateMachine {
       }
       const actorRef = createActor(logic, {
         id: actorId,
-        parent: _actorScope?.self,
+        parent: _actorScope.self,
         syncSnapshot: actorData.syncSnapshot,
         snapshot: childState,
         src,
@@ -688,10 +698,100 @@ function waitFor(actorRef, predicate, options) {
 // this is not 100% accurate since we can't make parallel regions required in the result
 // `TTestValue` doesn't encode this information anyhow for us to be able to do that
 // this is fine for most practical use cases anyway though
+/**
+ * Creates a state machine (statechart) with the given configuration.
+ *
+ * The state machine represents the pure logic of a state machine actor.
+ * 
+ * @param config The state machine configuration.
+ * @param options DEPRECATED: use `setup({ ... })` or `machine.provide({ ... })` to provide machine implementations instead.
+ * 
+ * @example
+  ```ts
+  import { createMachine } from 'xstate';
+
+  const lightMachine = createMachine({
+    id: 'light',
+    initial: 'green',
+    states: {
+      green: {
+        on: {
+          TIMER: { target: 'yellow' }
+        }
+      },
+      yellow: {
+        on: {
+          TIMER: { target: 'red' }
+        }
+      },
+      red: {
+        on: {
+          TIMER: { target: 'green' }
+        }
+      }
+    }
+  });
+
+  const lightActor = createActor(lightMachine);
+  lightActor.start();
+
+  lightActor.send({ type: 'TIMER' });
+  ```
+ */
 function createMachine(config, implementations) {
   return new StateMachine(config, implementations);
 }
 
+/** @internal */
+function createInertActorScope(actorLogic) {
+  const self = createActor(actorLogic);
+  const inertActorScope = {
+    self,
+    defer: () => {},
+    id: '',
+    logger: () => {},
+    sessionId: '',
+    stopChild: () => {},
+    system: self.system
+  };
+  return inertActorScope;
+}
+
+/**
+ * Determines the next snapshot for the given `actorLogic` based on
+ * the given `snapshot` and `event`.
+ *
+ * If the `snapshot` is `undefined`, the initial snapshot of the
+ * `actorLogic` is used.
+ *
+ * @example
+  ```ts
+  import { getNextSnapshot } from 'xstate';
+  import { trafficLightMachine } from './trafficLightMachine.ts';
+
+  const nextSnapshot = getNextSnapshot(
+    trafficLightMachine, // actor logic
+    undefined, // snapshot (or initial state if undefined)
+    { type: 'TIMER' }); // event object
+
+  console.log(nextSnapshot.value);
+  // => 'yellow'
+
+  const nextSnapshot2 = getNextSnapshot(
+    trafficLightMachine, // actor logic
+    nextSnapshot, // snapshot
+    { type: 'TIMER' }); // event object
+
+  console.log(nextSnapshot2.value);
+  // =>'red'
+  ```
+ */
+function getNextSnapshot(actorLogic, snapshot, event) {
+  const inertActorScope = createInertActorScope(actorLogic);
+  inertActorScope.self._snapshot = snapshot;
+  return actorLogic.transition(snapshot, event, inertActorScope);
+}
+
 // at the moment we allow extra actors - ones that are not specified by `children`
 // this could be reconsidered in the future
 function setup({
@@ -773,4 +873,4 @@ function assertEvent(event, type) {
   }
 }
 
-export { SimulatedClock, StateMachine, StateNode, assertEvent, createMachine, setup, toPromise, waitFor };
+export { SimulatedClock, StateMachine, StateNode, assertEvent, createMachine, getNextSnapshot, setup, toPromise, waitFor };