Forem: Mikey Stengel

The most elegant debounce code you'll ever write featuring XState

Mikey Stengel — Wed, 19 Feb 2020 02:25:00 +0000

Debouncing is the practice of delaying the execution of a resource or time-intensive task long enough to make the application feel very responsive. This is typically done by reducing the number of times the task is executed.

Whether you're filtering a giant list or simply want to wait a few seconds until the user has stopped typing before sending a request, chances are that you'll have to deal with debouncing one way or another especially if you happen to be a front end engineer.

I claim that handling this with the popular state management, state machine and statechart library XState is as good as it can get. Before you can convince yourself, let's quickly determine the best possible debounce user experience before translating it into code.

Good debounce logic should:

give users instant feedback about what they're doing. We might want to wait a second before sending a request to the server but we do not ever want to delay the input of the user by a second as they'll either think our app is broken or their computer is lagging.
have a way to cancel the resource-intensive action. Not only do we want to cancel it when the user makes another keystroke before our debounce timer has finished, but we also want the ability to cancel the queued action when changing state. For example, there is no point in filtering a giant list when we've already transitioned into a state that doesn't show the list anymore.
allow us to set the timed delay dynamically. This could allow us to make the delay longer for mobile users as the average typing speed decreases.

With our optimal user experience out of the way, let's dive into the code.

Check out the codesandbox and read below for detailed explanations.

Let's write an app that displays tasty plants with the ability to filter them.

Since there are soo many tasty plants, we are expecting the server to take quite a long time. Therefore, we'll need to debounce the user input before the server starts filtering.

const tastyPlants = [
  "seeds 🌱",
  "mushrooms 🍄",
  "nuts 🥜",
  "broccoli 🥦",
  "leafy greens🥬"
];

// For the extended state of the machine, we want to store the user input and the plants to render.
const machineContext = {
  input: "",
  filteredTastyPlants: []
};

In other words, we don't want to send a server request on every keystroke; instead, we want to add a minor delay of 450 milliseconds. Also, instead of using an actual HTTP request, we are going to keep things local and just use a timeout.

The code that is responsible for performing the (fake) slow filter operation might look like this:

If you're new to asynchronous code in statecharts, you may want to check out this blog post before understanding what's going on below.

// inside our machine
apiClient: {
  initial: "idle",
  on: {
    slowFilter: {
      target: ".filtering"
    }
  },
  states: {
    idle: {},
    filtering: {
      invoke: {
        id: "long-filter-operation",
        src: (context, event) =>
          new Promise(resolve =>
            setTimeout(
              () =>
                resolve(
                  tastyPlants.filter(plant => plant.includes(context.input))
                ),
              1500
            )
          ),
        onDone: {
          target: "idle",
          actions: assign({
            filteredTastyPlants: (context, event) => event.data
          })
        }
      }
    }
  }
},

We aren't doing anything special here just yet. We pretend that our server takes 1500 milliseconds until it completes the filtering and upon resolving, we can ultimately assign the filtered plants to our filteredTastyPlants context.

You might have noticed that within the slowFilter event, we haven't actually assigned the input to the state machine yet. As you'll see shortly, the trick to make debouncing work in XState is to use two events instead of one.

Responsiveness

For instant feedback, which was our very first constraint, we'll define an extra event that assigns the input to the machine context. This event will also have the responsibility of sending the slowFilter event after a delay of 450ms. That's right. A machine can send events to itself. Let's see it in action(s)!

// import { actions, assign } from 'xstate'
// const { send } = actions

// within our machine
on: {
  filter: {
    actions: [
      assign({
        input: (context, event) => event.input
      }),
      send("slowFilter", {
        delay: 450,
      });
    ];
  }
}

The above code guarantees that the slowFilter event is called 450ms after every keystroke. Cool! In our component, we treat the slowFilter event like an internal event of the machine, meaning we'll only ever work with the filter event as seen in the example below.

const [state, send] = useMachine(filterPlantsMachine).

return (
  <input value={state.context.input} onChange={(e) => void send({type: 'filter', input: e.target.value})}>
  // render state.context.filteredTastyPlants
)

Cancellation

To work towards our second constraint, we now need a way to cancel the slowFilter event that is about to be sent. We can do so by giving the event an id, then canceling the event by the same id using the cancel action creator.

// import { actions, assign } from 'xstate'
// const { send, cancel } = actions

// within our machine
on: {
  filter: {
    actions: [
      assign({
        input: (context, event) => event.input
      }),
      cancel('debounced-filter'),
      send("slowFilter", {
        delay: 450,
        id: "debounced-filter"
      });
    ];
  }
}

Because the above code cancels and resends the event on every keystroke, it'll only be sent once the user has stopped typing for at least 450ms. Pretty elegant right? For even better readability, we can expressively name the actions.

on: {
  filter: {
    actions: [
      'assignInput',
      'cancelSlowFilterEvent',
      'sendSlowFilterEventAfterDelay' 
    ];
  }
}
// ...
// pass actions as config to the second argument of the Machine({}, {/* config goes here */}) function.
{
  actions: {
    assignInput: assign({
      input: (context, event) => event.input,
    }),
    cancelSlowFilterEvent: cancel('debounced-filter'),
    sendSlowFilterEventAfterDelay: send('slowFilter', {
      delay: 450,
      id: 'debounced-filter',
    }),
  },
}

Dynamically set debounce delay

Last but not least, to provide the best possible user experience we may want to dynamically change the delay. To account for the typing speed decrease in words per minute when going from desktop to phone, let's only start the filtering 800ms after the last keystroke when the user is on their phone.

After adding an isPhone boolean to our context (we could also pass it via the event), we can use a delay expression to dynamically set the delay.

sendSlowFilterEventAfterDelay: send('slowFilter', {
  delay: (context, event) => context.isPhone ? 800 : 450,
  id: 'debounced-filter',
}),

Let me know in the comments what you think and if you have any questions. Happy debouncing! ❤️

State machine advent: Everything you need to master statecharts (24/24)

Mikey Stengel — Tue, 24 Dec 2019 20:51:16 +0000

1. Use TypeScript

Even though state machines help us eliminate lots of bugs, there can still be type errors that are difficult to catch on your own. The type definition of XState is really good. As a result, you do not only get amazing IntelliSense and autocompletion, TypeScript will shout at you whenever your machine definition is not in line with the types you created.

Another reason why I encourage everyone to use TypeScript is the fact that the types are being declared outside of the machine definition, making the machine code easy to read even for people without extensive TypeScript knowledge. I made a conscious decision to use TypeScript in most posts throughout the series and you'll find that when we got to implement the machines, all we need to do is to pass the context type, the state schema, and possible events to the Machine factory function. From that point, we don't have to worry about the types anymore.

const gameMachine = Machine<GameContext, GameStateSchema, GameEvent>({
  /**
   * Almost no types will be found in here
   */
})

2. UI is a function of state, make it explicit!

Without statecharts, our business logic is spread throughout the application and states are a fuzzy mess of interdependent booleans.

If we were to render todos in an app that doesn't use deterministic states, the code might look like the following.

{ !isLoading && !hasErrors && todos.length > 0 && (
  <ul>
    {todos.map((todo, index) => <li key={index}>{todo}</li>)}
  </ul>
  )
}

Going to state machines with a state structure like the following

interface TodoStateSchema {
  states: {
    idle: {};
    loading: {};
    error: {};
    hasLoaded: {};
  }
}

interface TodoContext {
  todos: string[];
}

We might be tempted to refactor our code from above to something like the one below.

{ state.matches('hasLoaded') && state.context.todos.length > 0 && (
  <ul>
    {todos.map((todo, index) => <li key={index}>{todo}</li>)}
  </ul>
  )
}

As we can see, we have eliminated the boolean variables and got rid of impossible states in the process (e.g isLoading and hasError being true at the same time). However, I want to point out that at times it can be better to distinctively express UI states with declarative state nodes.

