effect-machine 0.17.0 → 0.18.0

package/v3/dist/internal/transition.js

@@ -1,278 +0,0 @@
-import { INTERNAL_ENTER_EVENT, isDeferReplyResult, isEffect, isReplyResult } from "./utils.js";
-import { Cause, Effect, Exit, Scope } from "effect";
-//#region src/internal/transition.ts
-/**
-* Transition execution and indexing.
-*
-* Combines:
-* - Transition execution logic (for event processing, simulation, test harness)
-* - Event processing core (shared between actor and cluster entity)
-* - O(1) indexed lookup by state/event tag
-*
-* @internal
-*/
-/**
-* Run a transition handler and return the new state.
-* Shared logic for executing handlers with proper context.
-*
-* Used by:
-* - executeTransition (actor event loop, testing)
-* - Machine.replay (event sourcing restore)
-*
-* @internal
-*/
-const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(function* (machine, transition, state, event, self, system, actorId) {
-	const ctx = {
-		actorId,
-		state,
-		event,
-		self,
-		system
-	};
-	const handlerCtx = {
-		state,
-		event,
-		slots: machine._slots
-	};
-	const raw = transition.handler(handlerCtx);
-	const resolved = isEffect(raw) ? yield* raw.pipe(Effect.provideService(machine.Context, ctx)) : raw;
-	if (isReplyResult(resolved)) return {
-		newState: resolved.state,
-		hasReply: true,
-		deferReply: false,
-		reply: resolved.reply
-	};
-	if (isDeferReplyResult(resolved)) return {
-		newState: resolved.state,
-		hasReply: false,
-		deferReply: true,
-		reply: void 0
-	};
-	return {
-		newState: resolved,
-		hasReply: false,
-		deferReply: false,
-		reply: void 0
-	};
-});
-/**
-* Execute a transition for a given state and event.
-* Handles transition resolution, handler invocation, and guard/effect slot creation.
-*
-* Used by:
-* - processEvent in actor.ts (actual actor event loop)
-* - simulate in testing.ts (pure transition simulation)
-* - createTestHarness.send in testing.ts (step-by-step testing)
-*
-* @internal
-*/
-const executeTransition = Effect.fn("effect-machine.executeTransition")(function* (machine, currentState, event, self, system, actorId) {
-	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 { newState, hasReply, deferReply, reply } = yield* runTransitionHandler(machine, transition, currentState, event, self, system, actorId);
-	return {
-		newState,
-		transitioned: true,
-		reenter: transition.reenter === true,
-		hasReply,
-		deferReply,
-		reply
-	};
-});
-/**
-* Check if an event should be postponed in the current state.
-* @internal
-*/
-const shouldPostpone = (machine, stateTag, eventTag) => {
-	for (const rule of machine.postponeRules) if (rule.stateTag === stateTag && rule.eventTag === eventTag) return true;
-	return false;
-};
-/**
-* Process a single event through the machine.
-*
-* Handles:
-* - Transition execution
-* - State scope lifecycle (close old, create new)
-* - Running spawn effects
-*
-* Optional hooks allow inspection/tracing without coupling to specific impl.
-*
-* @internal
-*/
-const processEventCore = Effect.fn("effect-machine.processEventCore")(function* (machine, currentState, event, self, stateScopeRef, system, actorId, hooks) {
-	const result = yield* executeTransition(machine, currentState, event, self, system, actorId).pipe(Effect.catchAllCause((cause) => {
-		if (Cause.isInterruptedOnly(cause)) return Effect.interrupt;
-		const onError = hooks?.onError;
-		if (onError === void 0) return Effect.failCause(cause).pipe(Effect.orDie);
-		return onError({
-			phase: "transition",
-			state: currentState,
-			event,
-			cause
-		}).pipe(Effect.andThen(Effect.failCause(cause).pipe(Effect.orDie)));
-	}));
-	if (!result.transitioned) return {
-		newState: currentState,
-		previousState: currentState,
-		transitioned: false,
-		lifecycleRan: false,
-		isFinal: false,
-		hasReply: false,
-		deferReply: false,
-		reply: void 0,
-		postponed: false
-	};
-	const newState = result.newState;
-	const runLifecycle = newState._tag !== currentState._tag || result.reenter;
-	if (runLifecycle) {
-		yield* Scope.close(stateScopeRef.current, Exit.void);
-		stateScopeRef.current = yield* Scope.make();
-		if (hooks?.onTransition !== void 0) yield* hooks.onTransition(currentState, newState, event);
-		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);
-	}
-	return {
-		newState,
-		previousState: currentState,
-		transitioned: true,
-		lifecycleRan: runLifecycle,
-		isFinal: machine.finalStates.has(newState._tag),
-		hasReply: result.hasReply,
-		deferReply: result.deferReply,
-		reply: result.reply,
-		postponed: false
-	};
-});
-/**
-* Run spawn effects for a state (forked into state scope, auto-cancelled on state exit).
-*
-* @internal
-*/
-const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* (machine, state, event, self, stateScope, system, actorId, onError, onSpawnDefect) {
-	const spawnEffects = findSpawnEffects(machine, state._tag);
-	const ctx = {
-		actorId,
-		state,
-		event,
-		self,
-		system
-	};
-	const slots = machine._slots;
-	const reportError = onError;
-	const defectSignal = onSpawnDefect;
-	for (const spawnEffect of spawnEffects) {
-		const effect = spawnEffect.handler({
-			actorId,
-			state,
-			event,
-			self,
-			slots,
-			system
-		}).pipe(Effect.provideService(machine.Context, ctx), Effect.catchAllCause((cause) => {
-			if (Cause.isInterruptedOnly(cause)) return Effect.interrupt;
-			const report = reportError !== void 0 ? reportError({
-				phase: "spawn",
-				state,
-				event,
-				cause
-			}) : Effect.void;
-			const signal = defectSignal !== void 0 ? defectSignal(cause) : Effect.void;
-			return report.pipe(Effect.andThen(signal), Effect.andThen(Effect.failCause(cause).pipe(Effect.orDie)));
-		}));
-		yield* Effect.forkScoped(effect).pipe(Effect.provideService(Scope.Scope, stateScope));
-	}
-});
-/**
-* Resolve which transition should fire for a given state and event.
-* Uses indexed O(1) lookup. First matching transition wins.
-*/
-const resolveTransition = (machine, currentState, event) => {
-	return findTransitions(machine, currentState._tag, event._tag)[0];
-};
-const indexCache = /* @__PURE__ */ new WeakMap();
-/**
-* Invalidate cached index for a machine (call after mutation).
-*/
-const invalidateIndex = (machine) => {
-	indexCache.delete(machine);
-};
-/**
-* Build transition index from machine definition.
-* O(n) where n = number of transitions.
-*/
-const buildTransitionIndex = (transitions) => {
-	const index = /* @__PURE__ */ new Map();
-	for (const t of transitions) {
-		let stateMap = index.get(t.stateTag);
-		if (stateMap === void 0) {
-			stateMap = /* @__PURE__ */ new Map();
-			index.set(t.stateTag, stateMap);
-		}
-		let eventList = stateMap.get(t.eventTag);
-		if (eventList === void 0) {
-			eventList = [];
-			stateMap.set(t.eventTag, eventList);
-		}
-		eventList.push(t);
-	}
-	return index;
-};
-/**
-* Build spawn index from machine definition.
-*/
-const buildSpawnIndex = (effects) => {
-	const index = /* @__PURE__ */ new Map();
-	for (const e of effects) {
-		let stateList = index.get(e.stateTag);
-		if (stateList === void 0) {
-			stateList = [];
-			index.set(e.stateTag, stateList);
-		}
-		stateList.push(e);
-	}
-	return index;
-};
-/**
-* Get or build index for a machine.
-*/
-const getIndex = (machine) => {
-	let index = indexCache.get(machine);
-	if (index === void 0) {
-		index = {
-			transitions: buildTransitionIndex(machine.transitions),
-			spawn: buildSpawnIndex(machine.spawnEffects)
-		};
-		indexCache.set(machine, index);
-	}
-	return index;
-};
-/**
-* Find all transitions matching a state/event pair.
-* Returns empty array if no matches.
-*
-* O(1) lookup after first access (index is lazily built).
-*/
-const findTransitions = (machine, stateTag, eventTag) => {
-	const index = getIndex(machine);
-	const specific = index.transitions.get(stateTag)?.get(eventTag) ?? [];
-	if (specific.length > 0) return specific;
-	return index.transitions.get("*")?.get(eventTag) ?? [];
-};
-/**
-* Find all spawn effects for a state.
-* Returns empty array if no matches.
-*
-* O(1) lookup after first access (index is lazily built).
-*/
-const findSpawnEffects = (machine, stateTag) => {
-	return getIndex(machine).spawn.get(stateTag) ?? [];
-};
-//#endregion
-export { executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler, shouldPostpone };

