Strongly-typed finite-state machines with Redux and TypeScript

Oliver Joseph Ash
Sep 10, 2018 · 3 min read

Finite-state machines have been all the rage recently. There are many libraries that allow you to work with finite-state machines. However, I wondered: how far can we get with our existing tools — Redux and the reducer pattern?

Note that this article is not concerned with why finite-state machines are useful. If you’re interested in learning about why they are useful, I recommend David Khourshid’s talk “Simplifying Complex UIs with Finite Automata & Statecharts”.

Reducer is a state machine

At the core of state machines is the following function:

If you’re familiar with Redux, that might look familiar to you. A Redux reducer function is a state machine! A reducer function describes how the machine should transition, given the previous state and an action (aka an event in statechart terminology), to the next state.

This article is interested in how we can utilise Redux to write a strongly-typed finite-state machine, in the interests of code correctness and readability. By finite, we mean that the machine may only be in one of a finite number of states at any given time. By strongly-typed, we mean that the states and actions should carry the types of their parameters, and these parameters should only be accessible when we’ve narrowed the union of states or actions to a single variant.

The examples in this article are available on GitHub.

Setting the scene

Throughout this article we will use the example of a simple photo gallery search. The application starts in a Form state, where the user may enter a query. Upon form submission the Search event is triggered, and the application should transition into a Loading state. When request either fails or succeeds, corresponding events SearchFailure and SearchSuccess are triggered the application should transition into the Failed or Success states, respectively. We can represent this as a statechart diagram:

Generated via


To begin we must define some basic types and helpers which we’ll need to use later on:

Defining states

Our State type is a tagged union of all the possible state variants. By expressing our state as a union, we're defining which states are valid. Later we'll use these states to define which transitions are valid.

Note how the query parameter is only available in the Loading state, and the items parameter is only available in the Gallery state. By restricting these parameters so that they only exist in their corresponding states, we are making impossible states impossible: the type system only allows us to access the parameters when we are in a state where they can exist.

(Note there are cleaner ways to define tagged unions in TypeScript, but I refrained from using them in this example for simplicity. See the note at the end.)

Defining actions

Our Action type is a tagged union of all the possible action variants.

Defining transitions

Earlier we saw how Redux’s reducer functions allow us to describe our state transitions. As well how the transition should be performed, we can define which transitions are valid for given states. For example, a valid transition would be from a Loading state, given a SearchFailure event, to the Failed state—but the SearchFailure event should not cause a transition when we're in the Form state.

Tying it all together

To demonstrate our state machine, we can simulate actions. In a real world application, these would be driven by outside events such as user interactions or HTTP responses.

This produces the following output in the console:

Going further

There is much more to state machines than this example demonstrates. However, the simple primitive of a reducer allows for all types of state machines. For example, “nested state machines” can simply be modelled as nested reducers. Likewise, “parallel state machines” are just combined reducers.

Our Action and State types are known as tagged union types. There are much cleaner ways of defining and using tagged union types in TypeScript, but I refrained from using them in this example for simplicity. At Unsplash we tend to use Unionize. For example, here is how we might define the Action tagged union type if we were to use Unionize:

A full example using Unionize can be seen at

If you like how we do things at Unsplash, consider joining us!

Unsplash Blog

Behind the scenes building the open photography movement at…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store