This site runs best with JavaScript enabled.Implementing a simple state machine library in JavaScript

Implementing a simple state machine library in JavaScript


Let's write a state machine abstraction together to understand it better

Watch "Implement a simple Finite State Machine library in JavaScript" on egghead.io

If you're like me, the first time you heard the words "state machine" you were a little intrigued and as you dove in deeper, you were more confused than when you started. I find that when I hit that situation, writing my own implementation of the concept helps solidify the concept for me. So that's what we're going to do together.

I'm not going to take time to try and explain state machines or their use cases, so you'll need to find other resources for that. Here I'm just going to go through what a simple state machine implementation might look like. I wouldn't recommend using this implementation in production. For that, check out xstate.

There's a brilliant website (statecharts.github.io by Erik Mogensen) where you can learn a lot about this concept called "State Charts." (A state chart is basically a state machine with a few additional characteristics and it's another thing I'd recommend learning about.) On that website, there's a page titled What is a state machine? where you can learn the fundamentals of what a state machine is and that's where we're going to gather the parameters (or requirements) for our own state machine implementation. Here are some of those (borrowed from the site):

  • One state is defined as the initial state. When a machine starts to execute, it automatically enters this state.
  • Each state can define actions that occur when a machine enters or exits that state. Actions will typically have side effects.
  • Each state can define events that trigger a transition.
  • A transition defines how a machine would react to the event, by exiting one state and entering another state.
  • A transition can define actions that occur when the transition happens. Actions will typically have side effects.

Also, "When an event happens:"

  • The event is checked against the current state’s transitions.
  • If a transition matches the event, that transition “happens”.
  • By virtue of a transition “happening”, states are exited, and entered and the relevant actions are performed
  • The machine immediately is in the new state, ready to process the next event.

Ok, so let's get started. Let's start with something simple. A toggle! Here's our initial code:

1function createMachine(stateMachineDefinition) {
2 const machine = {
3 // machine object
4 }
5 return machine
6}
7
8// here's how we'll create the state machine
9const machine = createMachine({
10 // state machine definition object here...
11})
12
13// here's how we use the state machine
14// comments are what we _want_ to have logged
15let state = machine.value
16console.log(`current state: ${state}`) // current state: off
17
18state = machine.transition(state, 'switch')
19console.log(`current state: ${state}`) // current state: on
20
21state = machine.transition(state, 'switch')
22console.log(`current state: ${state}`) // current state: off

The state machine definition object

We'll start by filling out our state machine definition object and then we can figure out how to make the state machine do what we want it to with that information (ADD: API Driven Development).

One state is defined as the initial state. When a machine starts to execute, it automatically enters this state.

Simple enough, we'll have the user provide us with what that initialState value should be:

1const machine = createMachine({
2 initialState: 'off',
3})

And we'll probably want to have a definition for our states as well:

1const machine = createMachine({
2 initialState: 'off',
3 off: {},
4 on: {},
5})

Ok, great. Onto the next:

Each state can define actions that occur when a machine enters or exits that state. Actions will typically have side effects.

So we need to allow the user to provide a function that will be called when on enter and on exit for a given state:

1const machine = createMachine({
2 initialState: 'off',
3 off: {
4 actions: {
5 onEnter() {},
6 onExit() {},
7 },
8 },
9 on: {
10 actions: {
11 onEnter() {},
12 onExit() {},
13 },
14 },
15})

And we'll add console.logs so we can check our work later.

1const machine = createMachine({
2 initialState: 'off',
3 off: {
4 actions: {
5 onEnter() {
6 console.log('off: onEnter')
7 },
8 onExit() {
9 console.log('off: onExit')
10 },
11 },
12 },
13 on: {
14 actions: {
15 onEnter() {
16 console.log('on: onEnter')
17 },
18 onExit() {
19 console.log('on: onExit')
20 },
21 },
22 },
23})

Ok, so now what's next?

Each state can define events that trigger a transition.

Alrighty, let's add a transitions property to our state definitions:

1const machine = createMachine({
2 initialState: 'off',
3 off: {
4 actions: {
5 onEnter() {
6 console.log('off: onEnter')
7 },
8 onExit() {
9 console.log('off: onExit')
10 },
11 },
12 transitions: {},
13 },
14 on: {
15 actions: {
16 onEnter() {
17 console.log('on: onEnter')
18 },
19 onExit() {
20 console.log('on: onExit')
21 },
22 },
23 transitions: {},
24 },
25})

The off state should be able to transition to the on state and we'll call that event "switch". Then the on state should be able to transition to the off state as well and it makes sense to call that "switch" as well, so let's add a switch property to our transitions object:

