xstate 5.4.0 → 5.5.0

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

@@ -1,6 +1,6 @@
 'use strict';
 
-var guards_dist_xstateGuards = require('./raise-e3ff3de1.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-7df513e7.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
@@ -972,10 +973,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);
 }
 
 /**
@@ -1001,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) {
@@ -1031,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
     });
   }
@@ -1171,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;
@@ -1187,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;
@@ -1203,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;
@@ -2047,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);
         });
       }
@@ -2073,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) {
@@ -2133,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;

package/dist/{raise-e3ff3de1.development.cjs.js → raise-7af39710.development.cjs.js}

@@ -436,6 +436,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
@@ -988,10 +989,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);
 }
 
 /**
@@ -1017,11 +1016,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) {
@@ -1050,13 +1068,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
     });
   }
@@ -1201,6 +1219,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) {
     {
@@ -1219,6 +1264,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) {
     {
@@ -1237,6 +1313,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) {
     {
@@ -2094,18 +2201,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);
         });
       }
@@ -2120,10 +2227,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) {
@@ -2183,7 +2290,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;