@xstate/effect 1.0.0-alpha.9 → 1.0.0-beta.1

package/dist/{state-a2e5cb31.js → state-83513b45.js}

@@ -1,13 +1,97 @@
-import { Queue, Effect, Fiber, Scope, Exit, Cause, Context, Clock, Duration, Data } from 'effect';
-import { stopActor, terminateActor, deliverEvent, isMachineSnapshot } from 'xstate';
+import { Cause, Data, Queue, Effect, Exit, Fiber, Scope, Context, Clock, Duration } from 'effect';
+import { StateMachine, stopActor, terminateActor, deliverEvent, isMachineSnapshot } from 'xstate';
 import { createDurable } from 'xstate/durable';
 
-/** A mailbox item that reports a failed fire-and-forget action. */
+function _checkPrivateRedeclaration(e, t) {
+  if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object");
+}
+
+function _classPrivateFieldInitSpec(e, t, a) {
+  _checkPrivateRedeclaration(e, t), t.set(e, a);
+}
+
+function _checkInRHS(e) {
+  if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null"));
+  return e;
+}
+
+function _assertClassBrand(e, t, n) {
+  if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n;
+  throw new TypeError("Private element is not present on this object");
+}
+
+function _classPrivateFieldGet2(s, a) {
+  return s.get(_assertClassBrand(s, a));
+}
+
+var _effectFailure = /*#__PURE__*/new WeakMap();
+/**
+ * Preserves an Effect failure, defect or interruption through XState error routing.
+ *
+ * @experimental
+ */
+class EffectFailure extends Error {
+  static is(value) {
+    return typeof value === 'object' && value !== null && _effectFailure.has(_checkInRHS(value)) && _classPrivateFieldGet2(_effectFailure, value);
+  }
+  constructor(cause) {
+    super(Cause.pretty(cause));
+    this.cause = cause;
+    this._tag = 'EffectFailure';
+    _classPrivateFieldInitSpec(this, _effectFailure, true);
+    this.name = 'EffectFailure';
+  }
+}
+
+/**
+ * @deprecated Inspect `EffectFailure.cause` for interruption instead.
+ *
+ * @experimental
+ */
+class EffectInterruptedError extends Data.TaggedError('EffectInterruptedError') {
+  get message() {
+    return 'Effect was interrupted before the actor completed';
+  }
+}
+
+/**
+ * Reported by `waitFor` when the actor stops or errors before a snapshot
+ * matches, and by `join` when the actor stops without output. `join` reports
+ * an errored actor's outcome instead, preserving an Effect failure's Cause.
+ *
+ * @experimental
+ */
+class ActorStoppedError extends Data.TaggedError('ActorStoppedError') {
+  get message() {
+    return `Actor "${this.actorId}" ${this.snapshot.status === 'error' ? 'errored' : 'stopped'} before completing`;
+  }
+}
+
+/**
+ * Reported by the `send` atom of `createActorAtoms` when an event is sent
+ * before the actor's runtime has finished building.
+ *
+ * @experimental
+ */
+class NotReadyError extends Data.TaggedError('NotReadyError') {
+  get message() {
+    return 'The actor is not ready yet';
+  }
+}
 
