effect-machine 0.17.1 → 0.19.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Velasquez Ramos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -17,17 +17,16 @@ Use it when a feature has:
 bun add effect-machine effect
 ```
 
-`effect` is a peer dependency. The repository validates both the v4 entrypoint
-and the `effect-machine/v3` mirror with `@effect/tsgo`, the latest Effect beta,
-type-aware oxlint, and Bun tests.
+`effect` is a peer dependency. The repository validates the package with
+`@effect/tsgo`, the latest Effect release candidate, type-aware oxlint, and Bun tests.
 
 ## Core Pattern
 
 States and events are schemas. Types, validation, and serialization from one place.
 
 ```ts
-import { Schema } from "effect";
-import { Event, Machine, Slot, State } from "effect-machine";
+import { Cause, Context, Effect, Schema } from "effect";
+import { Event, Machine, State } from "effect-machine";
 
 const CheckoutState = State({
   ReviewingCart: { cartId: Schema.String, totalCents: Schema.Number },
@@ -43,30 +42,43 @@ const CheckoutEvent = Event({
   Cancel: {},
 });
 
-const CheckoutSlots = Slot.define({
-  chargeCard: Slot.fn({ cartId: Schema.String, totalCents: Schema.Number }),
-});
+class PaymentService extends Context.Service<
+  PaymentService,
+  {
+    readonly chargeCard: (
+      cartId: string,
+      totalCents: number,
+    ) => Effect.Effect<{ readonly receiptId: string }>;
+  }
+>()("app/PaymentService") {}
 
 const checkoutMachine = Machine.make({
   state: CheckoutState,
   event: CheckoutEvent,
-  slots: CheckoutSlots,
   initial: CheckoutState.ReviewingCart({ cartId: "cart_123", totalCents: 4200 }),
 })
   .on(CheckoutState.ReviewingCart, CheckoutEvent.Submit, ({ state }) =>
-    CheckoutState.ChargingCard.derive(state),
+    CheckoutState.ChargingCard.with(state),
   )
   .on(CheckoutState.ChargingCard, CheckoutEvent.Charged, ({ state, event }) =>
-    CheckoutState.Confirmed.derive(state, { receiptId: event.receiptId }),
+    CheckoutState.Confirmed.with(state, { receiptId: event.receiptId }),
   )
   .on(CheckoutState.ChargingCard, CheckoutEvent.Declined, ({ state, event }) =>
-    CheckoutState.Failed.derive(state, { reason: event.reason }),
+    CheckoutState.Failed.with(state, { reason: event.reason }),
   )
   .onAny(CheckoutEvent.Cancel, ({ state }) =>
-    CheckoutState.Failed.derive(state, { reason: "cancelled" }),
+    CheckoutState.Failed.with(state, { reason: "cancelled" }),
   )
-  .spawn(CheckoutState.ChargingCard, ({ slots, state }) =>
-    slots.chargeCard({ cartId: state.cartId, totalCents: state.totalCents }),
+  .task(
+    CheckoutState.ChargingCard,
+    ({ state }) =>
+      Effect.flatMap(PaymentService, (payment) =>
+        payment.chargeCard(state.cartId, state.totalCents),
+      ),
+    {
+      onSuccess: ({ receiptId }) => CheckoutEvent.Charged({ receiptId }),
+      onFailure: (cause) => CheckoutEvent.Declined({ reason: Cause.pretty(cause) }),
+    },
   )
   .final(CheckoutState.Confirmed)
   .final(CheckoutState.Failed);
@@ -75,42 +87,30 @@ const checkoutMachine = Machine.make({
 A few things to notice:
 
 - Empty variants are values: `State.Idle`. Non-empty are constructors: `State.Loading({ url })`.
-- `State.derive(source, overrides)` carries overlapping fields forward without manual copying.
+- `State.with(source, overrides)` carries overlapping fields forward without manual copying.
 - `.onAny(...)` is a fallback; a specific `.on(...)` wins.
 - `.spawn(...)` runs work on state entry and cancels it on state exit.
 
 The builder also supports `.timeout(state, { duration, event })`, `.postpone(state, event)` for buffering, and `.reenter(...)` for re-running lifecycle on same-state transitions.
 
-## Slots
+## Effect Services
 
-Slots separate what a machine needs from how the app provides it. Declare them on the machine, provide implementations where you run it.
+Task, spawn, and background handlers can use standard Effect services. The machine type records each service requirement.
 
 ```ts
 const actor =
   yield *
-  Machine.spawn(checkoutMachine, {
-    slots: {
-      chargeCard: ({ cartId, totalCents }) =>
-        Effect.gen(function* () {
-          const ctx = yield* checkoutMachine.Context;
-          const result = yield* PaymentService.charge(cartId, totalCents);
-          yield* ctx.self.send(
-            result.ok
-              ? CheckoutEvent.Charged({ receiptId: result.receiptId })
-              : CheckoutEvent.Declined({ reason: result.error }),
-          );
-        }),
-    },
-  });
+  Machine.spawn(checkoutMachine).pipe(
+    Effect.provideService(PaymentService, {
+      chargeCard: (cartId) => Effect.succeed({ receiptId: `rcpt_${cartId}` }),
+    }),
+  );
 yield * actor.start;
 ```
 
-The same machine can run with different slot implementations in tests, local apps, or production. Slots are accepted everywhere the machine runs:
+`Machine.spawn` captures the current Effect context. A later `actor.start` keeps those services. Use a different layer or service value in each test or runtime.
 
-- `Machine.spawn(machine, { slots })`
-- `Machine.replay(machine, events, { slots })`
-- `simulate(machine, events, { slots })`
-- `createTestHarness(machine, { slots })`
+Transition handlers in `.on()` and `.reenter()` stay pure. Use services only in `.task()`, `.spawn()`, and `.background()`.
 
 ## Running Actors
 
@@ -118,23 +118,20 @@ The same machine can run with different slot implementations in tests, local app
 
 ```ts
 const program = Effect.gen(function* () {
-  const actor = yield* Machine.spawn(checkoutMachine, {
-    slots: {
-      chargeCard: ({ cartId }) =>
-        checkoutMachine.Context.pipe(
-          Effect.flatMap((ctx) =>
-            ctx.self.send(CheckoutEvent.Charged({ receiptId: `rcpt_${cartId}` })),
-          ),
-        ),
-    },
-  });
+  const actor = yield* Machine.spawn(checkoutMachine);
   yield* actor.start;
 
   yield* actor.send(CheckoutEvent.Submit);
   const finalState = yield* actor.awaitFinal;
 });
 
-Effect.runPromise(Effect.scoped(program));
+Effect.runPromise(
+  Effect.scoped(program).pipe(
+    Effect.provideService(PaymentService, {
+      chargeCard: (cartId) => Effect.succeed({ receiptId: `rcpt_${cartId}` }),
+    }),
+  ),
+);
 ```
 
 Key actor operations:
@@ -145,7 +142,7 @@ Key actor operations:
 - `ask(event)` returns a typed domain reply (requires `Event.reply(...)`)
 - `waitFor(...)` / `awaitFinal` for coordination
 - `stop` interrupts now; `drain` processes the remaining queue first
-- `watch(other)` completes when another actor stops
+- `awaitExit` completes when the actor stops
 
 For named actors or shared lookup, use an actor system. `system.spawn` auto-starts — no `actor.start` needed:
 
@@ -182,17 +179,63 @@ import { simulate } from "effect-machine";
 
 const result =
   yield *
-  simulate(
-    checkoutMachine,
-    [CheckoutEvent.Submit, CheckoutEvent.Charged({ receiptId: "rcpt_123" })],
-    { slots: { chargeCard: () => Effect.void } },
-  );
+  simulate(checkoutMachine, [
+    CheckoutEvent.Submit,
+    CheckoutEvent.Charged({ receiptId: "rcpt_123" }),
+  ]);
 
 expect(result.states.map((s) => s._tag)).toEqual(["ReviewingCart", "ChargingCard", "Confirmed"]);
 ```
 
 `simulate` and `createTestHarness` test transition logic. They do not run `.spawn()` or `.background()` effects.
 
+## React, Solid, and Vue
+
+Use the Effect Atom adapter to connect one actor to any Effect Atom framework binding. The actor remains the state owner. Atom writes send typed events.
+
+```ts
+import { useAtomSet, useAtomValue } from "@effect/atom-react";
+import * as ActorAtom from "effect-machine/atom";
+
+const checkoutAtom = ActorAtom.make(actor);
+
+function CheckoutTotal() {
+  const totalCents = useAtomValue(checkoutAtom, (state) =>
+    "totalCents" in state ? state.totalCents : 0,
+  );
+  const send = useAtomSet(checkoutAtom);
+
+  return <button onClick={() => send(CheckoutEvent.Submit)}>Pay {totalCents}</button>;
+}
+```
+
+`useAtomValue` subscribes to the selected value. It does not render again when another state field changes. Use `ActorAtom.select` when you need a reusable selector or a custom equality function:
+
+```ts
+const totalAtom = ActorAtom.select(
+  checkoutAtom,
+  (state) => ("totalCents" in state ? { cents: state.totalCents } : { cents: 0 }),
+  (value, next) => value.cents === next.cents,
+);
+```
+
+The selected Atom stays writable. `useAtomSet(totalAtom)` still sends checkout events. Solid uses the same Atom with `@effect/atom-solid`. Vue uses the same Atom with `@effect/atom-vue`.
+
+Runnable React and Solid package examples are in `examples/react` and `examples/solid`.
+
+```bash
+bun run example:react
+bun run example:solid
+```
+
+Each example creates the actor through `Atom.make(Machine.scoped(...))`. React reads it with `useAtomSuspense`. Solid reads it with `useAtomResource` inside a Suspense boundary. The Atom scope owns actor cleanup.
+
+Each example has a framework performance test. The React test counts component renders. The Solid test counts reactive computations. Both tests prove that an unrelated selector does not update.
+
+The React example uses Motion `AnimatePresence`. The Solid example uses `solid-transition-group`. Both examples keep the old screen mounted for a 200 ms exit after the machine enters `Done`.
+
+The terminal `Done` state keeps the displayed `count` and `label`. The old screen stays valid without a local retained-value hook. Keep exit data in the terminal state or handle the terminal variant in the selector. Do not cache the last non-null selector value.
+
 ## Cluster
 
 When the same machine needs to run behind `@effect/cluster`, turn it into an entity:

package/dist/actor.d.ts

@@ -1,15 +1,10 @@
 import { ExtractReply, ReplyTypeBrand } from "./internal/brands.js";
 import { ActorStoppedError, DuplicateActorError, NoReplyError } from "./errors.js";
-import { ProvideSlots, SlotsDef } from "./slot.js";
 import { ActorExit, Supervision } from "./supervision.js";
-import { ProcessEventError, ProcessEventHooks, ProcessEventResult, processEventCore, resolveTransition, runSpawnEffects } from "./internal/transition.js";
 import { Lifecycle, Machine } from "./machine.js";
-import { RuntimeQueuedEvent } from "./internal/runtime.js";
-import { Context, Deferred, Effect, Layer, Option, PubSub, Queue, Ref, Scope, Stream, SubscriptionRef } from "effect";
-
+import { ProcessEventResult } from "./internal/transition.js";
+import { Context, Effect, Layer, Option, Scope, Stream, SubscriptionRef } from "effect";
 //#region src/actor.d.ts
-/** Discriminated mailbox request — alias for RuntimeQueuedEvent */
-type QueuedEvent<E> = RuntimeQueuedEvent<E>;
 /**
  * Sync projection of ActorRef for non-Effect boundaries (React hooks, framework callbacks).
  */
@@ -37,8 +32,6 @@ interface ActorRef<State extends {
   readonly id: string;
   /** Send an event (fire-and-forget). */
   readonly send: (event: Event) => Effect.Effect<void>;
-  /** Fire-and-forget alias for send (OTP gen_server:cast). */
-  readonly cast: (event: Event) => Effect.Effect<void>;
   /**
    * Serialized request-reply (OTP gen_server:call).
    * Event is processed through the queue; caller gets ProcessEventResult back.
@@ -103,15 +96,6 @@ interface ActorRef<State extends {
    * Set exactly once when the actor terminates (final, stop, drain, or defect).
    */
   readonly awaitExit: Effect.Effect<ActorExit<State>>;
-  /**
-   * Watch another actor. Returns an Effect that resolves with the exit reason
-   * when the watched actor terminally stops. Ignores restarts (Step 3).
-   * Built on the other actor's exitDeferred — authoritative, not system events.
-   */
-  readonly watch: (other: {
-    readonly id: string;
-    readonly awaitExit: Effect.Effect<ActorExit<unknown>>;
-  }) => Effect.Effect<ActorExit<unknown>>;
   /**
    * Drain: process all remaining events in the queue, then stop.
    * Unlike `stop` (which interrupts immediately), `drain` lets the actor finish its work.
@@ -167,9 +151,8 @@ interface ActorSystemService {
     readonly _tag: string;
   }, E extends {
     readonly _tag: string;
-  }, R, SD extends SlotsDef = Record<string, never>>(id: string, machine: Machine<S, E, R, any, any, SD>, options?: {
+  }, R>(id: string, machine: Machine<S, E, R, any, any>, options?: {
     readonly supervision?: Supervision.Policy;
-    readonly slots?: ProvideSlots<SD, any>;
     readonly lifecycle?: Lifecycle<S, E>;
   }) => Effect.Effect<ActorRef<S, E>, DuplicateActorError, R>;
   /**
@@ -212,20 +195,6 @@ declare const ActorScope_base: Context.ServiceClass<ActorScope, "effect-machine/
  * Provide via `Machine.scoped` or `Effect.provideService(ActorScope, scope)`.
  */
 declare class ActorScope extends ActorScope_base {}
-/** Listener set for sync subscriptions */
-type Listeners<S> = Set<(state: S) => void>;
-/**
- * Notify all listeners of state change.
- */
-declare const notifyListeners: <S>(listeners: Listeners<S>, state: S) => void;
-/**
- * Build core ActorRef methods.
- */
-declare const buildActorRefCore: <S extends {
-  readonly _tag: string;
-}, E extends {
-  readonly _tag: string;
-}, R, SD extends SlotsDef>(id: string, machine: Machine<S, E, R, any, any, SD>, stateRef: SubscriptionRef.SubscriptionRef<S>, eventQueueRef: Ref.Ref<Queue.Queue<QueuedEvent<E>>>, stoppedRef: Ref.Ref<boolean>, listeners: Listeners<S>, stop: Effect.Effect<void>, start: Effect.Effect<void>, system: ActorSystemService, childrenMap: ReadonlyMap<string, ActorRef<AnyState, unknown>>, pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, transitionsPubSub: PubSub.PubSub<TransitionInfo<S, E>> | undefined, exitDeferred: Deferred.Deferred<ActorExit<S>>) => ActorRef<S, E>;
 /**
  * Create and start an actor for a machine.
  * Delegates to the shared runtime kernel with actor-specific lifecycle hooks.
@@ -234,22 +203,16 @@ declare const createActor: <S extends {
   readonly _tag: string;
 }, E extends {
   readonly _tag: string;
-}, R, SD extends SlotsDef>(id: string, machine: Machine<S, E, R, any, any, SD>, options?: {
+}, R>(id: string, machine: Machine<S, E, R, any, any>, options?: {
   initialState?: S;
   supervision?: Supervision.Policy;
-  lifecycle?: Lifecycle<S, E>; /** @internal Called by system after each restart — emits ActorRestarted system event */
+  lifecycle?: Lifecycle<S, E>;
+  /** @internal Called by system after each restart — emits ActorRestarted system event */
   onRestart?: (generation: number, exit: ActorExit<unknown>) => Effect.Effect<void>;
-} | undefined) => Effect.Effect<ActorRef<S, E>, never, never>;
-/** Fail all pending call/ask Deferreds with ActorStoppedError. Safe to call multiple times. */
-declare const settlePendingReplies: (pendingReplies: Set<Deferred.Deferred<unknown, unknown>>, actorId: string) => Effect.Effect<void, never, never>;
-/**
- * Create an ActorSystem instance. Must be run in a Scope.
- * @internal — use Default layer for normal usage
- */
-declare const makeSystem: () => Effect.Effect<ActorSystemService, never, Scope.Scope>;
+} | undefined) => Effect.Effect<ActorRef<S, E>, never, R>;
 /**
  * Default ActorSystem layer
  */
 declare const Default: Layer.Layer<ActorSystem, never, never>;
 //#endregion
-export { ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemService, Default, Listeners, type ProcessEventError, type ProcessEventHooks, type ProcessEventResult, QueuedEvent, SystemEvent, SystemEventListener, TransitionInfo, buildActorRefCore, createActor, makeSystem, notifyListeners, processEventCore, resolveTransition, runSpawnEffects, settlePendingReplies };
+export { ActorRef, ActorRefSync, ActorScope, ActorSystem, ActorSystemService, Default, type ProcessEventResult, SystemEvent, SystemEventListener, TransitionInfo, createActor };