package/v3/dist/internal/utils.d.ts

@@ -1,101 +0,0 @@
-import { ActorSystem } from "../actor.js";
-import { Effect } from "effect";
-
-//#region src/internal/utils.d.ts
-/**
- * Extracts _tag from a tagged union member
- */
-type TagOf<T> = T extends {
-  readonly _tag: infer Tag;
-} ? Tag : never;
-/**
- * Extracts args type from a Data.taggedEnum constructor
- */
-type ArgsOf<C> = C extends ((args: infer A) => unknown) ? A : never;
-/**
- * Extracts return type from a Data.taggedEnum constructor
- * @internal
- */
-type InstanceOf<C> = C extends ((...args: unknown[]) => infer R) ? R : never;
-/**
- * A tagged union constructor (from Data.taggedEnum)
- */
-type TaggedConstructor<T extends {
-  readonly _tag: string;
-}> = (args: Omit<T, "_tag">) => T;
-declare const ReplyResultSymbol: unique symbol;
-type ReplyResultSymbol = typeof ReplyResultSymbol;
-/**
- * Branded reply result from a transition handler.
- * Created via `Machine.reply(state, value)`.
- */
-interface ReplyResult<State, Reply> {
-  readonly state: State;
-  readonly reply: Reply;
-  readonly [ReplyResultSymbol]: true;
-}
-/**
- * Create a reply result for ask-bearing event handlers.
- */
-declare const makeReply: <State, Reply>(state: State, reply: Reply) => ReplyResult<State, Reply>;
-/**
- * Type guard for ReplyResult (symbol-based, replaces duck-typing).
- */
-declare const isReplyResult: (value: unknown) => value is ReplyResult<unknown, unknown>;
-declare const DeferReplySymbol: unique symbol;
-type DeferReplySymbol = typeof DeferReplySymbol;
-/**
- * Branded deferred reply result from a transition handler.
- * Signals that the reply will be settled later by `self.reply()` in a spawn handler.
- * Created via `Machine.deferReply(state)`.
- */
-interface DeferReplyResult<State> {
-  readonly state: State;
-  readonly [DeferReplySymbol]: true;
-}
-/**
- * Create a deferred reply result. Handler returns this to signal
- * "spawn handler will call self.reply(value) later".
- */
-declare const makeDeferReply: <State>(state: State) => DeferReplyResult<State>;
-/**
- * Type guard for DeferReplyResult.
- */
-declare const isDeferReplyResult: (value: unknown) => value is DeferReplyResult<unknown>;
-/**
- * Transition handler result.
- * - When Reply is `never`: handler returns plain State (no reply allowed)
- * - When Reply is concrete: handler must return ReplyResult via Machine.reply()
- */
-type TransitionResult<State, R, Reply = never> = [Reply] extends [never] ? State | Effect.Effect<State, never, R> : ReplyResult<State, Reply> | DeferReplyResult<State> | Effect.Effect<ReplyResult<State, Reply> | DeferReplyResult<State>, never, R>;
-/**
- * Internal event tags used for lifecycle effect contexts.
- * Prefixed with $ to distinguish from user events.
- * @internal
- */
-declare const INTERNAL_INIT_EVENT: "$init";
-declare const INTERNAL_ENTER_EVENT: "$enter";
-/**
- * Extract _tag from a tagged value or constructor.
- *
- * Supports:
- * - Plain values with `_tag` (MachineSchema empty structs)
- * - Constructors with static `_tag` (MachineSchema non-empty structs)
- * - Data.taggedEnum constructors (fallback via instantiation)
- */
-declare const getTag: (constructorOrValue: {
-  _tag: string;
-} | ((...args: never[]) => {
-  _tag: string;
-})) => string;
-/** Check if a value is an Effect */
-declare const isEffect: (value: unknown) => value is Effect.Effect<unknown, unknown, unknown>;
-/**
- * Stub ActorSystem that dies on any method call.
- * Used in contexts where spawning/system access isn't supported
- * (testing simulation, persistent actor replay).
- * @internal
- */
-declare const stubSystem: ActorSystem;
-//#endregion
-export { ArgsOf, DeferReplyResult, DeferReplySymbol, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, ReplyResult, ReplyResultSymbol, TagOf, TaggedConstructor, TransitionResult, getTag, isDeferReplyResult, isEffect, isReplyResult, makeDeferReply, makeReply, stubSystem };

