Actors

What

An Actor is one running state machine. It owns the current state, mutable context, registered transitions and effects, clock, and child actors.

States, events, and effects are declarations until an Actor runs them.

Create

import { checkout } from "../checkout.ts";

// `checkout` is the canonical multi-step checkout machine (see ./checkout.ts):
//
//   basicInfo -> shippingAddress -> payment -> submitting -> success (final)
//                                      ^ (back) v                  v (back)
//                                                               error

basicInfo -> shippingAddress -> payment -> submitting -> success
                  ^ (back) v                   v (back)
                                              error

Send events

checkout.send(submitBasicInfo.create({ email: "a@b.com", name: "A" }));

Check state

checkout.snapshot().path[0]; // "payment"
matches(checkout, "payment"); // from @mantaq/sugar

Listen for changes

const unsub = checkout.on("change", (snap) => {
  /* ... */
});
// unsub() to stop

Fires immediately with current snapshot, then on every state or context change.

Settled

await checkout.settled();

Waits for internal events to drain and pending effects to finish.

Snapshot

checkout.snapshot();
// { path: ["payment"], context: {...}, regions: {} }

Constructor options

Option	Type	What
inputs	EventRef[]	External events accepted
outputs	EventRef[]	Events to parent
internal	EventRef[]	Events from effects/transitions
states	StateRef[]	All states
initial	StateRef or { state, payload? }	Start state
context	ActorContext	Initial context
clock	Clock	Default: RealClock
setup	(m: ActorBuilder) => void	Register transitions and effects
regions	Record<string, AnyActor>	Static children
internalBudget	number	Max internal events (default: 10000)

Setup builder

Method	What
m.on(state, event, fn)	Transition handler for one state/event pair
m.onAny(event, fn)	Handler for an event in every state
m.effect(state, { name, fn })	Run fn on state entry; name is required

Handlers return { state } (with optional payload or emit) to transition, or {} to stay put.