We can move the conditional logic from our component to state machines by adding deeper state nodes,

interface TodoStateSchema {
  states: {
    idle: {};
    loading: {};
    error: {};
    hasLoaded: {
      states: {
        noTodos: {};
        todos: {};
      };
    },
  }
}

or by refactoring to an orthogonal state structure (request and has are parallel state nodes).

interface TodoStateSchema {
  states: {
    request: {
      states: {
        idle: {};
        loading: {};
        error: {};
        hasLoaded: {};
      };
    };
    has: {
      states: {
        noTodos: {};
        todos: {};
      };
    };
  }
}

Then we can determine the state of the machine like so:

{ state.matches({has: 'todos'}) && (
  <ul>
    {todos.map((todo, index) => <li key={index}>{todo}</li>)}
  </ul>
  )
}

Using typestates which we didn't get to cover in the series, one can even enforce the condition that the machine must always have a non-empty array of todos inside the context before transitioning into the has.todos state.

The takeaway from this is to not be afraid to express your UI with distinct state nodes. When doing so, also don't be discouraged if certain state nodes sound weird in isolation. This is completely normal and happens usually with state nodes higher in the hierarchy (e.g has). The leaf state nodes or the combination of parent-child nodes are the ones that count.

Generally speaking, the more conditional logic you can move into your machine, the fewer bugs your application will have.

3. Visual Studio Code tooling

If you are using anything other than Visual Studio Code, feel free to add the extension name or config option of the editor you are using into the comments

The first thing you'd want to install is an extension that colors your brackets. Since most of our logic is defined within the JSON machine definition, we'd want to make sure that besides indentation, a visual clue can help us to maneuver between state nodes, events, guards and any other code we put into our machines. I'm using the Bracket Pair Colorizer 2 extension but have seen that some people experienced some performance issues when installing it in VSCode. Should you get hit by a significant performance penalty, try another extension that does the same thing and let us know.

Secondly, there is a command to jump the cursor from a closing bracket to the matching opening one and vice versa. This has saved me hours in finding the end of my state nodes and events. Below, you can see the default keybinding for the editor.action.jumpToBracket command. Feel free to bind it to a key that you can reach more easily. I personally settled on F3.

{
  "key": "ctrl+m",
  "command": "editor.action.jumpToBracket",
  "when": "editorFocus"
}

4. Chrome extension

Install the XState DevTools extension by @amitnovick and ensure to enable the visualization for your machines.

const [state, send] = useMachine(someMachine, { devTools: true})

5. Prototype using the visualizer

Always start with defining the state structure of your statecharts. Think about what kind of responsibility every machine should have and how you could wire them to other machines using the actor model. I found that it is always a good idea to start modeling on paper and have recently bought a whiteboard for the same reason. When you go to the prototyping phase, use the visualizer that is also being used in the chrome extension to ensure you are not missing any transitions or states. Visual debugging is so good, you'll never want to go back to code that can't be visualized.

My workflow of writing a new state machine/statechart mostly follows the following steps:

Brainstorming about possible states
Define state schema in TypeScript
Implement blueprint of machines with states and possible transitions
Visualize and iterate over 1-3
Implement machines and wire them together with other existing actors
Wire the machine to our UI

6. Consume resources

Throughout the past 24 days, we've learned a lot of XState concepts and despite my attempt to explain multiple concepts on any given day, we didn't get to cover every feature of XState. In particular, model-based testing, more actor communication and activities are things that I haven't written about. I highly encourage you to read through the whole documentation start to finish to get a firm grasp on what is feasible with statecharts.

I haven't explored everything XState has to offer (e.g model-based testing) just yet. Once I do, I'd love to blog about it as I had a lot of fun writing the posts for this series.

Here are some of the best resources to learn more about statecharts and state machines:

David Khourshid known as @DavidKPiano on social media is the creator of XState. I'm very thankful for his relentless work on XState and believe it will have the greatest positive impact on the future of web apps. Because of this and the fact that I've gotten a much better developer by watching his public talks and the keyframer videocast, he is one of the people I look up to the most.
"World of Statecharts" wiki
Spectrum community

This is not an exhaustive list. Is there anything you think I should add? Let me know in the comments.

Thank you for reading the state machine/statechart series. I would love your feedback on Twitter or Telegram (@codingdive) as they were the first 25 blog posts I've ever written.

If you are interested in improving yourself and reaching your potential, I have built an ai life coach & accountability partner, Zoe.

State machine advent: Accessing private actor state in components (23/24)

Mikey Stengel — Mon, 23 Dec 2019 22:55:41 +0000

Yesterday, we saw how to use the actor model to create hierarchy in applications and how to treat every actor as a computational unit that encapsulates behavior. Further, we established how actors have private state that can only be accessed from other actors using explicit communication (events). To build user interfaces, however, we do oftentimes want to access the private state of actors and render them to our UI. Today, we want to build a React component that renders the context of the Player actor.

Oftentimes, we can just mimic our actor architecture with React components. As a result, we can have a Game component that invokes the gameMachine and renders a Player component to display the action (Rock, Paper, Scissors) the player performed. Meanwhile, the gameMachine is a parent itself because it invokes the player actor. Essentially, recreating the same hierarchy and relationships between components that we first defined within our machines.

We can iterate through the array that holds the references to the player actor and pass them to the child component as props which can then deal with them in two different ways as we'll see in a minute.

import { useMachine } from '@xstate/react';
import React, { Fragment } from 'react';
import { Player } from './Player';

const Game = () => {
  const [state, send] = useMachine(gameMachine)

  return (
    <div>
      {state.context.playerRefs.map((playerRef, index) => (
        <Fragment key={index}>
          <Player playerRef={playerRef} />
        </Fragment>
      ))}
    </div>
  )
}

Once we define the Player component, we have a decision to make. Do we only want to access the actor so that we can receive and send events to it or do we want to access its private state? Although not the goal for today, for the former option, we should go with the useActor hook from the @xstate/react package.

When using this hook, state does not hold the context property since the actor state is private. Nonetheless, we could use the actor to send events from within our component.

import { useActor } from '@xstate/react';
import { PlayerActor } from './actorMachine'

const Player = ({playerRef}: {playerRef: PlayerActor }) => {
  const [state, send] = useActor(playerRef);
  // state.context === undefined 
  return null;
}

On the other hand, if we do want to access the context, we could make use of the running service which is another word for an invoked machine by using the useService hook of the same package.

import { useService } from '@xstate/react';
import { PlayerService } from './actorMachine'

const Player = ({playerRef}: {playerRef: PlayerService }) => {
  const [state, send] = useService(playerRef);

  return (
    <p>{state.context.identity} decided on: {state.context.playedAction}</p>
  );
}

Passing the reference to the actor into the useService subscribes the component to all the state changes of the actor. As a result, when the context or finite-state of the player actor changes, the component is rerendered as well. Needless to say, the reactive nature of state machines and React work harmoniously well together.

For a complete example, check the codesandbox for today's lecture and pay special attention to the type differences of the two respective hooks as pointed above (PlayerActor vs PlayerService).

About this series

Throughout the first 24 days of December, I'll publish a small blog post each day teaching you about the ins and outs of state machines and statecharts.

The first couple of days will be spent on the fundamentals before we'll progress to more advanced concepts.

State machine advent: Building hierarchy using the actor model and cross-machine communication (22/24)

Mikey Stengel — Sun, 22 Dec 2019 22:24:49 +0000

One of the reasons why state machines and statecharts enable us to write great applications is the fact that they have been around for ages and have gone through decades of iterations until formalized in the SCXML specification which is strictly being followed by XState as well. Today, we will introduce another old and established mathematical model in computer science, the actor model.

An actor in XState is simply a machine that communicates with other machines. They can spawn other actors and send messages to one and another all while deterministically managing the application state. In XState, we communicate by sending events. Today, we want to learn how those abstract concepts translate into code.