package/v3/dist/internal/utils.js

@@ -1,75 +0,0 @@
-import { Effect, Stream } from "effect";
-//#region src/internal/utils.ts
-/**
-* Internal utilities for effect-machine.
-* @internal
-*/
-const ReplyResultSymbol = Symbol.for("effect-machine/ReplyResult");
-/**
-* Create a reply result for ask-bearing event handlers.
-*/
-const makeReply = (state, reply) => ({
-	state,
-	reply,
-	[ReplyResultSymbol]: true
-});
-/**
-* Type guard for ReplyResult (symbol-based, replaces duck-typing).
-*/
-const isReplyResult = (value) => value !== null && typeof value === "object" && ReplyResultSymbol in value;
-const DeferReplySymbol = Symbol.for("effect-machine/DeferReply");
-/**
-* Create a deferred reply result. Handler returns this to signal
-* "spawn handler will call self.reply(value) later".
-*/
-const makeDeferReply = (state) => ({
-	state,
-	[DeferReplySymbol]: true
-});
-/**
-* Type guard for DeferReplyResult.
-*/
-const isDeferReplyResult = (value) => value !== null && typeof value === "object" && DeferReplySymbol in value;
-/**
-* Internal event tags used for lifecycle effect contexts.
-* Prefixed with $ to distinguish from user events.
-* @internal
-*/
-const INTERNAL_INIT_EVENT = "$init";
-const INTERNAL_ENTER_EVENT = "$enter";
-/**
-* Extract _tag from a tagged value or constructor.
-*
-* Supports:
-* - Plain values with `_tag` (MachineSchema empty structs)
-* - Constructors with static `_tag` (MachineSchema non-empty structs)
-* - Data.taggedEnum constructors (fallback via instantiation)
-*/
-const getTag = (constructorOrValue) => {
-	if ("_tag" in constructorOrValue && typeof constructorOrValue._tag === "string") return constructorOrValue._tag;
-	try {
-		return constructorOrValue()._tag;
-	} catch {
-		return constructorOrValue({})._tag;
-	}
-};
-/** Check if a value is an Effect */
-const isEffect = Effect.isEffect;
-/**
-* Stub ActorSystem that dies on any method call.
-* Used in contexts where spawning/system access isn't supported
-* (testing simulation, persistent actor replay).
-* @internal
-*/
-const stubSystem = {
-	spawn: () => Effect.die("spawn not supported in stub system"),
-	get: () => Effect.die("get not supported in stub system"),
-	stop: () => Effect.die("stop not supported in stub system"),
-	events: Stream.empty,
-	get actors() {
-		return /* @__PURE__ */ new Map();
-	},
-	subscribe: () => () => {}
-};
-//#endregion
-export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isDeferReplyResult, isEffect, isReplyResult, makeDeferReply, makeReply, stubSystem };