effect-machine 0.3.0 → 0.3.2

package/dist/internal/inspection.js

@@ -0,0 +1,15 @@
+import { Clock, Effect } from "effect";
+
+//#region src/internal/inspection.ts
+/**
+* Emit an inspection event with timestamp from Clock.
+* @internal
+*/
+const emitWithTimestamp = Effect.fn("effect-machine.emitWithTimestamp")(function* (inspector, makeEvent) {
+	if (inspector === void 0) return;
+	const timestamp = yield* Clock.currentTimeMillis;
+	yield* Effect.try(() => inspector.onInspect(makeEvent(timestamp))).pipe(Effect.ignore);
+});
+
+//#endregion
+export { emitWithTimestamp };

package/dist/internal/transition.d.ts

@@ -0,0 +1,159 @@
+import { EffectsDef, GuardsDef, MachineContext } from "../slot.js";
+import { BuiltMachine, Machine, MachineRef, SpawnEffect, Transition } from "../machine.js";
+import { Cause, Effect, Scope } from "effect";
+
+//#region src/internal/transition.d.ts
+/**
+ * Result of executing a transition.
+ */
+interface TransitionExecutionResult<S> {
+  /** New state after transition (or current state if no transition matched) */
+  readonly newState: S;
+  /** Whether a transition was executed */
+  readonly transitioned: boolean;
+  /** Whether reenter was specified on the transition */
+  readonly reenter: boolean;
+}
+/**
+ * Run a transition handler and return the new state.
+ * Shared logic for executing handlers with proper context.
+ *
+ * Used by:
+ * - executeTransition (actor event loop, testing)
+ * - persistent-actor replay (restore, replayTo)
+ *
+ * @internal
+ */
+declare const runTransitionHandler: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, transition: Transition<S, E, GD, EFD, R>, state: S, event: E, self: MachineRef<E>) => Effect.Effect<S, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
+/**
+ * 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
+ */
+declare const executeTransition: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, currentState: S, event: E, self: MachineRef<E>) => Effect.Effect<{
+  newState: S;
+  transitioned: boolean;
+  reenter: boolean;
+}, never, Exclude<R, MachineContext<S, E, MachineRef<E>>>>;
+/**
+ * Optional hooks for event processing inspection/tracing.
+ */
+interface ProcessEventHooks<S, E> {
+  /** Called before running spawn effects */
+  readonly onSpawnEffect?: (state: S) => Effect.Effect<void>;
+  /** Called after transition completes */
+  readonly onTransition?: (from: S, to: S, event: E) => Effect.Effect<void>;
+  /** Called when a transition handler or spawn effect fails with a defect */
+  readonly onError?: (info: ProcessEventError<S, E>) => Effect.Effect<void>;
+}
+/**
+ * Error info for inspection hooks.
+ */
+interface ProcessEventError<S, E> {
+  readonly phase: "transition" | "spawn";
+  readonly state: S;
+  readonly event: E;
+  readonly cause: Cause.Cause<unknown>;
+}
+/**
+ * Result of processing an event through the machine.
+ */
+interface ProcessEventResult<S> {
+  /** New state after processing */
+  readonly newState: S;
+  /** Previous state before processing */
+  readonly previousState: S;
+  /** Whether a transition occurred */
+  readonly transitioned: boolean;
+  /** Whether lifecycle effects ran (state change or reenter) */
+  readonly lifecycleRan: boolean;
+  /** Whether new state is final */
+  readonly isFinal: boolean;
+}
+/**
+ * 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
+ */
+declare const processEventCore: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, currentState: S, event: E, self: MachineRef<E>, stateScopeRef: {
+  current: Scope.CloseableScope;
+}, hooks?: ProcessEventHooks<S, E> | undefined) => Effect.Effect<{
+  newState: S;
+  previousState: S;
+  transitioned: boolean;
+  lifecycleRan: boolean;
+  isFinal: boolean;
+}, never, Exclude<R, MachineContext<S, E, MachineRef<E>>> | Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
+/**
+ * Run spawn effects for a state (forked into state scope, auto-cancelled on state exit).
+ *
+ * @internal
+ */
+declare const runSpawnEffects: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R, GD extends GuardsDef, EFD extends EffectsDef>(machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>, state: S, event: E, self: MachineRef<E>, stateScope: Scope.CloseableScope, onError?: ((info: ProcessEventError<S, E>) => Effect.Effect<void>) | undefined) => Effect.Effect<void, never, Exclude<Exclude<R, MachineContext<S, E, MachineRef<E>>>, Scope.Scope>>;
+/**
+ * Resolve which transition should fire for a given state and event.
+ * Uses indexed O(1) lookup. First matching transition wins.
+ */
+declare const resolveTransition: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R>(machine: Machine<S, E, R, any, any, any, any>, currentState: S, event: E) => (typeof machine.transitions)[number] | undefined;
+/**
+ * Invalidate cached index for a machine (call after mutation).
+ */
+declare const invalidateIndex: (machine: object) => void;
+/**
+ * Find all transitions matching a state/event pair.
+ * Returns empty array if no matches.
+ *
+ * Accepts both `Machine` and `BuiltMachine`.
+ * O(1) lookup after first access (index is lazily built).
+ */
+declare const findTransitions: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(input: Machine<S, E, R, any, any, GD, EFD> | BuiltMachine<S, E, R>, stateTag: string, eventTag: string) => ReadonlyArray<Transition<S, E, GD, EFD, R>>;
+/**
+ * Find all spawn effects for a state.
+ * Returns empty array if no matches.
+ *
+ * O(1) lookup after first access (index is lazily built).
+ */
+declare const findSpawnEffects: <S extends {
+  readonly _tag: string;
+}, E extends {
+  readonly _tag: string;
+}, R, GD extends GuardsDef = Record<string, never>, EFD extends EffectsDef = Record<string, never>>(machine: Machine<S, E, R, any, any, GD, EFD>, stateTag: string) => ReadonlyArray<SpawnEffect<S, E, EFD, R>>;
+//#endregion
+export { ProcessEventError, ProcessEventHooks, ProcessEventResult, TransitionExecutionResult, executeTransition, findSpawnEffects, findTransitions, invalidateIndex, processEventCore, resolveTransition, runSpawnEffects, runTransitionHandler };