Yesterday, we wrote a small player machine which can play a game of Rock, Paper, Scissors by invoking a tiny child machine that encapsulates just the behavior needed to play the game.

Today, we want to add a game machine that manages the two players, figures out who won and notifies the actor that came out on top. We'll use a lot of things in the toolbox of XState. To not be overwhelmed by the code, ensure you have a good grasp on the following concepts before diving in:

You can find the complete code in the Codesandbox here. Below, you can find all the relevant pieces and I'll explain the most important parts piece by piece.

Before writing actors, we used to think solely about the state architecture of the machine. Adding actors to the mix, we should also think about their hierarchy, how the different actors communicate with each other and which machines spawn which actors. When writing actors, we should also be aware of their responsibility. After all, they are just computational units that can talk to others. Generally speaking, the smaller the unit, the easier it can be reused and understood. Speaking about small is particularly referencing the number and complexity of events. They essentially represent the complete API surface area of an actor. On the contrary, you can design a deep or complex orthogonal state hierarchy, and the parent machine of an actor wouldn't know as it merely talks to its child with events. In other words, the finite and infinite-state (context) of actors are private and can only be shared with other actors using explicit events.

To give one example of how the actor architecture could vary, the game machine could be a spawned actor of the player machine and in turn invoke the second player machine (as an actor). As an introduction to actors, I decided that the game machine itself should be invoking and managing both player machines.

Actors live inside the context of a machine. Let's define their types:

import { Actor } from 'xstate';

export type PlayerActor = Actor<ActorContext, ActorEvent>;


interface GameStateContext {
  playerRefs: [] | [PlayerActor, PlayerActor];
}

The ActorContext and ActorEvent are the types of the child machine. We either want the playerRefs to be an empty array (initial context) or to be an array with exactly two actors.

One can spawn actors inside actions. As a result, spawning an actor can happen at any point in time, dynamically. Meanwhile, when we invoked a state machine or promise as a service, we had to define a distinct state node. Therefore, more flexibility is an added benefit of using actors.

Enough talking, let's spawn some actors inside our game machine:

initializing: {
  on: {
    "": {
      target: "idle",
      actions: assign({
        playerRefs: () => [
          spawn(
            actorMachine.withContext({
              identity: "player1"
            }),
          ),
          spawn(
            actorMachine.withContext({
              identity: "player2"
            }),
          )
        ]
      })
    }
  }
},

We can spawn the two players by importing the spawn function from XState and calling it within the assign call. This sets the actor references to the game machine context. Speaking of which, just like a component can set the initial context of a machine, the machine itself can set the initial context of its actors by spawning them and calling withContext. Because both have the same type, we use this mechanism to assign each player an identity. This helps us to easily distinguish the actor of player one from the player2 sibling.

After we've spawned the actors, we want to communicate with them. By using the playerRefs variable inside the context, we can send each one an event.

Once our game machine receives an event to start playing the game, it should notify both players to start playing as well.

// inside the parent (gameMachine)
idle: {
  on: {
    PLAY_GAME: {
      target: "playing",
      actions: [
        send("PLAY", {
          to: context => context.playerRefs[0]
        }),
        send("PLAY", {
          to: context => context.playerRefs[1]
        })
      ]
    }
  }
},

Once the child machine has finished playing, the parent should know about it. To succeed with the actor model in XState, we need to think about every message as an event. If you like to think in "request" and "response", they too are merely events that conditionally result in actions being executed and/or a state transition to occur.

As a result, for the parent to be notified about anything the child actor does, it should define an event first.

// type of the gameMachine
export type FinishedPlayingEvent = {
  type: "FINISHED_PLAYING";
  action: ROCK_PAPER_SCISSORS;
  identity: "player1" | "player2";
};

type GameEvent =
  | { type: "PLAY_GAME" }
  | FinishedPlayingEvent
  | { type: "DETERMINE_WINNER" };

If you are curious about the event implementation, you can find it further below or in the sandbox. For now, let's focus on how the child can notify its parent. It does so by... drumroll: sending the event.
To send an event from the child machine to the parent that invoked it, import sendParent from XState.

// inside the child machine
played: {
  entry: sendParent(
    context =>
      ({
        type: "FINISHED_PLAYING",
        action: context.playedAction,
        identity: context.identity
      })
  ),
  on: {
    PLAY: "playing"
  }
}

With a very deep state structure, we can even replicate the actor context using distinct state nodes and conditional guards. It can be very powerful at times to encapsulate behavior in child actors and still have the possibility to put them in declarative state nodes for your UI or further assertions like we do to decide on a winner.

If you have ever played Rock, Paper, Scissors before, you know how difficult it can be to distinguish paper from scissors. 😁 Let's add a "referee" state node that receives the FINISHED_PLAYING event of the child machine, conditionally transitions the game state and will determine a winner once both actors have made their move.

Below, you can see a very detailed example of this in action.

interface GameStateSchema {
  states: {
    initializing: {};
    idle: {};
    playing: {
      states: {
        referee: {};
        player1: {
          states: {
            deciding: {};
            action: {
              states: {
                rock: {};
                paper: {};
                scissors: {};
              };
            };
          };
        };
        player2: {
          states: {
            deciding: {};
            action: {
              states: {
                rock: {};
                paper: {};
                scissors: {};
              };
            };
          };
        };
      };
    };
    draw: {};
    winner: {
      states: {
        player1: {};
        player2: {};
      };
    };
  };
}

// then inside the game machine definition
playing: {
  type: "parallel",
  states: {
    referee: {
      on: {
        FINISHED_PLAYING: [
          {
            target: "player1.action.rock",
            cond: (context, event) =>
              event.identity === "player1" && event.action === "ROCK"
          },
          {
            target: "player1.action.paper",
            cond: (context, event) =>
              event.identity === "player1" && event.action === "PAPER"
          },
          {
            target: "player1.action.scissors",
            cond: (context, event) =>
              event.identity === "player1" && event.action === "SCISSORS"
          },
          {
            target: "player2.action.rock",
            cond: (context, event) =>
              event.identity === "player2" && event.action === "ROCK"
          },
          {
            target: "player2.action.paper",
            cond: (context, event) =>
              event.identity === "player2" && event.action === "PAPER"
          },
          {
            target: "player2.action.scissors",
            cond: (context, event) =>
              event.identity === "player2" && event.action === "SCISSORS"
          }
        ],
        DETERMINE_WINNER: [
          {
            target: "#draw",
            cond: (context, event, stateGuard) => {
              if (!haveBothPlayersMadeTheirMove(stateGuard.state)) {
                return false;
              }
              const isGameDrawn = haveBothPlayersMadeTheSameMove(
                stateGuard.state
              );
              return isGameDrawn;
            }
          },
          {
            target: "#winner.player1",
            cond: (context, event, stateGuard) => {
              if (!haveBothPlayersMadeTheirMove(stateGuard.state)) {
                return false;
              }
              const player1Action =
                stateGuard.state.value["playing"]["player1"]["action"];
              const player2Action =
                stateGuard.state.value["playing"]["player2"]["action"];
              const didPlayer1Win = gameLogic[player1Action].beats(
                player2Action
              );
              return didPlayer1Win;
            }
          },
          {
            target: "#winner.player2",
            cond: (context, event, stateGuard) => {
              if (!haveBothPlayersMadeTheirMove(stateGuard.state)) {
                return false;
              }
              const player1Action =
                stateGuard.state.value["playing"]["player1"]["action"];
              const player2Action =
                stateGuard.state.value["playing"]["player2"]["action"];
              const didPlayer2Win = gameLogic[player2Action].beats(
                player1Action
              );
              return didPlayer2Win;
            }
          }
        ]
      }
    },
    player1: {
      initial: "deciding",
      states: {
        deciding: {},
        action: {
          entry: raise("DETERMINE_WINNER"),
          states: {
            rock: {},
            paper: {},
            scissors: {}
          }
        }
      }
    },
    player2: {
      initial: "deciding",
      states: {
        deciding: {},
        action: {
          entry: raise("DETERMINE_WINNER"),
          states: {
            rock: {},
            paper: {},
            scissors: {}
          }
        }
      }
    }
  }
},
draw: {
  id: "draw"
},
winner: {
  id: "winner",
  states: {
    player1: {
      entry: send("WON", {
        to: context => context.playerRefs[0]
      })
    },
    player2: {
      entry: send("WON", {
        to: context => context.playerRefs[1]
      })
    }
  }
}