-const actionFailure = Symbol.for('@xstate/effect/actionFailure');
-function isActionFailure(value) {
-  return typeof value === 'object' && value !== null && actionFailure in value;
+/** @internal */
+function causeFromError(error) {
+  return error instanceof EffectFailure ? error.cause : Cause.fail(error);
 }
+/**
+ * An event rejected at the actor's delivery boundary.
+ *
+ * @experimental
+ */
+class EventRejectedError extends Data.TaggedError('EventRejectedError') {}
+
+/** @internal */
+
 const symbolObservable = (() => typeof Symbol === 'function' && Symbol.observable || '@@observable')();
 
 /**
@@ -39,6 +123,8 @@ function toObserver(nextHandler, errorHandler, completionHandler) {
  * contract (`send`, `getSnapshot`, `subscribe`, `on`), so it works with
  * `useSelector`, this package's actor functions and the inspection APIs, while
  * the actor itself is driven by an Effect fiber over pure transitions.
+ *
+ * @experimental
  */
 class EffectActor {
   constructor(logic, root, snapshot, _mailbox, _stopExecution, _inspectors) {
@@ -57,6 +143,10 @@ class EffectActor {
     this._observers = new Set();
     this._listeners = new Map();
     this._settled = false;
+    this._pending = new Set();
+    this._inStep = false;
+    this._deliveryDepth = 0;
+    this._stopHeld = false;
     this._root = root;
     this.id = root.id;
     this.address = root.address;
@@ -73,15 +163,76 @@ class EffectActor {
 
   /** Sends an event; the actor processes it on its own fiber. */
   send(event) {
+    if (this._deliveryError(event)) return;
+    Queue.offerUnsafe(this._mailbox, {
+      kind: 'event',
+      event
+    });
+  }
+
+  /** @internal */
+  _sendAndAwait(event) {
+    return Effect.callback(resume => {
+      const error = this._deliveryError(event);
+      if (error) {
+        resume(Effect.fail(error));
+        return;
+      }
+      const receipt = {
+        resume: exit => resume(exit)
+      };
+      this._pending.add(receipt);
+      Queue.offerUnsafe(this._mailbox, {
+        kind: 'event',
+        event,
+        receipt
+      });
+      return Effect.sync(() => {
+        this._pending.delete(receipt);
+        receipt.resume = undefined;
+      });
+    });
+  }
+  _deliveryError(event) {
     if (this._settled) {
       this.system.deadLetter(undefined, this._root, event, 'stopped');
-      return;
+      return this._stoppedError();
+    }
+    if (this.logic instanceof StateMachine && this.logic.isInternalEventType(event.type)) {
+      this.system.deadLetter(undefined, this._root, event, 'internalEvent');
+      return new EventRejectedError({
+        actorId: this.id,
+        event,
+        reason: 'internalEvent'
+      });
     }
-    Queue.offerUnsafe(this._mailbox, event);
+    return undefined;
+  }
+  _stoppedError() {
+    return new ActorStoppedError({
+      actorId: this.id,
+      snapshot: this._snapshot
+    });
+  }
+
+  /** @internal */
+  _completeReceipt(receipt, exit) {
+    if (!receipt || !this._pending.delete(receipt)) return;
+    const resume = receipt.resume;
+    receipt.resume = undefined;
+    resume?.(exit);
   }
 
-  /** Stops the actor, its children and every Effect it hosts. */
+  /**
+   * Stops the actor, its children and every Effect it hosts. If a listener or
+   * an observer calls `stop()` while the actor delivers a macrostep to it, the
+   * actor stops when that macrostep ends. `createActor` does the same.
+   */
   stop() {
+    if (this._inStep && this._deliveryDepth > 0) {
+      this._stopHeld = true;
+      return this;
+    }
     this._stopExecution();
     return this;
   }
@@ -122,9 +273,20 @@ class EffectActor {
 
   /** @internal Delivers an emitted event to `on` listeners. */
   _emit(event) {
+    if (this._settled) return;
     const listeners = [...(this._listeners.get(event.type) ?? []), ...(this._listeners.get('*') ?? [])];
-    for (const listener of listeners) {
-      safeCall(listener, event);
+    this._deliver(() => {
+      for (const listener of listeners) {
+        safeCall(listener, event);
+      }
+    });
+  }
+  _deliver(notify) {
+    this._deliveryDepth++;
+    try {
+      notify();
+    } finally {
+      this._deliveryDepth--;
     }
   }
 
@@ -146,25 +308,41 @@ class EffectActor {
   }
   toJSON() {
     return {
-      $actor: this.address
+      '@actor': this.address
     };
   }
 
-  /** @internal Publishes a snapshot produced by the execution loop. */
-  _publish(snapshot) {
-    this._snapshot = snapshot;
-    const status = snapshot.status;
-    if (status === 'active') {
-      for (const observer of this._observers) {
-        safeCall(observer.next, snapshot);
+  /** @internal */
+  _runStep(step) {
+    return Effect.gen({
+      self: this
+    }, function* () {
+      if (this._settled) return;
+      this._snapshot = step.snapshot;
+      this._inStep = true;
+      yield* step.effects;
+      if (this._settled) return;
+      if (this._snapshot.status !== 'active') {
+        this._settle(this._snapshot, step.kind === 'transition' ? step.receipt : undefined);
+      } else if (step.kind === 'transition') {
+        this._deliver(() => {
+          for (const observer of this._observers) {
+            safeCall(observer.next, this._snapshot);
+          }
+        });
       }
-      return;
-    }
-    this._settle(snapshot);
+    }).pipe(Effect.onExit(exit => Effect.sync(() => {
+      this._inStep = false;
+      if (this._stopHeld) {
+        this._stopExecution();
+      } else if (step.kind === 'transition' && Exit.isSuccess(exit)) {
+        this._completeReceipt(step.receipt, step.rejection ? Exit.fail(step.rejection) : Exit.succeed(step.snapshot));
+      }
+    })));
   }
 
-  /** @internal Marks the actor stopped and notifies observers. */
-  _settle(snapshot) {
+  /** @internal Settles the actor and notifies its observers. */
+  _settle(snapshot, processing) {
     if (this._settled) {
       return;
     }
@@ -173,17 +351,23 @@ class EffectActor {
     const observers = [...this._observers];
     this._observers.clear();
     const status = snapshot.status;
-    if (status === 'done') {
-      for (const observer of observers) {
-        safeCall(observer.next, snapshot);
+    this._deliver(() => {
+      if (status === 'done') {
+        for (const observer of observers) {
+          safeCall(observer.next, snapshot);
+        }
       }
-    }
-    for (const observer of observers) {
-      if (status === 'error') {
-        safeCall(observer.error, snapshot.error);
-      } else {
-        safeCall(observer.complete);
+      for (const observer of observers) {
+        if (status === 'error') {
+          safeCall(observer.error, snapshot.error);
+        } else {
+          safeCall(observer.complete);
+        }
       }
+    });
+    this._completeReceipt(processing, Exit.succeed(snapshot));
+    for (const receipt of this._pending) {
+      this._completeReceipt(receipt, Exit.fail(this._stoppedError()));
     }
   }
 
@@ -314,7 +498,7 @@ function trackEffect(actor, host, interrupt) {
  * The fiber belongs to the host scope, so closing the owning actor also
  * waits for asynchronous invocation finalizers.
  */
-function startHostedEffect(actor, effect, spanName, onExit) {
+function startHostedEffect(actor, effect, spanName, onExit, onCancel) {
   const host = requireEffectHost(actor);
   let active = true;
   const traced = Effect.withSpan(spanName, {
@@ -331,11 +515,18 @@ function startHostedEffect(actor, effect, spanName, onExit) {
     }
     active = false;
     untrackEffect(actor, host, cancel);
+    onCancel?.();
     interrupt();
   };
-  const fiber = Fiber.runIn(Effect.runForkWith(host.context)(traced), host.scope);
+  // Register the fiber before its body runs: the body can synchronously
+  // trigger the host's close, which only awaits registered fibers.
+  const registered = Effect.withFiber(fiber => {
+    Fiber.runIn(fiber, host.scope);
+    host.fibers.add(fiber);
+    return traced;
+  });
+  const fiber = Effect.runForkWith(host.context)(registered);
   const interrupt = () => fiber.interruptUnsafe();
-  host.fibers.add(fiber);
   fiber.addObserver(exit => {
     host.fibers.delete(fiber);
     if (!active) {
@@ -351,22 +542,16 @@ function startHostedEffect(actor, effect, spanName, onExit) {
   return cancel;
 }
 
-/**
- * Runs an Effect in the actor's host context and settles when it exits.
- * Interruption settles without error; failures and defects reject with the
- * squashed cause so the actor's error handling can observe them.
- */
+/** @internal */
 function runHostedEffect(actor, effect, spanName) {
   return new Promise((resolve, reject) => {
     startHostedEffect(actor, effect, spanName, exit => {
-      if (Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause)) {
+      if (Exit.isSuccess(exit)) {
         resolve();
       } else {
-        // Effect failures are arbitrary values, not necessarily Errors.
-        // oxlint-disable-next-line typescript/prefer-promise-reject-errors
-        reject(Cause.squash(exit.cause));
+        reject(new EffectFailure(exit.cause));
       }
-    });
+    }, resolve);
   });
 }
 
@@ -403,12 +588,18 @@ function relayToParent(actor, event) {
   }
 }
 
-/** The owning Effect actor's scope, supplied by `createEffectActor`. */
+/**
+ * The owning Effect actor's scope, supplied by `createEffectActor`.
+ *
+ * @experimental
+ */
 class ActorScope extends Context.Service()('@xstate/effect/ActorScope') {}
 
 /**
  * Acquires resources in the owning actor's scope. Their finalizers run when
  * that actor stops, even if the invoking task finishes or is cancelled first.
+ *
+ * @experimental
  */
 function withActorScope(effect) {
   return ActorScope.use(scope => Scope.provide(effect, scope));
@@ -417,7 +608,11 @@ function withActorScope(effect) {
 const XSTATE_TIMER = 'xstate.timer';
 const XSTATE_INIT = 'xstate.init';
 
-/** Options for {@link createEffectActor}. */
+/**
+ * Options for {@link createEffectActor}.
+ *
+ * @experimental
+ */
 
 /**
  * Creates and starts an actor as an Effect interpreter over pure transitions.
@@ -432,6 +627,8 @@ const XSTATE_INIT = 'xstate.init';
  * The actor is a scoped resource: it stops, and every Effect it hosts is
  * interrupted, when the enclosing `Scope` closes. The returned Effect never
  * fails; the actor's own outcome is its snapshot status, read with `join`.
+ *
+ * @experimental
  */
 function createEffectActor(logic, ...[options]) {
   return Effect.acquireRelease(Effect.gen(function* () {
@@ -443,6 +640,8 @@ function createEffectActor(logic, ...[options]) {
     const runFork = Effect.runForkWith(context);
     const runPromise = Effect.runPromiseWith(context);
     const mailbox = yield* Queue.unbounded();
+    let delivered;
+    const getDelivered = () => delivered;
     const timers = new Map();
     // `root` and `actor` are declared after the adapter below; its
     // callbacks only run once they are initialized.
@@ -469,14 +668,14 @@ function createEffectActor(logic, ...[options]) {
           if (result && typeof result.then === 'function') {
             void Promise.resolve(result).catch(error => {
               offer({
-                [actionFailure]: true,
+                kind: 'actionFailure',
                 error
               });
             });
           }
         } catch (error) {
           offer({
-            [actionFailure]: true,
+            kind: 'actionFailure',
             error
           });
         }
@@ -500,7 +699,10 @@ function createEffectActor(logic, ...[options]) {
       },
       sendEvent: (source, target, event) => {
         if (isRoot(target)) {
-          offer(event);
+          offer({
+            kind: 'event',
+            event: event
+          });
           return;
         }
         deliverEvent(source, target, event);
@@ -522,7 +724,10 @@ function createEffectActor(logic, ...[options]) {
             ...timer
           };
           if (isRoot(source)) {
-            offer(timerEvent);
+            offer({
+              kind: 'event',
+              event: timerEvent
+            });
           } else {
             deliverEvent(source, source, timerEvent);
           }
@@ -542,8 +747,15 @@ function createEffectActor(logic, ...[options]) {
           }
         }
       },
-      waitForEvent: () => runPromise(Queue.take(mailbox))
+      waitForEvent: () => runPromise(Queue.take(mailbox)).then(item => {
+        delivered = item;
+        return item.kind === 'event' ? item.event : {
+          type: 'xstate.effect.actionFailure'
+        };
+      })
     }, {
+      // A live actor needs one FIFO for child events, sends and timers.
+      captureRootEvents: false,
       inspect: event => {
         // The pure step scope re-materializes the root ref per step and
         // announces it again; observers should see the root once.
@@ -586,10 +798,11 @@ function createEffectActor(logic, ...[options]) {
       }
       runFork(Queue.shutdown(mailbox));
       if (!actor._isSettled) {
-        actor._settle({
-          ...actor.getSnapshot(),
+        const current = actor.getSnapshot();
+        actor._settle(current.status === 'active' ? {
+          ...current,
           status: 'stopped'
-        });
+        } : current);
       }
       closeEffectHost(host);
     };
@@ -624,39 +837,67 @@ function createEffectActor(logic, ...[options]) {
     bindEffectHost(actor, host);
     const executeEffects = batch => Effect.promise(() => durable.executeEffects(batch).then(() => undefined, error => {
       offer({
-        [actionFailure]: true,
+        kind: 'actionFailure',
         error
       });
     }));
     const loop = Effect.gen(function* () {
-      yield* executeEffects(effects);
+      yield* actor._runStep({
+        kind: 'start',
+        snapshot,
+        effects: executeEffects(effects)
+      });
       while (snapshot.status === 'active' && !stopped) {
-        const item = yield* Effect.promise(() => durable.waitForEvent().then(event => event, () => undefined));
-        if (item === undefined || stopped) {
-          break;
-        }
+        delivered = undefined;
+        const received = yield* Effect.promise(() => durable.waitForEvent().catch(() => undefined));
+        if (received === undefined || stopped) break;
+        const item = getDelivered() ?? {
+          kind: 'event',
+          event: received
+        };
+        const receipt = item.kind === 'event' ? item.receipt : undefined;
         let event;
-        if (isActionFailure(item)) {
+        if (item.kind === 'actionFailure') {
           const errorEvent = logic.getExecutionErrorEvent?.(snapshot, item.error);
           if (!errorEvent) {
             snapshot = errorSnapshot(snapshot, item.error);
+            yield* actor._runStep({
+              kind: 'transition',
+              snapshot,
+              effects: Effect.void
+            });
             break;
           }
           event = errorEvent;
         } else {
-          event = item;
+          event = item.event;
         }
         try {
           [snapshot, effects] = durable.transition(snapshot, event);
         } catch (error) {
           snapshot = errorSnapshot(snapshot, error);
+          yield* actor._runStep({
+            kind: 'transition',
+            snapshot,
+            effects: Effect.void,
+            receipt
+          });
           break;
         }
-        actor._publish(snapshot);
-        yield* executeEffects(effects);
+        const rejectedReason = effects.length === 1 && effects[0].effect.type === '@xstate.deadLetter' && 'reason' in effects[0].effect && effects[0].effect.reason === 'invalidEvent' ? effects[0].effect.reason : undefined;
+        yield* actor._runStep({
+          kind: 'transition',
+          snapshot,
+          effects: executeEffects(effects),
+          receipt,
+          rejection: rejectedReason !== undefined ? new EventRejectedError({
+            actorId: actor.id,
+            event,
+            reason: rejectedReason
+          }) : undefined
+        });
       }
       if (!stopped) {
-        actor._publish(snapshot);
         if (snapshot.status !== 'active') {
           stopChildren(snapshot);
           closeEffectHost(host);
@@ -666,13 +907,14 @@ function createEffectActor(logic, ...[options]) {
     yield* Effect.forkIn(loop, actorScope);
     return {
       actor,
-      host
+      host,
+      stopNow: stop
     };
   }), ({
-    actor,
-    host
+    host,
+    stopNow
   }) => Effect.gen(function* () {
-    actor.stop();
+    stopNow();
     if (host.closing) {
       yield* Fiber.join(host.closing);
     } else {
@@ -683,52 +925,28 @@ function createEffectActor(logic, ...[options]) {
   }) => actor));
 }
 
-/**
- * The failure an Effect-backed actor reports when its Effect was interrupted
- * by something other than the actor being stopped, such as `Effect.interrupt`,
- * losing an `Effect.race`, or an `Effect.timeout` that interrupts.
- */
-class EffectInterruptedError extends Data.TaggedError('EffectInterruptedError') {
-  get message() {
-    return 'Effect was interrupted before the actor completed';
-  }
-}
-
-/**
- * Reported by `waitFor` when the actor stops or errors before a snapshot
- * matches, and by `join` when the actor stops without output. `join` reports
- * an errored actor's own `snapshot.error` instead.
- */
-class ActorStoppedError extends Data.TaggedError('ActorStoppedError') {
-  get message() {
-    return `Actor "${this.actorId}" ${this.snapshot.status === 'error' ? 'errored' : 'stopped'} before completing`;
-  }
-}
-
-/**
- * Reported by the `send` atom of `createActorAtoms` when an event is sent
- * before the actor's runtime has finished building.
- */
-class NotReadyError extends Data.TaggedError('NotReadyError') {
-  get message() {
-    return 'The actor is not ready yet';
-  }
-}
-
 /**
  * The dotted path of a state value: `'idle'`, `'form.editing'`. A parallel
  * state has no single path, so its tag stops at the parallel state. When the
  * machine itself is parallel, the tag is `TRootTag`: the machine id, or `''`
  * for a machine without one.
+ *
+ * @experimental
  */
 
 /**
  * A machine snapshot as a tagged union over its states. `_tag` is the state's
  * dotted path and `context` is the context of that state, including any
  * per-state context schema, so `Match.tag` narrows both.
+ *
+ * @experimental
  */
 
-/** The tagged state union of a machine. */
+/**
+ * The tagged state union of a machine.
+ *
+ * @experimental
+ */
 
 /** Computes the dotted path tag of a state value. */
 function stateTag(value, rootTag, prefix = '') {
@@ -757,6 +975,8 @@ function stateTag(value, rootTag, prefix = '') {
  * );
  * view(taggedState(snapshot));
  * ```
+ *
+ * @experimental
  */
 function taggedState(snapshot) {
   return {
@@ -767,4 +987,4 @@ function taggedState(snapshot) {
   };
 }
 
-export { ActorStoppedError as A, EffectInterruptedError as E, NotReadyError as N, runHostedEffect as a, EffectActor as b, createEffectActor as c, ActorScope as d, relayToParent as r, startHostedEffect as s, taggedState as t, withActorScope as w };
+export { ActorStoppedError as A, EffectFailure as E, NotReadyError as N, causeFromError as a, runHostedEffect as b, createEffectActor as c, EffectActor as d, ActorScope as e, EventRejectedError as f, EffectInterruptedError as g, relayToParent as r, startHostedEffect as s, taggedState as t, withActorScope as w };