effect-state-machine

effect-state-machine is a code-first state-machine library for TypeScript applications built with Effect. A machine definition describes valid inputs, states, events, transitions, invoked Effects, timers, regions, and child machines as one immutable value. The same value can run through an explicit machine engine or project into a read-only graph for development tooling.

The library is intended for Effect users who want orchestration to remain visible in ordinary TypeScript. It assumes familiarity with Effect, Schema, Layer, and scoped resources.

Start here

Follow Build your first machine to create and run a small machine from an empty project. The tutorial covers the core loop: describe machine data with Schema, construct nodes, start a scoped machine instance, send events, and observe completion.

To see the browser devtools in action, open Explore an embedded Studio. It includes a live machine that you can inspect and dispatch from directly on the documentation page.

When you already know the result you need, use the how-to guides:

• Run an Effect when a state becomes active
• Model parallel regions
• Choose transitions with guards
• Retry invoked work
• Compose behavior with a child machine
• Observe a running machine
• Visualize a machine definition
• Run durable activities through Effect Workflow

For exact signatures and runtime constraints, use the reference:

• Machine API
• Machine engine API
• Machine store API
• Effect Workflow integration API
• Graph API
• Mermaid API
• Source-location API

For the design model and its trade-offs, read Why the library is Effect-native.

Installation

The current v0 release targets the Effect beta used to verify its semantics:

pnpm add effect-state-machine effect

The package is ESM, targets ES2022, and exposes the main API from effect-state-machine. Static graph tooling is also available from the opt-in effect-state-machine/devtools entry point.

What v0 models

A machine node has one visible behavior kind:

• an ordinary state with pure transitions and an optional entry-owned timer;
• invoked work with typed success and failure routes, including named all and race lanes;
• a region-bearing state with one compound or several parallel tagged-union slots;
• an invoked child machine with explicit event forwarding;
• a final state whose value becomes the machine completion value.

Machine instances serialize external events and asynchronous completions through one queue. Work owned by an invoked or child state is interrupted when the machine leaves that state.

Every machine runs through an explicit MachineEngine. The memory layer uses the same aggregate, mailbox, activity delivery, idempotency records, and absolute timer deadlines as persistent MachineStore adapters. External effects remain the application's responsibility; the library supplies stable work execution IDs for joining them to Effect Workflow or another durable task system.

V0 does not provide nested parent-state hierarchy, dynamic actors, visual editing, a bundled production Store, or application-framework bindings beyond the React Studio.