@xstate/effect 1.0.0-beta.0 → 1.0.0-beta.2

package/README.md

@@ -264,12 +264,13 @@ See [atoms and React](docs/atoms-and-react.md) for complete examples with import
 
 ## Testing and errors
 
-<!-- error types from src/errors.ts; timeout failure from src/actor.ts -->
+<!-- error types and causeFromError from src/errors.ts; timeout failure from src/actor.ts -->
 
-- Use `sendAndAwait` from `@xstate/effect/test` to acknowledge a specific event, including ignored events.
+- Use `sendAndAwait` from `@xstate/effect` to acknowledge one event after its transition and immediate effects. It does not wait for child replies, invoked work, background actions or future timers.
 - Use `TestClock` to drive deadlines without waiting for real time.
 - `ActorStoppedError` reports a stop before an awaited result.
 - `EffectFailure<E>` carries the original `Cause<E>` in task and stream error snapshots, including defects and self-interruption.
+- Use `causeFromError(error)` to obtain the original Cause from `EffectFailure` or wrap an ordinary error. Use `Cause.findErrorOption` to inspect its typed failure.
 - Timed waits fail with Effect's `Cause.TimeoutError`.
 - `join` replays the original Cause and preserves a task's typed failure. Unexpected machine errors have type `unknown`.
 

package/dist/declarations/src/effectActor.d.ts

@@ -41,6 +41,9 @@ export declare class EffectActor<TLogic extends AnyActorLogic> implements ActorR
     private readonly _listeners;
     private _settled;
     private readonly _pending;
+    private _inStep;
+    private _deliveryDepth;
+    private _stopHeld;
     constructor(logic: TLogic, root: AnyActor, snapshot: SnapshotFrom<TLogic>, _mailbox: Queue.Queue<MailboxItem<EventFromLogic<TLogic>, SnapshotFrom<TLogic>>>, _stopExecution: () => void, _inspectors: Set<(event: InspectionEvent) => void>);
     getSnapshot(): SnapshotFrom<TLogic>;
     getPersistedSnapshot(): PersistedSnapshotOf<TLogic>;
@@ -48,13 +51,18 @@ export declare class EffectActor<TLogic extends AnyActorLogic> implements ActorR
     send(event: EventFromLogic<TLogic>): void;
     private _deliveryError;
     private _stoppedError;
-    /** 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(): this;
     subscribe(observer: Observer<SnapshotFrom<TLogic>>): Subscription;
     subscribe(nextListener?: (snapshot: SnapshotFrom<TLogic>) => void, errorListener?: (error: any) => void, completeListener?: () => void): Subscription;
     on<TType extends EmittedFrom<TLogic>['type'] | '*'>(type: TType, handler: (emitted: EmittedFrom<TLogic> & (TType extends '*' ? unknown : {
         type: TType;
     })) => void): Subscription;
+    private _deliver;
     /**
      * Observes the inspection events of this actor and its children: every
      * actor creation and transition of the execution.
@@ -62,7 +70,7 @@ export declare class EffectActor<TLogic extends AnyActorLogic> implements ActorR
     inspect(observer: Observer<InspectionEvent> | ((event: InspectionEvent) => void)): Subscription;
     [symbolObservable](): this;
     toJSON(): {
-        $actor: string;
+        '@actor': string;
     };
 }
 export {};

package/dist/declarations/src/errors.d.ts

@@ -53,6 +53,18 @@ declare const NotReadyError_base: new <A extends Record<string, any> = {}>(args:
 export declare class NotReadyError extends NotReadyError_base {
     get message(): string;
 }
+/**
+ * Returns an EffectFailure's original Cause, or wraps an ordinary error with
+ * Cause.fail. Defects and interruption in an existing Cause are preserved.
+ *
+ * @experimental
+ */
+export declare function causeFromError<E>(error: E): Cause.Cause<UnwrapEffectFailure<E>>;
+/**
+ * Extracts the typed failure from EffectFailure while retaining ordinary errors.
+ *
+ * @experimental
+ */
 export type UnwrapEffectFailure<E> = E extends EffectFailure<infer Failure> ? Failure : E;
 declare const EventRejectedError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
     readonly _tag: "EventRejectedError";

package/dist/declarations/src/index.d.ts