1const machine = createMachine({
2 initialState: 'off',
3 off: {
4 actions: {
5 onEnter() {
6 console.log('off: onEnter')
7 },
8 onExit() {
9 console.log('off: onExit')
10 },
11 },
12 transitions: {
13 switch: {},
14 },
15 },
16 on: {
17 actions: {
18 onEnter() {
19 console.log('on: onEnter')
20 },
21 onExit() {
22 console.log('on: onExit')
23 },
24 },
25 transitions: {
26 switch: {},
27 },
28 },
29})

Sweet. And the next one:

A transition defines how a machine would react to the event, by exiting one state and entering another state.

Ok, so I think that we can specify a target for our transition event and when that event comes around, our machine will transition us from the current state to the target state:

1const machine = createMachine({
2 initialState: 'off',
3 off: {
4 actions: {
5 onEnter() {
6 console.log('off: onEnter')
7 },
8 onExit() {
9 console.log('off: onExit')
10 },
11 },
12 transitions: {
13 switch: {
14 target: 'on',
15 },
16 },
17 },
18 on: {
19 actions: {
20 onEnter() {
21 console.log('on: onEnter')
22 },
23 onExit() {
24 console.log('on: onExit')
25 },
26 },
27 transitions: {
28 switch: {
29 target: 'off',
30 },
31 },
32 },
33})

Cool, so when our state machine is in the off state and we call machine.transition(state, 'switch') then it should transition from the off state to the on state. We'll implement that logic when we get to it, but so far our definition has everything we need for that to happen.

Alright, let's check out the last one for the definition:

A transition can define actions that occur when the transition happens. Actions will typically have side effects.

Based on that, our state enter/exit can have actions, and our transitions can have actions too. At first when I read this, I was confused because it felt like two ways to do the same thing, but if you remember that in more real-world state machines, there can be many ways to enter a state and maybe we want some side-effect to happen only when transitioning to state A from a specific state B but not from state C. So let's add an action to our transition objects (and we'll put a console.log in there to keep track of it later).

1const machine = createMachine({
2 initialState: 'off',
3 off: {
4 actions: {
5 onEnter() {
6 console.log('off: onEnter')
7 },
8 onExit() {
9 console.log('off: onExit')
10 },
11 },
12 transitions: {
13 switch: {
14 target: 'on',
15 action() {
16 console.log('transition action for "switch" in "off" state')
17 },
18 },
19 },
20 },
21 on: {
22 actions: {
23 onEnter() {
24 console.log('on: onEnter')
25 },
26 onExit() {
27 console.log('on: onExit')
28 },
29 },
30 transitions: {
31 switch: {
32 target: 'off',
33 action() {
34 console.log('transition action for "switch" in "on" state')
35 },
36 },
37 },
38 },
39})

Excellent. We've fleshed out the API for the state definition object. Now let's implement what happens when transition is called.

Handling transitions

When a user wants to create a machine, we've already specified this as the API:

1const machine = createMachine({
2 // state machine definition object
3})
4
5machine.value // current state
6machine.transition(currentState, eventName)

Technically, we could make our state machine default the current state to machine.value, but I like the idea of transition accepting the current state from the user (and this is what xstate does) so that's what we'll go with.

So here's what we need for our initial implementation of createMachine:

1function createMachine(stateMachineDefinition) {
2 const machine = {
3 // machine object
4 }
5 return machine
6}

Let's go ahead and add the value and transition properties:

1function createMachine(stateMachineDefinition) {
2 const machine = {
3 value: stateMachineDefinition.initialState,
4 transition(currentState, event) {
5 return machine.value
6 },
7 }
8 return machine
9}

Remember, currentState would be something like 'off' or 'on' in our case and event would be 'switch' for our toggle example.

Great, now let's go down the list and implement things one by one:

The event is checked against the current state’s transitions.

Alright, let's grab the transitions object and determine the destination transition.

1function createMachine(stateMachineDefinition) {
2 const machine = {
3 value: stateMachineDefinition.initialState,
4 transition(currentState, event) {
5 const currentStateDefinition = stateMachineDefinition[currentState]
6 const destinationTransition = currentStateDefinition.transitions[event]
7
8 return machine.value
9 },
10 }
11 return machine
12}

To be clear, the destinationTransition at this point for our off -> on transition would be:

1{
2 target: 'on',
3 action() {
4 console.log('transition action for "switch" in "off" state')
5 },
6}

So here we've successfully accessed the transition information for this currentState + event combo.

If a transition matches the event, that transition “happens”.

Ok, so if the user defined a transition from the current state with this event, then we'll continue, otherwise, we'll exit early:

