effect-machine 0.19.0 → 0.20.0

package/dist/internal/transition.js

@@ -11,14 +11,21 @@ import { Cause, Effect, Exit, Scope } from "effect";
 *
 * @internal
 */
-const completeTransition = (transition, resolved) => {
+const completeTransition = (currentState, event, transition, resolved) => {
 	if (isReplyResult(resolved)) return {
 		newState: resolved.state,
 		transitioned: true,
 		reenter: transition.reenter === true,
 		hasReply: true,
 		deferReply: false,
-		reply: resolved.reply
+		reply: resolved.reply,
+		transition,
+		steps: [{
+			previousState: currentState,
+			newState: resolved.state,
+			event,
+			transition
+		}]
 	};
 	if (isDeferReplyResult(resolved)) return {
 		newState: resolved.state,
@@ -26,7 +33,14 @@ const completeTransition = (transition, resolved) => {
 		reenter: transition.reenter === true,
 		hasReply: false,
 		deferReply: true,
-		reply: void 0
+		reply: void 0,
+		transition,
+		steps: [{
+			previousState: currentState,
+			newState: resolved.state,
+			event,
+			transition
+		}]
 	};
 	return {
 		newState: resolved,
@@ -34,7 +48,14 @@ const completeTransition = (transition, resolved) => {
 		reenter: transition.reenter === true,
 		hasReply: false,
 		deferReply: false,
-		reply: void 0
+		reply: void 0,
+		transition,
+		steps: [{
+			previousState: currentState,
+			newState: resolved,
+			event,
+			transition
+		}]
 	};
 };
 /**
@@ -50,8 +71,10 @@ const completeTransition = (transition, resolved) => {
 */
 const executeTransition = (machine, currentState, event) => Effect.suspend(() => {
 	const result = executeTransitionImmediate(machine, currentState, event);
-	if (isEffect(result)) return result;
-	return Effect.succeed(result);
+	let first;
+	if (isEffect(result)) first = result;
+	else first = Effect.succeed(result);
+	return first.pipe(Effect.flatMap((initialResult) => stabilizeTransition(machine, currentState, event, initialResult)));
 });
 /**
 * Execute a transition without adding an Effect boundary for a synchronous handler.
@@ -59,29 +82,98 @@ const executeTransition = (machine, currentState, event) => Effect.suspend(() =>
 *
 * @internal
 */
-const executeTransitionImmediate = (machine, currentState, event) => {
-	const transition = resolveTransition(machine, currentState, event);
-	if (transition === void 0) return {
-		newState: currentState,
-		transitioned: false,
-		reenter: false,
-		hasReply: false,
-		deferReply: false,
-		reply: void 0
-	};
-	const handlerCtx = {
-		state: currentState,
-		event
-	};
-	let raw;
+const executeTransitionCandidatesImmediate = (currentState, event, candidates, hooks) => {
+	let resolution;
 	try {
-		raw = transition.handler(handlerCtx);
+		resolution = evaluateTransitions(candidates, currentState, event);
 	} catch (defect) {
 		return Effect.die(defect);
 	}
-	if (isEffect(raw)) return raw.pipe(Effect.map((resolved) => completeTransition(transition, resolved)));
-	return completeTransition(transition, raw);
+	const executeResolved = (resolved) => {
+		const transition = resolved.transition;
+		if (transition === void 0) {
+			const unhandled = {
+				newState: currentState,
+				transitioned: false,
+				reenter: false,
+				hasReply: false,
+				deferReply: false,
+				reply: void 0,
+				transition: void 0,
+				steps: []
+			};
+			if (hooks?.onGuard === void 0 || resolved.evaluations.length === 0) return unhandled;
+			return Effect.forEach(resolved.evaluations, hooks.onGuard, { discard: true }).pipe(Effect.as(unhandled));
+		}
+		const runHandler = () => {
+			const handlerCtx = {
+				state: currentState,
+				event
+			};
+			let raw;
+			try {
+				raw = transition.handler(handlerCtx);
+			} catch (defect) {
+				return Effect.die(defect);
+			}
+			if (isEffect(raw)) return raw.pipe(Effect.map((value) => completeTransition(currentState, event, transition, value)));
+			return completeTransition(currentState, event, transition, raw);
+		};
+		const runInspectedHandler = () => {
+			if (hooks?.onOperation === void 0) return runHandler();
+			return hooks.onOperation({
+				operation: transition.handler.name || "<inline>",
+				state: currentState,
+				event
+			}).pipe(Effect.andThen(Effect.suspend(() => {
+				const result = runHandler();
+				if (isEffect(result)) return result;
+				return Effect.succeed(result);
+			})));
+		};
+		if (hooks?.onGuard === void 0 || resolved.evaluations.length === 0) return runInspectedHandler();
+		return Effect.forEach(resolved.evaluations, hooks.onGuard, { discard: true }).pipe(Effect.andThen(Effect.suspend(() => {
+			const result = runInspectedHandler();
+			if (isEffect(result)) return result;
+			return Effect.succeed(result);
+		})));
+	};
+	if (!isEffect(resolution)) return executeResolved(resolution);
+	return resolution.pipe(Effect.flatMap((resolved) => {
+		const result = executeResolved(resolved);
+		if (isEffect(result)) return result;
+		return Effect.succeed(result);
+	}));
 };
+const executeTransitionImmediate = (machine, currentState, event, hooks) => executeTransitionCandidatesImmediate(currentState, event, machine._findTransitions(currentState._tag, event._tag), hooks);
+const stabilizeTransition = (machine, initialState, event, result, hooks) => Effect.gen(function* () {
+	const steps = [...result.steps];
+	let stableState = result.newState;
+	let lifecycleRequired = result.reenter || stableState._tag !== initialState._tag;
+	let depth = 0;
+	while (true) {
+		const candidates = machine._findImmediateTransitions(stableState._tag);
+		if (candidates.length === 0) break;
+		depth += 1;
+		if (depth > 100) return yield* Effect.die(/* @__PURE__ */ new Error("Immediate transition limit exceeded. Check for an eventless loop."));
+		const immediate = executeTransitionCandidatesImmediate(stableState, event, candidates, hooks);
+		let next;
+		if (isEffect(immediate)) next = yield* immediate;
+		else next = immediate;
+		if (!next.transitioned) break;
+		if (next.reenter || next.newState._tag !== stableState._tag) lifecycleRequired = true;
+		steps.push(...next.steps);
+		stableState = next.newState;
+	}
+	return {
+		...result,
+		newState: stableState,
+		transitioned: steps.length > 0,
+		reenter: lifecycleRequired,
+		transition: steps.at(-1)?.transition,
+		steps
+	};
+});
 /**
 * Check if an event should be postponed in the current state.
 * @internal
@@ -99,12 +191,12 @@ const shouldPostpone = (machine, stateTag, eventTag) => machine._shouldPostpone(
 *
 * @internal
 */
-const processEventCore = (machine, currentState, event, self, stateScopeRef, system, actorId, hooks) => Effect.suspend(() => {
-	const processed = processEventCoreImmediate(machine, currentState, event, self, stateScopeRef, system, actorId, hooks);
+const processEventCore = (machine, currentState, event, self, stateScopeRef, system, actorId, hooks, generation = 0) => Effect.suspend(() => {
+	const processed = processEventCoreImmediate(machine, currentState, event, self, stateScopeRef, system, actorId, hooks, generation);
 	if (isEffect(processed)) return processed;
 	return Effect.succeed(processed);
 });
-const completeProcessedEvent = (machine, currentState, event, result, self, stateScopeRef, system, actorId, hooks) => {
+const completeProcessedEvent = (machine, currentState, event, result, self, stateScopeRef, system, actorId, hooks, generation = 0) => {
 	if (!result.transitioned) return {
 		newState: currentState,
 		previousState: currentState,
@@ -114,7 +206,8 @@ const completeProcessedEvent = (machine, currentState, event, result, self, stat
 		hasReply: false,
 		deferReply: false,
 		reply: void 0,
-		postponed: false
+		postponed: false,
+		transitions: []
 	};
 	const newState = result.newState;
 	const runLifecycle = newState._tag !== currentState._tag || result.reenter;
@@ -127,22 +220,59 @@ const completeProcessedEvent = (machine, currentState, event, result, self, stat
 		hasReply: result.hasReply,
 		deferReply: result.deferReply,
 		reply: result.reply,
-		postponed: false
+		postponed: false,
+		transitions: result.steps
 	};
-	if (!runLifecycle) return processed;
+	const observeTransitions = hooks?.onTransition;
+	if (!runLifecycle) {
+		if (observeTransitions === void 0 || result.steps.length === 0) return processed;
+		return Effect.forEach(result.steps, (step) => observeTransitions(step.previousState, step.newState, step.event), { discard: true }).pipe(Effect.as(processed));
+	}
 	return Effect.gen(function* () {
 		yield* Scope.close(stateScopeRef.current, Exit.void);
 		stateScopeRef.current = yield* Scope.make();
-		if (hooks?.onTransition !== void 0) yield* hooks.onTransition(currentState, newState, event);
+		if (observeTransitions !== void 0) yield* Effect.forEach(result.steps, (step) => observeTransitions(step.previousState, step.newState, step.event), { discard: true });
 		if (hooks?.onSpawnEffect !== void 0) yield* hooks.onSpawnEffect(newState);
-		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, actorId, hooks?.onError, hooks?.onSpawnDefect);
+		yield* runSpawnEffects(machine, newState, { _tag: INTERNAL_ENTER_EVENT }, self, stateScopeRef.current, system, actorId, hooks?.onError, hooks?.onSpawnDefect, generation);
 		return processed;
 	});
 };
 /** @internal */
-const processEventCoreImmediate = (machine, currentState, event, self, stateScopeRef, system, actorId, hooks) => {
-	const execution = executeTransitionImmediate(machine, currentState, event);
-	const complete = (result) => completeProcessedEvent(machine, currentState, event, result, self, stateScopeRef, system, actorId, hooks);
+const processEventCoreImmediate = (machine, currentState, event, self, stateScopeRef, system, actorId, hooks, generation = 0) => {
+	const execution = executeTransitionImmediate(machine, currentState, event, hooks);
+	const complete = (result) => {
+		if (machine._findImmediateTransitions(result.newState._tag).length === 0) return completeProcessedEvent(machine, currentState, event, result, self, stateScopeRef, system, actorId, hooks, generation);
+		return Effect.gen(function* () {
+			const steps = [...result.steps];
+			let stableState = result.newState;
+			let lifecycleRequired = result.reenter || stableState._tag !== currentState._tag;
+			let depth = 0;
+			while (true) {
+				const candidates = machine._findImmediateTransitions(stableState._tag);
+				if (candidates.length === 0) break;
+				depth += 1;
+				if (depth > 100) return yield* Effect.die(/* @__PURE__ */ new Error("Immediate transition limit exceeded. Check for an eventless loop."));
+				const immediate = executeTransitionCandidatesImmediate(stableState, event, candidates, hooks);
+				let next;
+				if (isEffect(immediate)) next = yield* immediate;
+				else next = immediate;
+				if (!next.transitioned) break;
+				if (next.reenter || next.newState._tag !== stableState._tag) lifecycleRequired = true;
+				steps.push(...next.steps);
+				stableState = next.newState;
+			}
+			const processed = completeProcessedEvent(machine, currentState, event, {
+				...result,
+				newState: stableState,
+				transitioned: steps.length > 0,
+				reenter: lifecycleRequired,
+				transition: steps.at(-1)?.transition,
+				steps
+			}, self, stateScopeRef, system, actorId, hooks, generation);
+			if (isEffect(processed)) return yield* processed;
+			return processed;
+		});
+	};
 	if (!isEffect(execution)) return complete(execution);
 	return execution.pipe(Effect.catchCause((cause) => {
 		if (Cause.hasInterruptsOnly(cause)) return Effect.interrupt;
@@ -165,13 +295,14 @@ const processEventCoreImmediate = (machine, currentState, event, self, stateScop
 *
 * @internal
 */
-const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, actorId, onError, onSpawnDefect) {
+const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, actorId, onError, onSpawnDefect, generation = 0) {
 	const spawnEffects = machine._findSpawnEffects(state._tag);
 	const reportError = onError;
 	const defectSignal = onSpawnDefect;
 	for (const spawnEffect of spawnEffects) {
 		const effect = spawnEffect.handler({
 			actorId,
+			generation,
 			state,
 			event,
 			self,
@@ -197,7 +328,54 @@ const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (m
 * Uses indexed O(1) lookup. First matching transition wins.
 */
 const resolveTransition = (machine, currentState, event) => {
-	return machine._findTransitions(currentState._tag, event._tag)[0];
+	const resolution = evaluateTransitions(machine._findTransitions(currentState._tag, event._tag), currentState, event);
+	if (isEffect(resolution)) return Effect.runSync(Effect.die("Effect guards require actor.can(event). actor.client.canSync(event) is synchronous."));
+	return resolution.transition;
+};
+/** Resolve a transition with pure or Effect guards. */
+const resolveTransitionEffect = (machine, currentState, event) => {
+	const resolution = evaluateTransitions(machine._findTransitions(currentState._tag, event._tag), currentState, event);
+	if (isEffect(resolution)) return resolution.pipe(Effect.map((value) => value.transition));
+	return Effect.succeed(resolution.transition);
+};
+const evaluateTransitions = (candidates, currentState, event) => {
+	const ctx = {
+		state: currentState,
+		event
+	};
+	const loop = (index, evaluations) => {
+		const candidate = candidates[index];
+		if (candidate === void 0) return {
+			transition: void 0,
+			evaluations
+		};
+		if (candidate.guard === void 0) return {
+			transition: candidate,
+			evaluations
+		};
+		const guardName = candidate.guard.name || "<inline>";
+		const result = candidate.guard(ctx);
+		const continueWith = (passed) => {
+			const nextEvaluations = [...evaluations, {
+				guard: guardName,
+				state: currentState,
+				event,
+				result: passed
+			}];
+			if (passed) return {
+				transition: candidate,
+				evaluations: nextEvaluations
+			};
+			return loop(index + 1, nextEvaluations);
+		};
+		if (!isEffect(result)) return continueWith(result);
+		return result.pipe(Effect.flatMap((passed) => {
+			const next = continueWith(passed);
+			if (isEffect(next)) return next;
+			return Effect.succeed(next);
+		}));
+	};
+	return loop(0, []);
 };
 //#endregion
-export { executeTransition, executeTransitionImmediate, processEventCore, processEventCoreImmediate, resolveTransition, runSpawnEffects, shouldPostpone };
+export { executeTransition, executeTransitionImmediate, processEventCore, processEventCoreImmediate, resolveTransition, resolveTransitionEffect, runSpawnEffects, shouldPostpone };