xstate 5.4.0 → 5.5.0

package/dist/{raise-0fc3a80c.development.esm.js → raise-8da27ebb.development.esm.js}

@@ -434,6 +434,7 @@ class Actor {
     this._processingStatus = ProcessingStatus.NotStarted;
     // Actor Ref
     this._parent = void 0;
+    /** @internal */
     this._syncSnapshot = void 0;
     this.ref = void 0;
     // TODO: add typings for system
@@ -986,10 +987,8 @@ class Actor {
  * @param logic - The actor logic to create an actor from. For a state machine actor logic creator, see {@link createMachine}. Other actor logic creators include {@link fromCallback}, {@link fromEventObservable}, {@link fromObservable}, {@link fromPromise}, and {@link fromTransition}.
  * @param options - Actor options
  */
-
 function createActor(logic, options) {
-  const interpreter = new Actor(logic, options);
-  return interpreter;
+  return new Actor(logic, options);
 }
 
 /**
@@ -1015,11 +1014,30 @@ function executeCancel(actorScope, resolvedSendId) {
   });
 }
 /**
- * Cancels an in-flight `send(...)` action. A canceled sent action will not
- * be executed, nor will its event be sent, unless it has already been sent
- * (e.g., if `cancel(...)` is called after the `send(...)` action's `delay`).
+ * Cancels a delayed `sendTo(...)` action that is waiting to be executed. The canceled `sendTo(...)` action
+ * will not send its event or execute, unless the `delay` has already elapsed before `cancel(...)` is called.
  *
- * @param sendId The `id` of the `send(...)` action to cancel.
+ * @param sendId The `id` of the `sendTo(...)` action to cancel.
+ * 
+ * @example
+  ```ts
+  import { createMachine, sendTo, cancel } from 'xstate';
+
+  const machine = createMachine({
+    // ...
+    on: {
+      sendEvent: {
+        actions: sendTo('some-actor', { type: 'someEvent' }, {
+          id: 'some-id',
+          delay: 1000
+        })
+      },
+      cancelEvent: {
+        actions: cancel('some-id')
+      }
+    }
+  });
+  ```
  */
 function cancel(sendId) {
   function cancel(args, params) {
@@ -1048,13 +1066,13 @@ function resolveSpawn(actorScope, snapshot, actionArgs, _actionParams, {
     actorRef = createActor(logic, {
       id: resolvedId,
       src,
-      parent: actorScope?.self,
+      parent: actorScope.self,
       syncSnapshot,
       systemId,
       input: typeof input === 'function' ? input({
         context: snapshot.context,
         event: actionArgs.event,
-        self: actorScope?.self
+        self: actorScope.self
       }) : input
     });
   }
@@ -1199,6 +1217,33 @@ function checkNot(snapshot, {
 }) {
   return !evaluateGuard(guards[0], context, event, snapshot);
 }
+
+/**
+ * Higher-order guard that evaluates to `true` if the `guard` passed to it evaluates to `false`.
+ *
+ * @category Guards
+ * @example
+  ```ts
+  import { setup, not } from 'xstate';
+
+  const machine = setup({
+    guards: {
+      someNamedGuard: () => false
+    }
+  }).createMachine({
+    on: {
+      someEvent: {
+        guard: not('someNamedGuard'),
+        actions: () => {
+          // will be executed if guard in `not(...)`
+          // evaluates to `false`
+        }
+      }
+    }
+  });
+  ```
+ * @returns A guard 
+ */
 function not(guard) {
   function not(args, params) {
     {
@@ -1217,6 +1262,37 @@ function checkAnd(snapshot, {
 }) {
   return guards.every(guard => evaluateGuard(guard, context, event, snapshot));
 }
+
+/**
+ * Higher-order guard that evaluates to `true` if all `guards` passed to it
+ * evaluate to `true`.
+ *
+ * @category Guards
+ * @example
+  ```ts
+  import { setup, and } from 'xstate';
+
+  const machine = setup({
+    guards: {
+      someNamedGuard: () => true
+    }
+  }).createMachine({
+    on: {
+      someEvent: {
+        guard: and([
+          ({ context }) => context.value > 0,
+          'someNamedGuard'
+        ]),
+        actions: () => {
+          // will be executed if all guards in `and(...)`
+          // evaluate to true
+        }
+      }
+    }
+  });
+  ```
+ * @returns A guard action object
+ */
 function and(guards) {
   function and(args, params) {
     {
@@ -1235,6 +1311,37 @@ function checkOr(snapshot, {
 }) {
   return guards.some(guard => evaluateGuard(guard, context, event, snapshot));
 }
+
+/**
+ * Higher-order guard that evaluates to `true` if any of the `guards` passed to it
+ * evaluate to `true`.
+ *
+ * @category Guards
+ * @example
+  ```ts
+  import { setup, or } from 'xstate';
+
+  const machine = setup({
+    guards: {
+      someNamedGuard: () => true
+    }
+  }).createMachine({
+    on: {
+      someEvent: {
+        guard: or([
+          ({ context }) => context.value > 0,
+          'someNamedGuard'
+        ]),
+        actions: () => {
+          // will be executed if any of the guards in `or(...)`
+          // evaluate to true
+        }
+      }
+    }
+  });
+  ```
+ * @returns A guard action object
+ */
 function or(guards) {
   function or(args, params) {
     {
@@ -2092,18 +2199,18 @@ function resolveActionsAndContextWorker(currentSnapshot, event, actorScope, acti
     const actionArgs = {
       context: intermediateSnapshot.context,
       event,
-      self: actorScope?.self,
-      system: actorScope?.system
+      self: actorScope.self,
+      system: actorScope.system
     };
     const actionParams = isInline || typeof action === 'string' ? undefined : 'params' in action ? typeof action.params === 'function' ? action.params({
       context: intermediateSnapshot.context,
       event
     }) : action.params : undefined;
     if (!('resolve' in resolvedAction)) {
-      if (actorScope?.self._processingStatus === ProcessingStatus.Running) {
+      if (actorScope.self._processingStatus === ProcessingStatus.Running) {
         resolvedAction(actionArgs, actionParams);
       } else {
-        actorScope?.defer(() => {
+        actorScope.defer(() => {
           resolvedAction(actionArgs, actionParams);
         });
       }
@@ -2118,10 +2225,10 @@ function resolveActionsAndContextWorker(currentSnapshot, event, actorScope, acti
       retries?.push([builtinAction, params]);
     }
     if ('execute' in builtinAction) {
-      if (actorScope?.self._processingStatus === ProcessingStatus.Running) {
+      if (actorScope.self._processingStatus === ProcessingStatus.Running) {
         builtinAction.execute(actorScope, params);
       } else {
-        actorScope?.defer(builtinAction.execute.bind(null, actorScope, params));
+        actorScope.defer(builtinAction.execute.bind(null, actorScope, params));
       }
     }
     if (actions) {
@@ -2181,7 +2288,9 @@ function macrostep(snapshot, event, actorScope, internalQueue = []) {
         microstates: states
       };
     }
-    nextSnapshot = microstep(transitions, snapshot, actorScope, nextEvent, false, internalQueue);
+    nextSnapshot = microstep(transitions, snapshot, actorScope, nextEvent, false,
+    // isInitial
+    internalQueue);
     states.push(nextSnapshot);
   }
   let shouldSelectEventlessTransitions = true;

package/dist/{raise-c3bbdd3a.cjs.js → raise-ad8bb7c2.cjs.js}

@@ -433,6 +433,7 @@ class Actor {
     this._processingStatus = ProcessingStatus.NotStarted;
     // Actor Ref
     this._parent = void 0;
+    /** @internal */
     this._syncSnapshot = void 0;
     this.ref = void 0;
     // TODO: add typings for system
@@ -974,10 +975,8 @@ class Actor {
  * @param logic - The actor logic to create an actor from. For a state machine actor logic creator, see {@link createMachine}. Other actor logic creators include {@link fromCallback}, {@link fromEventObservable}, {@link fromObservable}, {@link fromPromise}, and {@link fromTransition}.
  * @param options - Actor options
  */
-
 function createActor(logic, options) {
-  const interpreter = new Actor(logic, options);
-  return interpreter;
+  return new Actor(logic, options);
 }
 
 /**
@@ -1003,11 +1002,30 @@ function executeCancel(actorScope, resolvedSendId) {
   });
 }
 /**
- * Cancels an in-flight `send(...)` action. A canceled sent action will not
- * be executed, nor will its event be sent, unless it has already been sent
- * (e.g., if `cancel(...)` is called after the `send(...)` action's `delay`).
+ * Cancels a delayed `sendTo(...)` action that is waiting to be executed. The canceled `sendTo(...)` action
+ * will not send its event or execute, unless the `delay` has already elapsed before `cancel(...)` is called.
  *
- * @param sendId The `id` of the `send(...)` action to cancel.
+ * @param sendId The `id` of the `sendTo(...)` action to cancel.
+ * 
+ * @example
+  ```ts
+  import { createMachine, sendTo, cancel } from 'xstate';
+
+  const machine = createMachine({
+    // ...
+    on: {
+      sendEvent: {
+        actions: sendTo('some-actor', { type: 'someEvent' }, {
+          id: 'some-id',
+          delay: 1000
+        })
+      },
+      cancelEvent: {
+        actions: cancel('some-id')
+      }
+    }
+  });
+  ```
  */
 function cancel(sendId) {
   function cancel(args, params) {
@@ -1033,13 +1051,13 @@ function resolveSpawn(actorScope, snapshot, actionArgs, _actionParams, {
     actorRef = createActor(logic, {
       id: resolvedId,
       src,
-      parent: actorScope?.self,
+      parent: actorScope.self,
       syncSnapshot,
       systemId,
       input: typeof input === 'function' ? input({
         context: snapshot.context,
         event: actionArgs.event,
-        self: actorScope?.self
+        self: actorScope.self
       }) : input
     });
   }
@@ -1173,6 +1191,33 @@ function checkNot(snapshot, {
 }) {
   return !evaluateGuard(guards[0], context, event, snapshot);
 }
+
+/**
+ * Higher-order guard that evaluates to `true` if the `guard` passed to it evaluates to `false`.
+ *
+ * @category Guards
+ * @example
+  ```ts
+  import { setup, not } from 'xstate';
+
+  const machine = setup({
+    guards: {
+      someNamedGuard: () => false
+    }
+  }).createMachine({
+    on: {
+      someEvent: {
+        guard: not('someNamedGuard'),
+        actions: () => {
+          // will be executed if guard in `not(...)`
+          // evaluates to `false`
+        }
+      }
+    }
+  });
+  ```
+ * @returns A guard 
+ */
 function not(guard) {
   function not(args, params) {
     return false;
@@ -1189,6 +1234,37 @@ function checkAnd(snapshot, {
 }) {
   return guards.every(guard => evaluateGuard(guard, context, event, snapshot));
 }
+
+/**
+ * Higher-order guard that evaluates to `true` if all `guards` passed to it
+ * evaluate to `true`.
+ *
+ * @category Guards
+ * @example
+  ```ts
+  import { setup, and } from 'xstate';
+
+  const machine = setup({
+    guards: {
+      someNamedGuard: () => true
+    }
+  }).createMachine({
+    on: {
+      someEvent: {
+        guard: and([
+          ({ context }) => context.value > 0,
+          'someNamedGuard'
+        ]),
+        actions: () => {
+          // will be executed if all guards in `and(...)`
+          // evaluate to true
+        }
+      }
+    }
+  });
+  ```
+ * @returns A guard action object
+ */
 function and(guards) {
   function and(args, params) {
     return false;
@@ -1205,6 +1281,37 @@ function checkOr(snapshot, {
 }) {
   return guards.some(guard => evaluateGuard(guard, context, event, snapshot));
 }
+
+/**
+ * Higher-order guard that evaluates to `true` if any of the `guards` passed to it
+ * evaluate to `true`.
+ *
+ * @category Guards
+ * @example
+  ```ts
+  import { setup, or } from 'xstate';
+
+  const machine = setup({
+    guards: {
+      someNamedGuard: () => true
+    }
+  }).createMachine({
+    on: {
+      someEvent: {
+        guard: or([
+          ({ context }) => context.value > 0,
+          'someNamedGuard'
+        ]),
+        actions: () => {
+          // will be executed if any of the guards in `or(...)`
+          // evaluate to true
+        }
+      }
+    }
+  });
+  ```
+ * @returns A guard action object
+ */
 function or(guards) {
   function or(args, params) {
     return false;
@@ -2049,18 +2156,18 @@ function resolveActionsAndContextWorker(currentSnapshot, event, actorScope, acti
     const actionArgs = {
       context: intermediateSnapshot.context,
       event,
-      self: actorScope?.self,
-      system: actorScope?.system
+      self: actorScope.self,
+      system: actorScope.system
     };
     const actionParams = isInline || typeof action === 'string' ? undefined : 'params' in action ? typeof action.params === 'function' ? action.params({
       context: intermediateSnapshot.context,
       event
     }) : action.params : undefined;
     if (!('resolve' in resolvedAction)) {
-      if (actorScope?.self._processingStatus === ProcessingStatus.Running) {
+      if (actorScope.self._processingStatus === ProcessingStatus.Running) {
         resolvedAction(actionArgs, actionParams);
       } else {
-        actorScope?.defer(() => {
+        actorScope.defer(() => {
           resolvedAction(actionArgs, actionParams);
         });
       }
@@ -2075,10 +2182,10 @@ function resolveActionsAndContextWorker(currentSnapshot, event, actorScope, acti
       retries?.push([builtinAction, params]);
     }
     if ('execute' in builtinAction) {
-      if (actorScope?.self._processingStatus === ProcessingStatus.Running) {
+      if (actorScope.self._processingStatus === ProcessingStatus.Running) {
         builtinAction.execute(actorScope, params);
       } else {
-        actorScope?.defer(builtinAction.execute.bind(null, actorScope, params));
+        actorScope.defer(builtinAction.execute.bind(null, actorScope, params));
       }
     }
     if (actions) {
@@ -2135,7 +2242,9 @@ function macrostep(snapshot, event, actorScope, internalQueue = []) {
         microstates: states
       };
     }
-    nextSnapshot = microstep(transitions, snapshot, actorScope, nextEvent, false, internalQueue);
+    nextSnapshot = microstep(transitions, snapshot, actorScope, nextEvent, false,
+    // isInitial
+    internalQueue);
     states.push(nextSnapshot);
   }
   let shouldSelectEventlessTransitions = true;

package/dist/xstate.cjs.js

@@ -3,8 +3,8 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var actors_dist_xstateActors = require('../actors/dist/xstate-actors.cjs.js');
-var guards_dist_xstateGuards = require('./raise-c3bbdd3a.cjs.js');
-var log = require('./log-a32b44b3.cjs.js');
+var guards_dist_xstateGuards = require('./raise-ad8bb7c2.cjs.js');
+var log = require('./log-742895c6.cjs.js');
 require('../dev/dist/xstate-dev.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 = {
@@ -581,7 +591,7 @@ class StateMachine {
       }
       const actorRef = guards_dist_xstateGuards.createActor(logic, {
         id: actorId,
-        parent: _actorScope?.self,
+        parent: _actorScope.self,
         syncSnapshot: actorData.syncSnapshot,
         snapshot: childState,
         src,
@@ -690,10 +700,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({
@@ -811,6 +911,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.cjs.mjs

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