xstate 5.14.0 → 5.16.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-0cd7e521.development.cjs.js');
-var log = require('./log-505687fd.development.cjs.js');
+var guards_dist_xstateGuards = require('./raise-bad6a97b.development.cjs.js');
+var log = require('./log-31321d85.development.cjs.js');
 require('../dev/dist/xstate-dev.development.cjs.js');
 
 class SimulatedClock {
@@ -107,71 +107,58 @@ const toSerializableAction = action => {
   return action;
 };
 class StateNode {
-  constructor(
-  /**
-   * The raw config used to create the machine.
-   */
+  constructor( /** The raw config used to create the machine. */
   config, options) {
     this.config = config;
     /**
-     * The relative key of the state node, which represents its location in the overall state value.
+     * The relative key of the state node, which represents its location in the
+     * overall state value.
      */
     this.key = void 0;
-    /**
-     * The unique ID of the state node.
-     */
+    /** The unique ID of the state node. */
     this.id = void 0;
     /**
      * The type of this state node:
      *
-     *  - `'atomic'` - no child state nodes
-     *  - `'compound'` - nested child state nodes (XOR)
-     *  - `'parallel'` - orthogonal nested child state nodes (AND)
-     *  - `'history'` - history state node
-     *  - `'final'` - final state node
+     * - `'atomic'` - no child state nodes
+     * - `'compound'` - nested child state nodes (XOR)
+     * - `'parallel'` - orthogonal nested child state nodes (AND)
+     * - `'history'` - history state node
+     * - `'final'` - final state node
      */
     this.type = void 0;
-    /**
-     * The string path from the root machine node to this node.
-     */
+    /** The string path from the root machine node to this node. */
     this.path = void 0;
-    /**
-     * The child state nodes.
-     */
+    /** The child state nodes. */
     this.states = void 0;
     /**
      * The type of history on this state node. Can be:
      *
-     *  - `'shallow'` - recalls only top-level historical state value
-     *  - `'deep'` - recalls historical state value at all levels
+     * - `'shallow'` - recalls only top-level historical state value
+     * - `'deep'` - recalls historical state value at all levels
      */
     this.history = void 0;
-    /**
-     * The action(s) to be executed upon entering the state node.
-     */
+    /** The action(s) to be executed upon entering the state node. */
     this.entry = void 0;
-    /**
-     * The action(s) to be executed upon exiting the state node.
-     */
+    /** The action(s) to be executed upon exiting the state node. */
     this.exit = void 0;
-    /**
-     * The parent state node.
-     */
+    /** The parent state node. */
     this.parent = void 0;
-    /**
-     * The root machine node.
-     */
+    /** The root machine node. */
     this.machine = void 0;
     /**
-     * The meta data associated with this state node, which will be returned in State instances.
+     * The meta data associated with this state node, which will be returned in
+     * State instances.
      */
     this.meta = void 0;
     /**
-     * The output data sent with the "xstate.done.state._id_" event if this is a final state node.
+     * The output data sent with the "xstate.done.state._id_" event if this is a
+     * final state node.
      */
     this.output = void 0;
     /**
-     * The order this state node appears. Corresponds to the implicit document order.
+     * The order this state node appears. Corresponds to the implicit document
+     * order.
      */
     this.order = -1;
     this.description = void 0;
@@ -219,9 +206,7 @@ class StateNode {
     });
   }
 
-  /**
-   * The well-structured state node definition.
-   */
+  /** The well-structured state node definition. */
   get definition() {
     return {
       id: this.id,
@@ -266,9 +251,7 @@ class StateNode {
     return this.definition;
   }
 
-  /**
-   * The logic invoked as actors by this state node.
-   */
+  /** The logic invoked as actors by this state node. */
   get invoke() {
     return memo(this, 'invoke', () => guards_dist_xstateGuards.toArray(this.config.invoke).map((invokeConfig, i) => {
       const {
@@ -299,9 +282,7 @@ class StateNode {
     }));
   }
 
-  /**
-   * The mapping of events to transitions.
-   */
+  /** The mapping of events to transitions. */
   get on() {
     return memo(this, 'on', () => {
       const transitions = this.transitions;
@@ -346,9 +327,7 @@ class StateNode {
     return selectedTransition ? [selectedTransition] : undefined;
   }
 
-  /**
-   * All the event types accepted by this state node and its descendants.
-   */
+  /** All the event types accepted by this state node and its descendants. */
   get events() {
     return memo(this, 'events', () => {
       const {
@@ -384,15 +363,10 @@ class StateNode {
 
 const STATE_IDENTIFIER = '#';
 class StateMachine {
-  constructor(
-  /**
-   * The raw config used to create the machine.
-   */
+  constructor( /** The raw config used to create the machine. */
   config, implementations) {
     this.config = config;
-    /**
-     * The machine's own version.
-     */
+    /** The machine's own version. */
     this.version = void 0;
     this.schemas = void 0;
     this.implementations = void 0;
@@ -404,10 +378,6 @@ class StateMachine {
     this.id = void 0;
     this.states = void 0;
     this.events = void 0;
-    /**
-     * @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 = {
       actors: implementations?.actors ?? {},
@@ -435,12 +405,11 @@ class StateMachine {
   }
 
   /**
-   * Clones this state machine with the provided implementations
-   * and merges the `context` (if provided).
-   *
-   * @param implementations Options (`actions`, `guards`, `actors`, `delays`, `context`)
-   *  to recursively merge with the existing options.
+   * Clones this state machine with the provided implementations and merges the
+   * `context` (if provided).
    *
+   * @param implementations Options (`actions`, `guards`, `actors`, `delays`,
+   *   `context`) to recursively merge with the existing options.
    * @returns A new `StateMachine` instance with the provided implementations.
    */
   provide(implementations) {
@@ -484,8 +453,8 @@ class StateMachine {
   }
 
   /**
-   * Determines the next snapshot given the current `snapshot` and received `event`.
-   * Calculates a full macrostep from all microsteps.
+   * Determines the next snapshot given the current `snapshot` and received
+   * `event`. Calculates a full macrostep from all microsteps.
    *
    * @param snapshot The current snapshot
    * @param event The received event
@@ -495,8 +464,8 @@ class StateMachine {
   }
 
   /**
-   * Determines the next state given the current `state` and `event`.
-   * Calculates a microstep.
+   * Determines the next state given the current `state` and `event`. Calculates
+   * a microstep.
    *
    * @param state The current state
    * @param event The received event
@@ -509,8 +478,8 @@ class StateMachine {
   }
 
   /**
-   * The initial state _before_ evaluating any microsteps.
-   * This "pre-initial" state is provided to initial actions executed in the initial state.
+   * The initial state _before_ evaluating any microsteps. This "pre-initial"
+   * state is provided to initial actions executed in the initial state.
    */
   getPreInitialState(actorScope, initEvent, internalQueue) {
     const {
@@ -538,7 +507,8 @@ class StateMachine {
   }
 
   /**
-   * Returns the initial `State` instance, with reference to `self` as an `ActorRef`.
+   * Returns the initial `State` instance, with reference to `self` as an
+   * `ActorRef`.
    */
   getInitialSnapshot(actorScope, input) {
     const initEvent = guards_dist_xstateGuards.createInitEvent(input); // TODO: fix;
@@ -636,14 +606,14 @@ const defaultWaitForOptions = {
 };
 
 /**
- * Subscribes to an actor ref and waits for its emitted value to satisfy
- * a predicate, and then resolves with that value.
- * Will throw if the desired state is not reached after an optional timeout.
- * (defaults to Infinity).
+ * Subscribes to an actor ref and waits for its emitted value to satisfy a
+ * predicate, and then resolves with that value. Will throw if the desired state
+ * is not reached after an optional timeout. (defaults to Infinity).
  *
  * @example
+ *
  * ```js
- * const state = await waitFor(someService, state => {
+ * const state = await waitFor(someService, (state) => {
  *   return state.hasTag('loaded');
  * });
  *
@@ -653,8 +623,8 @@ const defaultWaitForOptions = {
  * @param actorRef The actor ref to subscribe to
  * @param predicate Determines if a value matches the condition to wait for
  * @param options
- * @returns A promise that eventually resolves to the emitted value
- * that matches the condition
+ * @returns A promise that eventually resolves to the emitted value that matches
+ *   the condition
  */
 function waitFor(actorRef, predicate, options) {
   const resolvedOptions = {
@@ -713,40 +683,42 @@ function waitFor(actorRef, predicate, options) {
  *
  * 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' });
-  ```
+ *
+ * ```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' });
+ * ```
+ *
+ * @param config The state machine configuration.
+ * @param options DEPRECATED: use `setup({ ... })` or `machine.provide({ ... })`
+ *   to provide machine implementations instead.
  */
 function createMachine(config, implementations) {
   return new StateMachine(config, implementations);
@@ -773,33 +745,36 @@ function getInitialSnapshot(actorLogic, ...[input]) {
 }
 
 /**
- * Determines the next snapshot for the given `actorLogic` based on
- * the given `snapshot` and `event`.
+ * 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.
+ * 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'
-  ```
+ *
+ * ```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);
@@ -833,6 +808,7 @@ function setup({
  * Returns a promise that resolves to the `output` of the actor when it is done.
  *
  * @example
+ *
  * ```ts
  * const machine = createMachine({
  *   // ...
@@ -863,26 +839,27 @@ function toPromise(actor) {
 }
 
 /**
- * Asserts that the given event object is of the specified type or types.
- * Throws an error if the event object is not of the specified types.
-  @example
-
-  ```ts
-  // ...
-  entry: ({ event }) => {
-    assertEvent(event, 'doNothing');
-    // event is { type: 'doNothing' }
-  },
-  // ...
-  exit: ({ event }) => {
-    assertEvent(event, 'greet');
-    // event is { type: 'greet'; message: string }
-
-    assertEvent(event, ['greet', 'notify']);
-    // event is { type: 'greet'; message: string }
-    // or { type: 'notify'; message: string; level: 'info' | 'error' }
-  },
-  ```
+ * Asserts that the given event object is of the specified type or types. Throws
+ * an error if the event object is not of the specified types.
+ *
+ * @example
+ *
+ * ```ts
+ * // ...
+ * entry: ({ event }) => {
+ *   assertEvent(event, 'doNothing');
+ *   // event is { type: 'doNothing' }
+ * },
+ * // ...
+ * exit: ({ event }) => {
+ *   assertEvent(event, 'greet');
+ *   // event is { type: 'greet'; message: string }
+ *
+ *   assertEvent(event, ['greet', 'notify']);
+ *   // event is { type: 'greet'; message: string }
+ *   // or { type: 'notify'; message: string; level: 'info' | 'error' }
+ * },
+ * ```
  */
 function assertEvent(event, type) {
   const types = guards_dist_xstateGuards.toArray(type);