Raise action

Note how the referee transitions conditionally to the distinct action state nodes of the players. The entry of the action state node, raises the DETERMINE_WINNER event, meaning it sends the event to itself (the invoked game machine). I find this very beautiful as it allows your machine to call events of itself while an actor could send the same event 😍
You can learn more about the raise action here.

State id and deep state transitions

When using a state id, we can reference it by prefixing #. This is useful for transitioning state from a deeply nested state to a state node higher in the hierarchy. It's a coincidence that the ids have the same name as the state node (winner/draw), you can call the id anything you want.

target: "#winner.player2"

After we reference the state id, we can chain nested state nodes (like player2) using the dot notation.

Handling the WON event in the player/child machine

Earlier I spoke about the minimal API surface area of actors. One of the powers of this mechanism is the fact that they just receive events while not knowing anything about the internal structure, conditional logic, and state complexity of the actor friends they talk to. Yet, they can perfectly react to events that are important to them.

As established before, the player actor wants to know if they won the encounter. It could react to it by counting how many times this particular actor has won the game, all without knowing about the complexity of the parent, gameMachine.

// inside the child machine
WON: {
  actions: assign({
    winCount: context => context.winCount + 1
  })
}

So you don't have to scroll all the way up, here is the link to the sandbox again https://codesandbox.io/s/gracious-pare-qce8n

About this series

Throughout the first 24 days of December, I'll publish a small blog post each day teaching you about the ins and outs of state machines and statecharts.

The first couple of days will be spent on the fundamentals before we'll progress to more advanced concepts.

State machine advent: Invoking a reusable state machine (21/24)

Mikey Stengel — Sat, 21 Dec 2019 18:35:04 +0000

Two days ago, we learned about services for the very first time. In particular, we wrote our first service by invoking a promise. Today, we want to look at one of my favorite things to do in XState, invoking a machine as a service. When modeling state machines and statecharts, we should always strive to keep them as small as possible. We should write multiple small machines and wire them together using cross-machine communication and the actor model. The concept of invoking a machine as a service is quite similar to the promise. Just like we had to wait for the invoked promise to be resolved or rejected, a machine can invoke a child machine and be notified once the child machine has reached its final state via the onDone handler.

In XState, a machine can mark the last state - from which it doesn't define any more state transitions; therefore, it can't have events - with type: final.

To try this in action, we want to define some machines that allow us to play rock paper scissors. Where I'm from, most people scream "rock paper scissors" out loud before deciding on the action they take. 😄 Let's ensure our machine does the same thing by logging "rock", "paper", "scissor" with a small delay. Despite not focus of today's lecture, I wanted to sneak delayed transitions into the post because the ability to set a delay from one state to another with each state node performing a different action is really powerful and one of the reasons why XState resonates so well with animations.

Child machine

Let's get to building by defining some types. 🛠️

enum ROCK_PAPER_SCISSORS {
  'ROCK' = 'ROCK',
  'PAPER' = 'PAPER',
  'SCISSORS' = 'SCISSORS',
}

interface RockPaperScissorsStateSchema {
  states: {
    screamRock: {};
    screamPaper: {};
    screamScissors: {};
    randomizingAction: {};
    played: {};
  };
}

interface RockPaperScissorsContext {
  action: ROCK_PAPER_SCISSORS | 'NONE';
}

Let's implement the machine. Notice how we don't need any events in the child machine (third type argument is any when calling the Machine factory function). I'll explain why we don't define events (other than the null event) in a minute. For now, appreciate the fact that we are about to define our very first internal machine that will be invoked by another machine instead of a component 🤩

import { Machine, assign, actions } from 'xstate';
const { log } = actions;

const rockPaperScissorsMachine = Machine<RockPaperScissorsContext, RockPaperScissorsStateSchema, any>({
  id: 'rockPaperScissors',
  initial: 'screamRock',
  context: {
    action: 'NONE',
  },
  states: {
    screamRock: {
      entry: log((context, event) => "ROCK...", 'RockPaperScissors'),
      after: {
        // 1/10th later transition to scream "PAPER"
        100: 'screamPaper',
      },
    },
    screamPaper: {
      entry: log((context, event) => "PAPER...", 'RockPaperScissors'),
      after: {
        // 1/10th second later transition to scream "SCISSORS"
        100: 'screamScissors',
      },
    },
    screamScissors: {
      entry: log((context, event) => "SCISSORS...", 'RockPaperScissors'),
      after: {
      // 1/10th second later transition to randomizingAction
        100: 'randomizingAction',
      },
    },
    randomizingAction: {
      on: {
        '': {
          actions: assign({
            // click on the linked codesandbox at the very end
            // if you are curious about the randomEnum function 
            action: () => randomEnum(ROCK_PAPER_SCISSORS),
          }),
          target: 'played',
        },
      },
    },
    played: {
      type: 'final',
      data: {
        performedAction: (context, event) => context.action,  
      }
    },
  },
});

See how the machine can additionally define some extended state via data that the parent machine can read once the child reaches the final state. We can refer to it as done data.

Before moving on to the parent machine, let me tell you why we have defined a randomizingAction state with a null event. Right before the machine transitions to the next state (played), a randomized ROCK_PAPER_SCISSORS value is assigned to the action property of the machine's context. Alternatively, just like we perform a log action when entering the screaming state nodes, the action of changing the context could've also been performed as an entry action of the played state.
On the contrary, once we have entered the played state, we'd usually expect the action to be already set to ROCK | PAPER | SCISSORS. To prevent ambiguity, we want to set the value before entering the state node; hence, we added a very explicit state node randomizingAction. Don't be frugal when it comes to defining state nodes, they can add a lot of clarity to the code we write.

Parent machine

Our rock paper scissors machine should be invoked by a user. Let's represent the user with an ActorMachine.

interface ActorStateSchema {
  states: {
    idle: {};
    playing: {};
    played: {};
  };
}

interface ActorContext {
  playedAction?: ROCK_PAPER_SCISSORS;
}

type ActorEvent = { type: 'PLAY' };

As you can see, there are quite some things we had to repeat like playing, played and the action value inside the machine's context. Former state is essential to invoke the child machine and once the machine has reached the final state, the parent machine will also transition to a state indicating that a game has been played. As established before, there is no need to define state nodes sparingly and we get some nice benefits from having defined a parent machine. In particular, we managed to encapsulate the few states and actions needed to play the game into a distinct rock paper scissors machine. By invoking the machine, it doesn't need to be aware of the idle state and PLAY event of the parent machine. As a benefit, the machine has a single responsibility and because of its minimal API surface, it can be easily reused.

const actorMachine = Machine<ActorContext, ActorStateSchema, ActorEvent>({
  id: 'player',
  initial: 'idle',
  context: {
    playedAction: undefined,
  },
  states: {
   idle: {
     on: {
       'PLAY': 'playing',
     },
   },
   playing: {
      invoke: {
        id: 'playRockPaperScissor',
        src: rockPaperScissorsMachine,
        onDone: {
          target: 'played',
          actions: assign({ playedAction: (context, event) => event.data.performedAction }),
        }
      }
    },
    played: {
        on: {
          /** Let's play again :) */
          PLAY: "playing"
        }
    },
  },
});

