xstate 5.4.1 → 5.5.0

package/dist/{raise-3d3d6d51.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
@@ -1015,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) {
@@ -1048,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
     });
   }
@@ -1199,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) {
     {
@@ -1217,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) {
     {
@@ -1235,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) {
     {
@@ -2092,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);
         });
       }
@@ -2118,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) {
@@ -2181,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;

package/dist/{raise-057d17af.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
@@ -1013,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) {
@@ -1046,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
     });
   }
@@ -1197,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) {
     {
@@ -1215,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) {
     {
@@ -1233,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) {
     {
@@ -2090,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);
         });
       }
@@ -2116,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) {
@@ -2179,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-5c58eb8e.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
@@ -1001,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) {
@@ -1031,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
     });
   }
@@ -1171,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;
@@ -1187,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;
@@ -1203,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;
@@ -2047,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);
         });
       }
@@ -2073,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) {
@@ -2133,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;