@xstate/effect 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -195,7 +195,7 @@ These are free functions that take any XState `ActorRef`, including the `EffectA
 | `waitFor(actor, predicate, { timeout })` | `Effect<Snapshot, ActorStoppedError \| Cause.TimeoutError>` |
 | `join(actor)`                            | `Effect<Output, ErrorFrom<Logic> \| ActorStoppedError>`     |
 | `inspect(actor)`                         | `Stream<InspectionEvent>`                                   |
-| `deadLetters(actor)`                     | `Stream<DeadLetterInspectionEvent>`                         |
+| `deadLetters(actor)`                     | `Stream<EventRejection>`                                    |
 
 `send` and `waitFor` are dual: each takes the actor first, or returns a function of the actor so it can be piped.
 
@@ -215,7 +215,9 @@ const snapshot = yield* waitFor(
 
 The `timeout` failure is Effect's `Cause.TimeoutError`, not the `TimeoutError` that `xstate` exports for its own delayed-transition errors.
 
-`snapshots` ends when the actor completes. If the actor errors, the stream emits the error snapshot and ends. `waitFor` and `join` fail with `ActorStoppedError` when the actor stops or errors before the awaited result; `join` fails with the actor's typed error when the actor's status is `error`.
+`snapshots` ends when the actor completes. If the actor errors, the stream emits the error snapshot and ends. `waitFor` fails with `ActorStoppedError` when the actor stops or errors before the awaited result. `join` fails with `ActorStoppedError` when the actor stops without output, and with `snapshot.error` when the actor's status is `error`.
+
+For `fromEffect` logic that typed error is the Effect's `E`. For a machine it is `unknown`, because an action can throw an arbitrary value or an unhandled child error can fail the machine, so `join(machineActor)` has `unknown` in its error channel. Model domain failures as final states and read them from the machine's output; treat a machine-level error as a defect with `Effect.orDie`, or handle it with `Effect.catch`, to keep the rest of the program typed.
 
 ```ts
 const program = Effect.gen(function* () {
@@ -554,7 +556,7 @@ Assert with `waitFor` for a state the actor should reach, and with `join` for th
 
 Observe with `inspect` for every inspection event and `deadLetters` for events the system could not deliver. A test that ends with no dead letters confirms that every event it sent was accepted.
 
-Path generation in `xstate/graph` (`getShortestPaths`, `getSimplePaths`, `createTestModel`) operates on the machine, not on a running actor, so it works on an Effect-backed machine unchanged. Execute the generated paths against an actor from `createEffectActor`.
+Path generation in `xstate/graph` (`getShortestPaths`, `getSimplePaths`) operates on the machine, not on a running actor, so it works on an Effect-backed machine unchanged. Execute the generated paths against an actor from `createEffectActor`, or run them with `testPaths()` from `@xstate/test`.
 
 ## Retries and supervision
 
@@ -575,7 +577,7 @@ const supervised = Effect.retry(Effect.scoped(program), {
 });
 ```
 
-`join` fails with the machine's typed error, so the schedule sees the actual failure. Retrying `program` without `Effect.scoped` would reuse the outer scope and leak the actors from failed attempts until that scope closes.
+`join` fails when the actor errors or stops before producing output, so the schedule sees the actual failure. For a machine that failure is `unknown` (see [Observing actors](#observing-actors)); narrow it before the retry if the schedule should only see some errors. Retrying `program` without `Effect.scoped` would reuse the outer scope and leak the actors from failed attempts until that scope closes.
 
 ## Errors
 
@@ -583,7 +585,7 @@ const supervised = Effect.retry(Effect.scoped(program), {
 
 | Error                    | Raised by                                                                                      | Fields                                           |
 | ------------------------ | ---------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| `ActorStoppedError`      | `waitFor`, `join` when the actor stops or errors before the awaited result                     | `actorId: string`, `snapshot: Snapshot<unknown>` |
+| `ActorStoppedError`      | `waitFor` when the actor stops or errors; `join` when it stops without output                     | `actorId: string`, `snapshot: Snapshot<unknown>` |
 | `EffectInterruptedError` | Effect logic interrupted from inside, such as `Effect.interrupt`, reported as `snapshot.error` | `cause: Cause.Cause<never>`                      |
 | `Cause.TimeoutError`     | `waitFor` with `{ timeout }` when no snapshot matches in time                                  | Effect's own error; `_tag: 'TimeoutError'`       |
 

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

@@ -1,5 +1,5 @@
 import { Cause, Duration, Effect, Stream } from 'effect';
-import type { Actor, ActorRef, AnyActorRef, AnyEventObject, DeadLetterInspectionEvent, EmittedFrom, ErrorFrom, InspectionEvent, OutputFrom, SnapshotFrom } from 'xstate';
+import type { Actor, ActorRef, AnyActorRef, AnyEventObject, EmittedFrom, EventRejection, ErrorFrom, InspectionEvent, OutputFrom, SnapshotFrom } from 'xstate';
 import type { EffectActor } from "./effectActor.js";
 import { ActorStoppedError } from "./errors.js";
 /** The event type accepted by an actor's `send` method. */
@@ -68,9 +68,10 @@ export declare function join<TActor extends AnyActorRef>(actor: TActor): Effect.
  */
 export declare function inspect(actor: AnyActorRef): Stream.Stream<InspectionEvent>;
 /**
- * Streams the events the actor's system could not deliver: sends to a
- * stopped actor, invalid external events and internal events sent from
- * outside their owner. A dead letter is not an actor error. The stream runs
- * until it is interrupted or its scope closes.
+ * Streams the events the actor's system could not deliver, as reported by
+ * `system.onRejectedEvent`: sends to a stopped actor, invalid external
+ * events and internal events sent from outside their owner. A dead letter is
+ * not an actor error. The stream runs until it is interrupted or its scope
+ * closes.
  */
-export declare function deadLetters(actor: AnyActorRef): Stream.Stream<DeadLetterInspectionEvent>;
+export declare function deadLetters(actor: AnyActorRef): Stream.Stream<EventRejection>;

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

@@ -48,7 +48,7 @@ export declare class EffectActor<TLogic extends AnyActorLogic> implements ActorR
     })) => void): Subscription;
     /**
      * Observes the inspection events of this actor and its children: every
-     * transition, event delivery and dead letter of the execution.
+     * actor creation and transition of the execution.
      */
     inspect(observer: Observer<InspectionEvent> | ((event: InspectionEvent) => void)): Subscription;
     [symbolObservable](): this;

package/dist/{state-9a718be3.js → state-798ea663.js}

@@ -130,7 +130,7 @@ class EffectActor {
 
   /**
    * Observes the inspection events of this actor and its children: every
-   * transition, event delivery and dead letter of the execution.
+   * actor creation and transition of the execution.
    */
   inspect(observer) {
     const handler = typeof observer === 'function' ? observer : event => observer.next?.(event);

package/dist/xstate-effect-atom.js

@@ -1,7 +1,7 @@
 import { Cause } from 'effect';
 import { Atom, AsyncResult } from 'effect/unstable/reactivity';
-import { c as createEffectActor, N as NotReadyError, t as taggedState } from './state-9a718be3.js';
-export { N as NotReadyError } from './state-9a718be3.js';
+import { c as createEffectActor, N as NotReadyError, t as taggedState } from './state-798ea663.js';
+export { N as NotReadyError } from './state-798ea663.js';
 import 'xstate';
 import 'xstate/durable';
 

package/dist/xstate-effect.js

@@ -1,7 +1,7 @@
 import { Schema, Effect, Stream, Exit, Cause, Queue } from 'effect';
 import { createLogic, setup } from 'xstate';
-import { s as startHostedEffect, r as relayToParent, E as EffectInterruptedError, A as ActorStoppedError, a as runHostedEffect } from './state-9a718be3.js';
-export { A as ActorStoppedError, b as EffectActor, E as EffectInterruptedError, c as createEffectActor, t as taggedState } from './state-9a718be3.js';
+import { s as startHostedEffect, r as relayToParent, E as EffectInterruptedError, A as ActorStoppedError, a as runHostedEffect } from './state-798ea663.js';
+export { A as ActorStoppedError, b as EffectActor, E as EffectInterruptedError, c as createEffectActor, t as taggedState } from './state-798ea663.js';
 import { dual } from 'effect/Function';
 import 'xstate/durable';
 
@@ -608,13 +608,18 @@ function inspect(actor) {
 }
 
 /**
- * Streams the events the actor's system could not deliver: sends to a
- * stopped actor, invalid external events and internal events sent from
- * outside their owner. A dead letter is not an actor error. The stream runs
- * until it is interrupted or its scope closes.
+ * Streams the events the actor's system could not deliver, as reported by
+ * `system.onRejectedEvent`: sends to a stopped actor, invalid external
+ * events and internal events sent from outside their owner. A dead letter is
+ * not an actor error. The stream runs until it is interrupted or its scope
+ * closes.
  */
 function deadLetters(actor) {
-  return Stream.filter(inspect(actor), event => event.type === '@xstate.deadletter');
+  return Stream.callback(queue => Effect.acquireRelease(Effect.sync(() => actor.system.onRejectedEvent(rejection => {
+    Queue.offerUnsafe(queue, rejection);
+  })), subscription => Effect.sync(() => {
+    subscription.unsubscribe();
+  })));
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xstate/effect",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "type": "module",
   "description": "Effect integration for XState",
   "keywords": [
@@ -30,11 +30,11 @@
   },
   "peerDependencies": {
     "effect": "^4.0.0-rc.115",
-    "xstate": "^6.0.0-alpha.58"
+    "xstate": "^6.0.0-alpha.61"
   },
   "devDependencies": {
     "effect": "4.0.0-rc.115",
-    "xstate": "^6.0.0-alpha.58"
+    "xstate": "^6.0.0-alpha.61"
   },
   "preconstruct": {
     "entrypoints": [