@xstate/effect 0.1.0-alpha.6 → 1.0.0-alpha.10

package/dist/{state-14a1fecf.js → state-a3f54e06.js}

@@ -1,13 +1,79 @@
-import { Queue, Effect, Fiber, Scope, Exit, Cause, Context, Duration, Data } from 'effect';
-import { stopActor, terminateActor, deliverEvent } 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. */
+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. */
+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.
+ */
+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';
+  }
+}
 
-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. */
+class EventRejectedError extends Data.TaggedError('EventRejectedError') {}
+
 const symbolObservable = (() => typeof Symbol === 'function' && Symbol.observable || '@@observable')();
 
 /**
@@ -57,6 +123,7 @@ class EffectActor {
     this._observers = new Set();
     this._listeners = new Map();
     this._settled = false;
+    this._pending = new Set();
     this._root = root;
     this.id = root.id;
     this.address = root.address;
@@ -73,11 +140,69 @@ 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();
     }
-    Queue.offerUnsafe(this._mailbox, event);
+    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'
+      });
+    }
+    return undefined;
+  }
+
+  /** @internal */
+  _rejectReceipts() {
+    for (const receipt of this._pending) this._completeReceipt(receipt, Exit.fail(this._stoppedError()));
+  }
+  _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. */
@@ -146,13 +271,13 @@ class EffectActor {
   }
   toJSON() {
     return {
-      xstate$$type: 1,
-      id: this.id
+      $actor: this.address
     };
   }
 
   /** @internal Publishes a snapshot produced by the execution loop. */
-  _publish(snapshot) {
+  _publish(snapshot, receipt) {
+    if (this._settled) return;
     this._snapshot = snapshot;
     const status = snapshot.status;
     if (status === 'active') {
@@ -161,16 +286,19 @@ class EffectActor {
       }
       return;
     }
-    this._settle(snapshot);
+    this._settle(snapshot, receipt);
   }
 
   /** @internal Marks the actor stopped and notifies observers. */
-  _settle(snapshot) {
+  _settle(snapshot, processing) {
     if (this._settled) {
       return;
     }
     this._snapshot = snapshot;
     this._settled = true;
+    for (const receipt of this._pending) {
+      if (receipt !== processing) this._completeReceipt(receipt, Exit.fail(this._stoppedError()));
+    }
     const observers = [...this._observers];
     this._observers.clear();
     const status = snapshot.status;
@@ -315,7 +443,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, {
@@ -332,11 +460,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) {
@@ -352,22 +487,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);
   });
 }
 
@@ -416,6 +545,7 @@ function withActorScope(effect) {
 }
 
 const XSTATE_TIMER = 'xstate.timer';
+const XSTATE_INIT = 'xstate.init';
 
 /** Options for {@link createEffectActor}. */
 
@@ -443,6 +573,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.
@@ -453,10 +585,14 @@ function createEffectActor(logic, ...[options]) {
         Queue.offerUnsafe(mailbox, item);
       }
     };
-    const timerKey = (source, id) => `${source.sessionId}:${id}`;
+    const timerKey = (source, timer) => `${source.sessionId}:${JSON.stringify(timer)}`;
     const inspectors = new Set();
     let rootAnnounced = false;
+    const clock = Context.get(context, Clock.Clock);
     const durable = createDurable(logic, {
+      // Timer deadlines are measured on the same clock the timers sleep
+      // on, so a restored timer resumes with its remaining delay.
+      now: () => clock.currentTimeMillisUnsafe(),
       executeAction: (action, _metadata, runtime) => {
         // Fire-and-forget: the action starts now and the loop continues.
         // A rejection reaches the machine as an execution error.
@@ -465,14 +601,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
           });
         }
@@ -496,7 +632,10 @@ function createEffectActor(logic, ...[options]) {
       },
       sendEvent: (source, target, event) => {
         if (isRoot(target)) {
-          offer(event);
+          offer({
+            kind: 'event',
+            event: event
+          });
           return;
         }
         deliverEvent(source, target, event);
@@ -508,25 +647,28 @@ function createEffectActor(logic, ...[options]) {
         }
         source._emit(event);
       },
-      scheduleTimer: (source, id, delay) => {
-        const key = timerKey(source, id);
+      scheduleTimer: (source, timer, delay) => {
+        const key = timerKey(source, timer);
         timers.get(key)?.interruptUnsafe();
         const fiber = Fiber.runIn(runFork(Effect.andThen(Effect.sleep(Duration.millis(delay)), Effect.sync(() => {
           timers.delete(key);
           const timerEvent = {
             type: XSTATE_TIMER,
-            id
+            ...timer
           };
           if (isRoot(source)) {
-            offer(timerEvent);
+            offer({
+              kind: 'event',
+              event: timerEvent
+            });
           } else {
             deliverEvent(source, source, timerEvent);
           }
         }))), actorScope);
         timers.set(key, fiber);
       },
-      cancelTimer: (source, id) => {
-        const key = timerKey(source, id);
+      cancelTimer: (source, timer) => {
+        const key = timerKey(source, timer);
         timers.get(key)?.interruptUnsafe();
         timers.delete(key);
       },
@@ -538,7 +680,12 @@ 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'
+        };
+      })
     }, {
       inspect: event => {
         // The pure step scope re-materializes the root ref per step and
@@ -587,13 +734,33 @@ function createEffectActor(logic, ...[options]) {
           status: 'stopped'
         });
       }
+      actor._rejectReceipts();
       closeEffectHost(host);
     };
 
