Statecharts are a formalism for modeling stateful, reactive systems. This is useful for declaratively describing the behavior of your application, from the individual components to the overall application logic.

xstate

JavaScript® (often shortened to JS) is a lightweight, interpreted, object-oriented language with first-class functions, most known as the scripting language for Web pages, but used in many non-browser environments as well such as node.js or Apache CouchDB. It is a prototype-based, multi-paradigm scripting language that is dynamic, and supports object-oriented, imperative, and functional programming styles.

javascript

The difficulty of managing state is one of the primary reasons our applications become so complex. We try and manage this complexity with a lot of booleans, somewhat semantic variables like `isLoading`, `wasFetched`, and `hasError`, and over-engineered systems that are _still_ full of bugs. Surely, there's a better way.

That better way is *state machines*.

State machines formalize how we define and transition through the states of our application and give us ultimate control of the most complex parts of our apps.

In this course, we will explore the problems state machines purport to solve, like boolean explosion. We'll try to solve it our own way first, get so far, and then demonstrate how state machines get us all the way. After that, we'll dive into the XState library, JavaScript's premiere state machine library, to learn its API and how to use it to solve our problems.

By the time you're done taking this course, you should have a solid education about state machines and be able to start applying them.

Maxime Bourgeois

Taylor Bell: Hey Kyle, thanks for joining me today.Kyle Shevlin: Hey Taylor. Thanks for having me on.Taylor Bell: Yeah, so I wanted to talk to you about your new course, it's an introduction to state machines and ex state. And so what is a state machine?Kyle Shevlin: A state machine is a data structure that essentially allows us to enumerate all the possible states of a system and all the transitions between those states. It's a declarative way of making your state a graph. And I know that's a big computer science term to some degree, but it's a really robust way to define how we move from state to state in a program.Taylor Bell: Cool. And so how'd you get interested in state machines?Kyle Shevlin: Yeah, I listened to David [inaudible 00:00:44], often more better known as David K Piano on Twitter. His, talk at React Rally in 2017 was my first introduction to it. And during that talk, I just remember some light bulbs going off on my head. You know, I've been given designs from designers for years and never put it together that each of these is in finite individual state.Kyle Shevlin: And then just over the last few years I kind of tinkered with it and I really wanted to finally sit down and get to know it. And what better way to do that than to like choose it as a course material and bust your butt and learn it and share it.Taylor Bell: Cool. And so when somebody takes the course, what's like the journey that you take them on? Like what happens in the course?Kyle Shevlin: Yeah, so I start off with a function that just represents a simple light bulb. And the reason I do that is we quickly realize a light bulb isn't actually a boolean. It has more than two states. It's not just on or off. A light bulb can be broken. And as soon as we start trying to accommodate for the fact that a light bulb can be broken, we get into this place where we might have impossible states, we might have our function lead us to a place where the light bulb is both lit and broken. And we know that can't happen.Kyle Shevlin: And this happens all the time in our code, we write these booleans to try and control state or we manage state in some way and we're doing all these conditional checks when really what we're doing is trying to avoid states that shouldn't even be possible in the first place. So doesn't it make sense to instead enumerate only the possible states? So the next lesson teaches how do you do that? How do you just enumerate states? And you know, I write a function with a switch case that moves us from a lit to unlit or lit to broken but never to an impossible state.Kyle Shevlin: And you know, that could work in a lot of situations, but if you had something particularly complex that you were working on in a program or an app, it wouldn't scale super well. Like you'd have to rewrite this every time. You'd have to think about this every time state machines and the X state library itself comes in and gives us a structured and defined way to enumerate states and those transitions how to fire events to this machine. And you'll start to learn these patterns as you go through the course. That will show you how to do this over and over again and really kind of come up with a solid way to declaratively manage state throughout your programs. And I keep saying programs because I think in our world and JavaScript we so often think about state only as like maybe a couple of variables we're keeping in a function, you know, but it can really be as small as like a function that might have several states who are returning. Or it can be as big as a whole system in your application that you're controlling.Kyle Shevlin: Part of the lessons eventually show a little bit of how to compose those things together. Not really an intro level thing. I plan to make more material and, and release it as like a playlist eventually to do some of that. But I think the intro is more than enough to give people the education they need to get started and probably frankly learn a lot of that stuff on their own. They'll be well prepared for that.Taylor Bell: Cool. So do you have any specific next steps that somebody should take after your course?Kyle Shevlin: Sure. When they finish the course, I would recommend, you know, it's probably a good idea to go check out the docs themselves. You know, I've read through them several times. There's several gotchas in there that I go over a few in the course but would be worthwhile to make sure yourself. Like one of the ones I cover for example is that there's this concept of context in X state.Kyle Shevlin: It's how they deal with infinite states. And it might be confusing how you update that context the first time you do it. If you're trying to do it in some kind of sequence and you don't understand what's going on under the hood. I go over that in a lesson. But reading the docs would help. They also just released 4.7 which has a few new things that I wasn't able to cover in the course. Things like wildcard descriptors and better type systems for using it with TypeScript and that kind of stuff.Kyle Shevlin: So yeah, I think it's definitely worth checking out. You know, and I think I put in the repo, like a link to a code sandbox that has like a little starter thing. You know, if you feel like doing it, start playing around with it and give it a try.Taylor Bell: Cool. Well thanks so much for joining me today and looking forward to checking it out.Kyle Shevlin: Thank you.

