effect-machine 0.11.0 → 0.13.0

package/dist/actor.d.ts

@@ -1,29 +1,15 @@
-import { EffectsDef, GuardsDef, MachineContext } from "./slot.js";
+import { ExtractReply, ReplyTypeBrand } from "./internal/brands.js";
 import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
+import { EffectsDef, GuardsDef } 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 } from "./machine.js";
+import { RuntimeQueuedEvent } from "./internal/runtime.js";
 import { Deferred, Effect, Layer, Option, PubSub, Queue, Ref, Scope, ServiceMap, Stream, SubscriptionRef } from "effect";
-import * as effect_Tracer0 from "effect/Tracer";
 
 //#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).
  */
@@ -59,11 +45,11 @@ interface ActorRef<State extends {
    */
   readonly call: (event: Event) => Effect.Effect<ProcessEventResult<State>>;
   /**
-   * Typed request-reply. Event is processed through the queue; caller gets
-   * the domain value returned by the handler's `reply` field.
+   * Typed request-reply. Accepts only events with a reply schema
+   * (defined via `Event.reply()`). Return type is inferred from the schema.
    * Fails with NoReplyError if the handler doesn't provide a reply.
    */
-  readonly ask: <R>(event: Event) => Effect.Effect<R, NoReplyError | ActorStoppedError>;
+  readonly ask: <E extends Event & ReplyTypeBrand<unknown>>(event: E) => Effect.Effect<ExtractReply<E>, NoReplyError | ActorStoppedError>;
   /** Observable state. */
   readonly state: SubscriptionRef.SubscriptionRef<State>;
   /** Stop the actor gracefully. */
@@ -103,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. */
@@ -121,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.
@@ -139,15 +151,16 @@ 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>(id: string, machine: Machine<S, E, R, any, any, any, any>, options?: {
+    readonly supervision?: Supervision.Policy;
+  }) => Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
   /**
    * Get an existing actor by ID
    */
@@ -189,9 +202,10 @@ 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, GD extends GuardsDef, EFD extends EffectsDef>(id: string, machine: Machine<S, E, R, any, any, GD, EFD>, 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;
@@ -199,12 +213,19 @@ declare const createActor: <S 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?: {
   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_Tracer0.ParentSpan> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope> | Exclude<Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>, effect_Tracer0.ParentSpan>>;
+  supervision?: Supervision.Policy; /** @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 };