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

package/dist/{actions-b299d008.development.esm.js → actions-d4305983.development.esm.js}

@@ -1,5 +1,17 @@
 import { devToolsAdapter } from '../dev/dist/xstate-dev.development.esm.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
 
 /**
@@ -420,27 +432,18 @@ 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;
-    }
+  if (typeof mapper === 'object' && Object.values(mapper).some(val => typeof val === 'function')) {
+    console.warn(`Dynamically mapping values to individual properties is deprecated. Use a single function that returns the mapped object instead.\nFound object containing properties whose values are possibly mapping functions: ${Object.entries(mapper).filter(([key, value]) => typeof value === 'function').map(([key, value]) => `\n - ${key}: ${value.toString().replace(/\n\s*/g, '')}`).join('')}`);
   }
-  return result;
+  return mapper;
 }
 function isPromiseLike(value) {
   if (value instanceof Promise) {
@@ -492,13 +495,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) {
@@ -512,7 +514,7 @@ function resolveReferencedActor(referenced) {
 }
 
 function fromCallback(invokeCallback) {
-  const logic = {
+  return {
     config: invokeCallback,
     start: (_state, {
       self
@@ -578,19 +580,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,
@@ -620,6 +623,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:
@@ -697,7 +701,6 @@ function fromObservable(observableCreator) {
       subscription: undefined
     })
   };
-  return logic;
 }
 
 /**
@@ -714,7 +717,7 @@ function fromEventObservable(lazyObservable) {
   const completeEventType = '$$xstate.complete';
 
   // TODO: event types
-  const logic = {
+  return {
     config: lazyObservable,
     transition: (state, event) => {
       if (state.status !== 'active') {
@@ -727,6 +730,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:
@@ -801,7 +805,6 @@ function fromEventObservable(lazyObservable) {
       subscription: undefined
     })
   };
-  return logic;
 }
 
 const resolveEventType = '$$xstate.resolve';
@@ -829,6 +832,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:
@@ -935,7 +939,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() {
@@ -978,6 +995,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: {
@@ -991,9 +1013,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.
    */
 
   /**
@@ -1017,10 +1039,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;
@@ -1084,7 +1106,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();
@@ -1106,29 +1128,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: () => {
@@ -1138,7 +1169,7 @@ class Interpreter {
   }
 
   /**
-   * Starts the interpreter from the initial state
+   * Starts the Actor from the initial state
    */
   start() {
     if (this.status === ActorStatus.Running) {
@@ -1150,8 +1181,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
@@ -1165,23 +1214,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() {
@@ -1200,7 +1256,7 @@ class Interpreter {
   }
 
   /**
-   * Stops the interpreter and unsubscribe all listeners.
+   * Stops the Actor and unsubscribe all listeners.
    */
   stop() {
     if (this._parent) {
@@ -1210,19 +1266,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;
     }
 
@@ -1244,7 +1320,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
    */
@@ -1320,17 +1396,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,
@@ -1342,7 +1429,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,
@@ -1551,10 +1638,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) {
@@ -2181,7 +2268,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) {
@@ -2190,7 +2277,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,
@@ -2207,7 +2294,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);
@@ -2235,7 +2322,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') {
@@ -2558,6 +2645,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;
@@ -2574,6 +2662,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;
   }
 
   /**
@@ -2795,7 +2884,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({
@@ -2809,7 +2898,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,
@@ -3044,4 +3133,4 @@ function createInitEvent(input) {
   };
 }
 
-export { fromEventObservable as $, isAtomicStateNode as A, error as B, isStateId as C, getStateNodeByPath as D, getPersistedState as E, resolveReferencedActor as F, interpret as G, matchesState as H, sendTo as I, sendParent as J, forwardTo as K, Interpreter as L, ActorStatus as M, NULL_EVENT as N, doneInvoke as O, cancel as P, choose as Q, log as R, STATE_DELIMITER as S, pure as T, raise as U, stop as V, pathToStateValue as W, toObserver as X, fromPromise as Y, fromObservable as Z, fromCallback as _, toTransitionConfigArray as a, fromTransition as a0, stateIn as a1, not as a2, and as a3, or as a4, ConstantPrefix as a5, SpecialTargets as a6, startSignalType as a7, stopSignalType as a8, startSignal as a9, stopSignal as aa, isSignal as ab, isActorRef as ac, toActorRef as ad, createEmptyActor as ae, toGuardDefinition as af, constantPrefixes as ag, after as ah, done as ai, escalate as aj, formatTransition as b, memo as c, flatten as d, evaluateGuard as e, formatTransitions as f, createInvokeId as g, getDelayedTransitions as h, formatInitialTransition as i, getCandidates as j, toInvokeConfig as k, getConfiguration as l, mapValues as m, getStateNodes as n, isInFinalState as o, State as p, isErrorEvent as q, resolveStateValue as r, macrostep as s, toArray as t, transitionNode as u, getInitialConfiguration as v, resolveActionsAndContext as w, assign as x, createInitEvent as y, microstep as z };
+export { fromObservable as $, microstep as A, isAtomicStateNode as B, isStateId as C, getStateNodeByPath as D, getPersistedState as E, resolveReferencedActor as F, createActor as G, matchesState as H, sendTo as I, sendParent as J, forwardTo as K, interpret as L, Actor as M, NULL_EVENT as N, ActorStatus as O, InterpreterStatus as P, doneInvoke as Q, cancel as R, STATE_DELIMITER as S, choose as T, log as U, pure as V, raise as W, stop as X, pathToStateValue as Y, toObserver as Z, fromPromise as _, toTransitionConfigArray as a, fromCallback as a0, fromEventObservable as a1, fromTransition as a2, stateIn as a3, not as a4, and as a5, or as a6, ConstantPrefix as a7, SpecialTargets as a8, startSignalType as a9, stopSignalType as aa, startSignal as ab, stopSignal as ac, isSignal as ad, isActorRef as ae, toActorRef as af, createEmptyActor as ag, toGuardDefinition as ah, constantPrefixes as ai, after as aj, done as ak, error as al, escalate as am, formatTransition as b, memo as c, flatten as d, evaluateGuard as e, formatTransitions as f, createInvokeId as g, getDelayedTransitions as h, formatInitialTransition as i, getCandidates as j, toInvokeConfig as k, getConfiguration as l, mapValues as m, getStateNodes as n, isInFinalState as o, State as p, isErrorEvent as q, resolveStateValue as r, cloneState as s, toArray as t, macrostep as u, transitionNode as v, getInitialConfiguration as w, resolveActionsAndContext as x, assign as y, createInitEvent as z };