effect-machine 0.2.4 → 0.3.1

package/src/actor.ts

@@ -6,9 +6,11 @@
  * - ActorSystem service (spawn/stop/get actors)
  * - Actor creation and event loop
  */
+import type { Stream } from "effect";
 import {
   Cause,
   Context,
+  Deferred,
   Effect,
   Exit,
   Fiber,
@@ -17,12 +19,12 @@ import {
   Option,
   Queue,
   Ref,
+  Runtime,
   Scope,
-  Stream,
   SubscriptionRef,
 } from "effect";
 
-import type { Machine, MachineRef } from "./machine.js";
+import type { Machine, MachineRef, BuiltMachine } from "./machine.js";
 import type { Inspector } from "./inspection.js";
 import { Inspector as InspectorTag } from "./inspection.js";
 import { processEventCore, runSpawnEffects, resolveTransition } from "./internal/transition.js";
@@ -37,7 +39,7 @@ export type {
   ProcessEventResult,
 } from "./internal/transition.js";
 import type { GuardsDef, EffectsDef } from "./slot.js";
-import { DuplicateActorError, UnprovidedSlotsError } from "./errors.js";
+import { DuplicateActorError } from "./errors.js";
 import { INTERNAL_INIT_EVENT } from "./internal/utils.js";
 import type {
   ActorMetadata,
@@ -82,6 +84,13 @@ export interface ActorRef<State extends { readonly _tag: string }, Event> {
    */
   readonly stop: Effect.Effect<void>;
 
+  /**
+   * Stop the actor (fire-and-forget).
+   * Signals graceful shutdown without waiting for completion.
+   * Use when stopping from sync contexts (e.g. framework cleanup hooks).
+   */
+  readonly stopSync: () => void;
+
   /**
    * Get current state snapshot (Effect)
    */
@@ -118,9 +127,13 @@ export interface ActorRef<State extends { readonly _tag: string }, Event> {
   readonly changes: Stream.Stream<State>;
 
   /**
-   * Wait for a state that matches predicate (includes current snapshot)
+   * Wait for a state that matches predicate or state variant (includes current snapshot).
+   * Accepts a predicate function or a state constructor/value (e.g. `State.Active`).
    */
-  readonly waitFor: (predicate: (state: State) => boolean) => Effect.Effect<State>;
+  readonly waitFor: {
+    (predicate: (state: State) => boolean): Effect.Effect<State>;
+    (state: { readonly _tag: State["_tag"] }): Effect.Effect<State>;
+  };
 
   /**
    * Wait for a final state (includes current snapshot)
@@ -128,12 +141,21 @@ export interface ActorRef<State extends { readonly _tag: string }, Event> {
   readonly awaitFinal: Effect.Effect<State>;
 
   /**
-   * Send event and wait for predicate or final state
+   * Send event and wait for predicate, state variant, or final state.
+   * Accepts a predicate function or a state constructor/value (e.g. `State.Active`).
+   */
+  readonly sendAndWait: {
+    (event: Event, predicate: (state: State) => boolean): Effect.Effect<State>;
+    (event: Event, state: { readonly _tag: State["_tag"] }): Effect.Effect<State>;
+    (event: Event): Effect.Effect<State>;
+  };
+
+  /**
+   * Send event synchronously (fire-and-forget).
+   * No-op on stopped actors. Use when you need to send from sync contexts
+   * (e.g. framework hooks, event handlers).
    */
-  readonly sendAndWait: (
-    event: Event,
-    predicate?: (state: State) => boolean,
-  ) => Effect.Effect<State>;
+  readonly sendSync: (event: Event) => void;
 
   /**
    * Subscribe to state changes (sync callback)
@@ -159,14 +181,13 @@ export interface ActorSystem {
    * For regular machines, returns ActorRef.
    * For persistent machines (created with Machine.persist), returns PersistentActorRef.
    *
-   * Note: All effect slots must be provided via `Machine.provide` before spawning.
-   * Attempting to spawn a machine with unprovided effect slots will fail.
+   * All effect slots must be provided via `.build()` before spawning.
    *
    * @example
    * ```ts
-   * // Regular machine (effects provided)
-   * const machine = Machine.provide(baseMachine, { fetchData: ... })
-   * const actor = yield* system.spawn("my-actor", machine);
+   * // Regular machine (built)
+   * const built = machine.build({ fetchData: ... })
+   * const actor = yield* system.spawn("my-actor", built);
    *
    * // Persistent machine (auto-detected)
    * const persistentActor = yield* system.spawn("my-actor", persistentMachine);
@@ -175,18 +196,11 @@ export interface ActorSystem {
    * ```
    */
   readonly spawn: {
-    // Regular machine overload
-    <
-      S extends { readonly _tag: string },
-      E extends { readonly _tag: string },
-      R,
-      GD extends GuardsDef = Record<string, never>,
-      EFD extends EffectsDef = Record<string, never>,
-    >(
+    // Regular machine overload (BuiltMachine)
+    <S extends { readonly _tag: string }, E extends { readonly _tag: string }, R>(
       id: string,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
-      machine: Machine<S, E, R, any, any, GD, EFD>,
-    ): Effect.Effect<ActorRef<S, E>, DuplicateActorError | UnprovidedSlotsError, R | Scope.Scope>;
+      machine: BuiltMachine<S, E, R>,
+    ): Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
 
     // Persistent machine overload
     <S extends { readonly _tag: string }, E extends { readonly _tag: string }, R>(
@@ -194,8 +208,8 @@ export interface ActorSystem {
       machine: PersistentMachine<S, E, R>,
     ): Effect.Effect<
       PersistentActorRef<S, E, R>,
-      PersistenceError | VersionConflictError | DuplicateActorError | UnprovidedSlotsError,
-      R | Scope.Scope | PersistenceAdapterTag
+      PersistenceError | VersionConflictError | DuplicateActorError,
+      R | PersistenceAdapterTag
     >;
   };
 
@@ -218,8 +232,8 @@ export interface ActorSystem {
     machine: PersistentMachine<S, E, R>,
   ) => Effect.Effect<
     Option.Option<PersistentActorRef<S, E, R>>,
-    PersistenceError | DuplicateActorError | UnprovidedSlotsError,
-    R | Scope.Scope | PersistenceAdapterTag
+    PersistenceError | DuplicateActorError,
+    R | PersistenceAdapterTag
   >;
 
   /**
@@ -267,7 +281,7 @@ export interface ActorSystem {
   >(
     ids: ReadonlyArray<string>,
     machine: PersistentMachine<S, E, R>,
-  ) => Effect.Effect<RestoreResult<S, E, R>, never, R | Scope.Scope | PersistenceAdapterTag>;
+  ) => Effect.Effect<RestoreResult<S, E, R>, never, R | PersistenceAdapterTag>;
 
   /**
    * Restore all persisted actors for a machine type.
@@ -288,11 +302,7 @@ export interface ActorSystem {
   >(
     machine: PersistentMachine<S, E, R>,
     options?: { filter?: (meta: ActorMetadata) => boolean },
-  ) => Effect.Effect<
-    RestoreResult<S, E, R>,
-    PersistenceError,
-    R | Scope.Scope | PersistenceAdapterTag
-  >;
+  ) => Effect.Effect<RestoreResult<S, E, R>, PersistenceError, R | PersistenceAdapterTag>;
 }
 
 /**
@@ -362,16 +372,41 @@ export const buildActorRefCore = <
   });
 
   const waitFor = Effect.fn("effect-machine.actor.waitFor")(function* (
-    predicate: (state: S) => boolean,
+    predicateOrState: ((state: S) => boolean) | { readonly _tag: S["_tag"] },
   ) {
-    // Use stateRef.changes directly — it emits the current value as its first
-    // element inside the SubscriptionRef semaphore, so this is atomic and
-    // race-free (no gap between "check current" and "subscribe").
-    const result = yield* stateRef.changes.pipe(Stream.filter(predicate), Stream.runHead);
-    if (Option.isSome(result)) return result.value;
-    // Unreachable: changes always emits at least the current value.
-    // Fallback to snapshot for type completeness.
-    return yield* SubscriptionRef.get(stateRef);
+    const predicate =
+      typeof predicateOrState === "function" && !("_tag" in predicateOrState)
+        ? predicateOrState
+        : (s: S) => s._tag === (predicateOrState as { readonly _tag: string })._tag;
+
+    // Check current state first — SubscriptionRef.get acquires/releases
+    // the semaphore quickly (read-only), no deadlock risk.
+    const current = yield* SubscriptionRef.get(stateRef);
+    if (predicate(current)) return current;
+
+    // Use sync listener + Deferred to avoid holding the SubscriptionRef
+    // semaphore for the duration of a stream (which causes deadlock when
+    // send triggers SubscriptionRef.set concurrently).
+    const done = yield* Deferred.make<S>();
+    const rt = yield* Effect.runtime<never>();
+    const runFork = Runtime.runFork(rt);
+    const listener = (state: S) => {
+      if (predicate(state)) {
+        runFork(Deferred.succeed(done, state));
+      }
+    };
+    listeners.add(listener);
+
+    // Re-check after subscribing to close the race window
+    const afterSubscribe = yield* SubscriptionRef.get(stateRef);
+    if (predicate(afterSubscribe)) {
+      listeners.delete(listener);
+      return afterSubscribe;
+    }
+
+    const result = yield* Deferred.await(done);
+    listeners.delete(listener);
+    return result;
   });
 
   const awaitFinal = waitFor((state) => machine.finalStates.has(state._tag)).pipe(
@@ -380,11 +415,11 @@ export const buildActorRefCore = <
 
   const sendAndWait = Effect.fn("effect-machine.actor.sendAndWait")(function* (
     event: E,
-    predicate?: (state: S) => boolean,
+    predicateOrState?: ((state: S) => boolean) | { readonly _tag: S["_tag"] },
   ) {
     yield* send(event);
-    if (predicate !== undefined) {
-      return yield* waitFor(predicate);
+    if (predicateOrState !== undefined) {
+      return yield* waitFor(predicateOrState);
     }
     return yield* awaitFinal;
   });
@@ -394,6 +429,7 @@ export const buildActorRefCore = <
     send,
     state: stateRef,
     stop,
+    stopSync: () => Effect.runFork(stop),
     snapshot,
     snapshotSync: () => Effect.runSync(SubscriptionRef.get(stateRef)),
     matches,
@@ -407,6 +443,12 @@ export const buildActorRefCore = <
     waitFor,
     awaitFinal,
     sendAndWait,
+    sendSync: (event) => {
+      const stopped = Effect.runSync(Ref.get(stoppedRef));
+      if (!stopped) {
+        Effect.runSync(Queue.offer(eventQueue, event));
+      }
+    },
     subscribe: (fn) => {
       listeners.add(fn);
       return () => {
@@ -432,11 +474,6 @@ export const createActor = Effect.fn("effect-machine.actor.spawn")(function* <
 >(id: string, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>) {
   yield* Effect.annotateCurrentSpan("effect_machine.actor.id", id);
 
-  const missing = machine._missingSlots();
-  if (missing.length > 0) {
-    return yield* new UnprovidedSlotsError({ slots: missing });
-  }
-
   // Get optional inspector from context
   const inspectorValue = Option.getOrUndefined(yield* Effect.serviceOption(InspectorTag)) as
     | Inspector<S, E>
@@ -477,7 +514,7 @@ export const createActor = Effect.fn("effect-machine.actor.spawn")(function* <
   const { effects: effectSlots } = machine._slots;
 
   for (const bg of machine.backgroundEffects) {
-    const fiber = yield* Effect.fork(
+    const fiber = yield* Effect.forkDaemon(
       bg
         .handler({ state: machine.initial, event: initEvent, self, effects: effectSlots })
         .pipe(Effect.provideService(machine.Context, ctx)),
@@ -520,10 +557,9 @@ export const createActor = Effect.fn("effect-machine.actor.spawn")(function* <
     return buildActorRefCore(id, machine, stateRef, eventQueue, stoppedRef, listeners, stop);
   }
 
-  // Start the event loop — use forkScoped so the event loop fiber's lifetime
-  // is tied to the provided Scope, not the calling fiber. This prevents the
-  // event loop from being interrupted when a transient caller completes.
-  const loopFiber = yield* Effect.forkScoped(
+  // Start the event loop — use forkDaemon so the event loop fiber's lifetime
+  // is detached from any parent scope/fiber. actor.stop handles cleanup.
+  const loopFiber = yield* Effect.forkDaemon(
     eventLoop(
       machine,
       stateRef,
@@ -774,7 +810,16 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
   const spawnGate = yield* Effect.makeSemaphore(1);
   const withSpawnGate = spawnGate.withPermits(1);
 
-  /** Check for duplicate ID, register actor, add cleanup finalizer */
+  // Stop all actors on system teardown
+  yield* Effect.addFinalizer(() => {
+    const stops: Effect.Effect<void>[] = [];
+    MutableHashMap.forEach(actors, (actor) => {
+      stops.push(actor.stop);
+    });
+    return Effect.all(stops, { concurrency: "unbounded" }).pipe(Effect.asVoid);
+  });
+
+  /** Check for duplicate ID, register actor, attach scope cleanup if available */
   const registerActor = Effect.fn("effect-machine.actorSystem.register")(function* <
     T extends { stop: Effect.Effect<void> },
   >(id: string, actor: T) {
@@ -788,13 +833,17 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
     // Register it - O(1)
     MutableHashMap.set(actors, id, actor as unknown as ActorRef<AnyState, unknown>);
 
-    // Register cleanup on scope finalization
-    yield* Effect.addFinalizer(
-      Effect.fn("effect-machine.actorSystem.register.finalizer")(function* () {
-        yield* actor.stop;
-        MutableHashMap.remove(actors, id);
-      }),
-    );
+    // If scope available, attach per-actor cleanup
+    const maybeScope = yield* Effect.serviceOption(Scope.Scope);
+    if (Option.isSome(maybeScope)) {
+      yield* Scope.addFinalizer(
+        maybeScope.value,
+        Effect.gen(function* () {
+          yield* actor.stop;
+          MutableHashMap.remove(actors, id);
+        }),
+      );
+    }
 
     return actor;
   });
@@ -803,14 +852,12 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
     S extends { readonly _tag: string },
     E extends { readonly _tag: string },
     R,
-    GD extends GuardsDef = Record<string, never>,
-    EFD extends EffectsDef = Record<string, never>,
-  >(id: string, machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>) {
+  >(id: string, built: BuiltMachine<S, E, R>) {
     if (MutableHashMap.has(actors, id)) {
       return yield* new DuplicateActorError({ actorId: id });
     }
     // Create and register the actor
-    const actor = yield* createActor(id, machine);
+    const actor = yield* createActor(id, built._inner);
     return yield* registerActor(id, actor);
   });
 
@@ -846,68 +893,44 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
     S extends { readonly _tag: string },
     E extends { readonly _tag: string },
     R,
-    GD extends GuardsDef = Record<string, never>,
-    EFD extends EffectsDef = Record<string, never>,
-  >(
-    id: string,
-    machine:
-      | Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>
-      | PersistentMachine<S, E, R>,
-  ) {
+  >(id: string, machine: BuiltMachine<S, E, R> | PersistentMachine<S, E, R>) {
     if (isPersistentMachine(machine)) {
       // TypeScript can't narrow union with invariant generic params
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       return yield* spawnPersistent(id, machine as PersistentMachine<S, E, R>);
     }
-    return yield* spawnRegular(
-      id,
-      machine as Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>,
-    );
+    return yield* spawnRegular(id, machine as BuiltMachine<S, E, R>);
   });
 
   // Type-safe overloaded spawn implementation
-  function spawn<
-    S extends { readonly _tag: string },
-    E extends { readonly _tag: string },
-    R,
-    GD extends GuardsDef = Record<string, never>,
-    EFD extends EffectsDef = Record<string, never>,
-  >(
+  function spawn<S extends { readonly _tag: string }, E extends { readonly _tag: string }, R>(
     id: string,
-    machine: Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>,
-  ): Effect.Effect<ActorRef<S, E>, DuplicateActorError | UnprovidedSlotsError, R | Scope.Scope>;
+    machine: BuiltMachine<S, E, R>,
+  ): Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
   function spawn<S extends { readonly _tag: string }, E extends { readonly _tag: string }, R>(
     id: string,
     machine: PersistentMachine<S, E, R>,
   ): Effect.Effect<
     PersistentActorRef<S, E, R>,
-    PersistenceError | VersionConflictError | DuplicateActorError | UnprovidedSlotsError,
-    R | Scope.Scope | PersistenceAdapterTag
+    PersistenceError | VersionConflictError | DuplicateActorError,
+    R | PersistenceAdapterTag
   >;
-  function spawn<
-    S extends { readonly _tag: string },
-    E extends { readonly _tag: string },
-    R,
-    GD extends GuardsDef = Record<string, never>,
-    EFD extends EffectsDef = Record<string, never>,
-  >(
+  function spawn<S extends { readonly _tag: string }, E extends { readonly _tag: string }, R>(
     id: string,
-    machine:
-      | Machine<S, E, R, Record<string, never>, Record<string, never>, GD, EFD>
-      | PersistentMachine<S, E, R>,
+    machine: BuiltMachine<S, E, R> | PersistentMachine<S, E, R>,
   ):
-    | Effect.Effect<ActorRef<S, E>, DuplicateActorError | UnprovidedSlotsError, R | Scope.Scope>
+    | Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>
     | Effect.Effect<
         PersistentActorRef<S, E, R>,
-        PersistenceError | VersionConflictError | DuplicateActorError | UnprovidedSlotsError,
-        R | Scope.Scope | PersistenceAdapterTag
+        PersistenceError | VersionConflictError | DuplicateActorError,
+        R | PersistenceAdapterTag
       > {
     return withSpawnGate(spawnImpl(id, machine)) as
-      | Effect.Effect<ActorRef<S, E>, DuplicateActorError | UnprovidedSlotsError, R | Scope.Scope>
+      | Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>
       | Effect.Effect<
           PersistentActorRef<S, E, R>,
-          PersistenceError | VersionConflictError | DuplicateActorError | UnprovidedSlotsError,
-          R | Scope.Scope | PersistenceAdapterTag
+          PersistenceError | VersionConflictError | DuplicateActorError,
+          R | PersistenceAdapterTag
         >;
   }
 
@@ -961,7 +984,7 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
     const restored: PersistentActorRef<S, E, R>[] = [];
     const failed: {
       id: string;
-      error: PersistenceError | DuplicateActorError | UnprovidedSlotsError;
+      error: PersistenceError | DuplicateActorError;
     }[] = [];
 
     for (const id of ids) {
@@ -1032,4 +1055,4 @@ const make = Effect.fn("effect-machine.actorSystem.make")(function* () {
 /**
  * Default ActorSystem layer
  */
-export const Default = Layer.effect(ActorSystem, make());
+export const Default = Layer.scoped(ActorSystem, make());

package/src/errors.ts

@@ -49,7 +49,7 @@ export class SlotProvisionError extends Schema.TaggedError<SlotProvisionError>()
   },
 ) {}
 
-/** Machine.provide() validation failed - missing or extra handlers */
+/** Machine.build() validation failed - missing or extra handlers */
 export class ProvisionValidationError extends Schema.TaggedError<ProvisionValidationError>()(
   "ProvisionValidationError",
   {

package/src/index.ts

@@ -36,6 +36,7 @@ export type { MachineStateSchema, MachineEventSchema } from "./schema.js";
 // Core machine types (for advanced use)
 export type {
   Machine as MachineType,
+  BuiltMachine,
   MachineRef,
   MakeConfig,
   Transition,

package/src/internal/transition.ts

@@ -11,6 +11,7 @@
 import { Cause, Effect, Exit, Scope } from "effect";
 
 import type { Machine, MachineRef, Transition, SpawnEffect, HandlerContext } from "../machine.js";
+import { BuiltMachine } from "../machine.js";
 import type { GuardsDef, EffectsDef, MachineContext } from "../slot.js";
 import { isEffect, INTERNAL_ENTER_EVENT } from "./utils.js";
 
@@ -443,6 +444,7 @@ const getIndex = <
  * 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).
  */
 export const findTransitions = <
@@ -453,12 +455,16 @@ export const findTransitions = <
   EFD extends EffectsDef = Record<string, never>,
 >(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Schema fields need wide acceptance
-  machine: Machine<S, E, R, any, any, GD, EFD>,
+  input: Machine<S, E, R, any, any, GD, EFD> | BuiltMachine<S, E, R>,
   stateTag: string,
   eventTag: string,
 ): ReadonlyArray<Transition<S, E, GD, EFD, R>> => {
+  const machine = input instanceof BuiltMachine ? input._inner : input;
   const index = getIndex(machine);
-  return index.transitions.get(stateTag)?.get(eventTag) ?? [];
+  const specific = index.transitions.get(stateTag)?.get(eventTag) ?? [];
+  if (specific.length > 0) return specific;
+  // Fallback to wildcard transitions
+  return index.transitions.get("*")?.get(eventTag) ?? [];
 };
 
 /**