@statewalker/fsm
Hierarchical Finite State Machines for TypeScript
A tiny, zero-dependency library for modelling event-driven behaviour as a tree of nested states. Declare your states and the transitions between them, attach behaviour to each state, and drive the machine with events — the same definition runs in the browser, Node.js, Bun, and Deno.
npm install @statewalker/fsm
Event-driven control flow — UI wizards, connection lifecycles, long-running workflows — is painful to express with ad-hoc booleans and callbacks. StateWalker lets you write that flow declaratively as a nested state tree and hands the hard parts to the engine: descending into sub-states, bubbling unhandled events up to a parent, running enter/exit hooks in the right order, and serializing the whole machine so a process can be paused, persisted, and resumed.
The library gives you two layers — pick your altitude:
- The FsmProcess engine is the low-level machine you drive by hand with
dispatch(event)and lifecycle hooks. Use it when you want full control. - The startProcess runner is an ergonomic wrapper that attaches per-state handlers through a single
loadcallback and binds the machine into a shared context object. Most consumers use this.
Both live in the single @statewalker/fsm package — no runtime dependencies, no build step required.