Welcome to my introductory course on State Machines and the XState library. This course is roughly broken down into three parts.

In the first part, we'll explore the problem state machines set out to solve. We'll take a problematic function, iterate over it until we understand where state machines come in and save the day.

In the second part, we'll learn all the fundamental concepts of the XState library: machines, interpreters, states, events, actions, context and guards. This will be a solid foundation for starting to use XState on your own.

In the final part, we'll explore more advanced uses of the XState library: hierarchical, parallel and history states, and invoking services such as promises, callbacks and other machines.

My hope is that course teaches you what you need to get started with state machines in your work today.

Thank you for watching and enjoy the course.

Course Intro and Overview

Intro to XState Enhanced Transcript PDF

Sketch Notes

There are several fundamental problems with trying to manage the state of a function through the use of booleans. The first is often referred to as "boolean explosion". For every boolean we add to a function, we increase the number of possible states at a rate of `2^n` where `n` is the number of booleans. Running the math just a few times quickly reveals an absurd amount of states.

The second problem is that many of these states are "impossible states", states our application should never be in. The example in the lesson is that the light bulb should not be `isLit` and `isBroken`. It's simply not possible, and is an inaccurate modeling of an actual light bulb.

The way we solve for this problem is by enumerating the possible states. In other lessons in this course, we'll do that with state machines, but for now, we'll do that by enumerating the possible states and updating our function to only utilize these possible states.

Eliminate Boolean Explosion by Enumerating States

Enumerating the possible states of a function is a sound way to write a function, but it is imperative and could benefit from abstraction. We can do this with a state machine.

A state machine formalizes how we enumerate states and transitions. For the sake of clarity and to emphasize the core concepts, I will be overly verbose with my code in this lesson.

In this lesson, we'll replace the state enum with individual state objects. We'll also replace our events `toggle()` and `break()` with events `TOGGLE` and `BREAK`. I'll also demonstrate the usefulness of the Machine's `initialState` getter and the `transition` method. Lastly, I'll show what happens when we pass erroneous states or events into our machine.

Replace Enumerated States with a State Machine

While it's powerful enough to have `Machine.transition`, it can get tedious constantly passing it a state and an event. It would be nice if we had a function that could take a machine, instantiate it, maintain the state of the machine, and give us the ability to send events to it.

This is where an interpreter comes in handy.

And interpreter takes the abstract machine and brings it to life. XState provides us a function, `interpret`, to do this. `interpret` returns to us a service and we can use that service to send events, subscribe to changes, and add callbacks to events such as `onTransition`

Use an Interpreter to Instantiate a Machine

XState Viz is an online tool for visualizing our state machines. It allows you to write any state machine in the code panel on the right, and see it visualized on the left. Not only is the visualization helpful, but it is interactive. We're able to test out our machine manually by clicking the various events on the left. Anything lit blue is available for clicking. As we go further in the course, we'll discover other features of the visualization.

Use XState Viz to Visually Develop and Test Your Machine

Actions are "fire-and-forget" side effects that are triggered by transitions. We set functions on a transition object's `actions` property to have them called when a transition is taken.

```javascript
//...
EVENT_NAME: {
  target: 'name-of-state-to-transition-to',
  actions: [(context, event) => { sideEffectToFire(context, event) }]
}
//...
```

Add Actions to Transitions to Fire Side Effects

Actions aren't limited to being called on transitions. They can also be called when we enter or exit a state node. This is done through the `entry` and `exit` properties.

The API for `entry` and `exit` actions is the same as that for `actions` on transitions. It can receive a single function or an array of functions, each which will be called with the next `context` and the `event` object that caused the transition.

