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

package/README.md

@@ -266,7 +266,7 @@ See [atoms and React](docs/atoms-and-react.md) for complete examples with import
 
 <!-- error types 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.

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/index.d.ts

@@ -1,6 +1,7 @@
 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";

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-83513b45.js}

@@ -90,6 +90,8 @@ function causeFromError(error) {
  */
 class EventRejectedError extends Data.TaggedError('EventRejectedError') {}
 
+/** @internal */
+
 const symbolObservable = (() => typeof Symbol === 'function' && Symbol.observable || '@@observable')();
 
 /**
@@ -142,6 +144,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 +208,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 +223,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 +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--;
     }
   }
 
@@ -289,48 +308,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()));
     }
   }
 
@@ -761,12 +798,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 +842,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 +861,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 +876,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 +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 {

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-83513b45.js';
+export { N as NotReadyError } from './state-83513b45.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, r as relayToParent, E as EffectFailure, A as ActorStoppedError, a as causeFromError, b as runHostedEffect } from './state-83513b45.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-83513b45.js';
+export { s as sendAndAwait } from './sendAndAwait-bf1d4117.js';
 import { dual } from 'effect/Function';
 import 'xstate/durable';
 
@@ -748,6 +749,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.1",
   "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.2"
   },
   "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.2"
   },
   "preconstruct": {
     "entrypoints": [