xstate 5.0.0-beta.20 → 5.0.0-beta.22

package/dist/{actions-069d9805.cjs.js → actions-8f2e997e.cjs.js}

@@ -2,6 +2,18 @@
 
 var dev_dist_xstateDev = require('../dev/dist/xstate-dev.cjs.js');
 
+/**
+ * `T | unknown` reduces to `unknown` and that can be problematic when it comes to contextual typing.
+ * It especially is a problem when the union has a function member, like here:
+ *
+ * ```ts
+ * declare function test(cbOrVal: ((arg: number) => unknown) | unknown): void;
+ * test((arg) => {}) // oops, implicit any
+ * ```
+ *
+ * This type can be used to avoid this problem. This union represents the same value space as `unknown`.
+ */
+
 // https://github.com/microsoft/TypeScript/issues/23182#issuecomment-379091887
 
 /**
@@ -406,27 +418,15 @@ function toArray(value) {
   }
   return toArrayStrict(value);
 }
-function mapContext(mapper, context, event) {
+function mapContext(mapper, context, event, self) {
   if (typeof mapper === 'function') {
     return mapper({
       context,
-      event
+      event,
+      self
     });
   }
-  const result = {};
-  const args = {
-    context,
-    event
-  };
-  for (const key of Object.keys(mapper)) {
-    const subMapper = mapper[key];
-    if (typeof subMapper === 'function') {
-      result[key] = subMapper(args);
-    } else {
-      result[key] = subMapper;
-    }
-  }
-  return result;
+  return mapper;
 }
 function isPromiseLike(value) {
   if (value instanceof Promise) {
@@ -478,13 +478,12 @@ function toInvokeConfig(invocable, id) {
   };
 }
 function toObserver(nextHandler, errorHandler, completionHandler) {
-  const noop = () => {};
   const isObserver = typeof nextHandler === 'object';
-  const self = isObserver ? nextHandler : null;
+  const self = isObserver ? nextHandler : undefined;
   return {
-    next: ((isObserver ? nextHandler.next : nextHandler) || noop).bind(self),
-    error: ((isObserver ? nextHandler.error : errorHandler) || noop).bind(self),
-    complete: ((isObserver ? nextHandler.complete : completionHandler) || noop).bind(self)
+    next: (isObserver ? nextHandler.next : nextHandler)?.bind(self),
+    error: (isObserver ? nextHandler.error : errorHandler)?.bind(self),
+    complete: (isObserver ? nextHandler.complete : completionHandler)?.bind(self)
   };
 }
 function createInvokeId(stateNodeId, index) {
@@ -498,7 +497,7 @@ function resolveReferencedActor(referenced) {
 }
 
 function fromCallback(invokeCallback) {
-  const logic = {
+  return {
     config: invokeCallback,
     start: (_state, {
       self
@@ -564,19 +563,20 @@ function fromCallback(invokeCallback) {
     },
     getSnapshot: () => undefined,
     getPersistedState: ({
-      input
-    }) => input
+      input,
+      canceled
+    }) => ({
+      input,
+      canceled
+    })
   };
-  return logic;
 }
 
 function fromObservable(observableCreator) {
   const nextEventType = '$$xstate.next';
   const errorEventType = '$$xstate.error';
   const completeEventType = '$$xstate.complete';
-
-  // TODO: add event types
-  const logic = {
+  return {
     config: observableCreator,
     transition: (state, event, {
       self,
@@ -606,6 +606,7 @@ function fromObservable(observableCreator) {
             status: 'error',
             input: undefined,
             data: event.data,
+            // TODO: if we keep this as `data` we should reflect this in the type
             subscription: undefined
           };
         case completeEventType:
@@ -683,7 +684,6 @@ function fromObservable(observableCreator) {
       subscription: undefined
     })
   };
-  return logic;
 }
 
 /**
@@ -700,7 +700,7 @@ function fromEventObservable(lazyObservable) {
   const completeEventType = '$$xstate.complete';
 
   // TODO: event types
-  const logic = {
+  return {
     config: lazyObservable,
     transition: (state, event) => {
       if (state.status !== 'active') {
@@ -713,6 +713,7 @@ function fromEventObservable(lazyObservable) {
             status: 'error',
             input: undefined,
             data: event.data,
+            // TODO: if we keep this as `data` we should reflect this in the type
             subscription: undefined
           };
         case completeEventType:
@@ -787,7 +788,6 @@ function fromEventObservable(lazyObservable) {
       subscription: undefined
     })
   };
-  return logic;
 }
 
 const resolveEventType = '$$xstate.resolve';
@@ -815,6 +815,7 @@ promiseCreator) {
             ...state,
             status: 'error',
             data: event.data,
+            // TODO: if we keep this as `data` we should reflect this in the type
             input: undefined
           };
         case stopSignalType:
@@ -921,7 +922,20 @@ function toActorRef(actorRefLike) {
 }
 const emptyLogic = fromTransition(_ => undefined, undefined);
 function createEmptyActor() {
-  return interpret(emptyLogic);
+  return createActor(emptyLogic);
+}
+
+/**
+ * This function makes sure that unhandled errors are thrown in a separate macrotask.
+ * It allows those errors to be detected by global error handlers and reported to bug tracking services
+ * without interrupting our own stack of execution.
+ *
+ * @param err error to be thrown
+ */
+function reportUnhandledError(err) {
+  setTimeout(() => {
+    throw err;
+  });
 }
 
 function createSystem() {
@@ -964,6 +978,11 @@ let ActorStatus = /*#__PURE__*/function (ActorStatus) {
   ActorStatus[ActorStatus["Stopped"] = 2] = "Stopped";
   return ActorStatus;
 }({});
+
+/**
+ * @deprecated Use `ActorStatus` instead.
+ */
+const InterpreterStatus = ActorStatus;
 const defaultOptions = {
   deferEvents: true,
   clock: {
@@ -977,9 +996,9 @@ const defaultOptions = {
   logger: console.log.bind(console),
   devTools: false
 };
-class Interpreter {
+class Actor {
   /**
-   * The current state of the interpreted logic.
+   * The current internal state of the actor.
    */
 
   /**
@@ -1003,10 +1022,10 @@ class Interpreter {
    */
 
   /**
-   * Creates a new Interpreter instance (i.e., service) for the given logic with the provided options, if any.
+   * Creates a new actor instance for the given logic with the provided options, if any.
    *
-   * @param logic The logic to be interpreted
-   * @param options Interpreter options
+   * @param logic The logic to create an actor from
+   * @param options Actor options
    */
   constructor(logic, options) {
     this.logic = logic;
@@ -1070,7 +1089,7 @@ class Interpreter {
       }
     };
 
-    // Ensure that the send method is bound to this interpreter instance
+    // Ensure that the send method is bound to this Actor instance
     // if destructured
     this.send = this.send.bind(this);
     this._initState();
@@ -1092,29 +1111,38 @@ class Interpreter {
       deferredFn();
     }
     for (const observer of this.observers) {
-      observer.next?.(snapshot);
+      // TODO: should observers be notified in case of the error?
+      try {
+        observer.next?.(snapshot);
+      } catch (err) {
+        reportUnhandledError(err);
+      }
     }
     const status = this.logic.getStatus?.(state);
     switch (status?.status) {
       case 'done':
         this._stopProcedure();
+        this._complete();
         this._doneEvent = doneInvoke(this.id, status.data);
         this._parent?.send(this._doneEvent);
-        this._complete();
         break;
       case 'error':
         this._stopProcedure();
-        this._parent?.send(error(this.id, status.data));
         this._error(status.data);
+        this._parent?.send(error(this.id, status.data));
         break;
     }
   }
   subscribe(nextListenerOrObserver, errorListener, completeListener) {
     const observer = toObserver(nextListenerOrObserver, errorListener, completeListener);
-    this.observers.add(observer);
-    if (this.status === ActorStatus.Stopped) {
-      observer.complete?.();
-      this.observers.delete(observer);
+    if (this.status !== ActorStatus.Stopped) {
+      this.observers.add(observer);
+    } else {
+      try {
+        observer.complete?.();
+      } catch (err) {
+        reportUnhandledError(err);
+      }
     }
     return {
       unsubscribe: () => {
@@ -1124,7 +1152,7 @@ class Interpreter {
   }
 
   /**
-   * Starts the interpreter from the initial state
+   * Starts the Actor from the initial state
    */
   start() {
     if (this.status === ActorStatus.Running) {
@@ -1136,8 +1164,26 @@ class Interpreter {
       this.system._set(this._systemId, this);
     }
     this.status = ActorStatus.Running;
+    const status = this.logic.getStatus?.(this._state);
+    switch (status?.status) {
+      case 'done':
+        // a state machine can be "done" upon intialization (it could reach a final state using initial microsteps)
+        // we still need to complete observers, flush deferreds etc
+        this.update(this._state);
+      // fallthrough
+      case 'error':
+        // TODO: rethink cleanup of observers, mailbox, etc
+        return this;
+    }
     if (this.logic.start) {
-      this.logic.start(this._state, this._actorContext);
+      try {
+        this.logic.start(this._state, this._actorContext);
+      } catch (err) {
+        this._stopProcedure();
+        this._error(err);
+        this._parent?.send(error(this.id, err));
+        return this;
+      }
     }
 
     // TODO: this notifies all subscribers but usually this is redundant
@@ -1151,23 +1197,30 @@ class Interpreter {
     return this;
   }
   _process(event) {
+    // TODO: reexamine what happens when an action (or a guard or smth) throws
+    let nextState;
+    let caughtError;
     try {
-      const nextState = this.logic.transition(this._state, event, this._actorContext);
-      this.update(nextState);
-      if (event.type === stopSignalType) {
-        this._stopProcedure();
-        this._complete();
-      }
+      nextState = this.logic.transition(this._state, event, this._actorContext);
     } catch (err) {
-      // TODO: properly handle errors
-      if (this.observers.size > 0) {
-        this.observers.forEach(observer => {
-          observer.error?.(err);
-        });
-        this.stop();
-      } else {
-        throw err;
-      }
+      // we wrap it in a box so we can rethrow it later even if falsy value gets caught here
+      caughtError = {
+        err
+      };
+    }
+    if (caughtError) {
+      const {
+        err
+      } = caughtError;
+      this._stopProcedure();
+      this._error(err);
+      this._parent?.send(error(this.id, err));
+      return;
+    }
+    this.update(nextState);
+    if (event.type === stopSignalType) {
+      this._stopProcedure();
+      this._complete();
     }
   }
   _stop() {
@@ -1186,7 +1239,7 @@ class Interpreter {
   }
 
   /**
-   * Stops the interpreter and unsubscribe all listeners.
+   * Stops the Actor and unsubscribe all listeners.
    */
   stop() {
     if (this._parent) {
@@ -1196,19 +1249,39 @@ class Interpreter {
   }
   _complete() {
     for (const observer of this.observers) {
-      observer.complete?.();
+      try {
+        observer.complete?.();
+      } catch (err) {
+        reportUnhandledError(err);
+      }
     }
     this.observers.clear();
   }
-  _error(data) {
+  _error(err) {
+    if (!this.observers.size) {
+      if (!this._parent) {
+        reportUnhandledError(err);
+      }
+      return;
+    }
+    let reportError = false;
     for (const observer of this.observers) {
-      observer.error?.(data);
+      const errorListener = observer.error;
+      reportError ||= !errorListener;
+      try {
+        errorListener?.(err);
+      } catch (err2) {
+        reportUnhandledError(err2);
+      }
     }
     this.observers.clear();
+    if (reportError) {
+      reportUnhandledError(err);
+    }
   }
   _stopProcedure() {
     if (this.status !== ActorStatus.Running) {
-      // Interpreter already stopped; do nothing
+      // Actor already stopped; do nothing
       return this;
     }
 
@@ -1230,7 +1303,7 @@ class Interpreter {
   }
 
   /**
-   * Sends an event to the running interpreter to trigger a transition.
+   * Sends an event to the running Actor to trigger a transition.
    *
    * @param event The event to send
    */
@@ -1301,17 +1374,28 @@ class Interpreter {
 }
 
 /**
- * Creates a new Interpreter instance for the given machine with the provided options, if any.
+ * Creates a new `ActorRef` instance for the given machine with the provided options, if any.
  *
- * @param machine The machine to interpret
- * @param options Interpreter options
+ * @param machine The machine to create an actor from
+ * @param options `ActorRef` options
  */
 
-function interpret(logic, options) {
-  const interpreter = new Interpreter(logic, options);
+function createActor(logic, options) {
+  const interpreter = new Actor(logic, options);
   return interpreter;
 }
 
+/**
+ * Creates a new Interpreter instance for the given machine with the provided options, if any.
+ *
+ * @deprecated Use `createActor` instead
+ */
+const interpret = createActor;
+
+/**
+ * @deprecated Use `Actor` instead.
+ */
+
 function resolve$6(actorContext, state, actionArgs, {
   id,
   systemId,
@@ -1323,7 +1407,7 @@ function resolve$6(actorContext, state, actionArgs, {
   if (referenced) {
     // TODO: inline `input: undefined` should win over the referenced one
     const configuredInput = input || referenced.input;
-    actorRef = interpret(referenced.src, {
+    actorRef = createActor(referenced.src, {
       id,
       src,
       parent: actorContext?.self,
@@ -1526,10 +1610,10 @@ function toGuardDefinition(guardConfig, getPredicate) {
   }
 }
 
-function getOutput(configuration, context, event) {
+function getOutput(configuration, context, event, self) {
   const machine = configuration[0].machine;
   const finalChildStateNode = configuration.find(stateNode => stateNode.type === 'final' && stateNode.parent === machine.root);
-  return finalChildStateNode && finalChildStateNode.output ? mapContext(finalChildStateNode.output, context, event) : undefined;
+  return finalChildStateNode && finalChildStateNode.output ? mapContext(finalChildStateNode.output, context, event, self) : undefined;
 }
 const isAtomicStateNode = stateNode => stateNode.type === 'atomic' || stateNode.type === 'final';
 function getChildren(stateNode) {
@@ -2145,7 +2229,7 @@ function microstepProcedure(transitions, currentState, mutConfiguration, event,
   actions.push(...filteredTransitions.flatMap(t => t.actions));
 
   // Enter states
-  enterStates(event, filteredTransitions, mutConfiguration, actions, internalQueue, currentState, historyValue, isInitial);
+  enterStates(event, filteredTransitions, mutConfiguration, actions, internalQueue, currentState, historyValue, isInitial, actorCtx);
   const nextConfiguration = [...mutConfiguration];
   const done = isInFinalState(nextConfiguration);
   if (done) {
@@ -2154,7 +2238,7 @@ function microstepProcedure(transitions, currentState, mutConfiguration, event,
   }
   try {
     const nextState = resolveActionsAndContext(actions, event, currentState, actorCtx);
-    const output = done ? getOutput(nextConfiguration, nextState.context, event) : undefined;
+    const output = done ? getOutput(nextConfiguration, nextState.context, event, actorCtx.self) : undefined;
     internalQueue.push(...nextState._internalQueue);
     return cloneState(currentState, {
       configuration: nextConfiguration,
@@ -2171,7 +2255,7 @@ function microstepProcedure(transitions, currentState, mutConfiguration, event,
     throw e;
   }
 }
-function enterStates(event, filteredTransitions, mutConfiguration, actions, internalQueue, currentState, historyValue, isInitial) {
+function enterStates(event, filteredTransitions, mutConfiguration, actions, internalQueue, currentState, historyValue, isInitial, actorContext) {
   const statesToEnter = new Set();
   const statesForDefaultEntry = new Set();
   computeEntrySet(filteredTransitions, historyValue, statesForDefaultEntry, statesToEnter);
@@ -2199,7 +2283,7 @@ function enterStates(event, filteredTransitions, mutConfiguration, actions, inte
       if (!parent.parent) {
         continue;
       }
-      internalQueue.push(done(parent.id, stateNodeToEnter.output ? mapContext(stateNodeToEnter.output, currentState.context, event) : undefined));
+      internalQueue.push(done(parent.id, stateNodeToEnter.output ? mapContext(stateNodeToEnter.output, currentState.context, event, actorContext.self) : undefined));
       if (parent.parent) {
         const grandparent = parent.parent;
         if (grandparent.type === 'parallel') {
@@ -2519,6 +2603,7 @@ class State {
     this.value = void 0;
     this.done = void 0;
     this.output = void 0;
+    this.error = void 0;
     this.context = void 0;
     this.historyValue = {};
     this._internalQueue = void 0;
@@ -2535,6 +2620,7 @@ class State {
     this.tags = new Set(flatten(this.configuration.map(sn => sn.tags)));
     this.done = config.done ?? false;
     this.output = config.output;
+    this.error = config.error;
   }
 
   /**
@@ -2747,7 +2833,7 @@ function createSpawner(actorContext, {
       const input = 'input' in options ? options.input : referenced.input;
 
       // TODO: this should also receive `src`
-      const actor = interpret(referenced.src, {
+      const actor = createActor(referenced.src, {
         id: options.id,
         parent: actorContext.self,
         input: typeof input === 'function' ? input({
@@ -2761,7 +2847,7 @@ function createSpawner(actorContext, {
       return actor;
     } else {
       // TODO: this should also receive `src`
-      return interpret(src, {
+      return createActor(src, {
         id: options.id,
         parent: actorContext.self,
         input: options.input,
@@ -2984,9 +3070,10 @@ function createInitEvent(input) {
   };
 }
 
+exports.Actor = Actor;
 exports.ActorStatus = ActorStatus;
 exports.ConstantPrefix = ConstantPrefix;
-exports.Interpreter = Interpreter;
+exports.InterpreterStatus = InterpreterStatus;
 exports.NULL_EVENT = NULL_EVENT;
 exports.STATE_DELIMITER = STATE_DELIMITER;
 exports.SpecialTargets = SpecialTargets;
@@ -2996,7 +3083,9 @@ exports.and = and;
 exports.assign = assign;
 exports.cancel = cancel;
 exports.choose = choose;
+exports.cloneState = cloneState;
 exports.constantPrefixes = constantPrefixes;
+exports.createActor = createActor;
 exports.createEmptyActor = createEmptyActor;
 exports.createInitEvent = createInitEvent;
 exports.createInvokeId = createInvokeId;