package/dist/internal/transition.js

@@ -0,0 +1,235 @@
+import { INTERNAL_ENTER_EVENT, isEffect } from "./utils.js";
+import { BuiltMachine } from "../machine.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)
+* - persistent-actor replay (restore, replayTo)
+*
+* @internal
+*/
+const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(function* (machine, transition, state, event, self) {
+	const ctx = {
+		state,
+		event,
+		self
+	};
+	const { guards, effects } = machine._slots;
+	const handlerCtx = {
+		state,
+		event,
+		guards,
+		effects
+	};
+	const result = transition.handler(handlerCtx);
+	return isEffect(result) ? yield* result.pipe(Effect.provideService(machine.Context, ctx)) : result;
+});
+/**
+* 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) {
+	const transition = resolveTransition(machine, currentState, event);
+	if (transition === void 0) return {
+		newState: currentState,
+		transitioned: false,
+		reenter: false
+	};
+	return {
+		newState: yield* runTransitionHandler(machine, transition, currentState, event, self),
+		transitioned: true,
+		reenter: transition.reenter === true
+	};
+});
+/**
+* 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, hooks) {
+	const result = yield* executeTransition(machine, currentState, event, self).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.zipRight(Effect.failCause(cause).pipe(Effect.orDie)));
+	}));
+	if (!result.transitioned) return {
+		newState: currentState,
+		previousState: currentState,
+		transitioned: false,
+		lifecycleRan: false,
+		isFinal: 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, hooks?.onError);
+	}
+	return {
+		newState,
+		previousState: currentState,
+		transitioned: true,
+		lifecycleRan: runLifecycle,
+		isFinal: machine.finalStates.has(newState._tag)
+	};
+});
+/**
+* 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, onError) {
+	const spawnEffects = findSpawnEffects(machine, state._tag);
+	const ctx = {
+		state,
+		event,
+		self
+	};
+	const { effects: effectSlots } = machine._slots;
+	const reportError = onError;
+	for (const spawnEffect of spawnEffects) {
+		const effect = spawnEffect.handler({
+			state,
+			event,
+			self,
+			effects: effectSlots
+		}).pipe(Effect.provideService(machine.Context, ctx), Effect.catchAllCause((cause) => {
+			if (Cause.isInterruptedOnly(cause)) return Effect.interrupt;
+			if (reportError === void 0) return Effect.failCause(cause).pipe(Effect.orDie);
+			return reportError({
+				phase: "spawn",
+				state,
+				event,
+				cause
+			}).pipe(Effect.zipRight(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.
+*
+* Accepts both `Machine` and `BuiltMachine`.
+* O(1) lookup after first access (index is lazily built).
+*/
+const findTransitions = (input, stateTag, eventTag) => {
+	const index = getIndex(input instanceof BuiltMachine ? input._inner : input);
+	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 };

package/dist/internal/utils.d.ts

@@ -0,0 +1,52 @@
+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;
+/**
+ * Transition handler result - either a new state or Effect producing one
+ */
+type TransitionResult<State, R> = State | Effect.Effect<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>;
+//#endregion
+export { ArgsOf, INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, InstanceOf, TagOf, TaggedConstructor, TransitionResult, getTag, isEffect };

package/dist/internal/utils.js

@@ -0,0 +1,31 @@
+import { Effect } from "effect";
+
+//#region src/internal/utils.ts
+/**
+* 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 = (value) => typeof value === "object" && value !== null && Effect.EffectTypeId in value;
+
+//#endregion
+export { INTERNAL_ENTER_EVENT, INTERNAL_INIT_EVENT, getTag, isEffect };