Looking at the parent machine, the most important part is clearly when the rockPaperScissorsMachine gets invoked. Once the event handler is called to indicate that the child machine has finished its execution, we assign the done data to the parent context. Just one of multiple ways to handle cross-machine communication. For learning purposes, I named the extended state differently every time so you can clearly tell the difference. You could also call them by the same name e.g action which might make the code easier to look at.

action: property in the context of the child machine
performedAction: property of the done data inside the final state of the child machine. Gets assigned the action value
playedAction: property in the context of the parent machine. Gets assigned the performAction value

You can see everything working together smoothly in this codesandbox.

About this series

Throughout the first 24 days of December, I'll publish a small blog post each day teaching you about the ins and outs of state machines and statecharts.

The first couple of days will be spent on the fundamentals before we'll progress to more advanced concepts.

State machine advent: The power of null events (20/24)

Mikey Stengel — Fri, 20 Dec 2019 22:55:35 +0000

Events are what drive our state changes and are typically sent to a state machine by components. There is one event that is different and we have yet to cover. The null event:

someStateNode: {
  on: {
    // This is a null event.
    '': {
      target: 'someOtherStateNode',
    },
  },
}

It doesn't have a type and is an internal event, meaning no component on the outside can send it to the machine. To elaborate, it is immediately executed once a state node is entered and instantly transitions our state machine to a new state. In the example above, as soon as someStateNode is entered, the machine will transition to someOtherStateNode.

This doesn't seem particularly useful on its own so let's see how this translates to a real-world example.

If we look at a simplified thermostat machine from a few days ago, we can see that we've defined an initial temperature of 20°C and set the initial state to warm. This is correct since the SET_TEMPERATURE event would also transition our state machine to the warm state as soon as the temperature hits at least 18°C.

import { Machine, assign } = 'xstate';

const thermostatMachine = Machine({
  id: 'thermostat',
  initial: 'warm',
  context: {
    temperature: 20,
  },
  states: {
    cold: {},
    warm: {},
  },
  on: {
    SET_TEMPERATURE: [
      {
        target: '.cold',
        cond: (context, event) => event.temperature < 18,
        actions: assign({
          temperature: (context, event) => event.temperature,
        }),
      },
      {
        // transition without a guard as a fallback.
        target: '.warm',
        actions: assign({
          temperature: (context, event) => event.temperature,
        }),
      },
    ],
  },
});

A problem occurs if we lower the initial temperature but forget to change the initial state, or when we don't even control the initial temperature of the machine. You read that right. Similar to how a component can pass a configuration object to define actions and guards, components can also set the initial context of our machine.

import React from 'react';
import { useMachine } from 'xstate';
import {thermostatMachine} from './thermostatMachine';

const ColdRoom = () => {
  const [state, send] = useMachine(thermostatMachine.withContext({ temperature: 5 }));

  console.log(state);
  // state.context === 5;
  // state.matches('warm') === true (OH NO)
  return null;
}

When calling thermostatMachine.withContext, it merges and overwrites the context we have defined in our machine with the values passed to the function. Therefore, the initial temperature is no longer 20°C as specified in our machine definition, but 5°C. Despite the low initial temperature, our thermostat still thinks it's warm since the SET_TEMPERATURE event was never called to perform the conditional state transition that would rightfully put the machine into the cold state.

What I like to do to fix those kinds of problems is to add another state node called initializing. It should use a null event and multiple conditional transitions to set the correct initial state of the machine.

import { Machine, assign } = 'xstate';

const thermostatMachine = Machine({
  id: 'thermostat',
  initial: 'initializing',
  context: {
    temperature: 20,
  },
  states: {
    initializing: {
      on: {
        '':
          [
            {
              target: 'cold',
              cond: (context) => context.temperature < 18,
            },
            {
              // transition without a guard as a fallback.
              target: 'warm',
            },
          ],
      }
    },
    cold: {},
    warm: {},
  },
  on: {
    SET_TEMPERATURE: [
      {
        target: '.cold',
        cond: (context, event) => event.temperature < 18,
        actions: assign({
          temperature: (context, event) => event.temperature,
        }),
      },
      {
        // transition without a guard as a fallback.
        target: '.warm',
        actions: assign({
          temperature: (context, event) => event.temperature,
        }),
      },
    ],
  },
});

We have now ensured that our thermostat will always be in the correct state by setting initializing as the initial state which then instantly transitions our machine to warm or cold depending on the current context. Because the initializing state immediately transitions into another state, it is also known as a transient transition.

When defining null events, ensure to always work with the context as the event itself does not contain any data. If you were to log the event of the null event, it would just print: { type: '' }.

About this series

Throughout the first 24 days of December, I'll publish a small blog post each day teaching you about the ins and outs of state machines and statecharts.

The first couple of days will be spent on the fundamentals before we'll progress to more advanced concepts.

State machine advent: Asynchronous code in XState (19/24)

Mikey Stengel — Thu, 19 Dec 2019 22:59:36 +0000

Most applications are filled with asynchronous code. It's a shame when state management libraries do not support to write such code out of the box. Luckily, in XState multiple ways to handle asynchronicity exist. Today, we want to explore how to deal with promises and their superset - async functions.

Since most things in XState are modeled using actions and state transitions, let's take a look at how those two concepts translate to the invocation of a promise.

A promise is a state machine that at any point in time is either pending | fulfilled | rejected. When we want to call a promise within a state machine, the first thing we want to do is to represent the three possible states as state nodes inside the machine.

Let's say we want to create a state machine that fetches cat images from an external API.

One state node should represent the pending state of the promise. This is where we want to call the promise to fetch cat images. The promise will be invoked every time we enter the state node. Let's call this state node fetching.
One state node should represent the fulfilled state of the promise. We'll call this one success.
(Optionally) One state node that represents the rejected state of the promise. We'll call it failure.

interface CatFetchStateSchema {
  idle: {};
  fetching: {};
  success: {};
  failure: {};
}

type CatFetchEvent = { type: 'FETCH_CATS'};

interface CatFetchContext {
  /**
   * We also want to track error messages. After all, should the promise be rejected, the least we can do is to let the user know why they can't look at cat pictures 😿 (Did you know that a crying cat emoji exists? lol) 
   */
  errorMessage?: string;
  cats: any[];
}

We can then implement our state machine.

import { Machine, assign } from 'xstate';

const catFetchMachine = Machine<CatFetchContext, CatFetchStateSchema, CatFetchEvent>({
  id: 'catFetch',
  initial: 'idle',
  context: {
    errorMessage: undefined,
    cats: [],
  },
  states: {
    idle: {
      on: {
        'FETCH_CATS': {
          target: 'fetching',
        },
      },
    },
    fetching: {
      invoke: {
        id: 'retrieveCats',
        src: (context, event) => fetchCats(),
        onDone: {
          target: 'success',
          actions: assign({ cats: (context, event) => event.data })
        },
        onError: {
          target: 'failure',
          actions: assign({ errorMessage: (context, event) => event.data })
        }
      }
    },
    success: {},
    failure: {},
  }
})

The invoke property indicates that we are invoking something that does not return a response immediately. Since the response occurs at some point in the future, we define an error and success handler. They will be called when the promise is rejected or fulfilled respectively. In the onError and onDone event handlers, we can define the next state (value of target) and actions. Actions are used to perform side effects such as assigning a new value to the context.
Since we typically express state changes with state transitions and actions anyway, dealing with asynchronous code in XState is a breeze!

Another thing that makes me happy when dealing with async code in XState is exception management. Normally our fetchCats code would look something like this:

const fetchCats = async () => {
  try {
    const catResponse = await fetch('some-cat-picture-api');
    const cats = await catResponse.json().data;
    return cats;
  } catch (error){
    console.error("Something went wrong when fetching cats 😿", error);
    // handle error
  }
}

Because of the onError handler, we have moved the exception management into our state machine. As a result, we need to ensure the promise can be rejected and can happily remove the try-catch block from the async function:

const fetchCats = async () => {
  const catResponse = await fetch('some-cat-picture-api');
  const cats = await catResponse.json().data;
  return cats;
}

