effect-machine 0.1.0 → 0.2.1

package/src/cluster/entity-machine.ts

@@ -41,6 +41,8 @@ export interface EntityMachineOptions<S, E> {
    *       Effect.log(`Transition: ${from._tag} -> ${to._tag}`),
    *     onSpawnEffect: (state) =>
    *       Effect.log(`Running spawn effects for ${state._tag}`),
+   *     onError: ({ phase, state }) =>
+   *       Effect.log(`Defect in ${phase} at ${state._tag}`),
    *   },
    * })
    * ```
@@ -52,7 +54,7 @@ export interface EntityMachineOptions<S, E> {
  * Process a single event through the machine using shared core.
  * Returns the new state after processing.
  */
-const processEvent = <
+const processEvent = Effect.fn("effect-machine.cluster.processEvent")(function* <
   S extends { readonly _tag: string },
   E extends { readonly _tag: string },
   R,
@@ -65,27 +67,19 @@ const processEvent = <
   self: MachineRef<E>,
   stateScopeRef: { current: Scope.CloseableScope },
   hooks?: ProcessEventHooks<S, E>,
-): Effect.Effect<S, never, R> =>
-  Effect.gen(function* () {
-    const currentState = yield* Ref.get(stateRef);
-
-    // Process event using shared core
-    const result = yield* processEventCore(
-      machine,
-      currentState,
-      event,
-      self,
-      stateScopeRef,
-      hooks,
-    );
-
-    // Update state ref if transition occurred
-    if (result.transitioned) {
-      yield* Ref.set(stateRef, result.newState);
-    }
-
-    return result.newState;
-  });
+) {
+  const currentState = yield* Ref.get(stateRef);
+
+  // Process event using shared core
+  const result = yield* processEventCore(machine, currentState, event, self, stateScopeRef, hooks);
+
+  // Update state ref if transition occurred
+  if (result.transitioned) {
+    yield* Ref.set(stateRef, result.newState);
+  }
+
+  return result.newState;
+});
 
 /**
  * Create an Entity layer that wires a machine to handle RPC calls.
@@ -137,66 +131,71 @@ export const EntityMachine = {
     machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>,
     options?: EntityMachineOptions<S, E>,
   ): Layer.Layer<never, never, R> => {
-    return entity.toLayer(
-      Effect.gen(function* () {
-        // Get entity ID from context if available
-        const entityId = yield* Effect.serviceOption(Entity.CurrentAddress).pipe(
-          Effect.map((opt) => (opt._tag === "Some" ? opt.value.entityId : "")),
-        );
-
-        // Initialize state - use provided initializer or machine's initial state
-        const initialState =
-          options?.initializeState !== undefined
-            ? options.initializeState(entityId)
-            : machine.initial;
-
-        // Create self reference for sending events back to machine
-        const internalQueue = yield* Queue.unbounded<E>();
-        const self: MachineRef<E> = {
-          send: (event) => Queue.offer(internalQueue, event),
-        };
-
-        // Create state ref
-        const stateRef = yield* Ref.make<S>(initialState);
-
-        // Create state scope for spawn effects
-        const stateScopeRef: { current: Scope.CloseableScope } = {
-          current: yield* Scope.make(),
-        };
-
-        // Use $init event for initial lifecycle
-        const initEvent = { _tag: "$init" } as E;
-
-        // Run initial spawn effects
-        yield* runSpawnEffects(machine, initialState, initEvent, self, stateScopeRef.current);
-
-        // Process internal events in background
-        yield* Effect.forkScoped(
-          Effect.forever(
-            Effect.gen(function* () {
-              const event = yield* Queue.take(internalQueue);
-              yield* processEvent(machine, stateRef, event, self, stateScopeRef, options?.hooks);
-            }),
+    const layer = Effect.fn("effect-machine.cluster.layer")(function* () {
+      // Get entity ID from context if available
+      const entityId = yield* Effect.serviceOption(Entity.CurrentAddress).pipe(
+        Effect.map((opt) => (opt._tag === "Some" ? opt.value.entityId : "")),
+      );
+
+      // Initialize state - use provided initializer or machine's initial state
+      const initialState =
+        options?.initializeState !== undefined
+          ? options.initializeState(entityId)
+          : machine.initial;
+
+      // Create self reference for sending events back to machine
+      const internalQueue = yield* Queue.unbounded<E>();
+      const self: MachineRef<E> = {
+        send: Effect.fn("effect-machine.cluster.self.send")(function* (event: E) {
+          yield* Queue.offer(internalQueue, event);
+        }),
+      };
+
+      // Create state ref
+      const stateRef = yield* Ref.make<S>(initialState);
+
+      // Create state scope for spawn effects
+      const stateScopeRef: { current: Scope.CloseableScope } = {
+        current: yield* Scope.make(),
+      };
+
+      // Use $init event for initial lifecycle
+      const initEvent = { _tag: "$init" } as E;
+
+      // Run initial spawn effects
+      yield* runSpawnEffects(
+        machine,
+        initialState,
+        initEvent,
+        self,
+        stateScopeRef.current,
+        options?.hooks?.onError,
+      );
+
+      // Process internal events in background
+      const runInternalEvent = Effect.fn("effect-machine.cluster.internalEvent")(function* () {
+        const event = yield* Queue.take(internalQueue);
+        yield* processEvent(machine, stateRef, event, self, stateScopeRef, options?.hooks);
+      });
+      yield* Effect.forkScoped(Effect.forever(runInternalEvent()));
+
+      // Return handlers matching the Entity's RPC protocol
+      // The actual types are inferred from the entity definition
+      return entity.of({
+        Send: (envelope: { payload: { event: E } }) =>
+          processEvent(
+            machine,
+            stateRef,
+            envelope.payload.event,
+            self,
+            stateScopeRef,
+            options?.hooks,
           ),
-        );
-
-        // Return handlers matching the Entity's RPC protocol
-        // The actual types are inferred from the entity definition
-        return entity.of({
-          Send: (envelope: { payload: { event: E } }) =>
-            processEvent(
-              machine,
-              stateRef,
-              envelope.payload.event,
-              self,
-              stateScopeRef,
-              options?.hooks,
-            ),
-
-          GetState: () => Ref.get(stateRef),
-          // Entity.of expects handlers matching Rpcs type param - dynamic construction requires cast
-        } as unknown as Parameters<typeof entity.of>[0]);
-      }),
-    ) as unknown as Layer.Layer<never, never, R>;
+
+        GetState: () => Ref.get(stateRef),
+        // Entity.of expects handlers matching Rpcs type param - dynamic construction requires cast
+      } as unknown as Parameters<typeof entity.of>[0]);
+    });
+    return entity.toLayer(layer()) as unknown as Layer.Layer<never, never, R>;
   },
 };

package/src/index.ts

@@ -64,6 +64,7 @@ export type { SimulationResult, TestHarness, TestHarnessOptions } from "./testin
 // Inspection
 export type {
   EffectEvent,
+  ErrorEvent,
   EventReceivedEvent,
   InspectionEvent,
   Inspector,

package/src/inspection.ts

@@ -48,6 +48,19 @@ export interface EffectEvent<S> {
   readonly timestamp: number;
 }
 
+/**
+ * Event emitted when a transition handler or spawn effect fails with a defect
+ */
+export interface ErrorEvent<S, E> {
+  readonly type: "@machine.error";
+  readonly actorId: string;
+  readonly phase: "transition" | "spawn";
+  readonly state: S;
+  readonly event: E;
+  readonly error: string;
+  readonly timestamp: number;
+}
+
 /**
  * Event emitted when an actor stops
  */
@@ -66,6 +79,7 @@ export type InspectionEvent<S, E> =
   | EventReceivedEvent<S, E>
   | TransitionEvent<S, E>
   | EffectEvent<S>
+  | ErrorEvent<S, E>
   | StopEvent<S>;
 
 // ============================================================================
@@ -119,6 +133,9 @@ export const consoleInspector = <
       case "@machine.effect":
         console.log(prefix, event.effectType, "effect in", event.state._tag);
         break;
+      case "@machine.error":
+        console.log(prefix, "error in", event.phase, event.state._tag, "-", event.error);
+        break;
       case "@machine.stop":
         console.log(prefix, "stopped in", event.finalState._tag);
         break;

package/src/internal/inspection.ts

@@ -0,0 +1,18 @@
+import { Clock, Effect } from "effect";
+
+import type { InspectionEvent, Inspector } from "../inspection.js";
+
+/**
+ * Emit an inspection event with timestamp from Clock.
+ * @internal
+ */
+export const emitWithTimestamp = Effect.fn("effect-machine.emitWithTimestamp")(function* <S, E>(
+  inspector: Inspector<S, E> | undefined,
+  makeEvent: (timestamp: number) => InspectionEvent<S, E>,
+) {
+  if (inspector === undefined) {
+    return;
+  }
+  const timestamp = yield* Clock.currentTimeMillis;
+  yield* Effect.try(() => inspector.onInspect(makeEvent(timestamp))).pipe(Effect.ignore);
+});

package/src/internal/transition.ts

@@ -8,7 +8,7 @@
  *
  * @internal
  */
-import { Effect, Exit, Scope } from "effect";
+import { Cause, Effect, Exit, Scope } from "effect";
 
 import type { Machine, MachineRef, Transition, SpawnEffect, HandlerContext } from "../machine.js";
 import type { GuardsDef, EffectsDef, MachineContext } from "../slot.js";
@@ -40,7 +40,7 @@ export interface TransitionExecutionResult<S> {
  *
  * @internal
  */
-export const runTransitionHandler = <
+export const runTransitionHandler = Effect.fn("effect-machine.runTransitionHandler")(function* <
   S extends { readonly _tag: string },
   E extends { readonly _tag: string },
   R,
@@ -52,20 +52,19 @@ export const runTransitionHandler = <
   state: S,
   event: E,
   self: MachineRef<E>,
-): Effect.Effect<S, never, R> =>
-  Effect.gen(function* () {
-    const ctx: MachineContext<S, E, MachineRef<E>> = { state, event, self };
-    const { guards, effects } = machine._createSlotAccessors(ctx);
+) {
+  const ctx: MachineContext<S, E, MachineRef<E>> = { state, event, self };
+  const { guards, effects } = machine._slots;
 
-    const handlerCtx: HandlerContext<S, E, GD, EFD> = { state, event, guards, effects };
-    const result = transition.handler(handlerCtx);
+  const handlerCtx: HandlerContext<S, E, GD, EFD> = { state, event, guards, effects };
+  const result = transition.handler(handlerCtx);
 
-    return isEffect(result)
-      ? yield* (result as Effect.Effect<S, never, R>).pipe(
-          Effect.provideService(machine.Context, ctx),
-        )
-      : result;
-  });
+  return isEffect(result)
+    ? yield* (result as Effect.Effect<S, never, R>).pipe(
+        Effect.provideService(machine.Context, ctx),
+      )
+    : result;
+});
 
 /**
  * Execute a transition for a given state and event.
@@ -78,7 +77,7 @@ export const runTransitionHandler = <
  *
  * @internal
  */
-export const executeTransition = <
+export const executeTransition = Effect.fn("effect-machine.executeTransition")(function* <
   S extends { readonly _tag: string },
   E extends { readonly _tag: string },
   R,
@@ -89,26 +88,25 @@ export const executeTransition = <
   currentState: S,
   event: E,
   self: MachineRef<E>,
-): Effect.Effect<TransitionExecutionResult<S>, never, R> =>
-  Effect.gen(function* () {
-    const transition = resolveTransition(machine, currentState, event);
-
-    if (transition === undefined) {
-      return {
-        newState: currentState,
-        transitioned: false,
-        reenter: false,
-      };
-    }
-
-    const newState = yield* runTransitionHandler(machine, transition, currentState, event, self);
+) {
+  const transition = resolveTransition(machine, currentState, event);
 
+  if (transition === undefined) {
     return {
-      newState,
-      transitioned: true,
-      reenter: transition.reenter === true,
+      newState: currentState,
+      transitioned: false,
+      reenter: false,
     };
-  });
+  }
+
+  const newState = yield* runTransitionHandler(machine, transition, currentState, event, self);
+
+  return {
+    newState,
+    transitioned: true,
+    reenter: transition.reenter === true,
+  };
+});
 
 // ============================================================================
 // Event Processing Core (shared by actor and entity-machine)
@@ -122,6 +120,18 @@ export interface ProcessEventHooks<S, E> {
   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.
+ */
+export interface ProcessEventError<S, E> {
+  readonly phase: "transition" | "spawn";
+  readonly state: S;
+  readonly event: E;
+  readonly cause: Cause.Cause<unknown>;
 }
 
 /**
@@ -152,7 +162,7 @@ export interface ProcessEventResult<S> {
  *
  * @internal
  */
-export const processEventCore = <
+export const processEventCore = Effect.fn("effect-machine.processEventCore")(function* <
   S extends { readonly _tag: string },
   E extends { readonly _tag: string },
   R,
@@ -165,62 +175,84 @@ export const processEventCore = <
   self: MachineRef<E>,
   stateScopeRef: { current: Scope.CloseableScope },
   hooks?: ProcessEventHooks<S, E>,
-): Effect.Effect<ProcessEventResult<S>, never, R> =>
-  Effect.gen(function* () {
-    // Execute transition
-    const result = yield* executeTransition(machine, currentState, event, self);
-
-    if (!result.transitioned) {
-      return {
-        newState: currentState,
-        previousState: currentState,
-        transitioned: false,
-        lifecycleRan: false,
-        isFinal: false,
-      };
-    }
-
-    const newState = result.newState;
-    const stateTagChanged = newState._tag !== currentState._tag;
-    const runLifecycle = stateTagChanged || result.reenter;
+) {
+  // Execute transition (defect-aware)
+  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 === undefined) {
+        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,
+    };
+  }
 
-    if (runLifecycle) {
-      // Close old state scope (interrupts spawn fibers)
-      yield* Scope.close(stateScopeRef.current, Exit.void);
+  const newState = result.newState;
+  const stateTagChanged = newState._tag !== currentState._tag;
+  const runLifecycle = stateTagChanged || result.reenter;
 
-      // Create new state scope
-      stateScopeRef.current = yield* Scope.make();
+  if (runLifecycle) {
+    // Close old state scope (interrupts spawn fibers)
+    yield* Scope.close(stateScopeRef.current, Exit.void);
 
-      // Hook: transition complete (before spawn effects)
-      if (hooks?.onTransition !== undefined) {
-        yield* hooks.onTransition(currentState, newState, event);
-      }
+    // Create new state scope
+    stateScopeRef.current = yield* Scope.make();
 
-      // Hook: about to run spawn effects
-      if (hooks?.onSpawnEffect !== undefined) {
-        yield* hooks.onSpawnEffect(newState);
-      }
+    // Hook: transition complete (before spawn effects)
+    if (hooks?.onTransition !== undefined) {
+      yield* hooks.onTransition(currentState, newState, event);
+    }
 
-      // Run spawn effects for new state
-      const enterEvent = { _tag: INTERNAL_ENTER_EVENT } as E;
-      yield* runSpawnEffects(machine, newState, enterEvent, self, stateScopeRef.current);
+    // Hook: about to run spawn effects
+    if (hooks?.onSpawnEffect !== undefined) {
+      yield* hooks.onSpawnEffect(newState);
     }
 
-    return {
+    // Run spawn effects for new state
+    const enterEvent = { _tag: INTERNAL_ENTER_EVENT } as E;
+    yield* runSpawnEffects(
+      machine,
       newState,
-      previousState: currentState,
-      transitioned: true,
-      lifecycleRan: runLifecycle,
-      isFinal: machine.finalStates.has(newState._tag),
-    };
-  });
+      enterEvent,
+      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
  */
-export const runSpawnEffects = <
+export const runSpawnEffects = Effect.fn("effect-machine.runSpawnEffects")(function* <
   S extends { readonly _tag: string },
   E extends { readonly _tag: string },
   R,
@@ -232,25 +264,42 @@ export const runSpawnEffects = <
   event: E,
   self: MachineRef<E>,
   stateScope: Scope.CloseableScope,
-): Effect.Effect<void, never, R> =>
-  Effect.gen(function* () {
-    const spawnEffects = findSpawnEffects(machine, state._tag);
-    const ctx: MachineContext<S, E, MachineRef<E>> = { state, event, self };
-    const { effects: effectSlots } = machine._createSlotAccessors(ctx);
-
-    for (const spawnEffect of spawnEffects) {
-      // Fork the spawn effect into the state scope - interrupted when scope closes
-      yield* Effect.forkScoped(
-        (
-          spawnEffect.handler({ state, event, self, effects: effectSlots }) as Effect.Effect<
-            void,
-            never,
-            R
-          >
-        ).pipe(Effect.provideService(machine.Context, ctx)),
-      ).pipe(Effect.provideService(Scope.Scope, stateScope));
-    }
-  });
+  onError?: (info: ProcessEventError<S, E>) => Effect.Effect<void>,
+) {
+  const spawnEffects = findSpawnEffects(machine, state._tag);
+  const ctx: MachineContext<S, E, MachineRef<E>> = { state, event, self };
+  const { effects: effectSlots } = machine._slots;
+  const reportError = onError;
+
+  for (const spawnEffect of spawnEffects) {
+    // Fork the spawn effect into the state scope - interrupted when scope closes
+    const effect = (
+      spawnEffect.handler({ state, event, self, effects: effectSlots }) as Effect.Effect<
+        void,
+        never,
+        R
+      >
+    ).pipe(
+      Effect.provideService(machine.Context, ctx),
+      Effect.catchAllCause((cause) => {
+        if (Cause.isInterruptedOnly(cause)) {
+          return Effect.interrupt;
+        }
+        if (reportError === undefined) {
+          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.
@@ -300,6 +349,13 @@ interface MachineIndex<S, E, GD extends GuardsDef, EFD extends EffectsDef, R> {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const indexCache = new WeakMap<object, MachineIndex<any, any, any, any, any>>();
 
+/**
+ * Invalidate cached index for a machine (call after mutation).
+ */
+export const invalidateIndex = (machine: object): void => {
+  indexCache.delete(machine);
+};
+
 /**
  * Build transition index from machine definition.
  * O(n) where n = number of transitions.