effect-machine 0.22.0 → 0.23.0

package/README.md

@@ -95,6 +95,10 @@ Effect Machine does not add an action queue or a second context system.
 
 Effect requirements remain in `R`. A machine cannot start until the application provides every required service. Effectful transition handlers must have `never` in their error channel. Convert expected failures to states or events.
 
+Machine-lifetime backgrounds can read `self.state` and `self.latestTransition`. These are the
+actor-owned subscription refs. They stay stable across supervision generations. Treat them as
+read-only and use `SubscriptionRef.get` or `SubscriptionRef.changes` to observe them.
+
 Read [the Effect model](./docs/effect-model.md) and [async work ownership](./docs/async-work.md).
 
 ## Guards and stable state

package/dist/actor.js

@@ -259,6 +259,7 @@ const runSupervisionLoop = (cell, options) => Effect.gen(function* () {
 		const freshQueue = yield* Queue.unbounded();
 		yield* Ref.set(cell.eventQueueRef, freshQueue);
 		yield* SubscriptionRef.set(cell.stateRef, restartState);
+		yield* SubscriptionRef.set(cell.latestTransitionRef, void 0);
 		yield* Ref.set(cell.stoppedRef, false);
 		cell.children.clear();
 		const newRuntime = yield* options.spawnGeneration(cell.machine);
@@ -354,12 +355,6 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 		return {
 			onEvent,
 			onStateChange: (result, event) => Effect.gen(function* () {
-				const latest = result.transitions.at(-1);
-				if (latest !== void 0) yield* SubscriptionRef.set(latestTransitionRef, {
-					fromState: latest.previousState,
-					toState: latest.newState,
-					event: latest.event
-				});
 				notifyListeners(listeners, result.newState);
 				const durability = lifecycle?.durability;
 				if (durability === void 0 || !result.transitioned) return;
@@ -406,6 +401,7 @@ const createActor = Effect.fn("effect-machine.actor.spawn")(function* (id, machi
 			skipFinalizer: true,
 			cellResources: {
 				stateRef,
+				latestTransitionRef,
 				stoppedRef,
 				eventQueue: currentQueue
 			},

package/dist/cluster/entity-machine.js

@@ -55,6 +55,7 @@ const EntityMachine = { layer: (entity, machine, ...optionsArgument) => {
 		const versionRef = yield* Ref.make(persistCtx.initialVersion);
 		const computedInitial = initialState ?? machineInitial;
 		const stateRef = yield* SubscriptionRef.make(computedInitial);
+		const latestTransitionRef = yield* SubscriptionRef.make(void 0);
 		const stoppedRef = yield* Ref.make(false);
 		const eventQueue = yield* Queue.unbounded();
 		let hooks = void 0;
@@ -65,6 +66,7 @@ const EntityMachine = { layer: (entity, machine, ...optionsArgument) => {
 			childIdPrefix: `${entityId}/`,
 			cellResources: {
 				stateRef,
+				latestTransitionRef,
 				stoppedRef,
 				eventQueue
 			}

package/dist/internal/runtime.js

@@ -55,7 +55,7 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 	const generation = config.generation ?? 0;
 	const services = yield* Effect.context();
 	const fork = Effect.runForkWith(services);
-	const { stateRef, stoppedRef, eventQueue } = config.cellResources;
+	const { stateRef, latestTransitionRef, stoppedRef, eventQueue } = config.cellResources;
 	const pendingRequests = /* @__PURE__ */ new Set();
 	const exitDeferred = yield* Deferred.make();
 	const actorScope = yield* Scope.make();
@@ -72,6 +72,8 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 	let spawn = defaultSpawn;
 	if (onChildSpawned !== void 0) spawn = (childId, childMachine) => defaultSpawn(childId, childMachine).pipe(Effect.tap((child) => onChildSpawned(childId, child)));
 	const self = {
+		state: stateRef,
+		latestTransition: latestTransitionRef,
 		send: selfSend,
 		spawn,
 		reply: (value) => Effect.sync(() => {
@@ -117,6 +119,12 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 		else initialResult = initialProcessing;
 		if (initialResult.transitioned) {
 			yield* SubscriptionRef.set(stateRef, initialResult.newState);
+			const latest = initialResult.transitions.at(-1);
+			if (latest !== void 0) yield* SubscriptionRef.set(latestTransitionRef, {
+				fromState: latest.previousState,
+				toState: latest.newState,
+				event: latest.event
+			});
 			if (lifecycle?.onStateChange !== void 0) {
 				const stateChange = lifecycle.onStateChange(initialResult, initEvent);
 				if (isEffect(stateChange)) yield* stateChange;
@@ -164,7 +172,7 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 				return Effect.void;
 			})), Effect.asVoid)
 		};
-		const loopFiber = yield* runtimeEventLoop(machine, stateRef, eventQueue, pendingRequests, stoppedRef, self, stateScopeRef, actorId, generation, system, exitDeferred, augmentedHooks, deferredReplyRef, lifecycle, fork).pipe(Effect.provide(services), Effect.forkDetach);
+		const loopFiber = yield* runtimeEventLoop(machine, stateRef, latestTransitionRef, eventQueue, pendingRequests, stoppedRef, self, stateScopeRef, actorId, generation, system, exitDeferred, augmentedHooks, deferredReplyRef, lifecycle, fork).pipe(Effect.provide(services), Effect.forkDetach);
 		loopFiberRef.current = loopFiber;
 		if (backgroundFibers.length > 0) yield* Effect.raceAll(backgroundFibers.map((fiber) => Fiber.await(fiber).pipe(Effect.flatMap((exit) => {
 			if (exit._tag === "Failure" && !Cause.hasInterruptsOnly(exit.cause)) return setExit(RuntimeExit.Defect(exit.cause, "background")).pipe(Effect.andThen(Ref.set(stoppedRef, true)), Effect.andThen(Fiber.interrupt(loopFiber)));
@@ -190,7 +198,7 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 	}).pipe(Effect.asVoid);
 	if (config.skipFinalizer !== true) yield* Effect.addFinalizer(() => stop);
 	return {
-		...makeHandle(actorId, stateRef, stoppedRef, eventQueue, pendingRequests, exitDeferred),
+		...makeHandle(actorId, stateRef, latestTransitionRef, stoppedRef, eventQueue, pendingRequests, exitDeferred),
 		stop: stop.pipe(Effect.provide(services)),
 		start: start.pipe(Effect.provide(services))
 	};
@@ -199,7 +207,7 @@ const createRuntime = Effect.fn("effect-machine.runtime.create")(function* (mach
 * Build the runtime handle.
 * Shared between initial-final and normal paths.
 */
-const makeHandle = (actorId, stateRef, stoppedRef, eventQueue, pendingRequests, exitDeferred) => {
+const makeHandle = (actorId, stateRef, latestTransitionRef, stoppedRef, eventQueue, pendingRequests, exitDeferred) => {
 	const track = (deferred, settle) => {
 		pendingRequests.add(settle);
 		return Deferred.await(deferred).pipe(Effect.ensuring(Effect.sync(() => pendingRequests.delete(settle))));
@@ -261,6 +269,7 @@ const makeHandle = (actorId, stateRef, stoppedRef, eventQueue, pendingRequests,
 		},
 		getState: SubscriptionRef.get(stateRef),
 		stateRef,
+		latestTransitionRef,
 		stop: Effect.void,
 		start: Effect.void,
 		settlePendingRequests: settlePendingRequests(pendingRequests, actorId),
@@ -272,7 +281,7 @@ const settlePendingRequests = (pendingRequests, actorId) => Effect.gen(function*
 	for (const settle of pendingRequests) yield* settle(error);
 	pendingRequests.clear();
 });
-const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function* (machine, stateRef, eventQueue, pendingRequests, stoppedRef, self, stateScopeRef, actorId, generation, system, exitDeferred, hooks, deferredReplyRef, lifecycle, fork) {
+const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function* (machine, stateRef, latestTransitionRef, eventQueue, pendingRequests, stoppedRef, self, stateScopeRef, actorId, generation, system, exitDeferred, hooks, deferredReplyRef, lifecycle, fork) {
 	const forkEffect = fork ?? Effect.runFork;
 	/** Set the exit deferred exactly once. */
 	const setExit = (exit) => Deferred.succeed(exitDeferred, exit).pipe(Effect.asVoid);
@@ -320,7 +329,15 @@ const runtimeEventLoop = Effect.fn("effect-machine.runtime.eventLoop")(function*
 		let result;
 		if (isEffect(processing)) result = yield* processing;
 		else result = processing;
-		if (result.transitioned) yield* SubscriptionRef.set(stateRef, result.newState);
+		if (result.transitioned) {
+			yield* SubscriptionRef.set(stateRef, result.newState);
+			const latest = result.transitions.at(-1);
+			if (latest !== void 0) yield* SubscriptionRef.set(latestTransitionRef, {
+				fromState: latest.previousState,
+				toState: latest.newState,
+				event: latest.event
+			});
+		}
 		if (lifecycle?.onStateChange !== void 0 && result.transitioned) {
 			const stateChange = lifecycle.onStateChange(result, event);
 			if (isEffect(stateChange)) yield* stateChange;

package/dist/machine.d.ts

@@ -3,15 +3,19 @@ import { BrandedEvent, BrandedState, ExtractReply, TaggedOrConstructor } from ".
 import { MachineEventSchema, MachineStateSchema, VariantsUnion } from "./schema.js";
 import { ActorStoppedError, DuplicateActorError } from "./errors.js";
 import { Supervision } from "./supervision.js";
-import { ActorRef, ActorSystemService } from "./actor.js";
-import { Duration, Effect, Option, Schema, Scope } from "effect";
+import { ActorRef, ActorSystemService, TransitionInfo } from "./actor.js";
+import { Duration, Effect, Option, Schema, Scope, SubscriptionRef } from "effect";
 declare namespace machine_d_exports {
   export { DeferReplyResult, Durability, DurabilityCommit, FinalContext, GuardPredicate, HandlerContext, InputMakeConfig, Lifecycle, Machine, MachineRef, MakeConfig, Recovery, RecoveryContext, ReplayOptions, ReplyResult, SpawnOptions, StateEffectHandler, StateHandlerContext, TaskOptions, TimeoutConfig, TransitionHandler, deferReply, make, replay, reply, run, scoped, spawn };
 }
 /**
  * Self reference for sending events back to the machine
  */
-interface MachineRef<Event> {
+interface MachineRef<Event, State = never> {
+  /** Actor-owned current state. Consumers must treat this ref as read-only. */
+  readonly state: SubscriptionRef.SubscriptionRef<State>;
+  /** Actor-owned latest accepted transition. Consumers must treat this ref as read-only. */
+  readonly latestTransition: SubscriptionRef.SubscriptionRef<TransitionInfo<State, Event> | undefined>;
   readonly send: (event: Event) => Effect.Effect<void>;
   readonly spawn: <S2 extends {
     readonly _tag: string;
@@ -40,7 +44,7 @@ interface StateHandlerContext<State, Event> {
   readonly generation: number;
   readonly state: State;
   readonly event: Event;
-  readonly self: MachineRef<Event>;
+  readonly self: MachineRef<Event, State>;
   readonly system: ActorSystemService;
 }
 /**

package/package.json

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