Introduction

What is StateWalker FSM?

StateWalker FSM is a small TypeScript library for building event-driven logic as finite state machines. Instead of scattering behaviour across boolean flags and conditional statements, you describe your process as a set of states and the transitions between them. When a user logs in, the machine moves from LoggedOut to LoggingIn, then to LoggedIn. When a form is submitted, it transitions from Validating to either ShowingErrors or Submitting. Every behaviour becomes an explicit transition rather than an implicit side effect.

The whole machine is one plain object. You can see the entire flow in the configuration, test states in isolation, and add features by extending the state graph rather than weaving new conditions into existing code. The same definition runs anywhere JavaScript runs.

Why hierarchical?

Real processes rarely fit a flat list of states. A checkout has states, but so does the payment step nested inside it. StateWalker states are hierarchical: a state can contain its own child states with their own transitions. Entering a composite state automatically descends into its initial child; an event a child doesn’t handle bubbles up to the parent. This mirrors how you already think about processes — a big phase made of smaller ones — and keeps each level’s transition table small and local.

Key features

Hierarchical states. Nest states to any depth. The engine handles descending into initial children and bubbling unhandled events up the parent chain, so each state only declares the transitions between its own direct children.

Zero dependencies. The whole library is a single bundled entry with no runtime dependencies, so it can sit at the core of a larger system without pulling weight.

Universal JavaScript. One machine definition runs in Node.js, Bun, Deno, and the browser. Run business logic server-side without a DOM; add a UI in the browser.

Pause and resume. The complete machine — its stack of active states and the per-state data you record — can be dumped to a plain object and restored later, so a running process can be persisted and resumed.

Two altitudes. Drive the machine directly with the FsmProcess engine when you want full control, or let the startProcess runner attach per-state behaviour for you. Both ship in the same package.

Get started

Add StateWalker to your project, then build your first machine in a few minutes.

Installation — add @statewalker/fsm to your project.

Quick Start — build a working state machine from scratch.

Once you have the basics, read States, Events & Transitions to understand the model in depth.