Granted, with the machine implementation from above, cats will only be fetched once. We can fix this by adding some state transitions back to the fetching state.

  success: {
    on: {
      'MORE_CATS': {
        target: 'fetching'
      },
    },
  },
  failure: {
    on: {
      'RETRY': {
        target: 'fetching'
      },
    },
  },

Now the user can recover our machine from a failure state and also fetch more/different cats.

In summary, to perform asynchronous code in XState:

translate the three promise states into state nodes ( pending = fetching, fulfilled = success, rejected = failure)
define state transitions and actions in the error or success event handlers
give the object that invokes the promise (technically called a service) a unique id
ensure that promises can be rejected by removing the try-catch blocks from asynchronous functions

Very excited to have finally introduced the invoke property as we'll come back to it in the next couple of days when exploring some of the other things that can be invoked in XState.

About this series

Throughout the first 24 days of December, I'll publish a small blog post each day teaching you about the ins and outs of state machines and statecharts.

The first couple of days will be spent on the fundamentals before we'll progress to more advanced concepts.

State machine advent: Let the machine handle accessibility for you (18/24)

Mikey Stengel — Thu, 19 Dec 2019 01:07:04 +0000

When designing and building apps, we need to ensure that they are accessible to all people. Among other things, this includes managing focus and the tab order deliberately.

To give a small example of a login form where we'd want to manage focus:

No input field is shown initially.
Upon clicking a button saying "click here to login":
- Hide the button
- Show an input field to enter the email
- Focus the input field so that one can type their email immediately

Solving one of the most common a11y problems in our apps like focus management can be very complicated and error-prone even with straightforward requirements as the ones above.
In React for example, we usually create a ref and manage local state that tracks whether we have already set the focus or not. We then perform some conditional logic on the variable inside an effect where we ultimately perform the ref.currrent.focus() action to set the focus onto the input field.

Sounds complicated, let's put the words into code. We'll start off by adding some types for a little state machine.

interface LoginStateSchema {
  states: {
    /**
     * In the `idle` state, we'll just show the button
     */
    idle: {};

    /**
     * In the `canLogin` state, we want to show the email input field
     */
    canLogin: {};
  };
}

type LoginEvent = 
 | { type: 'ENABLE_LOGIN' }
 | { type: 'SET_EMAIL', email: string };

interface LoginContext {
  email: string;
}

After having written the types, let's go ahead and implement our state machine.

import { Machine, assign } from 'xstate';

const loginOrIdleMachine = Machine<LoginContext, LoginStateSchema, LoginEvent>({
  id: 'loginOrIdle',
  initial: 'idle',
  context: {
    email: '',
  },
  states: {
    idle: {
      on: {
        'ENABLE_LOGIN': {
          target: 'canLogin',
        },        
      },
    },
    canLogin: {
      on: {
        'SET_EMAIL': {
          actions: assign({
            email: (context, event) => event.email,
          })
        }
      }  
    },
  }  
})

With everything we have learned up until this point, our code to manage the focus of the input field is still pretty verbose:

import React, { Fragment, useRef, useLayouteffect, useState } from 'react';
import { useMachine } from '@xstate/react';

const Login = () => {
  const inputRef = useRef<HTMLInputElement>(null);
  const [state, send] = useMachine(loginOrIdleMachine);
  const [hasManagedFocus, setHasManagedFocus] = useState<boolean>(false);

  useLayoutEffect(() => {
    if (state.matches('canLogin') && !hasManagedFocus){
      inputRef?.current?.focus();
      setHasManagedFocus(true);
    }
  }, [state, setHasManagedFocus, hasManagedFocus, inputRef])

  return (
    <Fragment>
      {state.matches('idle') && 
        (
          <button onClick={() => void send({type: 'ENABLE_LOGIN'}) }>
            click here to login
          </button>
        )
      }

      <input 
        onChange={e => void send({type: 'SET_EMAIL', email: e.target.value})} 
        hidden={!state.matches('canLogin')}
        placeholder="Enter email"
        value={state.context.email}
        ref={inputRef}
      />
    </Fragment>
  )
}

Not only is the code verbose, if we introduced a state transition from the canLogin state towards the idle state again (e.g a button saying "login later" underneath the input field), the requirements would no longer be fulfilled and we'd also have to call setHasManagedFocus(false) conditionally. The reason why we need to reset the hasManagedFocus variable is because we need to ensure that when transitioning from idle => canLogin => idle => canLogin state, the input field of the second canLogin state transition will be focused as well. I'm sure it is possible to create fully accessible applications by managing local variables, but it can get out of hand really quickly.

Let's quickly determine what can happen if this particular part of our code gets out of hand. Once our code gets too complex, we tend to ship less. Introducing bugs or being too afraid to touch the a11y logic of our app can literally result in us denying people access to our app or service. Needless to say, we have to get this right!

We can simplify our code by reframing the question. Ask: "On which state transition should we perform the action to steal focus?" instead of asking in which states we should and shouldn't steal focus. Sure, when modeling our state machine, we should also think about the latter question but the worry is purely solved within the machine. As a consequence, it removes conditional logic from our code and frees our minds from a lot of cognitive overhead.

Now that we know what kind of question to ask, let's learn about one particular primitive in XState that could help us find a good answer. Each state node in XState has an entry property. We can call actions by their name as a value of the property and they'll be executed every time the invoked machine enters (or reenters) the state node.
To conclude our quest for the best place to put our focus action: We want to focus the input field right after entering the canLogin state.

canLogin: {
  // focusInput action will be called whenever the machine enters the state node 
  entry: 'focusInput',
  on: {
    'SET_EMAIL': {
      actions: assign({
        email: (context, event) => event.email,
      })
    }
  }  
},

Pretty rad but how can our machine define the focusInput action when it doesn't know anything about the input element or the DOM to begin with?
The machine doesn't define the action. Instead, the action will be defined within our React component and passed into the machine as a configuration.

const [state, send] = useMachine(loginOrIdleMachine.withConfig({
  actions: {
    'focusInput': () => void inputRef?.current?.focus(),
  }
}));

That's right, components can pass actions and guards inside a configuration object (withConfig) into the machine. We can then call the guard or action by their distinct name (e.g entry: 'focusInput'); hence, handle focus management within the state machine. 🎉🥳

Once we put everything together, our code could look like this:

import React, { useRef, Fragment } from 'react';
import { useMachine } from '@xstate/react';
import { Machine, assign } from 'xstate';

/** Type declarations  */
interface LoginStateSchema {
  states: {
    idle: {};
    canLogin: {};
  };
}

type LoginEvent =
 | { type: 'ENABLE_LOGIN' }
 | { type: 'SET_EMAIL'; email: string };

interface LoginContext {
  email: string;
}

/** Machine implementation  */
const loginOrIdleMachine = Machine<LoginContext, LoginStateSchema, LoginEvent>({
  id: 'loginOrIdle',
  initial: 'idle',
  context: {
    email: '',
  },
  states: {
    idle: {
      on: {
        'ENABLE_LOGIN': {
          target: 'canLogin',
        },
      },
    },
    canLogin: {
      entry: 'focusInput',
      on: {
        'SET_EMAIL': {
          actions: assign({
            email: (context, event) => event.email,
          }),
        },
      },
    },
  },
});


/** Component that invokes the machine  */
const Login = () => {
  const inputRef = useRef<HTMLInputElement>(null);
  const [state, send] = useMachine(loginOrIdleMachine.withConfig({
    actions: {
      'focusInput': () => void inputRef?.current?.focus(),
    },
  }));

  return (
    <Fragment>
      {state.matches('idle') &&
        (
          <button onClick={() => void send({type: 'ENABLE_LOGIN'}) }>
            click here to log in
          </button>
        )
      }

      <input
        onChange={e => void send({type: 'SET_EMAIL', email: e.target.value})}
        hidden={!state.matches('canLogin')}
        placeholder="Enter email"
        value={state.context.email}
        ref={inputRef}
      />
    </Fragment>
  );
};