@@ -1,9 +1,10 @@
 export { createEffectLogic, createEffectEventStreamLogic, createEffectStreamLogic, type EffectActorLogic, type EffectLogicBrand, type EffectSnapshot, type EffectSource, type EffectSourceArgs, type EffectStreamSource, type EffectStreamActorLogic, type EffectStreamSnapshot } from "./effectLogic.js";
 export { createEffectActor, type EffectActorOptions } from "./createEffectActor.js";
 export { EffectActor } from "./effectActor.js";
+export { sendAndAwait } from "./sendAndAwait.js";
 export { ActorScope, withActorScope } from "./actorScope.js";
 export { deadLetters, emitted, inspect, join, send, snapshots, waitFor, type EmittedEventFrom, type SendableEventFrom, type WaitForOptions } from "./actor.js";
-export { ActorStoppedError, EventRejectedError, EffectFailure, EffectInterruptedError } from "./errors.js";
+export { ActorStoppedError, EventRejectedError, EffectFailure, EffectInterruptedError, causeFromError, type UnwrapEffectFailure } from "./errors.js";
 export { setupEffect, type EffectAction, type EffectActionArgs, type EffectSetupReturn } from "./setupEffect.js";
 export { type RequirementsFrom } from "./types.js";
 export { taggedState, type StateTag, type TaggedState, type TaggedStateFrom } from "./state.js";

package/dist/declarations/src/sendAndAwait.d.ts

@@ -0,0 +1,14 @@
+import type { Effect } from 'effect';
+import type { AnyActorLogic, EventFromLogic, SnapshotFrom } from 'xstate';
+import type { EffectActor } from "./effectActor.js";
+import type { ActorStoppedError, EventRejectedError } from "./errors.js";
+/**
+ * Sends one event and acknowledges its transition and immediate effects.
+ * Ignored events are acknowledged too, as are events whose actions fail; the
+ * failure is processed afterwards. Child replies, invoked work, background
+ * action bodies and future timers are not awaited. Interrupting the waiter
+ * detaches its receipt without retracting the event.
+ *
+ * @experimental
+ */
+export declare function sendAndAwait<TLogic extends AnyActorLogic>(actor: EffectActor<TLogic>, event: EventFromLogic<TLogic>): Effect.Effect<SnapshotFrom<TLogic>, ActorStoppedError | EventRejectedError>;

package/dist/declarations/src/test.d.ts

@@ -1,13 +1 @@
-import type { Effect } from 'effect';
-import type { AnyActorLogic, EventFromLogic, SnapshotFrom } from 'xstate';
-import type { EffectActor } from "./effectActor.js";
-import type { ActorStoppedError, EventRejectedError } from "./errors.js";
-/**
- * Sends one mailbox item and awaits its macrostep publication and immediate
- * effect scheduling. Ignored events are acknowledged too. Does not await
- * invoked work, background actions or future timers. Interrupting the waiter
- * detaches its receipt without retracting the event.
- *
- * @experimental
- */
-export declare function sendAndAwait<TLogic extends AnyActorLogic>(actor: EffectActor<TLogic>, event: EventFromLogic<TLogic>): Effect.Effect<SnapshotFrom<TLogic>, ActorStoppedError | EventRejectedError>;
+export { sendAndAwait } from "./sendAndAwait.js";

package/dist/sendAndAwait-bf1d4117.js

@@ -0,0 +1,14 @@
+/**
+ * Sends one event and acknowledges its transition and immediate effects.
+ * Ignored events are acknowledged too, as are events whose actions fail; the
+ * failure is processed afterwards. Child replies, invoked work, background
+ * action bodies and future timers are not awaited. Interrupting the waiter
+ * detaches its receipt without retracting the event.
+ *
+ * @experimental
+ */
+function sendAndAwait(actor, event) {
+  return actor._sendAndAwait(event);
+}
+
+export { sendAndAwait as s };

package/dist/{state-a2154dce.js → state-54c1cda0.js}

@@ -79,10 +79,22 @@ class NotReadyError extends Data.TaggedError('NotReadyError') {
   }
 }
 
-/** @internal */
+/**
+ * Returns an EffectFailure's original Cause, or wraps an ordinary error with
+ * Cause.fail. Defects and interruption in an existing Cause are preserved.
+ *
+ * @experimental
+ */
 function causeFromError(error) {
   return error instanceof EffectFailure ? error.cause : Cause.fail(error);
 }
