effect-machine 0.19.0 → 0.21.0

package/dist/actor.d.ts

@@ -5,17 +5,31 @@ import { Lifecycle, Machine } from "./machine.js";
 import { ProcessEventResult } from "./internal/transition.js";
 import { Context, Effect, Layer, Option, Scope, Stream, SubscriptionRef } from "effect";
 //#region src/actor.d.ts
-/**
- * Sync projection of ActorRef for non-Effect boundaries (React hooks, framework callbacks).
- */
+/** JavaScript client for code that does not run inside Effect. */
+interface ActorClient<State extends {
+  readonly _tag: string;
+}, Event, Output = State> {
+  readonly send: (event: Event) => void;
+  readonly stop: () => void;
+  readonly getSnapshot: () => State;
+  readonly matches: (tag: State["_tag"]) => boolean;
+  readonly canSync: (event: Event) => boolean;
+  readonly can: (event: Event) => Promise<boolean>;
+  readonly getLifecycle: () => ActorLifecycle<State, Output>;
+  readonly getLatestTransition: () => TransitionInfo<State, Event> | undefined;
+  readonly subscribe: (listener: (state: State) => void) => () => void;
+}
+/** @deprecated Use `ActorClient`. */
 interface ActorRefSync<State extends {
   readonly _tag: string;
-}, Event> {
+}, Event, Output = State> {
   readonly send: (event: Event) => void;
   readonly stop: () => void;
   readonly snapshot: () => State;
   readonly matches: (tag: State["_tag"]) => boolean;
   readonly can: (event: Event) => boolean;
+  readonly lifecycle: () => ActorLifecycle<State, Output>;
+  readonly latestTransition: () => TransitionInfo<State, Event> | undefined;
 }
 /**
  * Information about a successful transition.
@@ -26,9 +40,19 @@ interface TransitionInfo<State, Event> {
   readonly toState: State;
   readonly event: Event;
 }
+/** Observable actor lifecycle. Domain state remains available through `actor.state`. */
+type ActorLifecycle<State, Output = State> = {
+  readonly _tag: "Created";
+} | {
+  readonly _tag: "Starting";
+  readonly generation: number;
+} | {
+  readonly _tag: "Active";
+  readonly generation: number;
+} | ActorExit<State, Output>;
 interface ActorRef<State extends {
   readonly _tag: string;
-}, Event> {
+}, Event, Output = State> {
   readonly id: string;
   /** Send an event (fire-and-forget). */
   readonly send: (event: Event) => Effect.Effect<void>;
@@ -36,7 +60,7 @@ interface ActorRef<State extends {
    * Serialized request-reply (OTP gen_server:call).
    * Event is processed through the queue; caller gets ProcessEventResult back.
    */
-  readonly call: (event: Event) => Effect.Effect<ProcessEventResult<State>>;
+  readonly call: (event: Event) => Effect.Effect<ProcessEventResult<State, Event>>;
   /**
    * Typed request-reply. Accepts only events with a reply schema
    * (defined via `Event.reply()`). Return type is inferred from the schema.
@@ -45,6 +69,10 @@ interface ActorRef<State extends {
   readonly ask: <E extends Event & ReplyTypeBrand<unknown>>(event: E) => Effect.Effect<ExtractReply<E>, NoReplyError | ActorStoppedError>;
   /** Observable state. */
   readonly state: SubscriptionRef.SubscriptionRef<State>;
+  /** Observable actor lifecycle. */
+  readonly lifecycle: SubscriptionRef.SubscriptionRef<ActorLifecycle<State, Output>>;
+  /** The latest accepted edge. This value remains available after actor exit. */
+  readonly latestTransition: SubscriptionRef.SubscriptionRef<TransitionInfo<State, Event> | undefined>;
   /** Stop the actor gracefully. */
   readonly stop: Effect.Effect<void>;
   /**
@@ -60,7 +88,7 @@ interface ActorRef<State extends {
   readonly snapshot: Effect.Effect<State>;
   /** Check if current state matches tag. */
   readonly matches: (tag: State["_tag"]) => Effect.Effect<boolean>;
-  /** Check if event can be handled in current state. */
+  /** Check if an event has an enabled transition. Supports Boolean and Effect predicates. */
   readonly can: (event: Event) => Effect.Effect<boolean>;
   /** Stream of state changes. */
   readonly changes: Stream.Stream<State>;
@@ -81,6 +109,8 @@ interface ActorRef<State extends {
   };
   /** Wait for a final state (includes current snapshot). */
   readonly awaitFinal: Effect.Effect<State>;
+  /** Wait for the domain output of a final state. */
+  readonly awaitOutput: Effect.Effect<Output, ActorStoppedError>;
   /** Send event and wait for predicate, state variant, or final state. */
   readonly sendAndWait: {
     (event: Event, predicate: (state: State) => boolean): Effect.Effect<State>;
@@ -91,18 +121,20 @@ interface ActorRef<State extends {
   };
   /** Subscribe to state changes (sync callback). Returns unsubscribe function. */
   readonly subscribe: (fn: (state: State) => void) => () => void;
+  /** JavaScript client for callbacks and applications outside Effect. */
+  readonly client: ActorClient<State, Event, Output>;
   /**
    * 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>>;
+  readonly awaitExit: Effect.Effect<ActorExit<State, Output>>;
   /**
    * 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>;
+  /** @deprecated Use `client`. */
+  readonly sync: ActorRefSync<State, Event, Output>;
   /** The actor system this actor belongs to. */
   readonly system: ActorSystemService;
   /** Child actors spawned via `self.spawn` in this actor's handlers. */
@@ -112,6 +144,20 @@ interface ActorRef<State extends {
 type AnyState = {
   readonly _tag: string;
 };
+declare const ActorSystemKeyTypeId: unique symbol;
+/** A typed identity for an actor stored in an ActorSystem. */
+declare class ActorSystemKey<State extends AnyState, Event, Output = State> {
+  readonly id: string;
+  readonly [ActorSystemKeyTypeId]: {
+    readonly state: State;
+    readonly event: Event;
+    readonly output: Output;
+  };
+  constructor(id: string);
+}
+/** Create a typed ActorSystem identity. */
+declare const actorSystemKey: <State extends AnyState, Event, Output = State>(id: string) => ActorSystemKey<State, Event, Output>;
+type AnyActorSystemKey = ActorSystemKey<AnyState, unknown, unknown>;
 /**
  * Events emitted by the ActorSystem when actors are spawned or stopped.
  */
@@ -147,22 +193,36 @@ interface ActorSystemService {
    * const actor = yield* system.spawn("my-actor", machine);
    * ```
    */
-  readonly spawn: <S extends {
-    readonly _tag: string;
-  }, E extends {
-    readonly _tag: string;
-  }, R>(id: string, machine: Machine<S, E, R, any, any>, options?: {
-    readonly supervision?: Supervision.Policy;
-    readonly lifecycle?: Lifecycle<S, E>;
-  }) => Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
+  readonly spawn: {
+    <S extends AnyState, E extends {
+      readonly _tag: string;
+    }, R, Output>(key: ActorSystemKey<S, E, Output>, machine: Machine<S, E, R, any, any, void, Output>, options?: SystemSpawnOptions<S, E, void>): Effect.Effect<ActorRef<S, E, Output>, DuplicateActorError, R>;
+    <S extends AnyState, E extends {
+      readonly _tag: string;
+    }, R, Output>(id: string, machine: Machine<S, E, R, any, any, void, Output>, options?: SystemSpawnOptions<S, E, void>): Effect.Effect<ActorRef<S, E, Output>, DuplicateActorError, R>;
+    <S extends AnyState, E extends {
+      readonly _tag: string;
+    }, R, Input, Output>(key: ActorSystemKey<S, E, Output>, machine: Machine<S, E, R, any, any, Input, Output>, options: SystemSpawnOptions<S, E, Input>): Effect.Effect<ActorRef<S, E, Output>, DuplicateActorError, R>;
+    <S extends AnyState, E extends {
+      readonly _tag: string;
+    }, R, Input, Output>(id: string, machine: Machine<S, E, R, any, any, Input, Output>, options: SystemSpawnOptions<S, E, Input>): Effect.Effect<ActorRef<S, E, Output>, DuplicateActorError, R>;
+  };
   /**
    * Get an existing actor by ID
    */
-  readonly get: (id: string) => Effect.Effect<Option.Option<ActorRef<AnyState, unknown>>>;
+  readonly get: {
+    <S extends AnyState, E, Output>(key: ActorSystemKey<S, E, Output>): Effect.Effect<Option.Option<ActorRef<S, E, Output>>>;
+    (id: string): Effect.Effect<Option.Option<ActorRef<AnyState, unknown>>>;
+  };
+  /** Observe the current actor for one ID across actor generations. */
+  readonly watch: {
+    <S extends AnyState, E, Output>(key: ActorSystemKey<S, E, Output>): Stream.Stream<Option.Option<ActorRef<S, E, Output>>>;
+    (id: string): Stream.Stream<Option.Option<ActorRef<AnyState, unknown>>>;
+  };
   /**
    * Stop an actor by ID
    */
-  readonly stop: (id: string) => Effect.Effect<boolean>;
+  readonly stop: (id: string | AnyActorSystemKey) => Effect.Effect<boolean>;
   /**
    * Async stream of system events (actor spawned/stopped).
    * Each subscriber gets their own queue — late subscribers miss prior events.
@@ -179,6 +239,15 @@ interface ActorSystemService {
    */
   readonly subscribe: (fn: SystemEventListener) => () => void;
 }
+type SystemSpawnOptions<S, E, Input> = {
+  readonly supervision?: Supervision.Policy;
+  readonly lifecycle?: Lifecycle<S, E>;
+  readonly hydrate?: S;
+} & ([Input] extends [void] ? {
+  readonly input?: never;
+} : {
+  readonly input: Input;
+});
 declare const ActorSystem_base: Context.ServiceClass<ActorSystem, "effect-machine/actor/ActorSystem", ActorSystemService>;
 /**
  * ActorSystem service tag
@@ -203,16 +272,18 @@ declare const createActor: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R>(id: string, machine: Machine<S, E, R, any, any>, options?: {
-  initialState?: S;
+}, R, O>(id: string, machine: Machine<S, E, R, any, any, any, O>, options: {
+  initialState: S;
+  machineInitial: S;
+  hydrated?: boolean;
   supervision?: Supervision.Policy;
   lifecycle?: Lifecycle<S, E>;
   /** @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, R>;
+}) => Effect.Effect<ActorRef<S, E, O>, never, R>;
 /**
  * Default ActorSystem layer
  */
 declare const Default: Layer.Layer<ActorSystem, never, never>;
 //#endregion
-export { ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemService, Default, type ProcessEventResult, SystemEvent, SystemEventListener, TransitionInfo, createActor };
+export { ActorClient, ActorLifecycle, ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemKey, ActorSystemService, Default, type ProcessEventResult, SystemEvent, SystemEventListener, SystemSpawnOptions, TransitionInfo, actorSystemKey, createActor };