jakesgordon/javascript-state-machine

★ 8,751JavaScriptAudience · developerComplexity · 2/5LicenseSetup · easy

Mindmap

mindmap
  root((repo))
    Core concepts
      States
      Transitions
      Lifecycle hooks
    Hook types
      Before transition
      After transition
      On enter state
      On leave state
    Usage
      Browser script tag
      npm install
      Factory pattern
    Compatibility
      Node.js
      All browsers

mindmap root((repo)) Core concepts States Transitions Lifecycle hooks Hook types Before transition After transition On enter state On leave state Usage Browser script tag npm install Factory pattern Compatibility Node.js All browsers

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Model a multi-step checkout flow so your app always knows whether the user is in cart, address, payment, or confirmed state.

USE CASE 2

Build a traffic light or game character controller where state transitions are named and predictable.

USE CASE 3

Add lifecycle hooks to a form wizard so validation code runs automatically when the user leaves each step.

USE CASE 4

Create multiple independent instances of the same state machine for parallel workflows in a Node.js application.

Tech stack

JavaScriptNode.js

Getting it running

Difficulty · easy Time to first run · 5min

Use freely for any purpose including commercial projects as long as you keep the MIT copyright notice.

In plain English

A finite state machine is a pattern used in programming where a system can be in exactly one state at any given time, and it moves between states through named transitions. This library provides a simple way to define and run such machines in JavaScript, for both browsers and Node.js. You set up a machine by listing its possible states and the transitions between them. The example in the README models matter: the starting state is solid, and you define transitions like melt (solid to liquid), vaporize (liquid to gas), and condense (gas to liquid). Each transition becomes a method you can call directly on the machine object. The library also supports lifecycle events, which are functions that run automatically at particular points in a transition: before it starts, after it completes, when leaving a state, or when entering one. This makes it straightforward to attach side effects to state changes without scattering manual checks throughout your code. You can also store arbitrary data on the machine and attach custom methods alongside the state logic. Helper methods let you ask questions about the current state: whether a given transition is currently allowed, which transitions are possible from where you are, and what all the defined states or transitions are. A factory pattern is also available for creating multiple independent instances from the same definition. The library is available as an npm package or as a script tag in a browser page. The README notes that version 3.0 was a substantial rewrite from the 2.x series, so existing users should read the upgrade guide before updating. It is released under the MIT license.

Copy-paste prompts

Prompt 1

I have a checkout flow with states browsing, cart, checkout, payment, and confirmed. Using javascript-state-machine, model these states and the transitions between them, and add a lifecycle hook that logs each state change.

Prompt 2

Show me how to use javascript-state-machine to build a simple traffic light that cycles green, yellow, red with a timer, and prevents illegal transitions.

Prompt 3

I want to guard a transition in javascript-state-machine so it only proceeds if a condition is met. Walk me through using an onBefore lifecycle hook for this.

Prompt 4

How do I use the factory pattern in javascript-state-machine to create 10 independent instances of the same state machine definition for 10 concurrent users?

Open on GitHub → Explain another repo

← jakesgordon on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.