effect-machine 0.20.0 → 0.21.0

package/dist/actor.d.ts

@@ -144,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.
  */
@@ -180,9 +194,15 @@ interface ActorSystemService {
    * ```
    */
   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>;
@@ -190,11 +210,19 @@ interface ActorSystemService {
   /**
    * 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.
@@ -258,4 +286,4 @@ declare const createActor: <S extends {
  */
 declare const Default: Layer.Layer<ActorSystem, never, never>;
 //#endregion
-export { ActorClient, ActorLifecycle, ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemService, Default, type ProcessEventResult, SystemEvent, SystemEventListener, SystemSpawnOptions, TransitionInfo, createActor };
+export { ActorClient, ActorLifecycle, ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemKey, ActorSystemService, Default, type ProcessEventResult, SystemEvent, SystemEventListener, SystemSpawnOptions, TransitionInfo, actorSystemKey, createActor };

package/dist/actor.js

@@ -14,6 +14,19 @@ import { Cause, Context, Deferred, Effect, Exit, Fiber, Layer, MutableHashMap, O
 * - ActorSystem service (spawn/stop/get actors)
 * - Actor creation and event loop
 */
+/** A typed identity for an actor stored in an ActorSystem. */
+var ActorSystemKey = class {
+	id;
+	constructor(id) {
+		this.id = id;
+	}
+};
+/** Create a typed ActorSystem identity. */
+const actorSystemKey = (id) => new ActorSystemKey(id);
+const actorSystemId = (id) => {
+	if (typeof id === "string") return id;
+	return id.id;
+};
 /**
 * ActorSystem service tag
 */
@@ -552,11 +565,34 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 		yield* actor.start.pipe(Effect.catchCause((cause) => actor.stop.pipe(Effect.andThen(Effect.failCause(cause)))));
 		return actor;
 	});
-	const spawn = (id, machine, options) => withSpawnGate(spawnRegular(id, machine, options));
-	const get = Effect.fn("effect-machine.actorSystem.get")(function* (id) {
-		return yield* Effect.sync(() => MutableHashMap.get(actorsMap, id));
-	});
-	const stop = Effect.fn("effect-machine.actorSystem.stop")(function* (id) {
+	const spawn = (idOrKey, machine, options) => {
+		const id = actorSystemId(idOrKey);
+		return withSpawnGate(spawnRegular(id, machine, options));
+	};
+	function get(idOrKey) {
+		return Effect.sync(() => MutableHashMap.get(actorsMap, actorSystemId(idOrKey)));
+	}
+	const sameActor = (left, right) => {
+		if (Option.isNone(left)) return Option.isNone(right);
+		return Option.isSome(right) && Object.is(left.value, right.value);
+	};
+	function watch(idOrKey) {
+		const id = actorSystemId(idOrKey);
+		return Stream.callback((queue) => Effect.acquireRelease(Effect.sync(() => {
+			const unsubscribe = (event) => {
+				if (event.id !== id) return;
+				if (event._tag === "ActorSpawned") Queue.offerUnsafe(queue, Option.some(event.actor));
+				else if (event._tag === "ActorStopped") Queue.offerUnsafe(queue, Option.none());
+			};
+			eventListeners.add(unsubscribe);
+			Queue.offerUnsafe(queue, MutableHashMap.get(actorsMap, id));
+			return () => {
+				eventListeners.delete(unsubscribe);
+			};
+		}), (unsubscribe) => Effect.sync(unsubscribe))).pipe(Stream.changesWith(sameActor));
+	}
+	const stop = Effect.fn("effect-machine.actorSystem.stop")(function* (idOrKey) {
+		const id = actorSystemId(idOrKey);
 		const maybeActor = MutableHashMap.get(actorsMap, id);
 		if (Option.isNone(maybeActor)) return false;
 		const actor = maybeActor.value;
@@ -573,6 +609,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 	return ActorSystem.of({
 		spawn,
 		get,
+		watch,
 		stop,
 		events: Stream.fromPubSub(eventPubSub),
 		get actors() {
@@ -600,4 +637,4 @@ const makeSystem = make;
 */
 const Default = Layer.effect(ActorSystem, make());
 //#endregion
-export { ActorScope, ActorSystem, Default, createActor, makeSystem };
+export { ActorScope, ActorSystem, ActorSystemKey, Default, actorSystemKey, createActor, makeSystem };

package/dist/atom.d.ts

@@ -1,6 +1,8 @@
-import { ActorLifecycle, ActorRef, TransitionInfo } from "./actor.js";
+import { ActorLifecycle, ActorRef, ActorSystemKey, ActorSystemService, TransitionInfo } from "./actor.js";
+import * as Option from "effect/Option";
 import * as Atom from "effect/unstable/reactivity/Atom";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+import * as Cause from "effect/Cause";
 //#region src/atom.d.ts
 /**
  * A writable Atom projection of an actor.
@@ -8,6 +10,32 @@ import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
  * The Atom value is the current actor state. Atom writes send actor events.
  */
 type ActorAtom<State, Event> = Atom.Writable<State, Event>;
+/** A reactive ActorSystem lookup for one typed actor identity. */
+type ActorLookupAtom<State extends {
+  readonly _tag: string;
+}, Event, Output> = Atom.Atom<AsyncResult.AsyncResult<Option.Option<ActorRef<State, Event, Output>>, Cause.NoSuchElementError>>;
+/** A Suspense-ready actor acquisition that follows later actor generations. */
+type ActorAcquireAtom<State extends {
+  readonly _tag: string;
+}, Event, Output> = Atom.Atom<AsyncResult.AsyncResult<ActorRef<State, Event, Output>, Cause.NoSuchElementError>>;
+/** Observe the current ActorRef for one ActorSystem key. */
+declare const fromSystem: {
+  <State extends {
+    readonly _tag: string;
+  }, Event, Output>(key: ActorSystemKey<State, Event, Output>): (system: ActorSystemService) => ActorLookupAtom<State, Event, Output>;
+  <State extends {
+    readonly _tag: string;
+  }, Event, Output>(system: ActorSystemService, key: ActorSystemKey<State, Event, Output>): ActorLookupAtom<State, Event, Output>;
+};
+/** Suspend while an ActorSystem key is absent and follow later generations. */
+declare const acquire: {
+  <State extends {
+    readonly _tag: string;
+  }, Event, Output>(key: ActorSystemKey<State, Event, Output>): (system: ActorSystemService) => ActorAcquireAtom<State, Event, Output>;
+  <State extends {
+    readonly _tag: string;
+  }, Event, Output>(system: ActorSystemService, key: ActorSystemKey<State, Event, Output>): ActorAcquireAtom<State, Event, Output>;
+};
 /**
  * Make a writable Atom from an actor.
  *
@@ -53,4 +81,4 @@ declare const can: {
   }, Event, Output>(actor: ActorRef<State, Event, Output>, event: Event): CanAtom;
 };
 //#endregion
-export { ActorAtom, CanAtom, can, latestTransition, lifecycle, make, select };
+export { ActorAcquireAtom, ActorAtom, ActorLookupAtom, CanAtom, acquire, can, fromSystem, latestTransition, lifecycle, make, select };

package/dist/atom.js

@@ -1,4 +1,6 @@
+import { Match } from "effect";
 import { dual } from "effect/Function";
+import * as Option$1 from "effect/Option";
 import * as Atom from "effect/unstable/reactivity/Atom";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 //#region src/atom.ts
@@ -8,6 +10,17 @@ import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 * The adapter keeps the actor as the state owner. Atom registries observe the
 * actor's SubscriptionRef and write events through its synchronous boundary.
 */
+/** Observe the current ActorRef for one ActorSystem key. */
+const fromSystem = dual(2, (system, key) => Atom.make(system.watch(key), { initialValue: Option$1.none() }));
+/** Suspend while an ActorSystem key is absent and follow later generations. */
+const acquire = dual(2, (system, key) => Atom.map(fromSystem(system, key), (result) => Match.value(result).pipe(Match.tagsExhaustive({
+	Initial: (initial) => AsyncResult.initial(initial.waiting),
+	Failure: (failure) => AsyncResult.failure(failure.cause, { waiting: failure.waiting }),
+	Success: (success) => Option$1.match(success.value, {
+		onNone: () => AsyncResult.initial(true),
+		onSome: (actor) => AsyncResult.success(actor, success)
+	})
+}))));
 /**
 * Make a writable Atom from an actor.
 *
@@ -44,4 +57,4 @@ const can = dual(2, (actor, event) => {
 	}).pipe(Atom.withEquality((value, next) => AsyncResult.isSuccess(value) && AsyncResult.isSuccess(next) && Object.is(value.value, next.value)));
 });
 //#endregion
-export { can, latestTransition, lifecycle, make, select };
+export { acquire, can, fromSystem, latestTransition, lifecycle, make, select };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaEr
 import { ActorExit, DefectPhase, Supervision } from "./supervision.js";
 import { Durability, DurabilityCommit, FinalContext, GuardPredicate, HandlerContext, InputMakeConfig, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, ReplayOptions, SpawnOptions, StateHandlerContext, TaskOptions, TimeoutConfig, machine_d_exports } from "./machine.js";
 import { ProcessEventResult } from "./internal/transition.js";
-import { ActorClient, ActorLifecycle, ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemService, Default, SystemEvent, SystemEventListener, SystemSpawnOptions, TransitionInfo } from "./actor.js";
+import { ActorClient, ActorLifecycle, ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemKey, ActorSystemService, Default, SystemEvent, SystemEventListener, SystemSpawnOptions, TransitionInfo, actorSystemKey } from "./actor.js";
 import { InputTestHarnessOptions, SimulationOptions, SimulationResult, TestHarness, TestHarnessOptions, assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
 import { AnyInspectionEvent, EffectEvent, ErrorEvent, EventReceivedEvent, GuardEvent, InspectionEvent, Inspector, InspectorHandler, InspectorService, OperationEvent, SpawnEvent, StopEvent, TaskEvent, TracingInspectorOptions, TransitionEvent, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
-export { type ActorClient, ActorExit, type ActorExit as ActorExitType, type ActorLifecycle, type ActorRef, type ActorRefSync, ActorScope, ActorStoppedError, type ActorSystemService as ActorSystem, Default as ActorSystemDefault, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type DefectPhase, type DeferReplyResult, DuplicateActorError, type Durability, type DurabilityCommit, type EffectEvent, type ErrorEvent, Event, type EventReceivedEvent, type FinalContext, type GuardEvent, type GuardPredicate, type HandlerContext, type InputMakeConfig, type InputTestHarnessOptions, type InspectionEvent, type InspectorService as Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, type Lifecycle, machine_d_exports as Machine, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, NoReplyError, type OperationEvent, PersistenceError, type ProcessEventResult, type Recovery, type RecoveryContext, type ReplayOptions, type ReplyFields, type ReplyResult, type SimulationOptions, type SimulationResult, type SpawnEvent, type SpawnOptions, State, type StateHandlerContext, type StopEvent, Supervision, type SystemEvent, type SystemEventListener, type SystemSpawnOptions, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TimeoutConfig, type TracingInspectorOptions, type TransitionEvent, type TransitionInfo, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };
+export { type ActorClient, ActorExit, type ActorExit as ActorExitType, type ActorLifecycle, type ActorRef, type ActorRefSync, ActorScope, ActorStoppedError, type ActorSystemService as ActorSystem, Default as ActorSystemDefault, ActorSystemKey, ActorSystem as ActorSystemService, type AnyInspectionEvent, AssertionError, type DefectPhase, type DeferReplyResult, DuplicateActorError, type Durability, type DurabilityCommit, type EffectEvent, type ErrorEvent, Event, type EventReceivedEvent, type FinalContext, type GuardEvent, type GuardPredicate, type HandlerContext, type InputMakeConfig, type InputTestHarnessOptions, type InspectionEvent, type InspectorService as Inspector, type InspectorHandler, Inspector as InspectorService, InvalidSchemaError, type Lifecycle, machine_d_exports as Machine, type MachineEventSchema, type MachineRef, type MachineStateSchema, type Machine as MachineType, type MakeConfig, MissingMatchHandlerError, NoReplyError, type OperationEvent, PersistenceError, type ProcessEventResult, type Recovery, type RecoveryContext, type ReplayOptions, type ReplyFields, type ReplyResult, type SimulationOptions, type SimulationResult, type SpawnEvent, type SpawnOptions, State, type StateHandlerContext, type StopEvent, Supervision, type SystemEvent, type SystemEventListener, type SystemSpawnOptions, type TaskEvent, type TaskOptions, type TestHarness, type TestHarnessOptions, type TimeoutConfig, type TracingInspectorOptions, type TransitionEvent, type TransitionInfo, VersionConflictError, actorSystemKey, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };

package/dist/index.js

@@ -2,7 +2,7 @@ import { ActorStoppedError, AssertionError, DuplicateActorError, InvalidSchemaEr
 import { Event, State } from "./schema.js";
 import { Inspector, collectingInspector, combineInspectors, consoleInspector, makeInspector, makeInspectorEffect, tracingInspector } from "./inspection.js";
 import { ActorExit, Supervision } from "./supervision.js";
-import { ActorScope, ActorSystem, Default } from "./actor.js";
+import { ActorScope, ActorSystem, ActorSystemKey, Default, actorSystemKey } from "./actor.js";
 import { machine_exports } from "./machine.js";
 import { assertNeverReaches, assertPath, assertReaches, createTestHarness, simulate } from "./testing.js";
-export { ActorExit, ActorScope, ActorStoppedError, Default as ActorSystemDefault, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, NoReplyError, PersistenceError, State, Supervision, VersionConflictError, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };
+export { ActorExit, ActorScope, ActorStoppedError, Default as ActorSystemDefault, ActorSystemKey, ActorSystem as ActorSystemService, AssertionError, DuplicateActorError, Event, Inspector as InspectorService, InvalidSchemaError, machine_exports as Machine, MissingMatchHandlerError, NoReplyError, PersistenceError, State, Supervision, VersionConflictError, actorSystemKey, assertNeverReaches, assertPath, assertReaches, collectingInspector, combineInspectors, consoleInspector, createTestHarness, makeInspector, makeInspectorEffect, simulate, tracingInspector };

package/dist/internal/utils.js

@@ -64,6 +64,7 @@ const isEffect = Effect.isEffect;
 const stubSystem = {
 	spawn: () => Effect.die("spawn not supported in stub system"),
 	get: () => Effect.die("get not supported in stub system"),
+	watch: () => Stream.die("watch not supported in stub system"),
 	stop: () => Effect.die("stop not supported in stub system"),
 	events: Stream.empty,
 	get actors() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-machine",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/cevr/effect-machine.git"