This is a powerful way to fire side effects based on states rather than transitions.

```javascript
//...
states: {
  broken: {
    entry: [
      (context, event) => {
        sideEffectToFireWhenWeEnterTheBrokenState(context, event)
      }
    ],
    exit: [
      (context, event) => {
        sideEffectToFireWhenWeExitTheBrokenState(context, event)
      }
    ]
  }
}
```

Trigger Actions When Entering and Exiting a XState State

It is considered best practice to use the string shorthand for actions, guards, and more when configuring an XState `Machine`. We do this by providing a second argument to the `Machine` factory function: the `options` object.

On this object, we can define our actions, guards, activities, services and more. We then refer to the name of these functions with a string of the same name.

```javascript
//...
broken: {
  entry: ['logBroken']
}
//...
// In the options object
{
  actions: {
    logBroken: (context, event) => { console.log('yo I am broke') }
  }
}
```

Replace Inline Functions with String Shorthands

Transitions come in two varieties: "external" and "internal". By default, a transition is considered external. This means that a transition will _exit_ the current state node, and _enter_ the next state node (even if that state node is the state the machine is currently in). This exit/enter loop will trigger any actions that are set on the `exit` and `entry` properties.

A transition can be set to internal, either through setting a `.` (dot) in front of the state node name (as we do in this lesson), or through setting the property `internal` to `true` on the transition object.

When a transition is internal, it will not exit and enter the state node, which means that the actions in the `exit/transition/entry` loop will not be called.

Use Internal Transitions in XState to Avoid State Exit and Re-Entry

XState provides the `send` function to create an action that will send the event passed in to the machine. If we provide the second argument to the `send` function, the `options` object, we can send the event `to` a particular machine. This is useful when you have invoked a machine as a service on a state node, a concept that will be explored in a later lesson.

Send Events to the Machine with the XState Send Action Creator

Consider a text input. It would be impossible for anyone to model every value you could possibly put into it, because the number of possible values is infinite. This is an infinite state.

Infinite state can be tracked and utilized by XState machines as "extended state". This extended state is called `context`. Context is passed to every function that is triggered by the machine: actions, activities, guards, and more.

In this lesson we learn how to set `context` and update it through `assign` actions.

Track Infinite States with with XState Context

While the order of actions in XState is fairly clear, how `assign`s are handled in them is non-obvious.

If you have a scenario where you try and utilize `context` in one action, then `assign` a new value to `context`, and _then_ try and utilize the new context in another action, you'll find that actually _both_ actions received the new `context` as their argument. Why does this happen?

This happens because `XState.Machine.transition` is a pure function. In order to remain pure, it does not run the actions, it accumulates them into an `actions` array that is returned in the next state object. Since `transition` does not run any side effects, it must calculate the next `context` object and return this on the state object as well. Thus, any action returned is then called in the interpreter with the next context, _not the context assumed to exist at the time and order the action was written_.

How Action Order Affects Assigns to Context in a XState Machine

Activities are continuous, ongoing side effects that are triggered by entering a particular state, and only stop when that state is exited. In the example in this lesson, we have an alarm clock machine that does the activity of beeping for the duration of the `alarming` state.

Activities are a function that receives `context` and the `event` object (just like actions). They fire off the ongoing side effect in the body of the function, and optionally return a function that performs any cleanup necessary for the activity.

```javascript
{
  activities: {
    beeping: (context, event) => {
      const beep = () => {
        console.log('beep!')
      }

      beep()
      const interval = setInterval(beep, 1000)

      return () => { clearInterval(interval) }
    }
  }
}
```

Use Activities in XState to Run Ongoing Side Effects

Not all transitions should be taken immediately. Occasionally, we would like to conditionally take a transition. We do this through the use of "guards". A "guard" is a predicate function (a function that returns a boolean) that is set on a transition object's `cond` property (short for "conditional").

When an event is sent to the machine and it encounters a transition object with a `cond` property set to a guard function, it will call that function with the current `context` and `event` object. If the guard returns `true`, the transition will be taken, otherwise, it will attempt the next transition for the event, or remain in the current state.

```javascript
//...
EVENT_NAME: {
  target: 'state-name-of-transition-target',
  cond: (context, event) => predicateFunction(context, event)
}
```

Conditionally Transition to States with Guards in XState

As our state machines grow more complex, we might find ourselves in a situation where a state should only exist if the machine is already in another state. To do this, we can use hierarchical states.