+
+/**
+ * Extracts the typed failure from EffectFailure while retaining ordinary errors.
+ *
+ * @experimental
+ */
+
 /**
  * An event rejected at the actor's delivery boundary.
  *
@@ -90,6 +102,8 @@ function causeFromError(error) {
  */
 class EventRejectedError extends Data.TaggedError('EventRejectedError') {}
 
+/** @internal */
+
 const symbolObservable = (() => typeof Symbol === 'function' && Symbol.observable || '@@observable')();
 
 /**
@@ -142,6 +156,9 @@ class EffectActor {
     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;
@@ -203,11 +220,6 @@ class EffectActor {
     }
     return undefined;
   }
-
-  /** @internal */
-  _rejectReceipts() {
-    for (const receipt of this._pending) this._completeReceipt(receipt, Exit.fail(this._stoppedError()));
-  }
   _stoppedError() {
     return new ActorStoppedError({
       actorId: this.id,
@@ -223,8 +235,16 @@ class EffectActor {
     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;
   }
@@ -265,9 +285,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--;
     }
   }
 
@@ -289,48 +320,66 @@ class EffectActor {
   }
   toJSON() {
     return {
-      $actor: this.address
+      '@actor': this.address
     };
   }
 
-  /** @internal Publishes a snapshot produced by the execution loop. */
-  _publish(snapshot, receipt) {
-    if (this._settled) return;
-    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, receipt);
+    }).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. */
+  /** @internal Settles the actor and notifies its observers. */
   _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;
-    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()));
     }
   }
 
@@ -539,15 +588,16 @@ function closeEffectHost(host) {
     discard: true
   }).pipe(Effect.andThen(Scope.close(host.scope, Exit.void))));
 }
+const EFFECT_FORWARD = 'xstate.effect.forward';
 
-/**
- * Delivers a stream item to the parent as an event. This runs outside a
- * transition, so it uses the system relay like core's observable logic does.
- */
+/** Queues a stream item for the source actor to forward in its transition. */
 function relayToParent(actor, event) {
   const actorWithParent = actor;
   if (actorWithParent._parent) {
-    actor.system._relay(actorWithParent, actorWithParent._parent, event);
+    actor.system._relay(actorWithParent, actorWithParent, {
+      type: EFFECT_FORWARD,
+      event
+    });
   }
 }
 
@@ -761,12 +811,12 @@ 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);
       }
-      actor._rejectReceipts();
       closeEffectHost(host);
     };
 
