xstate 5.4.1 → 5.5.0

package/dist/{log-11038f00.development.esm.js → log-285f62db.development.esm.js}

@@ -1,4 +1,4 @@
-import { R as ProcessingStatus, y as resolveReferencedActor, z as createActor, T as cloneMachineSnapshot, U as XSTATE_ERROR, V as createErrorActorEvent, e as evaluateGuard, L as cancel, M as raise, O as spawnChild, Q as stopChild } from './raise-057d17af.development.esm.js';
+import { R as ProcessingStatus, y as resolveReferencedActor, z as createActor, T as cloneMachineSnapshot, U as XSTATE_ERROR, V as createErrorActorEvent, e as evaluateGuard, L as cancel, M as raise, O as spawnChild, Q as stopChild } from './raise-8da27ebb.development.esm.js';
 
 // it's likely-ish that `(TActor & { src: TSrc })['logic']` would be faster
 // but it's only possible to do it since https://github.com/microsoft/TypeScript/pull/53098 (TS 5.1)
@@ -67,8 +67,8 @@ function resolveAssign(actorScope, snapshot, actionArgs, actionParams, {
     context: snapshot.context,
     event: actionArgs.event,
     spawn: createSpawner(actorScope, snapshot, actionArgs.event, spawnedChildren),
-    self: actorScope?.self,
-    system: actorScope?.system
+    self: actorScope.self,
+    system: actorScope.system
   };
   let partialUpdate = {};
   if (typeof assignment === 'function') {
@@ -91,7 +91,34 @@ function resolveAssign(actorScope, snapshot, actionArgs, actionParams, {
 /**
  * Updates the current context of the machine.
  *
- * @param assignment An object that represents the partial context to update.
+ * @param assignment An object that represents the partial context to update, or a
+ * function that returns an object that represents the partial context to update.
+ * 
+ * @example
+  ```ts
+  import { createMachine, assign } from 'xstate';
+
+  const countMachine = createMachine({
+    context: {
+      count: 0,
+      message: ''
+    },
+    on: {
+      inc: {
+        actions: assign({
+          count: ({ context }) => context.count + 1
+        })
+      },
+      updateMessage: {
+        actions: assign(({ context, event }) => {
+          return {
+            message: event.message.trim()
+          }
+        })
+      }
+    }
+  });
+  ```
  */
 function assign(assignment) {
   function assign(args, params) {
@@ -141,7 +168,9 @@ function assign(assignment) {
 /** @deprecated use `AnyMachineSnapshot` instead */
 
 // TODO: possibly refactor this somehow, use even a simpler type, and maybe even make `machine.options` private or something
-
+/**
+ * @internal
+ */
 let SpecialTargets = /*#__PURE__*/function (SpecialTargets) {
   SpecialTargets["Parent"] = "#_parent";
   SpecialTargets["Internal"] = "#_internal";
@@ -154,6 +183,14 @@ let SpecialTargets = /*#__PURE__*/function (SpecialTargets) {
 
 // Based on RxJS types
 
+/**
+ * @internal
+ */
+
+/**
+ * @internal
+ */
+
 /**
  * @deprecated Use `Actor<T>` instead.
  */
@@ -191,9 +228,9 @@ function resolveSendTo(actorScope, snapshot, args, actionParams, {
   let targetActorRef;
   if (typeof resolvedTarget === 'string') {
     if (resolvedTarget === SpecialTargets.Parent) {
-      targetActorRef = actorScope?.self._parent;
+      targetActorRef = actorScope.self._parent;
     } else if (resolvedTarget === SpecialTargets.Internal) {
-      targetActorRef = actorScope?.self;
+      targetActorRef = actorScope.self;
     } else if (resolvedTarget.startsWith('#_')) {
       // SCXML compatibility: https://www.w3.org/TR/scxml/#SCXMLEventProcessor
       // #_invokeid. If the target is the special term '#_invokeid', where invokeid is the invokeid of an SCXML session that the sending session has created by <invoke>, the Processor must add the event to the external queue of that session.
@@ -205,7 +242,7 @@ function resolveSendTo(actorScope, snapshot, args, actionParams, {
       throw new Error(`Unable to send event to actor '${resolvedTarget}' from machine '${snapshot.machine.id}'.`);
     }
   } else {
-    targetActorRef = resolvedTarget || actorScope?.self;
+    targetActorRef = resolvedTarget || actorScope.self;
   }
   return [snapshot, {
     to: targetActorRef,
@@ -275,9 +312,9 @@ function sendParent(event, options) {
   return sendTo(SpecialTargets.Parent, event, options);
 }
 /**
- * Forwards (sends) an event to a specified service.
+ * Forwards (sends) an event to the `target` actor.
  *
- * @param target The target service to forward the event to.
+ * @param target The target actor to forward the event to.
  * @param options Options to pass into the send action creator.
  */
 function forwardTo(target, options) {
@@ -331,6 +368,26 @@ function resolveEnqueueActions(actorScope, snapshot, args, _actionParams, {
   });
   return [snapshot, undefined, actions];
 }
+/**
+ * Creates an action object that will execute actions that are queued by the `enqueue(action)` function.
+ * 
+ * @example
+  ```ts
+  import { createMachine, enqueueActions } from 'xstate';
+
+  const machine = createMachine({
+    entry: enqueueActions(({ enqueue, check }) => {
+      enqueue.assign({ count: 0 });
+
+      if (check('someGuard')) {
+        enqueue.assign({ count: 1 });
+      }
+
+      enqueue('someAction');
+    })
+  })
+  ```
+ */
 function enqueueActions(collect) {
   function enqueueActions(args, params) {
     {

package/dist/{log-2580e864.cjs.js → log-742895c6.cjs.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-var guards_dist_xstateGuards = require('./raise-5c58eb8e.cjs.js');
+var guards_dist_xstateGuards = require('./raise-ad8bb7c2.cjs.js');
 
 // it's likely-ish that `(TActor & { src: TSrc })['logic']` would be faster
 // but it's only possible to do it since https://github.com/microsoft/TypeScript/pull/53098 (TS 5.1)
@@ -69,8 +69,8 @@ function resolveAssign(actorScope, snapshot, actionArgs, actionParams, {
     context: snapshot.context,
     event: actionArgs.event,
     spawn: createSpawner(actorScope, snapshot, actionArgs.event, spawnedChildren),
-    self: actorScope?.self,
-    system: actorScope?.system
+    self: actorScope.self,
+    system: actorScope.system
   };
   let partialUpdate = {};
   if (typeof assignment === 'function') {
@@ -93,7 +93,34 @@ function resolveAssign(actorScope, snapshot, actionArgs, actionParams, {
 /**
  * Updates the current context of the machine.
  *
- * @param assignment An object that represents the partial context to update.
+ * @param assignment An object that represents the partial context to update, or a
+ * function that returns an object that represents the partial context to update.
+ * 
+ * @example
+  ```ts
+  import { createMachine, assign } from 'xstate';
+
+  const countMachine = createMachine({
+    context: {
+      count: 0,
+      message: ''
+    },
+    on: {
+      inc: {
+        actions: assign({
+          count: ({ context }) => context.count + 1
+        })
+      },
+      updateMessage: {
+        actions: assign(({ context, event }) => {
+          return {
+            message: event.message.trim()
+          }
+        })
+      }
+    }
+  });
+  ```
  */
 function assign(assignment) {
   function assign(args, params) {
@@ -140,7 +167,9 @@ function assign(assignment) {
 /** @deprecated use `AnyMachineSnapshot` instead */
 
 // TODO: possibly refactor this somehow, use even a simpler type, and maybe even make `machine.options` private or something
-
+/**
+ * @internal
+ */
 let SpecialTargets = /*#__PURE__*/function (SpecialTargets) {
   SpecialTargets["Parent"] = "#_parent";
   SpecialTargets["Internal"] = "#_internal";
@@ -153,6 +182,14 @@ let SpecialTargets = /*#__PURE__*/function (SpecialTargets) {
 
 // Based on RxJS types
 
+/**
+ * @internal
+ */
+
+/**
+ * @internal
+ */
+
 /**
  * @deprecated Use `Actor<T>` instead.
  */
@@ -190,9 +227,9 @@ function resolveSendTo(actorScope, snapshot, args, actionParams, {
   let targetActorRef;
   if (typeof resolvedTarget === 'string') {
     if (resolvedTarget === SpecialTargets.Parent) {
-      targetActorRef = actorScope?.self._parent;
+      targetActorRef = actorScope.self._parent;
     } else if (resolvedTarget === SpecialTargets.Internal) {
-      targetActorRef = actorScope?.self;
+      targetActorRef = actorScope.self;
     } else if (resolvedTarget.startsWith('#_')) {
       // SCXML compatibility: https://www.w3.org/TR/scxml/#SCXMLEventProcessor
       // #_invokeid. If the target is the special term '#_invokeid', where invokeid is the invokeid of an SCXML session that the sending session has created by <invoke>, the Processor must add the event to the external queue of that session.
@@ -204,7 +241,7 @@ function resolveSendTo(actorScope, snapshot, args, actionParams, {
       throw new Error(`Unable to send event to actor '${resolvedTarget}' from machine '${snapshot.machine.id}'.`);
     }
   } else {
-    targetActorRef = resolvedTarget || actorScope?.self;
+    targetActorRef = resolvedTarget || actorScope.self;
   }
   return [snapshot, {
     to: targetActorRef,
@@ -271,9 +308,9 @@ function sendParent(event, options) {
   return sendTo(SpecialTargets.Parent, event, options);
 }
 /**
- * Forwards (sends) an event to a specified service.
+ * Forwards (sends) an event to the `target` actor.
  *
- * @param target The target service to forward the event to.
+ * @param target The target actor to forward the event to.
  * @param options Options to pass into the send action creator.
  */
 function forwardTo(target, options) {
@@ -317,6 +354,26 @@ function resolveEnqueueActions(actorScope, snapshot, args, _actionParams, {
   });
   return [snapshot, undefined, actions];
 }
+/**
+ * Creates an action object that will execute actions that are queued by the `enqueue(action)` function.
+ * 
+ * @example
+  ```ts
+  import { createMachine, enqueueActions } from 'xstate';
+
+  const machine = createMachine({
+    entry: enqueueActions(({ enqueue, check }) => {
+      enqueue.assign({ count: 0 });
+
+      if (check('someGuard')) {
+        enqueue.assign({ count: 1 });
+      }
+
+      enqueue('someAction');
+    })
+  })
+  ```
+ */
 function enqueueActions(collect) {
   function enqueueActions(args, params) {
   }

package/dist/{log-18eb632d.development.cjs.js → log-da322832.development.cjs.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-var guards_dist_xstateGuards = require('./raise-3d3d6d51.development.cjs.js');
+var guards_dist_xstateGuards = require('./raise-7af39710.development.cjs.js');
 
 // it's likely-ish that `(TActor & { src: TSrc })['logic']` would be faster
 // but it's only possible to do it since https://github.com/microsoft/TypeScript/pull/53098 (TS 5.1)
@@ -69,8 +69,8 @@ function resolveAssign(actorScope, snapshot, actionArgs, actionParams, {
     context: snapshot.context,
     event: actionArgs.event,
     spawn: createSpawner(actorScope, snapshot, actionArgs.event, spawnedChildren),
-    self: actorScope?.self,
-    system: actorScope?.system
+    self: actorScope.self,
+    system: actorScope.system
   };
   let partialUpdate = {};
   if (typeof assignment === 'function') {
@@ -93,7 +93,34 @@ function resolveAssign(actorScope, snapshot, actionArgs, actionParams, {
 /**
  * Updates the current context of the machine.
  *
- * @param assignment An object that represents the partial context to update.
+ * @param assignment An object that represents the partial context to update, or a
+ * function that returns an object that represents the partial context to update.
+ * 
+ * @example
+  ```ts
+  import { createMachine, assign } from 'xstate';
+
+  const countMachine = createMachine({
+    context: {
+      count: 0,
+      message: ''
+    },
+    on: {
+      inc: {
+        actions: assign({
+          count: ({ context }) => context.count + 1
+        })
+      },
+      updateMessage: {
+        actions: assign(({ context, event }) => {
+          return {
+            message: event.message.trim()
+          }
+        })
+      }
+    }
+  });
+  ```
  */
 function assign(assignment) {
   function assign(args, params) {
@@ -143,7 +170,9 @@ function assign(assignment) {
 /** @deprecated use `AnyMachineSnapshot` instead */
 
 // TODO: possibly refactor this somehow, use even a simpler type, and maybe even make `machine.options` private or something
-
+/**
+ * @internal
+ */
 let SpecialTargets = /*#__PURE__*/function (SpecialTargets) {
   SpecialTargets["Parent"] = "#_parent";
   SpecialTargets["Internal"] = "#_internal";
@@ -156,6 +185,14 @@ let SpecialTargets = /*#__PURE__*/function (SpecialTargets) {
 
 // Based on RxJS types
 
+/**
+ * @internal
+ */
+
+/**
+ * @internal
+ */
+
 /**
  * @deprecated Use `Actor<T>` instead.
  */
@@ -193,9 +230,9 @@ function resolveSendTo(actorScope, snapshot, args, actionParams, {
   let targetActorRef;
   if (typeof resolvedTarget === 'string') {
     if (resolvedTarget === SpecialTargets.Parent) {
-      targetActorRef = actorScope?.self._parent;
+      targetActorRef = actorScope.self._parent;
     } else if (resolvedTarget === SpecialTargets.Internal) {
-      targetActorRef = actorScope?.self;
+      targetActorRef = actorScope.self;
     } else if (resolvedTarget.startsWith('#_')) {
       // SCXML compatibility: https://www.w3.org/TR/scxml/#SCXMLEventProcessor
       // #_invokeid. If the target is the special term '#_invokeid', where invokeid is the invokeid of an SCXML session that the sending session has created by <invoke>, the Processor must add the event to the external queue of that session.
@@ -207,7 +244,7 @@ function resolveSendTo(actorScope, snapshot, args, actionParams, {
       throw new Error(`Unable to send event to actor '${resolvedTarget}' from machine '${snapshot.machine.id}'.`);
     }
   } else {
-    targetActorRef = resolvedTarget || actorScope?.self;
+    targetActorRef = resolvedTarget || actorScope.self;
   }
   return [snapshot, {
     to: targetActorRef,
@@ -277,9 +314,9 @@ function sendParent(event, options) {
   return sendTo(SpecialTargets.Parent, event, options);
 }
 /**
- * Forwards (sends) an event to a specified service.
+ * Forwards (sends) an event to the `target` actor.
  *
- * @param target The target service to forward the event to.
+ * @param target The target actor to forward the event to.
  * @param options Options to pass into the send action creator.
  */
 function forwardTo(target, options) {
@@ -333,6 +370,26 @@ function resolveEnqueueActions(actorScope, snapshot, args, _actionParams, {
   });
   return [snapshot, undefined, actions];
 }
+/**
+ * Creates an action object that will execute actions that are queued by the `enqueue(action)` function.
+ * 
+ * @example
+  ```ts
+  import { createMachine, enqueueActions } from 'xstate';
+
+  const machine = createMachine({
+    entry: enqueueActions(({ enqueue, check }) => {
+      enqueue.assign({ count: 0 });
+
+      if (check('someGuard')) {
+        enqueue.assign({ count: 1 });
+      }
+
+      enqueue('someAction');
+    })
+  })
+  ```
+ */
 function enqueueActions(collect) {
   function enqueueActions(args, params) {
     {

package/dist/{raise-3b380e4b.esm.js → raise-0e64ee6e.esm.js}

@@ -431,6 +431,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
@@ -999,11 +1000,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) {
@@ -1029,13 +1049,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
     });
   }
@@ -1169,6 +1189,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;
@@ -1185,6 +1232,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;
@@ -1201,6 +1279,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;
@@ -2045,18 +2154,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);
         });
       }
@@ -2071,10 +2180,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) {
@@ -2131,7 +2240,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;