Instead of attempting to define all the states of a machine at a top level, we can nest states that should only be available as children of a parent state. These substates are written _exactly_ like the states of the top level of a machine: with an `initial` property, and the `states` of the nested state graph.

Using hierarchical states is a great way to avoid needing to check for booleans in an application. If a state can only exist when another state exists, consider if the one isn't in fact a child of the other.

Simplify State Explosion in XState through Hierarchical States

Can you walk and talk at the same time? If so, you've experienced what it's like to be in two states at the same time. Hopefully, those two states have no influence on the other. Whether or not you talk, you can walk, and vice versa. States that occur concurrently and have no affect on the other are known as "parallel states".

Parallel states happen simultaneously. The machine is in _all_ of the parallel states at the same time. To create a parallel state node, we set the `type` to `'parallel'` and then remove the `initial` state. There's no need for an `initial` property when you're in all the child states at the same time.

Multiple Simultaneous States with Parallel States

Generally speaking, state machines do not and should not have a sense of _time_. They are intended to be pure functions that receive a state and event and return the next state. Pure functions by design have no sense of _history_.

Yet, it is occasionally useful to return to a previous state. How is this accomplished? With history state nodes. Each state object returned by XState contains a special property that points to the previous state. When a history state node is defined and is the target of a transition, the machine returns to this previously stored state.

We can create a history node by defining the `type` as `history`, and setting the `history` property to either `shallow` (the default) or `deep`.

Recall Previous States with XState History States Nodes

It is often useful to identify conditional branching in your machine as a state itself. A state that is designed to determine the next state does not need a specific event sent to trigger the transition. Instead, we can use the "null event" to trigger an immediate, transient transition.

The null event is identified with an event name of an empty string `''`, and is immediately sent to the state upon entry. We can setup multiple targets with conditionals, or fire off actions to set up a future state with this transient transitions.

Use XState Null Events and Transient Transitions to Immediately Transition States

The passing of time can be represented as an event in XState. Rather than requiring the user to send an event after an amount of time has passed, XState provides the `after` property.

The value of `after` is an object whose keys are the milliseconds that should pass before a transition is taken. Consider a stop light transitioning from yellow to red after three seconds:

```javascript
//...
yellow: {
  after: { 3000: 'red' }
},
red: {
  //...
}
//...
```

We can also create dynamic delays with expressions using the `options` object as the second argument to `Machine`. This is also demonstrated in the lesson.

Delay XState Events and Transitions

Unbeknownst to many, promises are state machines. They exist in either an `idle`, `pending`, `resolved` or `rejected` state. Because they can be modeled as state machines, we can invoke them when we enter a state in a `Machine`.

We invoke services such as a promise by using the `invoke` property on a state node. When the state is entered, the `src` of the `invoke` object is called. In the case of promises, the `Promise` is called. When the `Promise` resolves, the `onDone` transition is taken. When the `Promise` rejects, the `onError` transition is taken. In either case, the data returned from the promise, whether resolved or errored, is passed back on the event object as `event.data`.

Invoking a Promise for Asynchronous State Transitions in XState

We can invoke a callback as a service when we enter a state in XState. This gives us the ability to trigger various functionality by responding to events sent to the service, and allows us to send events _back_ to the parent machine.

We do this by writing a "callback handler" and setting it as the `src` of our invoked service. A callback handler is a function that receives the current `context` and the `event` object that triggered the invocation. This function returns another function that receives two functions as arguments. A `callback` function to send events to the parent machine, and an `onEvent` function for the handler to respond to events sent to the handler.

The way events are sent to the callback handler is by utilizing the `options` argument of the `send` action creator. We identify where we send events to using the `to` property, and setting the value to the `id` of our service.

Invoke Callbacks to Send and Receive Events from a Parent XState Machine

Trying to structure the state logic of an application as a single machine can begin to become unwieldy when we have too many states. It is often better to divide our app into smaller machines and invoke those machines as necessary.

When we enter a state in a machine, we can invoke a child machine. This machine can send and receive events from the parent. When the child machine reaches a final state, the `onDone` transition is taken by the parent's current state node.

To invoke a child machine, we use the `invoke` property and set the `src` property to a machine. We can forward events in the parent machine to the child machine by setting the property `autoForwards` to `true`. We can also send events to the child machine through setting the second argument of the `send()` function to `{ to: 'child-machine-id' }`.

The child machine can send events to the parent machine by using the `sendParent` function. In this way, parent and child machines can communicate.

Introduction to State Machines Using XState

Kyle Shevlin

Free Community Resource

What you'll learn:

Prerequisites:

Credits

Free Community Resource

Course Content