1function createMachine(stateMachineDefinition) {
2 const machine = {
3 value: stateMachineDefinition.initialState,
4 transition(currentState, event) {
5 const currentStateDefinition = stateMachineDefinition[currentState]
6 const destinationTransition = currentStateDefinition.transitions[event]
7 if (!destinationTransition) {
8 return
9 }
10
11 return machine.value
12 },
13 }
14 return machine
15}

By virtue of a transition “happening”, states are exited, and entered and the relevant actions are performed

Ok, so we'll need to call the action for the transition, the onExit for the current state and the onEnter for the next state. To do that, we'll also need to get the destination state definition as well. Let's do all of that:

1function createMachine(stateMachineDefinition) {
2 const machine = {
3 value: stateMachineDefinition.initialState,
4 transition(currentState, event) {
5 const currentStateDefinition = stateMachineDefinition[currentState]
6 const destinationTransition = currentStateDefinition.transitions[event]
7 if (!destinationTransition) {
8 return
9 }
10 const destinationState = destinationTransition.target
11 const destinationStateDefinition =
12 stateMachineDefinition[destinationState]
13
14 destinationTransition.action()
15 currentStateDefinition.actions.onExit()
16 destinationStateDefinition.actions.onEnter()
17
18 return machine.value
19 },
20 }
21 return machine
22}

And finally:

The machine immediately is in the new state, ready to process the next event.

We've got to update the machine's value which is the target for the transition (which we've assigned to the destinationState variable):

1function createMachine(stateMachineDefinition) {
2 const machine = {
3 value: stateMachineDefinition.initialState,
4 transition(currentState, event) {
5 const currentStateDefinition = stateMachineDefinition[currentState]
6 const destinationTransition = currentStateDefinition.transitions[event]
7 if (!destinationTransition) {
8 return
9 }
10 const destinationState = destinationTransition.target
11 const destinationStateDefinition =
12 stateMachineDefinition[destinationState]
13
14 destinationTransition.action()
15 currentStateDefinition.actions.onExit()
16 destinationStateDefinition.actions.onEnter()
17
18 machine.value = destinationState
19
20 return machine.value
21 },
22 }
23 return machine
24}

All together

Alright, so here's the whole thing:

1function createMachine(stateMachineDefinition) {
2 const machine = {
3 value: stateMachineDefinition.initialState,
4 transition(currentState, event) {
5 const currentStateDefinition = stateMachineDefinition[currentState]
6 const destinationTransition = currentStateDefinition.transitions[event]
7 if (!destinationTransition) {
8 return
9 }
10 const destinationState = destinationTransition.target
11 const destinationStateDefinition =
12 stateMachineDefinition[destinationState]
13
14 destinationTransition.action()
15 currentStateDefinition.actions.onExit()
16 destinationStateDefinition.actions.onEnter()
17
18 machine.value = destinationState
19
20 return machine.value
21 },
22 }
23 return machine
24}
25
26const machine = createMachine({
27 initialState: 'off',
28 off: {
29 actions: {
30 onEnter() {
31 console.log('off: onEnter')
32 },
33 onExit() {
34 console.log('off: onExit')
35 },
36 },
37 transitions: {
38 switch: {
39 target: 'on',
40 action() {
41 console.log('transition action for "switch" in "off" state')
42 },
43 },
44 },
45 },
46 on: {
47 actions: {
48 onEnter() {
49 console.log('on: onEnter')
50 },
51 onExit() {
52 console.log('on: onExit')
53 },
54 },
55 transitions: {
56 switch: {
57 target: 'off',
58 action() {
59 console.log('transition action for "switch" in "on" state')
60 },
61 },
62 },
63 },
64})
65
66let state = machine.value
67console.log(`current state: ${state}`)
68state = machine.transition(state, 'switch')
69console.log(`current state: ${state}`)
70state = machine.transition(state, 'switch')
71console.log(`current state: ${state}`)

And if you were to pop that up in your Chrome DevTools, here are the logs you'd get:

1current state: off
2transition action for "switch" in "off" state
3off: onExit
4on: onEnter
5current state: on
6transition action for "switch" in "on" state
7on: onExit
8off: onEnter
9current state: off

And you can play around with this in codesandbox.

I hope you found that interesting, informative, and entertaining. If you're really like to dive into this stuff further, then definitely give statecharts.github.io a look and give David Khourshid a follow. He's on a personal mission to make state machines more approachable and is responsible for my own interest in the concept.

Good luck!

Discuss on TwitterEdit post on GitHub

Share article
loading relevant upcoming workshops...
Kent C. Dodds

Kent C. Dodds is a JavaScript software engineer and teacher. He's taught hundreds of thousands of people how to make the world a better place with quality software development tools and practices. He lives with his wife and four kids in Utah.