@@ -805,7 +855,11 @@ function createEffectActor(logic, ...[options]) {
       });
     }));
     const loop = Effect.gen(function* () {
-      yield* executeEffects(effects);
+      yield* actor._runStep({
+        kind: 'start',
+        snapshot,
+        effects: executeEffects(effects)
+      });
       while (snapshot.status === 'active' && !stopped) {
         delivered = undefined;
         const received = yield* Effect.promise(() => durable.waitForEvent().catch(() => undefined));
@@ -820,6 +874,11 @@ function createEffectActor(logic, ...[options]) {
           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;
@@ -830,22 +889,28 @@ function createEffectActor(logic, ...[options]) {
           [snapshot, effects] = durable.transition(snapshot, event);
         } catch (error) {
           snapshot = errorSnapshot(snapshot, error);
-          actor._publish(snapshot, receipt);
-          actor._completeReceipt(receipt, Exit.succeed(snapshot));
+          yield* actor._runStep({
+            kind: 'transition',
+            snapshot,
+            effects: Effect.void,
+            receipt
+          });
           break;
         }
-        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));
+        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);
@@ -855,13 +920,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 {
@@ -934,4 +1000,4 @@ function taggedState(snapshot) {
   };
 }
 
-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 };
+export { ActorStoppedError as A, EFFECT_FORWARD as E, NotReadyError as N, causeFromError as a, EffectFailure as b, createEffectActor as c, runHostedEffect as d, EffectActor as e, ActorScope as f, EventRejectedError as g, EffectInterruptedError as h, 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 { StateMachine } from 'xstate';
-import { c as createEffectActor, a as causeFromError, N as NotReadyError, t as taggedState } from './state-a2154dce.js';
-export { N as NotReadyError } from './state-a2154dce.js';
+import { c as createEffectActor, a as causeFromError, N as NotReadyError, t as taggedState } from './state-54c1cda0.js';
+export { N as NotReadyError } from './state-54c1cda0.js';
 import 'xstate/durable';
 
 /**

package/dist/xstate-effect-test.js

@@ -1,13 +1 @@
-/**
- * Sends one mailbox item and awaits its macrostep publication and immediate
- * effect scheduling. Ignored events are acknowledged too. Does not await
- * invoked work, background actions or future timers. Interrupting the waiter
- * detaches its receipt without retracting the event.
- *
- * @experimental
- */
-function sendAndAwait(actor, event) {
-  return actor._sendAndAwait(event);
-}
-
-export { sendAndAwait };
+export { s as sendAndAwait } from './sendAndAwait-bf1d4117.js';

package/dist/xstate-effect.js

@@ -1,7 +1,8 @@
 import { Schema, Effect, Stream, Cause, Exit, Queue, Data } from 'effect';
 import { createStepLogic, setup } from 'xstate';
-import { s as startHostedEffect, r as relayToParent, E as EffectFailure, A as ActorStoppedError, a as causeFromError, b as runHostedEffect } from './state-a2154dce.js';
-export { e as ActorScope, A as ActorStoppedError, d as EffectActor, E as EffectFailure, g as EffectInterruptedError, f as EventRejectedError, c as createEffectActor, t as taggedState, w as withActorScope } from './state-a2154dce.js';
+import { s as startHostedEffect, E as EFFECT_FORWARD, r as relayToParent, b as EffectFailure, A as ActorStoppedError, a as causeFromError, d as runHostedEffect } from './state-54c1cda0.js';
+export { f as ActorScope, A as ActorStoppedError, e as EffectActor, b as EffectFailure, h as EffectInterruptedError, g as EventRejectedError, a as causeFromError, c as createEffectActor, t as taggedState, w as withActorScope } from './state-54c1cda0.js';
+export { s as sendAndAwait } from './sendAndAwait-bf1d4117.js';
 import { dual } from 'effect/Function';
 import 'xstate/durable';
 
@@ -389,7 +390,9 @@ function createEffectEventStreamLogic(sourceOrConfig) {
   const stream = config.stream;
   const logic = createStepLogic({
     id: config.id,
-    validator: config.validator,
+    validator: config.validator && {
+      check: request => request.kind === 'event' && request.event.type === EFFECT_FORWARD ? undefined : config.validator.check(request)
+    },
     schemas: toLogicSchemas(config.schemas),
     context: undefined,
     run: ({
@@ -398,6 +401,10 @@ function createEffectEventStreamLogic(sourceOrConfig) {
       self,
       system
     }, enq) => {
+      if (event.type === EFFECT_FORWARD) {
+        enq.sendBack(event.event);
+        return;
+      }
       if (event.type === EFFECT_COMPLETE) {
         return {
           status: 'done',
@@ -433,6 +440,9 @@ function createEffectEventStreamLogic(sourceOrConfig) {
       }));
     }
   });
+  Object.assign(logic, {
+    isInternalEventType: eventType => eventType === EFFECT_FORWARD
+  });
   return brandLogic(logic, undefined, undefined);
 }
 
@@ -748,6 +758,12 @@ function wrapActions(actions) {
       }
       return Effect.isEffect(result) ? runHostedEffect(args.self, result, `action.${key}`) : result;
     };
+    // Built-in effect descriptors use these reserved prefixes.
+    if (!key.startsWith('xstate.') && !key.startsWith('@xstate.')) {
+      Object.defineProperty(wrapped[key], 'name', {
+        value: key
+      });
+    }
   }
   return wrapped;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xstate/effect",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.2",
   "type": "module",
   "description": "Effect integration for XState",
   "keywords": [
@@ -33,14 +33,14 @@
   "peerDependencies": {
     "@oxlint/plugins": "^1.76.0",
     "effect": "^4.0.0",
-    "xstate": "^6.0.0-beta.0"
+    "xstate": "^6.0.0-beta.3"
   },
   "devDependencies": {
     "@oxlint/plugins": "^1.76.0",
     "effect": "4.0.6",
     "fast-check": "4.10.2",
-    "@xstate/test": "^2.0.0-beta.0",
-    "xstate": "^6.0.0-beta.0"
+    "@xstate/test": "^2.0.0-beta.1",
+    "xstate": "^6.0.0-beta.3"
   },
   "preconstruct": {
     "entrypoints": [