effect-machine 0.12.0 → 0.14.0

package/dist/testing.js

@@ -1,13 +1,22 @@
 import { stubSystem } from "./internal/utils.js";
 import { AssertionError } from "./errors.js";
-import { BuiltMachine } from "./machine.js";
 import { executeTransition, shouldPostpone } from "./internal/transition.js";
+import { materializeMachine } from "./machine.js";
 import { Effect, SubscriptionRef } from "effect";
 //#region src/testing.ts
+const makeDummySelf = (label) => {
+	const dummySend = Effect.fn(label)((_event) => Effect.void);
+	return {
+		send: dummySend,
+		cast: dummySend,
+		spawn: () => Effect.die(`spawn not supported in ${label}`),
+		reply: () => Effect.succeed(false)
+	};
+};
 /**
 * Simulate a sequence of events through a machine without running an actor.
 * Useful for testing state transitions in isolation.
-* Does not run onEnter/spawn/background effects, but does run guard/effect slots
+* Does not run onEnter/spawn/background effects, but does run slots
 * within transition handlers.
 *
 * @example
@@ -24,15 +33,9 @@ import { Effect, SubscriptionRef } from "effect";
 * expect(result.states).toHaveLength(3) // Idle -> Loading -> Success
 * ```
 */
-const simulate = Effect.fn("effect-machine.simulate")(function* (input, events) {
-	const machine = input instanceof BuiltMachine ? input._inner : input;
-	const dummySend = Effect.fn("effect-machine.testing.simulate.send")((_event) => Effect.void);
-	const dummySelf = {
-		send: dummySend,
-		cast: dummySend,
-		spawn: () => Effect.die("spawn not supported in simulation"),
-		reply: () => Effect.succeed(false)
-	};
+const simulate = Effect.fn("effect-machine.simulate")(function* (input, events, options) {
+	const machine = materializeMachine(input, options?.slots);
+	const dummySelf = makeDummySelf("effect-machine.testing.simulate");
 	let currentState = machine.initial;
 	const states = [currentState];
 	const hasPostponeRules = machine.postponeRules.length > 0;
@@ -74,8 +77,8 @@ const simulate = Effect.fn("effect-machine.simulate")(function* (input, events)
 /**
 * Assert that a machine can reach a specific state given a sequence of events
 */
-const assertReaches = Effect.fn("effect-machine.assertReaches")(function* (input, events, expectedTag) {
-	const result = yield* simulate(input, events);
+const assertReaches = Effect.fn("effect-machine.assertReaches")(function* (input, events, expectedTag, options) {
+	const result = yield* simulate(input, events, options);
 	if (result.finalState._tag !== expectedTag) return yield* new AssertionError({ message: `Expected final state "${expectedTag}" but got "${result.finalState._tag}". States visited: ${result.states.map((s) => s._tag).join(" -> ")}` });
 	return result.finalState;
 });
@@ -91,8 +94,8 @@ const assertReaches = Effect.fn("effect-machine.assertReaches")(function* (input
 * )
 * ```
 */
-const assertPath = Effect.fn("effect-machine.assertPath")(function* (input, events, expectedPath) {
-	const result = yield* simulate(input, events);
+const assertPath = Effect.fn("effect-machine.assertPath")(function* (input, events, expectedPath, options) {
+	const result = yield* simulate(input, events, options);
 	const actualPath = result.states.map((s) => s._tag);
 	if (actualPath.length !== expectedPath.length) return yield* new AssertionError({ message: `Path length mismatch. Expected ${expectedPath.length} states but got ${actualPath.length}.\nExpected: ${expectedPath.join(" -> ")}\nActual:   ${actualPath.join(" -> ")}` });
 	for (let i = 0; i < expectedPath.length; i++) if (actualPath[i] !== expectedPath[i]) return yield* new AssertionError({ message: `Path mismatch at position ${i}. Expected "${expectedPath[i]}" but got "${actualPath[i]}".\nExpected: ${expectedPath.join(" -> ")}\nActual:   ${actualPath.join(" -> ")}` });
@@ -111,15 +114,15 @@ const assertPath = Effect.fn("effect-machine.assertPath")(function* (input, even
 * )
 * ```
 */
-const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(function* (input, events, forbiddenTag) {
-	const result = yield* simulate(input, events);
+const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(function* (input, events, forbiddenTag, options) {
+	const result = yield* simulate(input, events, options);
 	const visitedIndex = result.states.findIndex((s) => s._tag === forbiddenTag);
 	if (visitedIndex !== -1) return yield* new AssertionError({ message: `Machine reached forbidden state "${forbiddenTag}" at position ${visitedIndex}.\nStates visited: ${result.states.map((s) => s._tag).join(" -> ")}` });
 	return result;
 });
 /**
 * Create a test harness for step-by-step testing.
-* Does not run onEnter/spawn/background effects, but does run guard/effect slots
+* Does not run onEnter/spawn/background effects, but does run slots
 * within transition handlers.
 *
 * @example Basic usage
@@ -139,14 +142,8 @@ const assertNeverReaches = Effect.fn("effect-machine.assertNeverReaches")(functi
 * ```
 */
 const createTestHarness = Effect.fn("effect-machine.createTestHarness")(function* (input, options) {
-	const machine = input instanceof BuiltMachine ? input._inner : input;
-	const dummySend = Effect.fn("effect-machine.testing.harness.send")((_event) => Effect.void);
-	const dummySelf = {
-		send: dummySend,
-		cast: dummySend,
-		spawn: () => Effect.die("spawn not supported in test harness"),
-		reply: () => Effect.succeed(false)
-	};
+	const machine = materializeMachine(input, options?.slots);
+	const dummySelf = makeDummySelf("effect-machine.testing.harness");
 	const stateRef = yield* SubscriptionRef.make(machine.initial);
 	const hasPostponeRules = machine.postponeRules.length > 0;
 	const postponed = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-machine",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/effect-machine.git"
@@ -56,20 +56,20 @@
     "release": "bun run build && changeset publish"
   },
   "dependencies": {
-    "effect": "4.0.0-beta.42"
+    "effect": "4.0.0-beta.43"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.6.0",
     "@changesets/cli": "^2.30.0",
-    "@effect/language-service": "^0.82.0",
+    "@effect/language-service": "^0.84.2",
     "@types/bun": "1.3.11",
     "concurrently": "^9.2.1",
     "effect-bun-test": "0.3.0",
     "effect-v3": "npm:effect@^3.21.0",
     "lefthook": "^2.1.4",
-    "oxfmt": "^0.41.0",
-    "oxlint": "^1.56.0",
-    "tsdown": "^0.21.4",
+    "oxfmt": "^0.42.0",
+    "oxlint": "^1.57.0",
+    "tsdown": "^0.21.7",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
@@ -81,6 +81,6 @@
     }
   },
   "overrides": {
-    "effect": "4.0.0-beta.42"
+    "effect": "4.0.0-beta.43"
   }
 }

package/v3/dist/actor.d.ts

@@ -1,30 +1,15 @@
-import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
 import { ExtractReply, ReplyTypeBrand } from "./internal/brands.js";
 import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
+import { ProvideSlots, SlotsDef } from "./slot.js";
+import { ActorExit, Supervision } from "./supervision.js";
 import { ProcessEventError, ProcessEventHooks, ProcessEventResult, processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
-import { BuiltMachine, Machine, MachineRef } from "./machine.js";
+import { Machine, PersistConfig } from "./machine.js";
+import { RuntimeQueuedEvent } from "./internal/runtime.js";
 import { Context, Deferred, Effect, Layer, Option, PubSub, Queue, Ref, Scope, Stream, SubscriptionRef } from "effect";
-import * as effect_dist_dts_Tracer_js0 from "effect/dist/dts/Tracer.js";
 
 //#region src/actor.d.ts
-/** Discriminated mailbox request */
-type QueuedEvent<E> = {
-  readonly _tag: "send";
-  readonly event: E;
-} | {
-  readonly _tag: "call";
-  readonly event: E;
-  readonly reply: Deferred.Deferred<ProcessEventResult<{
-    readonly _tag: string;
-  }>, ActorStoppedError>;
-} | {
-  readonly _tag: "ask";
-  readonly event: E;
-  readonly reply: Deferred.Deferred<unknown, NoReplyError | ActorStoppedError>;
-};
-/**
- * Reference to a running actor.
- */
+/** Discriminated mailbox request — alias for RuntimeQueuedEvent */
+type QueuedEvent<E> = RuntimeQueuedEvent<E>;
 /**
  * Sync projection of ActorRef for non-Effect boundaries (React hooks, framework callbacks).
  */
@@ -104,6 +89,25 @@ interface ActorRef<State extends {
   };
   /** Subscribe to state changes (sync callback). Returns unsubscribe function. */
   readonly subscribe: (fn: (state: State) => void) => () => void;
+  /**
+   * Wait for this actor's terminal exit. Resolves with the exit reason.
+   * Set exactly once when the actor terminates (final, stop, drain, or defect).
+   */
+  readonly awaitExit: Effect.Effect<ActorExit<State>>;
+  /**
+   * Watch another actor. Returns an Effect that resolves with the exit reason
+   * when the watched actor terminally stops. Ignores restarts (Step 3).
+   * Built on the other actor's exitDeferred — authoritative, not system events.
+   */
+  readonly watch: (other: {
+    readonly id: string;
+    readonly awaitExit: Effect.Effect<ActorExit<unknown>>;
+  }) => Effect.Effect<ActorExit<unknown>>;
+  /**
+   * Drain: process all remaining events in the queue, then stop.
+   * Unlike `stop` (which interrupts immediately), `drain` lets the actor finish its work.
+   */
+  readonly drain: Effect.Effect<void>;
   /** Sync helpers for non-Effect boundaries. */
   readonly sync: ActorRefSync<State, Event>;
   /** The actor system this actor belongs to. */
@@ -122,10 +126,17 @@ type SystemEvent = {
   readonly _tag: "ActorSpawned";
   readonly id: string;
   readonly actor: ActorRef<AnyState, unknown>;
+} | {
+  readonly _tag: "ActorRestarted";
+  readonly id: string;
+  readonly actor: ActorRef<AnyState, unknown>;
+  readonly generation: number;
+  readonly exit: ActorExit<unknown>;
 } | {
   readonly _tag: "ActorStopped";
   readonly id: string;
   readonly actor: ActorRef<AnyState, unknown>;
+  readonly exit: ActorExit<unknown>;
 };
 /**
  * Listener callback for system events.
@@ -140,15 +151,18 @@ interface ActorSystem {
    *
    * @example
    * ```ts
-   * const built = machine.build({ fetchData: ... })
-   * const actor = yield* system.spawn("my-actor", built);
+   * const actor = yield* system.spawn("my-actor", machine);
    * ```
    */
   readonly spawn: <S extends {
     readonly _tag: string;
   }, E extends {
     readonly _tag: string;
-  }, R>(id: string, machine: BuiltMachine<S, E, R>) => Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
+  }, R, SD extends SlotsDef = Record<string, never>>(id: string, machine: Machine<S, E, R, any, any, SD>, options?: {
+    readonly supervision?: Supervision.Policy;
+    readonly slots?: ProvideSlots<SD, any>;
+    readonly persist?: PersistConfig<S>;
+  }) => Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
   /**
    * Get an existing actor by ID
    */
@@ -184,28 +198,37 @@ type Listeners<S> = Set<(state: S) => void>;
  */
 declare const notifyListeners: <S>(listeners: Listeners<S>, state: S) => void;
 /**
- * Build core ActorRef methods shared between regular and persistent actors.
+ * Build core ActorRef methods.
  */
 declare const buildActorRefCore: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, any, any, GD, EFD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueue: Queue.Queue<QueuedEvent<E>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, transitionsPubSub?: PubSub.PubSub<TransitionInfo<S, E>>) => ActorRef<S, E>;
+}, R, SD extends SlotsDef>(id: string, machine: Machine<S, E, R, any, any, SD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueueRef: Ref.Ref<Queue.Queue<QueuedEvent<E>>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, system: ActorSystem, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, transitionsPubSub: PubSub.PubSub<TransitionInfo<S, E>> | undefined, exitDeferred: Deferred.Deferred<ActorExit<S>, never>) => ActorRef<S, E>;
 /**
- * Create and start an actor for a machine
+ * Create and start an actor for a machine.
+ * Delegates to the shared runtime kernel with actor-specific lifecycle hooks.
  */
 declare const createActor: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, options?: {
+}, R, SD extends SlotsDef>(id: string, machine: Machine<S, E, R, any, any, SD>, options?: {
   initialState?: S;
-} | undefined) => Effect.Effect<ActorRef<S, E>, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, effect_dist_dts_Tracer_js0.ParentSpan> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope> | Exclude<Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>, effect_dist_dts_Tracer_js0.ParentSpan>>;
+  supervision?: Supervision.Policy;
+  persist?: PersistConfig<S>; /** @internal Called by system after each restart — emits ActorRestarted system event */
+  onRestart?: (generation: number, exit: ActorExit<unknown>) => Effect.Effect<void>;
+} | undefined) => Effect.Effect<ActorRef<S, E>, never, never>;
 /** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
 declare const settlePendingReplies: (pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, actorId: string) => Effect.Effect<void, never, never>;
+/**
+ * Create an ActorSystem instance. Must be run in a Scope.
+ * @internal — use Default layer for normal usage
+ */
+declare const makeSystem: () => Effect.Effect<ActorSystem, never, Scope.Scope>;
 /**
  * Default ActorSystem layer
  */
 declare const Default: Layer.Layer<ActorSystem, never, never>;
 //#endregion
-export { ActorRef, ActorRefSync, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, QueuedEvent, SystemEvent, SystemEventListener, TransitionInfo, buildActorRefCore, createActor, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };
+export { ActorRef, ActorRefSync, ActorSystem, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, QueuedEvent, SystemEvent, SystemEventListener, TransitionInfo, buildActorRefCore, createActor, makeSystem, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };