Forem: Matt Pocock

What is XState used for?

Matt Pocock — Tue, 21 Jun 2022 12:28:17 +0000

XState can be used wherever JavaScript runs, whether on the backend or frontend. Because the code it creates can be visualized, it's great at handling complex use cases - being able to see what a complex piece of code does can be extremely useful.

Let's look at each use case one-by-one.

On the web

XState can be used in any frontend application to manage state. It has first-class integrations for React, Vue, Svelte, as well as an upcoming Solid integration. It also works well in Angular without any integrations needed.

You can try it in a Vanilla JS app by running this simple piece of code:

import { createMachine, interpret } from "xstate";

const machine = createMachine({
  initial: "waiting",
  states: {
    waiting: {
      after: {
        2000: "alerted",
      },
    },
    alerted: {
      entry: () => {
        alert("Hello from the state machine!");
      },
    },
  },
});

interpret(machine).start();

In this example, the machine will wait for 2 seconds, then call alert() to let you know it's alive.

There are plenty of ways XState can be used on the frontend - let's talk about two of the most common patterns:

Complex components

Most frontend apps split their code into components - individual pieces which can be reused across the app. If need to build a complex component, you can use XState to co-ordinate it.

A great example of this is the library Zag.js, which is using XState-style syntax and statecharts to build reusable components across frameworks. You can even see them visualized using Stately's tools.

Global state

You can also use XState to manage global state in your apps. A common pattern is the Flux architecture, where you dispatch events to a single top-level store. Parts of your app can subscribe to updates from that store, using selectors.

XState can replace global state managers like Redux or Vuex, with one major benefit - your global state can be visualised and visually edited. XState gives you the ability to create a global store, dispatch events to it, and subscribe to only the pieces that matter. See our specific instructions in React for more info.

Native/extensions

XState is also extremely useful in React Native or Electron apps, Browser extensions and IDE extensions. Since XState doesn't use any browser API's, you can use it anywhere JavaScript runs.

For instance, we use XState at Stately to co-ordinate our VSCode extension. Centered uses XState extensively in their Electron and React Native apps to co-ordinate timers, control app updates and handle complex user interactions.

Backend

You can use XState in Node.js or Deno to build serverless functions or persistent servers.

For lambda functions, XState exposes a function called waitFor, which allows you to wait for a state machine to be in a certain state. This allows you to use XState inside async functions with ease.

To learn more about XState in the backend, see our recent video introducing the topic.

Scripting and CLI's

XState can be used when running scripts or CLI's to co-ordinate long-running processes.

The most famous example of this in the wild is the frontend framework Gatsby. They use XState in their build process and development server to co-ordinate file-system changes and parallelize multiple processes. This means their entire build system is visualisable - an incredibly boon for such a complex process.

Summary

XState works anywhere JS runs - and folks are using it in the wild for all sorts or use cases. Any time you're building something that feels remotely complex, you can use XState to simplify your code and enable powerful visual tooling.

State Management: How to tell a bad boolean from a good boolean

Matt Pocock — Thu, 27 May 2021 14:05:02 +0000

TL;DR: Bad booleans represent state. Good booleans are derived from state.

When you're managing state in your app, it's easy to fall prey to bad booleans. Bad booleans look like this:

let isLoading = true;
let isComplete = false;
let hasErrored = false;

On the surface, this looks like good code. It appears as though you've represented three separate states with proper boolean names. In the 'model' you've pictured for your state, only one of these states can be true at any one time.

In a fetch request, you might model the state like this:

const makeFetch = async () => {
  isLoading = true;
  try {
    await fetch('/users');

    isComplete = true;
  } catch (e) {
    hasErrored = true;
  }
  isLoading = false;
};

Again, this looks nice. We're orchestrating our booleans as we move through the async request.

But there's a bug here. What happens if we make the fetch, it succeeds, and we make the fetch again? We'll end up with:

let isLoading = true;
let isComplete = true;
let hasErrored = false;

Implicit states

You probably hadn't considered this when you made your initial model. You may have frontend components which are checking for isComplete === true or isLoading === true. You might end up with a loading spinner and the previous data showing at the same time.

How is this possible? Well, you've created some implicit states. Let's imagine you considered 3 states as ones you actually wanted to handle:

loading: Loading the data
complete: Showing the data
errored: Erroring if the data doesn't turn up

Well, you've actually allowed 8 states! That's 2 for the first boolean, times 2 for the second, times 2 for the third.

This is what's known as boolean explosion - I learned about this from Kyle Shevlin's egghead course.

Making states explicit

How do you get around this? Instead of a system with 8 possible values, we need a system with three possible values. We can do this in Typescript with an enum.

type Status = 'loading' | 'complete' | 'errored';

let status: Status = 'loading';

We'd implement this in a fetch like this:

const makeFetch = async () => {
  status = 'loading';
  try {
    await fetch('/users');

    status = 'complete';
  } catch (e) {
    status = 'errored';
  }
};

It's now impossible to be in the 'loading' and 'complete' state at once - we've fixed our bug. We've turned our bad booleans into a good enum.

Making good booleans

But not all booleans are bad. Many popular libraries, such as react-query, apollo and urql use booleans in their state. An example implementation:

const [result] = useQuery();

if (result.isLoading) {
  return <div>Loading...</div>;
}

The reason these are good booleans is that their underlying mechanism is based on an enum. Bad booleans represent state. Good booleans are derived from state:

let status: Status = 'loading';

// Derived from the status above
let isLoading = status === 'loading';

You can safely use this isLoading to display your loading spinner, happy in the knowledge that you've removed all impossible states.

Addendum: Enums in Javascript

A couple of folks in the comments are asking how we represent a state enum in Javascript. While the above code will work without typings, you can also represent enums as an object type.

const statusEnum = {
  loading: 'loading',
  complete: 'complete',
  errored: 'errored',
};

let status = statusEnum.loading;

const makeFetch = async () => {
  status = statusEnum.loading;
  try {
    await fetch('/users');

    status = statusEnum.complete;
  } catch (e) {
    status = statusEnum.errored;
  }
};

How to manage global state with XState and React

Matt Pocock — Tue, 25 May 2021 15:02:17 +0000

This article has become part of the official XState docs!

Many React applications follow the Flux architecture popularised by Redux. This setup can be characterised by a few key ideas:

It uses a single object at the top of your app which stores all application state, often called the store.
It provides a single dispatch function which can be used to send messages up to the store. Redux calls these actions, but I'll be calling them events - as they're known in XState.
How the store responds to these messages from the app are expressed in pure functions - most often in reducers.

This article won't go into depth on whether the Flux architecture is a good idea. David Khourshid's article Redux is half a pattern goes into great detail here. For the purposes of this article, we're going to assume that you like having a global store, and you want to replicate it in XState.

There are many reasons for wanting to do so. XState is second-to-none when it comes to managing complex asynchronous behaviour and modelling difficult problems. Managing this in Redux apps usually involves middleware: either redux-thunk, redux-loop or redux-saga. Choosing XState gives you a first-class way to manage complexity.

A globally available store

To mimic Redux's globally-available store, we're going to use React context. React context can be a tricky tool to work with - if you pass in values which change too often, in can result in re-renders all the way down the tree. That means we need to pass in values which change as little as possible.

Luckily, XState gives us a first-class way to do that.

import React, { createContext } from 'react';
import { useInterpret } from '@xstate/react';
import { authMachine } from './authMachine';
import { ActorRefFrom } from 'xstate';

interface GlobalStateContextType {
  authService: ActorRefFrom<typeof authMachine>;
}

export const GlobalStateContext = createContext(
  // Typed this way to avoid TS errors,
  // looks odd I know
  {} as GlobalStateContextType,
);

export const GlobalStateProvider = (props) => {
  const authService = useInterpret(authMachine);

  return (
    <GlobalStateContext.Provider value={{ authService }}>
      {props.children}
    </GlobalStateContext.Provider>
  );
};

Using useInterpret returns a service, which is a static reference to the running machine which can be subscribed to. This value never changes, so we don't need to worry about wasted re-renders.

Utilising context

Further down the tree, you can subscribe to the service like this:

import React, { useContext } from 'react';
import { GlobalStateContext } from './globalState';
import { useActor } from '@xstate/react';

export const SomeComponent = (props) => {
  const globalServices = useContext(GlobalStateContext);
  const [state] = useActor(globalServices.authService);

  return state.matches('loggedIn') ? 'Logged In' : 'Logged Out';
};

The useActor hook listens for whenever the service changes, and updates the state value.

Improving Performance

There's an issue with the implementation above - this will update the component for any change to the service. Redux offers tools for deriving state using selectors - functions which restrict which parts of the state can result in components re-rendering.

Luckily, XState provides that too.

import React, { useContext } from 'react';
import { GlobalStateContext } from './globalState';
import { useSelector } from '@xstate/react';

const selector = (state) => {
  return state.matches('loggedIn');
};

export const SomeComponent = (props) => {
  const globalServices = useContext(GlobalStateContext);
  const isLoggedIn = useSelector(globalServices.authService, selector);

  return isLoggedIn ? 'Logged In' : 'Logged Out';
};

Now, this component will only re-render when state.matches('loggedIn') returns a different value. This is my recommended approach over useActor for when you want to optimise performance.

Dispatching events

For dispatching events to the global store, you can call a service's send function directly.

import React, { useContext } from 'react';
import { GlobalStateContext } from './globalState';

export const SomeComponent = (props) => {
  const globalServices = useContext(GlobalStateContext);

  return (
    <button onClick={() => globalServices.authService.send('LOG_OUT')}>
      Log Out
    </button>
  );
};

Note that you don't need to call useActor for this, it's available right on the context.

Deviations from Flux

Keen-eyed readers may spot that this implementation is slightly different from Flux. For instance - instead of a single global store, one might have several running machines at once: authService, dataCacheService, and globalTimeoutService. Each of them have their own send attributes, too - so you're not calling a global dispatch.

These changes can be worked around. One could create a synthetic send inside the global store which called all the services' send function manually. But personally, I prefer knowing exactly which services my messages are being passed to, and it avoids having to keep events globally namespaced.

Summary

XState can work beautifully as a global store for a React application. It keeps application logic co-located, treats side effects as first-class citizens, and offers good performance with useSelector. You should choose this approach if you're keen on the Flux architecture but feel your app's logic is getting out of hand.

XState: Why I Love Invoked Callbacks

Matt Pocock — Thu, 13 May 2021 20:57:49 +0000

XState offers several primitives for representing long-running application processes. These are usually expressed as services. I've written a bit about services here - but today I wanted to talk about my favourite way of expressing services: the Invoked Callback.

The Invoked Callback combines immense flexibility with good readability and a solid Typescript experience. They look like this:

createMachine({
  invoke: {
    src: (context, event) => (send, onReceive) => {
      // Run any code you like inside here

      return () => {
        // Any code inside here will be called when
        // you leave this state, or the machine is stopped
      };
    },
  },
});

Let's break this down. You get access to context and event, just like promise-based services. But send is where things really get interesting. Let's break down what makes send useful with an example.

File Uploads

Imagine you need to build a file uploader, and you have a handy function called startUpload that uploads some data, and exposes an onProgressUpdate parameter to update the progress.

createMachine({
  context: {
    progress: 0,
  },
  initial: 'idle',
  states: {
    idle: {
      on: {
        START: 'pending',
      },
    },
    pending: {
      on: {
        PROGRESS_UPDATED: {
          assign: assign({
            progress: (context, event) => event.progress,
          }),
        },
        CANCEL: {
          target: 'idle',
        },
      },
      invoke: {
        src: (context) => (send) => {
          const uploader = startUpload({
            onProgressUpdate: (progress) => {
              send({
                type: 'PROGRESS_UPDATED',
                progress,
              });
            },
          });

          return () => {
            uploader.cancel();
          };
        },
      },
    },
  },
});

This machine starts in the idle state, but on the START event begins its invoked service, which uploads the file. It then listens for PROGRESS_UPDATED events, and updates the context based on its updates.

The CANCEL event will trigger the uploader.cancel() function, which gets called when the state is left. React users may recognise this syntax - it's the same as the cleanup function in the useEffect hook.

Note how simple and idiomatic it is to cancel the uploader - just exit the state, and the service gets cleaned up.

Event Listeners

The invoked callback's cleanup function makes it very useful for event listeners, for instance window.addEventListener(). XState Catalogue's Tab Focus Machine is a perfect example of this - copied here for ease:

createMachine(
  {
    initial: 'userIsOnTab',
    states: {
      userIsOnTab: {
        invoke: {
          src: 'checkForDocumentBlur',
        },
        on: {
          REPORT_TAB_BLUR: 'userIsNotOnTab',
        },
      },
      userIsNotOnTab: {
        invoke: {
          src: 'checkForDocumentFocus',
        },
        on: {
          REPORT_TAB_FOCUS: 'userIsOnTab',
        },
      },
    },
  },
  {
    services: {
      checkForDocumentBlur: () => (send) => {
        const listener = () => {
          send('REPORT_TAB_BLUR');
        };

        window.addEventListener('blur', listener);

        return () => {
          window.removeEventListener('blur', listener);
        };
      },
      checkForDocumentFocus: () => (send) => {
        const listener = () => {
          send('REPORT_TAB_FOCUS');
        };

        window.addEventListener('focus', listener);

        return () => {
          window.removeEventListener('focus', listener);
        };
      },
    },
  },
);

When in the userIsOnTab state, we listen for the window's blur event. When that happens, and REPORT_TAB_BLUR is fired, we clean up the event listener and head right on over to userIsNotOnTab, where we fire up the other service.

Websockets

Invoked callbacks can also receive events via the onReceive function. This is perfect when you need to communicate to your service, such as sending events to websockets.

import { createMachine, forwardTo } from 'xstate';

createMachine({
  on: {
    SEND: {
      actions: forwardTo('websocket'),
    },
  },
  invoke: {
    id: 'websocket',
    src: () => (send, onReceive) => {
      const websocket = connectWebsocket();

      onReceive((event) => {
        if (event.type === 'SEND') {
          websocket.send(event.message);
        }
      });

      return () => {
        websocket.disconnect();
      };
    },
  },
});

In order to receive events, services need an id. Not all events are forwarded to the invoked service, only those which we select via the forwardTo action.

Here, we can connect to the websocket, establish two-way communication, and clean it up all in a few lines of code.

My Love Letter

Invoked callbacks are a concise, flexible method of invoking services in XState. There isn't a case they can't cover - and they're one of my favourite parts of the XState API.

XState: Should this be an action, or a service?

Matt Pocock — Fri, 30 Apr 2021 07:56:37 +0000

XState offers several ways of orchestrating side effects. Since it's a statechart tool, with significantly more power than a reducer, side effects are treated as a first-class concept.

'Side effects' as a concept spring from the idea of 'pure' functions. I.e. a function is at its best when it takes an input and returns an output. Pure functions don't tend to involve:

Waiting a set amount of time
Making an API call to an external service
Logging things to an external service

So we can think of all of the above as 'side effects' of our programme running. The name gives them a negative, medical, connotation - but really, they're the meat of your app. Apps that don't have side effects don't talk to anything external, don't worry about time, and don't react to unexpected errors.

Actions

"Thank u, next." - Ariana Grande

Side effects can be expressed in two ways in XState. First, as a fire-and-forget action. Let's imagine that when the user opens this modal, we want to report to a logging service that this happened.

const modalMachine = createMachine(
  {
    initial: 'closed',
    states: {
      closed: {
        on: {
          OPEN: 'open',
        },
      },
      open: {
        entry: ['reportThatUserOpenedTheModal'],
        on: {
          CLOSE: 'closed',
        },
      },
    },
  },
  {
    actions: {
      // Note that I'm declaring the action name above, but implementing
      // it here. This keeps the logic and implementation separate,
      // which I like
      reportThatUserOpenedTheModal: async () => {
        await fetch('/external-service/user-opened-modal');
      },
    },
  },
);

Actions are fire-and-forget, which means you can fire them off without worrying about consequences. If the action I declared above errors, my state machine won't react - it's already forgotten about it.

Actions represent a single point in time, like a dot on a graph. This means that you can place them very flexibly. Above, I've placed them on the entry attribute of the state, meaning that action will be fired when we enter the state. I could also place them on the transition:

const modalMachine = createMachine(
  {
    initial: 'closed',
    states: {
      closed: {
        on: {
          OPEN: {
            actions: 'reportThatUserOpenedTheModal',
            target: 'open',
          },
        },
      },
      open: {
        on: {
          CLOSE: 'closed',
        },
      },
    },
  },
  {
    actions: {
      reportThatUserOpenedTheModal: async () => {
        // implementation
      },
    },
  },
);

This means that whenever OPEN is called from the closed state, that action will be fired. In this modal, we could also fire the action whenever the user leaves the closed state, since we know they'll be going to the open state.

const modalMachine = createMachine(
  {
    initial: 'closed',
    states: {
      closed: {
        on: {
          OPEN: 'open',
        },
        exit: ['reportThatUserOpenedTheModal'],
      },
      open: {
        on: {
          CLOSE: 'closed',
        },
      },
    },
  },
  {
    actions: {
      reportThatUserOpenedTheModal: async () => {
        // implementation
      },
    },
  },
);

Actions are flexible precisely because we don't care about their outcome. We can hang them on the hooks our state machine gives us: transitions between states, exiting states and entering states.

Services

"And I plan to be forgotten when I'm gone..." - The Tallest Man on Earth

But actions have a specific limitation - they are designed to be forgotten. Let's imagine that you wanted to track whether the analytics call you made was successful, and only open the modal if it was. We'll add an opening state which handles that check.

const modalMachine = createMachine({
  initial: 'closed',
  states: {
    closed: {
      on: {
        OPEN: 'opening',
      },
    },
    opening: {
      entry: [
        async () => {
          await fetch('/external-service/user-opened-modal');

          // OK, this was successful - how do I get to the open state?!
        },
      ],
    },
    open: {
      on: {
        CLOSE: 'closed',
      },
    },
  },
});

This isn't possible in an action. We can't fire back an event to the machine, because it's already forgotten about us.

When you care about the result of an action, put it in a service. This is how this would be expressed as a service:

const modalMachine = createMachine({
  initial: 'closed',
  states: {
    closed: {
      on: {
        OPEN: 'opening',
      },
    },
    opening: {
      invoke: {
        // This uses the invoked callback syntax - my favourite
        // syntax for expressing services
        src: () => async (send) => {
          await fetch('/external-service/user-opened-modal');

          send('OPENED_SUCCESSFULLY');
        },
        onError: {
          target: 'closed',
        },
      },
      on: {
        OPENED_SUCCESSFULLY: {
          target: 'open',
        },
      },
    },
    open: {
      on: {
        CLOSE: 'closed',
      },
    },
  },
});

If actions are a dot on the graph, services represent a line - a continuous process which takes some amount of time. If the service errors, it'll trigger an event called error.platform.serviceName, which you can listen for with the onError attribute, as above.

Crucially, they can also send events back to the machine, using the send function above. Notice that we're both sending back the OPENED_SUCCESSFULLY event and listening to it in the on: {} attribute of the opening state.

Services are less flexible than actions, because they demand more from you. You can't hang them on every hook your machine offers. They must be contained within one state, and they're cancelled when you leave that state. (Note: they can also be at the root of the machine definition, meaning they run for the lifetime of the machine.)

Guidelines

Actions are the 'thank u, next' of the XState world. They represent points in time. Use them for fire-and-forget actions. Actions are great for:

console.log
Showing ephemeral error or success messages (toasts)
Navigating between pages
Firing off events to external services or parents of your machine

Services are like a 'phase' your machine goes through. They represent a length of time. Use them for processes where you care about the outcome, or you want the process to run for a long time. Services are great for:

API calls
Event listeners (window.addEventListener)

State Machines: Should this be a state, or in context?

Matt Pocock — Thu, 29 Apr 2021 07:54:37 +0000

State machines offer several API's for expressing state. Like other tools, you can keep arbitrary values in a store (usually expressed as an object) called context.

This is handy for values which change over time and you need to keep updated, like the value of a form input:

import { createMachine, assign } from 'xstate';

const machine = createMachine({
  context: {
    name: '',
  },
  on: {
    CHANGE_NAME: {
      actions: assign((context, event) => {
        return {
          name: event.value,
        };
      }),
    },
  },
});

Every time the CHANGE_NAME event is sent to the machine, we'll update the value in context. We can then use that value to display the value in our UI or send it to an API.

XState also gives you another way of expressing state - through finite states. Let's imagine a modal:

const machine = createMachine({
  initial: 'closed',
  states: {
    closed: {
      on: {
        OPEN: 'open',
      },
    },
    open: {
      on: {
        CLOSE: 'close',
      },
    },
  },
});

Here, the modal's state is expressed through the states: {} attribute, which also defines which events can be received during each state. You can only CLOSE the modal when it's open, and vice versa.

Which should I choose?

The choice between using context and states isn't always clear. For instance, the modal machine above could be expressed using context:

const machine = createMachine({
  context: {
    isOpen: false,
  },
  on: {
    OPEN: {
      actions: assign({ isOpen: true }),
    },
    CLOSE: {
      actions: assign({ isOpen: false }),
    },
  },
});

This gives you exactly the same functionality as the states-based one above - you can track when the modal is open and closed, and send the same events.

The reason this can be expressed using both states and context is because all of the events do the same thing no matter what state you're in. There are no events you need to declare as impossible in certain states.

To show you what I mean, let's imagine a form input inside a modal. We only want to allow changes to the form input while the modal is open.

const machine = createMachine({
  initial: 'closed',
  context: {
    name: '',
  },
  states: {
    closed: {
      on: {
        OPEN: 'open',
      },
    },
    open: {
      on: {
        CLOSE: 'close',
        CHANGE_NAME: {
          actions: assign((context, event) => {
            return {
              name: event.value,
            };
          }),
        },
      },
    },
  },
});

When the modal is in the closed state, the CHANGE_NAME event will not change the value in context. State machines are great at this - only allowing the things you want to happen to happen. Some other examples might be:

Not allowing users to submit a form while the previous API call is loading
Only allowing users to log in if they're not already logged in

Putting things in context

You might be wondering - but, I can express the above in context!

const machine = createMachine({
  context: {
    name: '',
    isOpen: false,
  },
  on: {
    OPEN: { actions: assign({ isOpen: true }) },
    CLOSE: { actions: assign({ isOpen: false }) },
    CHANGE_NAME: {
      actions: assign((context, event) => {
        // This acts as the guard to prevent editing
        // the name while it's open
        if (!context.isOpen) return {};
        return {
          name: event.value,
        };
      }),
    },
  },
});

I think this is incorrect for two reasons. First, as requirements grow, so will the complexity of your logic. Let's imagine that the modal can now be either closing (i.e. animating out) or closed. We'll soon see an explosion of booleans, as I discussed in this article on useState/useReducer.

Second, XState is auto-documenting via the XState visualiser. The more your logic is expressed in states, the easier it's going to be to visualise. The machine above is basically a single state with its logic expressed in ways that XState can't visualise.

Rules to live by

You should be keeping most of your state in context. That includes form values, API data - anything which cannot be expressed finitely.

But state machines are powerful because of their states. Use states when you want to express your logic visually, or gate events to certain states.

XState: What's the difference between Machine and createMachine?

Matt Pocock — Wed, 28 Apr 2021 07:51:16 +0000

XState offers two options for declaring machine definitions:

import { Machine } from 'xstate';

const machine = Machine({ ...config });

...or...

import { createMachine } from 'xstate';

const machine = createMachine({ ...config });

This can be confusing for beginners. Why are there two very similar-looking methods? What's the difference?

The Difference

In Javascript, there is no difference between the two. You can use them completely interchangeably.

In Typescript, there is only a small difference between them - it's to do with the ordering of the generics you can pass to the machine. Machine allows you to pass a generic called 'Typestates' in the middle of the Context and Event generics.

import { Machine } from 'xstate';

interface Context {}

type Event = { type: 'EVENT_NAME' }

type States = {}

const machine = Machine<Context, States, Event>({ ...config });

Whereas createMachine asks you to insert it at the end:


import { createMachine } from 'xstate';

interface Context {}

type Event = { type: 'EVENT_NAME' }

type States = {}

const machine = createMachine<Context, Event, States>({ ...config });

Whichever you choose, there is no functional difference in the created machine. The two functions reference the same code, and create the machine in the same way.

What should I choose?

Going forward, you should use createMachine. That's the syntax that will be preferred when v5 releases. But if you're happy with Machine, you can keep using it.

"Just Use Props": An opinionated guide to React and XState

Matt Pocock — Mon, 11 Jan 2021 22:03:57 +0000

XState can feel overwhelming. Once you've gone through Kyle or David's courses and read through the docs, you'll get a thorough understanding of the API. You'll see that XState is the most powerful tool available for managing complex state.

The challenge comes when integrating XState with React. Where should state machines live in my React tree? How should I manage parent and child machines?

// Detect dark theme var iframe = document.getElementById('tweet-1345085887026106368-591'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1345085887026106368&theme=dark" }

Just Use Props

I'd like to propose an architecture for XState and React which prioritises simplicity, readability and type-safety. It's incrementally adoptable, and gives you a base for exploring more complex solutions. We've used it at Yozobi in production, and we're planning to use it for every project moving forward.

It's called just use props. It's got a few simple rules:

Create machines. Not too many. Mostly useMachine
Let React handle the tree
Keep state as local as possible

Create machines. Not too many. Mostly useMachine

The simplest way to integrate a state machine in your app is with useMachine.



import { createMachine, interpret } from 'xstate';
import { useMachine } from '@xstate/react';

const machine = createMachine({
  initial: 'open',
  states: {
    open: {},
    closed: {},
  },
});

const Component = () => {
  const [state, send] = useMachine(machine);

  return state.matches('open') ? 'Open' : 'Closed';
};

Note that this puts React in charge of the machine. The machine is tied to the component, and it obeys all the normal React rules of the data flowing down. In other words, you can think of it just like useState or useReducer, but a vastly improved version.

Let React handle the tree

Let's say you have a parent component and a child component. The parent has some state which it needs to pass to the child. There are several ways to do this.

Passing services through props

The first is to pass a running service to the child which the child can subscribe to:



import { useMachine, useService } from '@xstate/react';
import { createMachine, Interpreter } from 'xstate';

/**
 * Types for the machine declaration
 */
type MachineContext = {};
type MachineEvent = { type: 'TOGGLE' };

const machine = createMachine<MachineContext, MachineEvent>({});

const ParentComponent = () => {
  /**
   * We instantiate the service here...
   */
  const [state, send, service] = useMachine(machine);

  return <ChildComponent service={service} />;
};

interface ChildComponentProps {
  service: Interpreter<MachineContext, any, MachineEvent>;
}

const ChildComponent = (props: ChildComponentProps) => {
  /**
   * ...and receive it here
   */
  const [state, send] = useService(props.service);

  return (
    <button onClick={() => send('TOGGLE')}>
      {state.matches('open') ? 'Open' : 'Closed'}
    </button>
  );
};

I don't like this pattern. For someone not used to XState, it's unclear what a 'service' is. We don't get clarity from reading the types, which is a particularly ugly Interpreter with multiple generics.

The machine appears to bleed across multiple components. Its service seems to have a life of its own, outside of React's tree. To a newbie, this feels like misdirection.

Just pass props

This can be expressed much more cleanly using props:



import { useMachine } from '@xstate/react';
import { createMachine } from 'xstate';

/**
 * Types for the machine declaration
 */
type MachineContext = {};
type MachineEvent = { type: 'TOGGLE' };

const machine = createMachine<MachineContext, MachineEvent>({});

const ParentComponent = () => {
  const [state, send] = useMachine(machine);

  return (
    <ChildComponent
      isOpen={state.matches('open')}
      toggle={() => send('TOGGLE')}
    />
  );
};

/**
 * Note that the props declarations are
 * much more specific
 */
interface ChildComponentProps {
  isOpen: boolean;
  toggle: () => void;
}

const ChildComponent = (props: ChildComponentProps) => {
  return (
    <button onClick={() => props.toggle()}>
      {props.isOpen ? 'Open' : 'Closed'}
    </button>
  );
};

Much better. We get several improvements in clarity in the ChildComponent - the types are much easier to read. We get to ditch the use of Interpreter and useService entirely.

The best improvement, though, is in the ParentComponent. In the previous example, the machine crossed multiple components by passing its service around. In this example, it's scoped to the component, and props are derived from its state. This is far easier to grok for someone unused to XState.

Keep state as local as possible

Unlike tools which require a global store, XState has no opinion on where you keep your state. If you have a piece of state which belongs near the root of your app, you can use React Context to make it globally available:



import React, { createContext } from 'react';
import { useMachine } from '@xstate/react';
import { createMachine } from 'xstate';

const globalMachine = createMachine({});

interface GlobalContextType {
  isOpen: boolean;
  toggle: () => void;
}

export const GlobalContext = createContext<GlobalContextType>();

const Provider: React.FC = ({ children }) => {
  const [state, send] = useMachine(globalMachine);

  return (
    <GlobalContext.Provider
      value={{ isOpen: state.matches('open'), toggle: () => send('TOGGLE') }}
    >
      {children}
    </GlobalContext.Provider>
  );
};

Just as above, we're not passing a service, but props, into context.

If you have a piece of state which needs to belong lower in your tree, then obey the usual rules by lifting state up to where it's needed.

If that feels familiar, you're right. You're making the same decisions you're used to: where to store state and how to pass it around.

Examples and challenges

Syncing parents and children

Sometimes, you need to use a parent machine and a child machine. Let's say that you need the child to pay attention to when a prop changes from the parent - for instance to sync some data. Here's how you can do it:



const machine = createMachine({
  initial: 'open',
  context: {
    numberToStore: 0,
  },
  on: {
    /**
     * When REPORT_NEW_NUMBER occurs, sync
     * the new number to context
     */
    REPORT_NEW_NUMBER: {
      actions: [
        assign((context, event) => {
          return {
            numberToStore: event.newNumber,
          };
        }),
      ],
    },
  },
});

interface ChildComponentProps {
  someNumber: number;
}

const ChildComponent = (props: ChildComponentProps) => {
  const [state, send] = useMachine(machine);

  useEffect(() => {
    send({
      type: 'REPORT_NEW_NUMBER',
      newNumber: props.someNumber,
    });
  }, [props.someNumber]);
};

This can also be used to sync data from other sources, such as query hooks:



const ChildComponent = () => {

  const [result] = useSomeDataHook(() => fetchNumber());

const [state, send] = useMachine(machine);

useEffect(() => {

    send({

      type: 'REPORT_NEW_NUMBER',

      newNumber: result.data.someNumber,

    });

  }, [result.data.someNumber]);

};

Summary

In the "just use props" approach, XState lets React take charge. We stick to idiomatic React by passing props, not services. We keep machines scoped to components. And we put state at the level it's needed, just like you're used to.

This article isn't finished. I'm sure there will be many more questions about integrating XState with React. My plan is to come back to this article again with more examples and clarifications. Thanks for your time, and I'm looking forward to seeing what you build with XState.

Test Driven Development with Sextant

Matt Pocock — Mon, 16 Nov 2020 13:49:39 +0000

Test-Driven-Development with Sextant

TL;DR: Using Sextant for Test Driven Development (TDD) is heavenly. You can plan and document business requirements visually, generate mock fixtures, and get coverage reports based on desired functionality instead of lines of code.

What is Sextant?

Sextant is a tool that lets you plan your application, then generate code from those plans. This makes app development faster, ensures up-to-date documentation, and makes refactoring simple and visual.

In this article, we'll be building a simple function for fetching a user from our Auth server. We'll be using Typescript and Jest.

Check out the Sextant docs for more information on what Sextant can do.

What are we building?

We're going to build a function to fetch a user from our Auth server. We'll call the Auth server Cognito, and our function Lambda.

Our lambda needs to handle three scenarios:

We successfully fetch a user from Cognito
The user can't be found
The user who's doing the fetching doesn't have permission

Setup

Create a project of your choice with Typescript and Jest set up. create-react-app is a fine choice.
Run yarn add sextant @sextant-tools/plugin-jest to install Sextant, and a plugin for use with Jest.
Run yarn sextant ./src to start the Sextant GUI on http://localhost:3000.

This will have created a sextant.config.js file at the ./src directory. Change the file to look like this:

// sextant.config.js

module.exports = {
  plugins: ['@sextant-tools/plugin-jest'],
};

Cancel the terminal running yarn sextant ./src and restart it.

Congratulations! You're ready to start building.

Planning our tests

We now need to plan out our 'Get User' feature in the Sextant GUI.

Success Case

A successful call happens when the lambda sends a GET_USER event to cognito, and Cognito responds with a USER event. We can diagram that like this:

Not Found Case

Things won't always succeed, though. Sometimes, we'll provide some incorrect information, and Cognito will reply with a NOT_FOUND event.

You can press the Duplicate button at the top right of the "Success" panel to quickly duplicate a scenario.

No Permission Case

Things can fail in another way, too. The user who's trying to get the information might not have permission to do so. In that case, Cognito will reply with a NO_PERMISSION event.

Events

In Sextant, events can carry information. Our GET_USER event needs to ask for a specific user, so let's handle that by giving it an id payload. These are defined in GraphQL syntax, in the 'Event Payloads' panel to the right.

type GET_USER {
  id: ID!
}

Our USER event will also need to fire back some information about the user we fetched:

type USER {
  id: ID!
  name: String!
  email: String!
}

Setting up our test

Since TDD is all about writing tests before you start writing code, let's start there.

Create a ./src/__tests__/getUser.test.ts file.
You'll notice that Sextant has now generated several files inside your src directory. Find the file with jest in the name, and import it into your test file:

// getUser.test.ts
import { describeSextantFeature } from '../sextant-jest.generated';

Let's use that function to describe our Sextant feature, and bootstrap a test for the success case:

// getUser.test.ts
import { describeSextantFeature } from '../sextant-jest.generated';

describeSextantFeature('getUser', (feature) => {
  feature.test('success', () => {
    // We'll test the success case in here
  });

  feature.test('notFound', () => {
    // We'll test the notFound case in here
  });

  feature.test('noPermission', () => {
    // We'll test the noPermission case in here
  });

  feature.testCoverage();
});

describeSextantFeature

describeSextantFeature works like a describe block in Jest. Anything tested within it corresponds to the feature being described.

The feature object which describeSextantFeature makes available gives you some methods for testing, and testing coverage.

feature.test() works like a test block. You can make assertions inside to ensure the scenario described works as expected.

feature.testCoverage() gives you coverage reports based on what you've described in Sextant. This fails if it detects a scenario in Sextant which isn't covered by the tests.

Mocking our function

Let's quickly mock our function so that we have something to test. Create a file at ./src/getUser.ts containing the following:

// src/getUser.ts

const getUser = () => {};

We can type the file with Typescript to ensure that our function corresponds to what we've declared in Sextant. Let's use the SextantHandler type, which is exported from sextant-types.generated.d.ts.

// src/getUser.ts
import { SextantHandler } from './sextant-types.generated';

const getUser: SextantHandler<'getUser', 'lambda', 'cognito'> = () => {};

SextantHandler is a type that takes in three generics. getUser corresponds to which feature it's handling. The last two generics are where the events flow from (lambda) and to (cognito).

In other words, the getUser function handles events from lambda to cognito, and can return a response from cognito to lambda at the end.

Using mockSextantEvent

We can mock our function using fixtures generated by Sextant. For now, let's mock that the function always succeeds by returning a USER event:

// src/getUser.ts
import { SextantHandler } from './sextant-types.generated';
import { mockSextantEvent } from './sextant-fixture-mock.generated';

const getUser: SextantHandler<'getUser', 'lambda', 'cognito'> = () => {
  return mockSextantEvent('getUser', 'USER');
};

mockSextantEvent returns a javascript object that corresponds to what we declared in our Event Payloads in the Sextant GUI. For instance, this payload declaration:

type USER {
  id: ID!
  name: String!
  email: String!
}

Results in this object being generated:

{
  "type": "USER",
  "id": "d99c9580-cb80-4518-9d2c-5472fd4ff675",
  "name": "random-string",
  "email": "another-random-string"
}

mockSextantEvent is exceptionally useful because it stays up to date with what you declare in Sextant. This means you can focus on how your app should work, not maintaining fixture files.

Writing the tests

Now that our function is mocked, we can start testing it:

// getUser.test.ts
import { describeSextantFeature } from '../sextant-jest.generated';
import { getUser } from './getUser';

describeSextantFeature('getUser', (feature) => {
  feature.test('success', async () => {
    const result = await getUser(feature.mockEvent('GET_USER'));

    // Expect that the event is of type USER
    expect(result.type).toEqual('USER');
  });

  feature.test('notFound', async () => {
    const result = await getUser(
      feature.mockEvent('GET_USER', { id: 'an-id-which-does-not-exist' }),
    );

    // Expect that the event is of type NOT_FOUND
    expect(result.type).toEqual('NOT_FOUND');
  });

  feature.test('noPermission', async () => {
    const result = await getUser(
      feature.mockEvent('GET_USER', {
        id: 'an-id-which-you-do-not-have-permission-to-view',
      }),
    );

    // Expect that the event is of type NO_PERMISSION
    expect(result.type).toEqual('NO_PERMISSION');
  });

  feature.testCoverage();
});

The notFound and noPermission cases will fail, because we are returning a mocked USER event from our function. If we were to continue developing this, we'd need to use a mocker like jest.mock to test how the function performed when things failed. But let's leave it here for now.

feature.mockEvent

feature.mockEvent is exactly like mockSextantEvent, but scoped only to events in that feature. We're also using a second parameter to override specific attributes of the event: { id: 'a-specific-id' }

Next steps

Our function is now ready to be implemented!

We've laid out our test files
We've worked out the cases we want to test
We've mocked our function with a success case

But more importantly, we know exactly why we're testing each case, and we've documented it visually in Sextant.

What we've learned

Sextant can supercharge your testing approach in a number of ways.

Tests are self-documenting

With Sextant, every test you write has a specific, documented purpose. This helps when scoping how many tests to write - each test must apply to a specific scenario, so you can't write useless, or duplicate tests.

Meaningful coverage metrics

Using feature.testCoverage() means your tests fail when a documented scenario is missing. This gives you confidence that all your app's behaviour is documented, tested and implemented according to an agreed-upon spec.

Tests are tied to business requirements

If your business requirements change, your tests need to change too. Without Sextant, this can be difficult to track and often needs manual maintenance.

With Sextant, this process is automatic. When you delete a scenario, any feature.test blocks which specify that scenario will fail. When you add or update one, your testCoverage() functions fail.

Thanks for reading!

Sextant is in early days, but I'm excited to bring you more articles about how to use it. The ability to take application charts and turn them into type-safe code has enormous potential. You can learn how to build your own plugins here.

Follow along on GitHub, or check out a live demo of Sextant. I can't wait to see what you do with it.

XState Brain Teaser #1 - Auth Flow

Matt Pocock — Fri, 09 Oct 2020 08:19:54 +0000

It's time for the first XState brain teaser! Let's get our heads together and work out the best state machine solution to this problem:

// Detect dark theme var iframe = document.getElementById('tweet-1314480129628876801-600'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1314480129628876801&theme=dark" }

Good luck!

Type-safe routing with Typescript and Route Maps

Matt Pocock — Wed, 29 Jul 2020 21:03:28 +0000

Routing in web apps can be a subtle, but persistent source of bugs. You think you've updated every reference to a route you're changing, and BAM. You've caused a bug in some unrelated part of your app.

This gets worse when you need to add path parameters (/user/:id/edit) and search parameters (/auth?redirectPath=somewhere). Usually, this leads to a ton of string concatenation clogging up your code, and a mess of routes that are hard to maintain.

That's why I built make-route-map, an npm package which helps get your routing under control. It's 100% Typescript, and it lets you create a gorgeous, clean API for your routing which has type-safe routes, path parameters and search parameters.

I can't tell you how much stress it's saved me already. Refactoring or removing a route no longer takes dozens of find-in-files to remove the references. All that stress is Typescripted away.

The Basics

import { makeRouteMap } from 'make-route-map';

const routeMap = makeRouteMap({
  users: {
    path: '/users',
  },
  editUser: {
    path: '/users/:id/edit',
    params: {
      id: true,
    },
  },
  auth: {
    path: '/auth',
    search: {
      redirectPath: true,
    },
  },
});

console.log(routeMap.users());
// '/users'