Awesome! We have eliminated most of the local state (except the ref which we always need for focusing) and have refactored the React effect to an action that is called by our machine. Even if we were to introduce some more states, or a button + event to transition back to the initial idle state as described above, the input field will always be focused when our machine enters the canLogin state.

I hope this post gave you some insights on how to pass actions to a machine and also showcased the accessibility benefits by doing so.

About this series

Throughout the first 24 days of December, I'll publish a small blog post each day teaching you about the ins and outs of state machines and statecharts.

The first couple of days will be spent on the fundamentals before we'll progress to more advanced concepts.

State machine advent: Reusable conditional logic with custom guards (17/24)

Mikey Stengel — Tue, 17 Dec 2019 16:05:55 +0000

Just yesterday, we learned about the second argument of the XState Machine factory function to explicitly define guards and actions. Today, we want to take our conditional logic to the next level by passing arguments to a guard.

What if instead of two states (warm | cold), our thermostat machine needs to determine whether the temperature is freezing | cold | warm | hot. We could totally create a distinct guard for each scenario.

// event determines the next state based on the first guard that evaluates to true
SET_TEMPERATURE: [
  {
    target: '.freezing',
    cond: 'isTemperatureFreezing',
    actions: 'assignTemperature',
  },
  {
    target: '.cold',
    cond: 'isTemperatureCold',
    actions: 'assignTemperature',
  },
  {
    target: '.warm',
    cond: 'isTemperatureWarm',
    actions: 'assignTemperature',
  },
  {
    target: '.hot',
    actions: 'assignTemperature',
  },
]

Then we define the guards inside the configuration object

{
  guards: {
    isTemperatureFreezing: (context, event) => event.temperature < 0, 
    isTemperatureCold: (context, event) => event.temperature < 18, 
    isTemperatureWarm: (context, event) => event.temperature < 30,
  },
}

This works great but if we want to make our code even nicer, we can define a single guard to which we can pass arguments. The cond keyword also accepts an object to which we can pass arguments. To reference our custom guard, the same API as for events is used: The name is specified as a string value of the type property.

// event determines the next state based on the first guard that evaluates to true
SET_TEMPERATURE: [
  {
    target: '.freezing',
    cond: {
      type: 'isTemperatureBelow',
      temperatureThreshold: 0, 
    },
    actions: 'assignTemperature',
  },
  {
    target: '.cold',
    cond: {
      type: 'isTemperatureBelow',
      temperatureThreshold: 18, 
    },
    actions: 'assignTemperature',
  },
  {
    target: '.warm',
    cond: {
      type: 'isTemperatureBelow',
      temperatureThreshold: 30, 
    },
    actions: 'assignTemperature',
  },
  {
    target: '.hot',
    actions: 'assignTemperature',
  },
]


// then we define a single custom guard that can access the temperatureThreshold variable to perform our conditional logic.
{
  guards: {
    isTemperatureBelow: (context, event, stateGuard) => event.temperature < stateGuard.cond.temperatureThreshold  
  }
}

Guards are invoked with one more argument than actions. Besides the context and event, the third argument of a guard holds the current state of the machine as well as the whole cond object. All the variables we pass to our custom guard can be read within this object as seen in the example above.

Even though guards are really powerful, do not be tempted to abuse their power by performing side effects in them just because you can access the current state of your machine. They should always be pure functions meaning they take in some input and always return a boolean without performing any mutations, sending requests, etc.

Last but not least, let's put our custom guard into our thermostat machine so that we can visualize it properly.

import { Machine, assign } = 'xstate';

const thermostatMachine = Machine(
  {
    id: 'thermostat',
    initial: 'inactive',
    context: {
      temperature: 20,
    },
    states: {
      inactive: {
        on: {
          POWER_TOGGLE: 'active'
        }
      },
      active: {
        initial: 'warm',
        states: {
          freezing: {},
          cold: {},
          warm: {},
          hot: {},
        },
        on: {
          POWER_TOGGLE: {
            target: 'inactive',
          },
          SET_TEMPERATURE: [
            {
              target: '.freezing',
              cond: {
                type: 'isTemperatureBelow',
                temperatureThreshold: 0, 
              },
              actions: 'assignTemperature',
            },
            {
              target: '.cold',
              cond: {
                type: 'isTemperatureBelow',
                temperatureThreshold: 18, 
              },
              actions: 'assignTemperature',
            },
            {
              target: '.warm',
              cond: {
                type: 'isTemperatureBelow',
                temperatureThreshold: 30, 
              },
              actions: 'assignTemperature',
            },
            {
              target: '.hot',
              actions: 'assignTemperature',
            },
          ]
        }
      },
    }
  },
  /**
   * Configuration object
   */
  {
    actions: {
      assignTemperature: assign({
        temperature: (context, event) => event.temperature,
      }),
    },
    guards: {
      isTemperatureBelow: (context, event, stateGuard) => event.temperature < stateGuard.cond.temperatureThreshold  
    }
  }
);

Sweet! Our conditional logic is now very reusable. In case we want to add some more temperature states to our thermostat machine, we can simply call the custom guard with a different value. Tomorrow, we'll take a look at how to define actions outside of our machine which will open a realm of possibilities.

About this series

Throughout the first 24 days of December, I'll publish a small blog post each day teaching you about the ins and outs of state machines and statecharts.

The first couple of days will be spent on the fundamentals before we'll progress to more advanced concepts.

State machine advent: A better way to type guards and actions (16/24)

Mikey Stengel — Mon, 16 Dec 2019 21:15:22 +0000

Using conditional logic with guards often means that we have to define the same action twice. This is exactly what we had to do yesterday:

SET_TEMPERATURE: [
  {
    target: '.cold',
    cond: (context, event) => event.temperature < 18,
    actions: assign({
      temperature: (context, event) => event.temperature,
    }),
  },
  {
    target: '.warm',
    actions: assign({
      temperature: (context, event) => event.temperature,
    }),
  },
]

Today, we want to refactor our code so that we don't have to repeat ourselves. Instead of defining the very same action (of assigning the temperature) twice, we can give the action a name, define it in a separate configuration object and then call the action by its name within the machine definition.

import { Machine, assign } = 'xstate';

const thermostatMachine = Machine(
  {
    id: 'thermostat',
    initial: 'inactive',
    context: {
      temperature: 20,
    },
    states: {
      inactive: {
        on: {
          POWER_TOGGLE: 'active'
        }
      },
      active: {
        initial: 'warm',
        states: {
          cold: {},
          warm: {},
        },
        on: {
          POWER_TOGGLE: {
            target: 'inactive',
          },
          SET_TEMPERATURE: [
            {
              target: '.cold',
              cond: 'isTemperatureCold',
              actions: 'assignTemperature',
            },
            {
              target: '.warm',
              actions: 'assignTemperature',
            },
          ]
        }
      },
    }
  },
  /**
   * Configuration object
   */
  {
    actions: {
      assignTemperature: assign({
        temperature: (context, event) => event.temperature,
      }),
    },
    guards: {
      isTemperatureCold: (context, event) => event.temperature < 18,
    },
  }
);

The configuration object is the second argument of the Machine factory function. We are now using the named action - assignTemperature - to update the context. Since we can use this named action throughout our machine definition, we do not have to define the action twice.
Likewise, we apply the very same concept to guards. As a result, we can use an expressive name for the conditional logic of our machine (isTemperatureCold).

Moving actions and guards into the configuration object does not only make our code more DRY and readable, it also improves how well our machine can be serialized and will show the distinct action/guard names within the visualization.

visualization before

visualization after

A couple of days ago, I wrote how I dislike string variables within my machines as it makes the code harder to refactor and additionally, easier to introduce bugs by mistyping. If you like enums as much as I do, you can totally get rid of all the strings by defining your named actions and guards with string enums. 🎉

