xstate 5.0.0-beta.27 → 5.0.0-beta.29

package/dist/interpreter-498891b2.esm.js

@@ -0,0 +1,741 @@
+import { devToolsAdapter } from '../dev/dist/xstate-dev.esm.js';
+
+const STATE_DELIMITER = '.';
+const TARGETLESS_KEY = '';
+const NULL_EVENT = '';
+const STATE_IDENTIFIER = '#';
+const WILDCARD = '*';
+const XSTATE_INIT = 'xstate.init';
+const XSTATE_ERROR = 'xstate.error';
+const XSTATE_STOP = 'xstate.stop';
+
+/**
+ * Returns an event that represents an implicit event that
+ * is sent after the specified `delay`.
+ *
+ * @param delayRef The delay in milliseconds
+ * @param id The state node ID where this event is handled
+ */
+function createAfterEvent(delayRef, id) {
+  const idSuffix = id ? `#${id}` : '';
+  return {
+    type: `xstate.after(${delayRef})${idSuffix}`
+  };
+}
+
+/**
+ * Returns an event that represents that a final state node
+ * has been reached in the parent state node.
+ *
+ * @param id The final state node's parent state node `id`
+ * @param output The data to pass into the event
+ */
+function createDoneStateEvent(id, output) {
+  return {
+    type: `xstate.done.state.${id}`,
+    output
+  };
+}
+
+/**
+ * Returns an event that represents that an invoked service has terminated.
+ *
+ * An invoked service is terminated when it has reached a top-level final state node,
+ * but not when it is canceled.
+ *
+ * @param invokeId The invoked service ID
+ * @param output The data to pass into the event
+ */
+function createDoneActorEvent(invokeId, output) {
+  return {
+    type: `xstate.done.actor.${invokeId}`,
+    output
+  };
+}
+function createErrorActorEvent(id, data) {
+  return {
+    type: `xstate.error.actor.${id}`,
+    data
+  };
+}
+function createInitEvent(input) {
+  return {
+    type: XSTATE_INIT,
+    input
+  };
+}
+
+class Mailbox {
+  constructor(_process) {
+    this._process = _process;
+    this._active = false;
+    this._current = null;
+    this._last = null;
+  }
+  start() {
+    this._active = true;
+    this.flush();
+  }
+  clear() {
+    // we can't set _current to null because we might be currently processing
+    // and enqueue following clear shouldnt start processing the enqueued item immediately
+    if (this._current) {
+      this._current.next = null;
+      this._last = this._current;
+    }
+  }
+
+  // TODO: rethink this design
+  prepend(event) {
+    if (!this._current) {
+      this.enqueue(event);
+      return;
+    }
+
+    // we know that something is already queued up
+    // so the mailbox is already flushing or it's inactive
+    // therefore the only thing that we need to do is to reassign `this._current`
+    this._current = {
+      value: event,
+      next: this._current
+    };
+  }
+  enqueue(event) {
+    const enqueued = {
+      value: event,
+      next: null
+    };
+    if (this._current) {
+      this._last.next = enqueued;
+      this._last = enqueued;
+      return;
+    }
+    this._current = enqueued;
+    this._last = enqueued;
+    if (this._active) {
+      this.flush();
+    }
+  }
+  flush() {
+    while (this._current) {
+      // atm the given _process is responsible for implementing proper try/catch handling
+      // we assume here that this won't throw in a way that can affect this mailbox
+      const consumed = this._current;
+      this._process(consumed.value);
+      // something could have been prepended in the meantime
+      // so we need to be defensive here to avoid skipping over a prepended item
+      if (consumed === this._current) {
+        this._current = this._current.next;
+      }
+    }
+    this._last = null;
+  }
+}
+
+/**
+ * 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;
+  });
+}
+
+const symbolObservable = (() => typeof Symbol === 'function' && Symbol.observable || '@@observable')();
+
+function createSystem() {
+  let sessionIdCounter = 0;
+  const children = new Map();
+  const keyedActors = new Map();
+  const reverseKeyedActors = new WeakMap();
+  const system = {
+    _bookId: () => `x:${sessionIdCounter++}`,
+    _register: (sessionId, actorRef) => {
+      children.set(sessionId, actorRef);
+      return sessionId;
+    },
+    _unregister: actorRef => {
+      children.delete(actorRef.sessionId);
+      const systemId = reverseKeyedActors.get(actorRef);
+      if (systemId !== undefined) {
+        keyedActors.delete(systemId);
+        reverseKeyedActors.delete(actorRef);
+      }
+    },
+    get: systemId => {
+      return keyedActors.get(systemId);
+    },
+    _set: (systemId, actorRef) => {
+      const existing = keyedActors.get(systemId);
+      if (existing && existing !== actorRef) {
+        throw new Error(`Actor with system ID '${systemId}' already exists.`);
+      }
+      keyedActors.set(systemId, actorRef);
+      reverseKeyedActors.set(actorRef, systemId);
+    }
+  };
+  return system;
+}
+
+function matchesState(parentStateId, childStateId) {
+  const parentStateValue = toStateValue(parentStateId);
+  const childStateValue = toStateValue(childStateId);
+  if (typeof childStateValue === 'string') {
+    if (typeof parentStateValue === 'string') {
+      return childStateValue === parentStateValue;
+    }
+
+    // Parent more specific than child
+    return false;
+  }
+  if (typeof parentStateValue === 'string') {
+    return parentStateValue in childStateValue;
+  }
+  return Object.keys(parentStateValue).every(key => {
+    if (!(key in childStateValue)) {
+      return false;
+    }
+    return matchesState(parentStateValue[key], childStateValue[key]);
+  });
+}
+function toStatePath(stateId) {
+  try {
+    if (isArray(stateId)) {
+      return stateId;
+    }
+    return stateId.toString().split(STATE_DELIMITER);
+  } catch (e) {
+    throw new Error(`'${stateId}' is not a valid state path.`);
+  }
+}
+function isStateLike(state) {
+  return typeof state === 'object' && 'value' in state && 'context' in state && 'event' in state;
+}
+function toStateValue(stateValue) {
+  if (isStateLike(stateValue)) {
+    return stateValue.value;
+  }
+  if (isArray(stateValue)) {
+    return pathToStateValue(stateValue);
+  }
+  if (typeof stateValue !== 'string') {
+    return stateValue;
+  }
+  const statePath = toStatePath(stateValue);
+  return pathToStateValue(statePath);
+}
+function pathToStateValue(statePath) {
+  if (statePath.length === 1) {
+    return statePath[0];
+  }
+  const value = {};
+  let marker = value;
+  for (let i = 0; i < statePath.length - 1; i++) {
+    if (i === statePath.length - 2) {
+      marker[statePath[i]] = statePath[i + 1];
+    } else {
+      const previous = marker;
+      marker = {};
+      previous[statePath[i]] = marker;
+    }
+  }
+  return value;
+}
+function mapValues(collection, iteratee) {
+  const result = {};
+  const collectionKeys = Object.keys(collection);
+  for (let i = 0; i < collectionKeys.length; i++) {
+    const key = collectionKeys[i];
+    result[key] = iteratee(collection[key], key, collection, i);
+  }
+  return result;
+}
+function flatten(array) {
+  return [].concat(...array);
+}
+function toArrayStrict(value) {
+  if (isArray(value)) {
+    return value;
+  }
+  return [value];
+}
+function toArray(value) {
+  if (value === undefined) {
+    return [];
+  }
+  return toArrayStrict(value);
+}
+function mapContext(mapper, context, event, self) {
+  if (typeof mapper === 'function') {
+    return mapper({
+      context,
+      event,
+      self
+    });
+  }
+  return mapper;
+}
+function isArray(value) {
+  return Array.isArray(value);
+}
+function isErrorActorEvent(event) {
+  return event.type.startsWith('xstate.error.actor');
+}
+function toTransitionConfigArray(configLike) {
+  return toArrayStrict(configLike).map(transitionLike => {
+    if (typeof transitionLike === 'undefined' || typeof transitionLike === 'string') {
+      return {
+        target: transitionLike
+      };
+    }
+    return transitionLike;
+  });
+}
+function normalizeTarget(target) {
+  if (target === undefined || target === TARGETLESS_KEY) {
+    return undefined;
+  }
+  return toArray(target);
+}
+function toObserver(nextHandler, errorHandler, completionHandler) {
+  const isObserver = typeof nextHandler === 'object';
+  const self = isObserver ? nextHandler : undefined;
+  return {
+    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) {
+  return `${stateNodeId}:invocation[${index}]`;
+}
+function resolveReferencedActor(referenced) {
+  return referenced ? 'transition' in referenced ? {
+    src: referenced,
+    input: undefined
+  } : referenced : undefined;
+}
+
+let ActorStatus = /*#__PURE__*/function (ActorStatus) {
+  ActorStatus[ActorStatus["NotStarted"] = 0] = "NotStarted";
+  ActorStatus[ActorStatus["Running"] = 1] = "Running";
+  ActorStatus[ActorStatus["Stopped"] = 2] = "Stopped";
+  return ActorStatus;
+}({});
+
+/**
+ * @deprecated Use `ActorStatus` instead.
+ */
+const InterpreterStatus = ActorStatus;
+const defaultOptions = {
+  clock: {
+    setTimeout: (fn, ms) => {
+      return setTimeout(fn, ms);
+    },
+    clearTimeout: id => {
+      return clearTimeout(id);
+    }
+  },
+  logger: console.log.bind(console),
+  devTools: false
+};
+class Actor {
+  /**
+   * The current internal state of the actor.
+   */
+
+  /**
+   * The clock that is responsible for setting and clearing timeouts, such as delayed events and transitions.
+   */
+
+  /**
+   * The unique identifier for this actor relative to its parent.
+   */
+
+  /**
+   * Whether the service is started.
+   */
+
+  // Actor Ref
+
+  // TODO: add typings for system
+
+  /**
+   * The globally unique process ID for this invocation.
+   */
+
+  /**
+   * Creates a new actor instance for the given logic with the provided options, if any.
+   *
+   * @param logic The logic to create an actor from
+   * @param options Actor options
+   */
+  constructor(logic, options) {
+    this.logic = logic;
+    this._state = void 0;
+    this.clock = void 0;
+    this.options = void 0;
+    this.id = void 0;
+    this.mailbox = new Mailbox(this._process.bind(this));
+    this.delayedEventsMap = {};
+    this.observers = new Set();
+    this.logger = void 0;
+    this.status = ActorStatus.NotStarted;
+    this._parent = void 0;
+    this.ref = void 0;
+    this._actorContext = void 0;
+    this._systemId = void 0;
+    this.sessionId = void 0;
+    this.system = void 0;
+    this._doneEvent = void 0;
+    this.src = void 0;
+    this._deferred = [];
+    const resolvedOptions = {
+      ...defaultOptions,
+      ...options
+    };
+    const {
+      clock,
+      logger,
+      parent,
+      id,
+      systemId
+    } = resolvedOptions;
+    const self = this;
+    this.system = parent?.system ?? createSystem();
+    if (systemId) {
+      this._systemId = systemId;
+      this.system._set(systemId, this);
+    }
+    this.sessionId = this.system._bookId();
+    this.id = id ?? this.sessionId;
+    this.logger = logger;
+    this.clock = clock;
+    this._parent = parent;
+    this.options = resolvedOptions;
+    this.src = resolvedOptions.src;
+    this.ref = this;
+    this._actorContext = {
+      self,
+      id: this.id,
+      sessionId: this.sessionId,
+      logger: this.logger,
+      defer: fn => {
+        this._deferred.push(fn);
+      },
+      system: this.system,
+      stopChild: child => {
+        if (child._parent !== this) {
+          throw new Error(`Cannot stop child actor ${child.id} of ${this.id} because it is not a child`);
+        }
+        child._stop();
+      }
+    };
+
+    // Ensure that the send method is bound to this Actor instance
+    // if destructured
+    this.send = this.send.bind(this);
+    this._initState();
+  }
+  _initState() {
+    this._state = this.options.state ? this.logic.restoreState ? this.logic.restoreState(this.options.state, this._actorContext) : this.options.state : this.logic.getInitialState(this._actorContext, this.options?.input);
+  }
+
+  // array of functions to defer
+
+  update(state) {
+    // Update state
+    this._state = state;
+    const snapshot = this.getSnapshot();
+
+    // Execute deferred effects
+    let deferredFn;
+    while (deferredFn = this._deferred.shift()) {
+      deferredFn();
+    }
+    for (const observer of this.observers) {
+      // 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 = createDoneActorEvent(this.id, status.data);
+        this._parent?.send(this._doneEvent);
+        break;
+      case 'error':
+        this._stopProcedure();
+        this._error(status.data);
+        this._parent?.send(createErrorActorEvent(this.id, status.data));
+        break;
+    }
+  }
+  subscribe(nextListenerOrObserver, errorListener, completeListener) {
+    const observer = toObserver(nextListenerOrObserver, errorListener, completeListener);
+    if (this.status !== ActorStatus.Stopped) {
+      this.observers.add(observer);
+    } else {
+      try {
+        observer.complete?.();
+      } catch (err) {
+        reportUnhandledError(err);
+      }
+    }
+    return {
+      unsubscribe: () => {
+        this.observers.delete(observer);
+      }
+    };
+  }
+
+  /**
+   * Starts the Actor from the initial state
+   */
+  start() {
+    if (this.status === ActorStatus.Running) {
+      // Do not restart the service if it is already started
+      return this;
+    }
+    this.system._register(this.sessionId, this);
+    if (this._systemId) {
+      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) {
+      try {
+        this.logic.start(this._state, this._actorContext);
+      } catch (err) {
+        this._stopProcedure();
+        this._error(err);
+        this._parent?.send(createErrorActorEvent(this.id, err));
+        return this;
+      }
+    }
+
+    // TODO: this notifies all subscribers but usually this is redundant
+    // there is no real change happening here
+    // we need to rethink if this needs to be refactored
+    this.update(this._state);
+    if (this.options.devTools) {
+      this.attachDevTools();
+    }
+    this.mailbox.start();
+    return this;
+  }
+  _process(event) {
+    // TODO: reexamine what happens when an action (or a guard or smth) throws
+    let nextState;
+    let caughtError;
+    try {
+      nextState = this.logic.transition(this._state, event, this._actorContext);
+    } catch (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(createErrorActorEvent(this.id, err));
+      return;
+    }
+    this.update(nextState);
+    if (event.type === XSTATE_STOP) {
+      this._stopProcedure();
+      this._complete();
+    }
+  }
+  _stop() {
+    if (this.status === ActorStatus.Stopped) {
+      return this;
+    }
+    this.mailbox.clear();
+    if (this.status === ActorStatus.NotStarted) {
+      this.status = ActorStatus.Stopped;
+      return this;
+    }
+    this.mailbox.enqueue({
+      type: XSTATE_STOP
+    });
+    return this;
+  }
+
+  /**
+   * Stops the Actor and unsubscribe all listeners.
+   */
+  stop() {
+    if (this._parent) {
+      throw new Error('A non-root actor cannot be stopped directly.');
+    }
+    return this._stop();
+  }
+  _complete() {
+    for (const observer of this.observers) {
+      try {
+        observer.complete?.();
+      } catch (err) {
+        reportUnhandledError(err);
+      }
+    }
+    this.observers.clear();
+  }
+  _error(err) {
+    if (!this.observers.size) {
+      if (!this._parent) {
+        reportUnhandledError(err);
+      }
+      return;
+    }
+    let reportError = false;
+    for (const observer of this.observers) {
+      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) {
+      // Actor already stopped; do nothing
+      return this;
+    }
+
+    // Cancel all delayed events
+    for (const key of Object.keys(this.delayedEventsMap)) {
+      this.clock.clearTimeout(this.delayedEventsMap[key]);
+    }
+
+    // TODO: mailbox.reset
+    this.mailbox.clear();
+    // TODO: after `stop` we must prepare ourselves for receiving events again
+    // events sent *after* stop signal must be queued
+    // it seems like this should be the common behavior for all of our consumers
+    // so perhaps this should be unified somehow for all of them
+    this.mailbox = new Mailbox(this._process.bind(this));
+    this.status = ActorStatus.Stopped;
+    this.system._unregister(this);
+    return this;
+  }
+
+  /**
+   * Sends an event to the running Actor to trigger a transition.
+   *
+   * @param event The event to send
+   */
+  send(event) {
+    if (typeof event === 'string') {
+      throw new Error(`Only event objects may be sent to actors; use .send({ type: "${event}" }) instead`);
+    }
+    if (this.status === ActorStatus.Stopped) {
+      return;
+    }
+    this.mailbox.enqueue(event);
+  }
+
+  // TODO: make private (and figure out a way to do this within the machine)
+  delaySend({
+    event,
+    id,
+    delay,
+    to
+  }) {
+    const timerId = this.clock.setTimeout(() => {
+      if (to) {
+        to.send(event);
+      } else {
+        this.send(event);
+      }
+    }, delay);
+
+    // TODO: consider the rehydration story here
+    if (id) {
+      this.delayedEventsMap[id] = timerId;
+    }
+  }
+
+  // TODO: make private (and figure out a way to do this within the machine)
+  cancel(sendId) {
+    this.clock.clearTimeout(this.delayedEventsMap[sendId]);
+    delete this.delayedEventsMap[sendId];
+  }
+  attachDevTools() {
+    const {
+      devTools
+    } = this.options;
+    if (devTools) {
+      const resolvedDevToolsAdapter = typeof devTools === 'function' ? devTools : devToolsAdapter;
+      resolvedDevToolsAdapter(this);
+    }
+  }
+  toJSON() {
+    return {
+      id: this.id
+    };
+  }
+  getPersistedState() {
+    return this.logic.getPersistedState?.(this._state);
+  }
+  [symbolObservable]() {
+    return this;
+  }
+  getSnapshot() {
+    return this.logic.getSnapshot ? this.logic.getSnapshot(this._state) : this._state;
+  }
+}
+
+/**
+ * Creates a new `ActorRef` instance for the given machine with the provided options, if any.
+ *
+ * @param machine The machine to create an actor from
+ * @param options `ActorRef` 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.
+ */
+
+export { Actor as A, InterpreterStatus as I, NULL_EVENT as N, STATE_DELIMITER as S, WILDCARD as W, XSTATE_INIT as X, toTransitionConfigArray as a, createInitEvent as b, createInvokeId as c, createActor as d, matchesState as e, ActorStatus as f, interpret as g, toObserver as h, isErrorActorEvent as i, XSTATE_STOP as j, createErrorActorEvent as k, toStateValue as l, mapValues as m, STATE_IDENTIFIER as n, normalizeTarget as o, pathToStateValue as p, toStatePath as q, resolveReferencedActor as r, createDoneStateEvent as s, toArray as t, mapContext as u, isArray as v, createAfterEvent as w, flatten as x, XSTATE_ERROR as y };