-    // The first transition runs here so the handle is ready when this
-    // Effect succeeds, and the initial actions start before any send.
-    let [snapshot, effects] = durable.initialTransition(options?.input);
+    // The first transition (or the restore) runs here so the handle is
+    // ready when this Effect succeeds, and the initial actions start before
+    // any send. Restoring runs no entry actions; its effects resume
+    // machine children, restart running Effect children and re-arm pending
+    // timers.
+    let [snapshot, effects] = options?.snapshot ? durable.restore(options.snapshot) : durable.initialTransition(options?.input);
+    const initial = snapshot;
+    if (options?.snapshot && !isMachineSnapshot(initial) && initial.status === 'active') {
+      // A restored machine resumes through the effects above. Other logic
+      // (an Effect task or stream at the root) reattaches its active work by
+      // replaying its init event, as its restored `start` does under
+      // `createActor`.
+      const [started, startEffects] = durable.transition(snapshot, {
+        type: XSTATE_INIT,
+        input: 'input' in initial ? initial.input : undefined
+      });
+      snapshot = started;
+      effects = [...effects, ...startEffects];
+    }
     const root = durable.getActorRef(snapshot);
+    // Restored children are created by the snapshot, not spawned through
+    // the adapter; they find this host through their parent chain.
+    bindEffectHost(root, host);
     // The root exists from here on; later announcements are step
     // re-materializations, not new actors.
     rootAnnounced = true;
@@ -601,19 +768,23 @@ 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);
       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);
@@ -621,16 +792,25 @@ function createEffectActor(logic, ...[options]) {
           }
           event = errorEvent;
         } else {
-          event = item;
+          event = item.event;
         }
         try {
           [snapshot, effects] = durable.transition(snapshot, event);
         } catch (error) {
           snapshot = errorSnapshot(snapshot, error);
+          actor._publish(snapshot, receipt);
+          actor._completeReceipt(receipt, Exit.succeed(snapshot));
           break;
         }
-        actor._publish(snapshot);
+        actor._publish(snapshot, receipt);
+        if (stopped) break;
+        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* executeEffects(effects);
+        actor._completeReceipt(receipt, rejectedReason !== undefined ? Exit.fail(new EventRejectedError({
+          actorId: actor.id,
+          event,
+          reason: rejectedReason
+        })) : Exit.succeed(snapshot));
       }
       if (!stopped) {
         actor._publish(snapshot);
@@ -660,45 +840,11 @@ 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 tag of the machine itself, used when the root state is parallel. */
-const MACHINE_TAG = '(machine)';
-
 /**
  * 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, or is
- * `'(machine)'` when the machine itself is 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.
  */
 
 /**
@@ -710,16 +856,16 @@ const MACHINE_TAG = '(machine)';
 /** The tagged state union of a machine. */
 
 /** Computes the dotted path tag of a state value. */
-function stateTag(value, prefix = '') {
+function stateTag(value, rootTag, prefix = '') {
   if (typeof value === 'string') {
     return prefix ? `${prefix}.${value}` : value;
   }
   const keys = Object.keys(value);
   if (keys.length !== 1) {
-    return prefix || MACHINE_TAG;
+    return prefix || rootTag;
   }
   const key = keys[0];
-  return stateTag(value[key], prefix ? `${prefix}.${key}` : key);
+  return stateTag(value[key], rootTag, prefix ? `${prefix}.${key}` : key);
 }
 
 /**
@@ -739,11 +885,11 @@ function stateTag(value, prefix = '') {
  */
 function taggedState(snapshot) {
   return {
-    _tag: stateTag(snapshot.value),
+    _tag: stateTag(snapshot.value, snapshot.machine.id),
     value: snapshot.value,
     context: snapshot.context,
     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 };

package/dist/xstate-effect-atom.js

@@ -1,8 +1,8 @@
 import { Cause } from 'effect';
 import { Atom, AsyncResult } from 'effect/reactivity';
-import { c as createEffectActor, N as NotReadyError, t as taggedState } from './state-14a1fecf.js';
-export { N as NotReadyError } from './state-14a1fecf.js';
-import 'xstate';
+import { StateMachine } from 'xstate';
+import { c as createEffectActor, a as causeFromError, N as NotReadyError, t as taggedState } from './state-a3f54e06.js';
+export { N as NotReadyError } from './state-a3f54e06.js';
 import 'xstate/durable';
 
 /**
@@ -55,7 +55,7 @@ function createActorAtoms(runtime, logic, ...[options]) {
     }
     const value = current.value;
     if (value.status === 'error') {
-      return AsyncResult.failureWithPrevious(Cause.fail(value.error), {
+      return AsyncResult.failureWithPrevious(causeFromError(value.error), {
         previous: get.self()
       });
     }
@@ -75,15 +75,17 @@ function createActorAtoms(runtime, logic, ...[options]) {
   function select(selector) {
     return Atom.map(snapshot, result => AsyncResult.map(result, selector));
   }
-  const state = select(current => taggedState(current));
-  return {
+  const base = {
     actor,
     snapshot,
     result,
     send: sendAtom,
-    select,
-    state
+    select
   };
+  return logic instanceof StateMachine ? {
+    ...base,
+    state: select(current => taggedState(current))
+  } : base;
 }
 
 export { createActorAtoms };

package/dist/xstate-effect-oxlint.d.ts

@@ -0,0 +1,3 @@
+export * from "./declarations/src/oxlint.js";
+export { default } from "./declarations/src/oxlint.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoieHN0YXRlLWVmZmVjdC1veGxpbnQuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4vZGVjbGFyYXRpb25zL3NyYy9veGxpbnQuZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9