import { Machine, assign } = 'xstate';

enum THERMOSTAT {
  'INACTIVE' = 'inactive',
  'ACTIVE' = 'active',
  'COLD' = 'cold',
  'WARM' = 'warm',
}

enum THERMOSTAT_EVENT {
  'POWER_TOGGLE' = 'POWER_TOGGLE',
  'SET_TEMPERATURE' = 'SET_TEMPERATURE',
}

enum THERMOSTAT_GUARD {
  'IS_TEMPERATURE_COLD' = 'isTemperatureCold',
}

enum THERMOSTAT_ACTION {
  'ASSIGN_TEMPERATURE' = 'assignTemperature',
}


const thermostatMachine = Machine(
  {
    id: 'thermostat',
    initial: THERMOSTAT.INACTIVE,
    context: {
      temperature: 20,
    },
    states: {
      [THERMOSTAT.INACTIVE]: {
        on: {
          [THERMOSTAT_EVENT.POWER_TOGGLE]: THERMOSTAT.ACTIVE,
        }
      },
      [THERMOSTAT.ACTIVE]: {
        initial: THERMOSTAT.WARM,
        states: {
          [THERMOSTAT.COLD]: {},
          [THERMOSTAT.WARM]: {},
        },
        on: {
          [THERMOSTAT_EVENT.POWER_TOGGLE]: {
            target: THERMOSTAT.INACTIVE,
          },
          [THERMOSTAT_EVENT.SET_TEMPERATURE]: [
            {
              target: THERMOSTAT.COLD,
              cond: THERMOSTAT_GUARD.IS_TEMPERATURE_COLD,
              actions: THERMOSTAT_ACTION.ASSIGN_TEMPERATURE,
            },
            {
              target: THERMOSTAT.WARM,
              actions: THERMOSTAT_ACTION.ASSIGN_TEMPERATURE,
            },
          ]
        }
      },
    }
  },
  /**
   * Configuration object
   */
  {
    actions: {
      [THERMOSTAT_ACTION.ASSIGN_TEMPERATURE]: assign({
        temperature: (context, event) => event.temperature,
      }),
    },
    guards: {
      [THERMOSTAT_GUARD.IS_TEMPERATURE_COLD]: (context, event) => event.temperature < 18,
    },
  }
);

Again, using enums and the configuration object is optional but I do highly recommend you to use both extensively.

About this series

Throughout the first 24 days of December, I'll publish a small blog post each day teaching you about the ins and outs of state machines and statecharts.

The first couple of days will be spent on the fundamentals before we'll progress to more advanced concepts.

State machine advent: One event, two possible state transitions (15/24)

Mikey Stengel — Sun, 15 Dec 2019 20:26:13 +0000

Conditional logic is everywhere. While state machines reduce conditional logic by eliminating impossible states, there is some conditional logic we want to have within our machines. In particular, when one or the other action should be executed or multiple state transitions exist. We can define such conditional logic using the very concept we've learned yesterday, guards.

By providing an array of possible state transitions, the state transition with the first guard that evaluates to true will determine the next state of our machine. Let's say we want our thermostat to distinctively express whether it is cold or warm. If the temperature is below 18°C, it should go into the cold state and above, transition to the warm state.

import { Machine, assign } = 'xstate';

const thermostatMachine = Machine({
  id: 'thermostat',
  initial: 'inactive',
  context: {
    temperature: 20,
  },
  states: {
    inactive: {
      on: {
        POWER_TOGGLE: 'active'
      }
    },
    active: {
      initial: 'warm',
      states: {
        cold: {},
        warm: {},
      },
      on: {
        POWER_TOGGLE: {
          target: 'inactive',
        },
        SET_TEMPERATURE: [
            {
              target: '.cold',
              cond: (context, event) => event.temperature < 18,
              actions: assign({
                temperature: (context, event) => event.temperature,
              }),
            },
            {
              // transition without a guard as a fallback.
              target: '.warm',
              actions: assign({
                temperature: (context, event) => event.temperature,
              }),
            },
         ]
      }
    },
  }
});

Think of the state transition array as a switch case to determine the next state of a machine. The default transition can be expressed as a state transition without a guard as seen in the example above.

Notice how we had to duplicate the action to assign the temperature. Similar to when machines transition from one state to another, actions are only executed if no guard is defined, or when a guard evaluates to true.

To give one more example of this behavior, the code below will never call the 'log' action.

[
    {
        target: 'cold',
        cond: () => false,
        actions: 'log',
    },
    {
        target: 'warm',
    },
]

Tomorrow we'll refactor the thermostatMachine so that we don't have to define the same action twice.

About this series

Throughout the first 24 days of December, I'll publish a small blog post each day teaching you about the ins and outs of state machines and statecharts.

The first couple of days will be spend on the fundamentals before we'll progress to more advanced concepts.

State machine advent: Guard state transitions, guard actions (14/24)

Mikey Stengel — Sat, 14 Dec 2019 17:09:05 +0000

One really powerful concept of statecharts that we haven't covered yet are guards. They are conditional functions that determine whether a state transition should be taken, or actions executed. They are fundamental building blocks when building applications using statecharts. Today, we will cover how to use them.

Guard actions

Let's say we want our thermostat to only work with temperatures below 100°C. We can do so by conditionally executing the action that changes our temperature in context. In XState, we can define this guard within events using the cond keyword. Its value is a function that will be invoked with the context, event, and must always return a boolean value.

import { Machine, assign } = 'xstate';

const thermostatMachine = Machine({
  id: 'thermostat',
  initial: 'inactive',
  context: {
    temperature: 20,
  },
  states: {
    inactive: {
      on: {
        POWER_TOGGLE: 'active'
      }
    },
    active: {
      on: {
        POWER_TOGGLE: 'inactive',
        SET_TEMPERATURE: {
          cond: (context, event) => event.temperature < 100,
          actions: assign({
            temperature: (context, event) => event.temperature,
          }),
        }
      }
    },
  }
});

In plain English, our code above is saying

Once the SET_TEMPERATURE event is called, evaluate the guard. If the temperature of our event is below 100°C, update the temperature of the machine. Should the temperature be higher than 99°C, do not perform any action

For a visual representation, you can even see the guard being visualized by the XState visualizer here 🎉

Guard state transitions

Likewise, should the guard evaluate to false, no state transitions will be taken. In the example above, no state transition was taken as no target was defined but let's say we only want our thermostat to be turned off if the temperature has risen to at least 10°C. Below that point, the thermostat should always actively be monitoring the temperature.

import { Machine, assign } = 'xstate';

const thermostatMachine = Machine({
  id: 'thermostat',
  initial: 'inactive',
  context: {
    temperature: 20,
  },
  states: {
    inactive: {
      on: {
        POWER_TOGGLE: 'active'
      }
    },
    active: {
      on: {
        POWER_TOGGLE: {
          cond: (context, event) => {
            const isWarmEnough = context.temperature >= 10;
            if (!isWarmEnough) console.log("I think it's too cold for you to turn this off");
            // Do not forget to return the boolean :) 
            return isWarmEnough;
          },
          target: 'inactive',
        },
        SET_TEMPERATURE: {
          cond: (context, event) => event.temperature < 100,
          actions: assign({
            temperature: (context, event) => event.temperature,
          }),
        }
      }
    },
  }
});

As seen above, only if the temperature is equal or greater than 10°C, the thermostat will go into the inactive state.

We've now seen how to guard transitions and actions using conditional logic. Guards are very important and especially when using them in conjunction with some other concepts - I'm eager to introduce the upcoming days - guards enable us to safely model a lot of complex behavior. I'm excited to be showing you what one can do with them.

About this series

Throughout the first 24 days of December, I'll publish a small blog post each day teaching you about the ins and outs of state machines and statecharts.

The first couple of days will be spent on the fundamentals before we'll progress to more advanced concepts.