console.log(routeMap.editUser({ params: { id: '240' } });
// '/users/240/edit'

console.log(
  routeMap.auth({
    search: { redirectPath: 'somewhere' },
  }),
);
// /auth?redirectPath=somewhere

The makeRouteMap function just creates a set of helpers which pull out the routes. You can pass in path parameters and search parameters.

Navigating

makeNavigate can take in a routeMap and a function to send you to a route, and will navigate you there when it's called.

const goToRoute = route => {
  window.location.href = route;
};

const navigate = makeNavigate(routeMap, goToRoute);

// This would take the user to '/users/240/edit'
navigate.editUser({
  params: {
    id: '240',
  },
});

This means you can plug in navigate into your current navigation implementation, like history.push.

Try it out

The repo
The package

Let me know how you get on, and if you have any requests for the API. I'm so excited to have a pattern that's been working wonders for us public available.

useState vs useReducer vs XState - Part 1: Modals

Matt Pocock — Tue, 28 Jul 2020 15:31:28 +0000

Managing state at different levels of complexity is hard. Different tools make different trade-offs between readability, complexity and speed of development. The worst part is that as apps get more complex, it's easy to regret choices that were made early on.

This series of articles should help you make the right choice off the bat. The plan is to cover a bunch of state use cases, starting with the simple and graduating to more complexity as we go. We'll see how easy they are to write, and also how they survive changing requirements.

Today, we're starting with modals.

useState

For modals, the key piece of state is whether or not the modal is open. useState lets us capture that single piece of state pretty succinctly.

const [isOpen, setIsOpen] = useState(false);

const open = () => {
  setIsOpen(true);
};

const close = () => {
  setIsOpen(false);
};

const toggle = () => {
  setIsOpen(!isOpen);
};

Highly readable, simple enough, fast to write, bug-proof. For a simple toggle like this, useState is great.

useReducer

const reducer = (state = { isOpen: false }, action) => {
  switch (action.type) {
    case 'OPEN':
      return {
        isOpen: true,
      };
    case 'CLOSE':
      return {
        isOpen: false,
      };
    case 'TOGGLE':
      return {
        isOpen: !state.isOpen,
      };
    default:
      return state;
  }
};

const [state, dispatch] = useReducer(reducer, { isOpen: false });

const open = () => {
  dispatch({ type: 'OPEN' });
};

const close = () => {
  dispatch({ type: 'CLOSE' });
};

const toggle = () => {
  dispatch({ type: 'TOGGLE' });
};

useReducer gives us a reducer, a powerful centralized spot in our code where we can visualise the changes happening. However, it took us quite a few more lines of code to reach the same result as useState. For now, I'd say useState has the edge.

useMachine

useMachine is a hook from XState, which allows us to use the power of state machines in our code. Let's see how it looks.

const machine = Machine({
  id: 'modalMachine',
  initial: 'closed',
  states: {
    closed: {
      on: {
        OPEN: {
          target: 'open',
        },
        TOGGLE: 'open',
      },
    },
    open: {
      on: {
        TOGGLE: 'closed',
        CLOSE: 'closed',
      },
    },
  },
});

const [state, send] = useMachine(machine);

const open = () => {
  send({ type: 'OPEN' });
};

const close = () => {
  send({ type: 'CLOSE' });
};

const toggle = () => {
  send({ type: 'TOGGLE' });
};

You can see the state machine on the XState visualiser here.

It's remarkably similar in structure to the reducer above. Similar amount of lines, nearly the same event handlers. The state machine takes the edge over the reducer because of being able to easily visualise its logic - that's something the reducer can't match.

However, the useState implementation still has the edge for me. The simplicity of execution, the elegance. It's hard to see how it could be beaten...

ALERT: REQUIREMENTS CHANGING

Oh no. Requirements have changed. Now, instead of immediately closing, the modal needs to animate out. This means we need to insert a third state, closing, which we automatically leave after 500ms. Let's see how our implementations hold up.

useState

Refactor 1: Our initial isOpen boolean won't handle all the states we need it to any more. Let's change it to an enum: closed, closing and open.

Refactor 2: isOpen is no longer a descriptive variable name, so we need to rename it to modalState and setModalState.

Refactor 3: useState doesn't handle async changes by itself, so we need to bring in useEffect to run a timeout when the state is in the closing state. We also need to clear the timeout if the state is no longer closing.

Refactor 4: We need to change the toggle event handler to add logic to ensure it only triggers on the closed and open states. Toggles work great for booleans, but become much harder to manage with enums.

// Refactor 1, 2
const [modalState, setModalState] = useState('closed');

// Refactor 3
useEffect(() => {
  if (modalState === 'closing') {
    const timeout = setTimeout(() => {
      setModalState('closed');
    }, 500);
    return () => {
      clearTimeout(timeout)
    }
  }
}, [modalState]);

// Refactor 1, 2
const open = () => {
  setModalState('open');
};

// Refactor 1, 2
const close = () => {
  setModalState('closing');
};

// Refactor 1, 2, 4
const toggle = () => {
  if (modalState === 'closed') {
    setModalState('open');
  } else if (modalState === 'open') {
    setModalState('closing');
  }
};

Yuck. That was an enormous amount of refactoring to do just to add a simple, single requirement. On code that might be subject to changing requirements, think twice before using useState.

useReducer

Refactor 1: Same as above - we turn the isOpen boolean to the same enum.

Refactor 2: Same as above, isOpen is now improperly named, so we need to change it to status. This is changed in fewer places than useState, but there are still some changes to make.

Refactor 3: The same as above, we use useEffect to manage the timeout. An additional wrinkle is that we need a new action type in the reducer, REPORT_ANIMATION_FINISHED, to cover this.

** Refactor 4**: The same as above, but instead of the logic being in the event handler, we can actually change the logic inside the reducer. This is a cleaner change, but is still similar in the amount of lines it produces.

// Refactor 1, 2
const reducer = (state = { status: 'closed' }, action) => {
  switch (action.type) {
    // Refactor 2
    case 'OPEN':
      return {
        status: 'open',
      };
    // Refactor 2
    case 'CLOSE':
      return {
        status: 'closing',
      };
    // Refactor 3
    case 'REPORT_ANIMATION_FINISHED':
      return {
        status: 'closed',
      };
    // Refactor 4
    case 'TOGGLE':
      switch (state.status) {
        case 'closed':
          return {
            status: 'open',
          };
        case 'open':
          return {
            status: 'closing',
          };
      }
      break;
    default:
      return state;
  }
};

// Refactor 1
const [state, dispatch] = useReducer(reducer, { status: 'closed' });

// Refactor 3
useEffect(() => {
  if (state.status === 'closing') {
    const timeout = setTimeout(() => {
      dispatch({ type: 'REPORT_ANIMATION_FINISHED' });
    }, 500);
    return () => {
      clearTimeout(timeout);
    };
  }
}, [state.status]);

const open = () => {
  dispatch({ type: 'OPEN' });
};

const close = () => {
  dispatch({ type: 'CLOSE' });
};

const toggle = () => {
  dispatch({ type: 'TOGGLE' });
};

This file required the same number of refactors as the useState implementation. One crucial advantage is that these refactors were mostly located together: most changes occurred inside the reducer, and the event handlers went largely untouched. For me, this gives useReducer the edge over useState.

useMachine

Refactor 1: Add a new closing state, which after 500 milliseconds goes to the closed state.

Refactor 2: Changed the targets of the TOGGLE and CLOSE actions to point at closing instead of closed.

export const machine = Machine({
  id: 'modalMachine',
  initial: 'closed',
  states: {
    closed: {
      on: {
        OPEN: {
          target: 'open',
        },
        TOGGLE: 'open',
      },
    },
    // Refactor 1
    closing: {
      after: {
        500: 'closed',
      },
    },
    open: {
      on: {
        // Refactor 2
        TOGGLE: 'closing',
        CLOSE: 'closing',
      },
    },
  },
});

const [state, send] = useMachine(machine);

const open = () => {
  send({ type: 'OPEN' });
};

const close = () => {
  send({ type: 'CLOSE' });
};

const toggle = () => {
  send({ type: 'TOGGLE' });
};

See the changed machine here.

The difference here is stark. A minimal number of refactors, all within the state machine itself. The amount of lines has hardly changed. None of the event handlers changed. AND we have a working visualisation of the new implementation.

Conclusion

Before the requirements changed, useState was the champion. It's faster, easier to implement, and fairly clear. useReducer and useMachine were too verbose, but useMachine took the edge by being easier to visualise.

But after the requirements changed, useState hit the floor. It quickly became the worst implementation. It was the hardest to refactor, and its refactors were in the most diverse places. useReducer was equally hard to refactor, with the same set of changes. useMachine emerged as the champion, with a minimal diff required to build in new, complex functionality.

So if you're looking to build a modal fast, use useState. If you want to build it right, use useMachine.

I'm excited to work on this set of articles - I'm looking forward to tackling the toughest state models out there. What would you like to see covered in the next one? Some ideas:

Data fetching
Form state
Multi-step sequences (checkout flows, signup flows)

Let me know in the comments below, and follow me for the next article!