6 minImpossible States, part 2

Prevent Impossible States Pt. 2 - State Transitions

Model a timer's states and events with TypeScript unions, then define the rules for moving between them.

This post builds on discriminated unions. They let us describe valid state shapes, but on their own, they don’t define which state transitions are valid.

To define those rules, we can use a finite state machine (FSM).1

If you’ve ever seen a traffic light, then you’re already acquainted with FSMs. Consider a simple traffic light and its three states: Green, Yellow, Red.

State diagram: green goes to yellow, yellow goes to red, and red goes back to green, each on the timer event. timertimertimerGreenYellowRed

green

Each time the traffic light receives a timer event, it moves to the next state: green to yellow, yellow to red, and red back to green.

It’s called a finite state machine because the model has a fixed, finite set of states. We can then use this knowledge to define which state transitions are allowed.

The best way to learn is by doing, so let’s create our own finite state machine: a timer with four statuses, idle, running, paused, and finished.

Below we have the events and their corresponding state transitions:

EventFromTo
Startidlerunning
Pauserunningpaused
Resumepausedrunning
Tickrunningrunning while time remains, or finished when the last second elapses
Resetany stateidle

The impact of an event depends on the current state. Dispatching a start event to an idle timer moves its status to running. A pause event moves a running timer to paused.

Timer state diagram. start moves idle to running. tick keeps running, or moves it to finished on the last second. pause moves running to paused, and resume moves paused back to running. reset moves any state to idle. startpauseresumeticktick, 1s leftresetresetresetidlerunningpausedfinished

Send an event

{ status: 'idle' }

This runs the transition function from this post. Send an event the rules don’t allow, like pause while idle, and the state stays the same.

Defining states and events

To model our timer, we’ll create two tagged unions.

The first, TimerState, describes our timer’s status and its data at a specific point in time. The second, TimerEvent, defines the events we can send to it.

type TimerState =
  | { status: 'idle' }
  | { status: 'running'; remainingSeconds: number }
  | { status: 'paused'; remainingSeconds: number }
  | { status: 'finished' };

type TimerEvent =
  | { type: 'start'; durationSeconds: number }
  | { type: 'pause' }
  | { type: 'resume' }
  | { type: 'tick' }
  | { type: 'reset' };

We’ll use both unions together to create our state machine, with a strict set of rules for transitioning between states.

In our model, remainingSeconds is required when a timer’s status is running or paused, and it isn’t part of the other cases. The object literals below therefore produce type errors.

State shapesTypeScript 5.9.3 · strict
type TimerState =
  | { status: 'idle' }
  | { status: 'running'; remainingSeconds: number }
  | { status: 'paused'; remainingSeconds: number }
  | { status: 'finished' };

// An idle timer has no remaining time.
const bad: TimerState = { status: 'idle', remainingSeconds: 5 };

// A running timer must say how much time is left.
const bad2: TimerState = { status: 'running' };

console.log(bad, bad2);

Modeling enforceable transitions

An idle state with a pause event results in nothing happening. The transition function just returns the current state, because start is the only event that moves an idle timer into another status. Our rules are listed below.

Current stateEventResult
idlestartrunning, with remainingSeconds taken from the event’s durationSeconds
runningpausepaused, keeping remainingSeconds
pausedresumerunning, keeping remainingSeconds
runningtickrunning with one second less, or finished when the last second elapses
anyresetidle
anything elseunchanged

Our function accepts any TimerState with any TimerEvent, so the implementation has to enforce the transition rules we’ve defined.

Writing the transition function

With our data modeled, we can describe our transition function using mathematical notation:

δ:S×E→S\delta : S \times E \to S

We use δ (delta) to represent our transition function. It takes two inputs: a current state from the set S and an event from the set E. The × groups those inputs into a state–event pair, and → S tells us that the function returns a timer state.

For example, a running timer with two seconds remaining and a tick event produces a running timer with one second remaining. The returned state can also be unchanged, as when an idle timer receives a pause event.

In TypeScript, we express the same signature like this:

type Transition = (state: TimerState, event: TimerEvent) => TimerState;

We can use Transition to type our implementation:

const transition: Transition = (state, event) => {
  if (event.type === 'reset') {
    return { status: 'idle' };
  }

  switch (state.status) {
    case 'idle':
      return event.type === 'start'
        ? { status: 'running', remainingSeconds: event.durationSeconds }
        : state;

    case 'running':
      switch (event.type) {
        case 'pause':
          return { status: 'paused', remainingSeconds: state.remainingSeconds };
        case 'tick':
          return state.remainingSeconds > 1
            ? { status: 'running', remainingSeconds: state.remainingSeconds - 1 }
            : { status: 'finished' };
        default:
          return state;
      }

    case 'paused':
      return event.type === 'resume'
        ? { status: 'running', remainingSeconds: state.remainingSeconds }
        : state;

    case 'finished':
      return state;

    default: {
      const unreachable: never = state;
      return unreachable;
    }
  }
};

In JavaScript land, we’re used to finishing a reducer with default: return state. In the outer switch here, though, we’re checking state.status, so we can use never to ensure that every status in TimerState has a corresponding case. If we add a status without handling it, TypeScript reports a type error.

Exhaustive switchTypeScript 5.9.3 · strict
type TimerState =
  | { status: 'idle' }
  | { status: 'running'; remainingSeconds: number }
  | { status: 'paused'; remainingSeconds: number }
  | { status: 'finished' }
  | { status: 'cancelled' };

type TimerEvent =
  | { type: 'start'; durationSeconds: number }
  | { type: 'pause' }
  | { type: 'resume' }
  | { type: 'tick' }
  | { type: 'reset' };

const transition = (state: TimerState, event: TimerEvent): TimerState => {
  if (event.type === 'reset') {
    return { status: 'idle' };
  }

  switch (state.status) {
    case 'idle':
      return event.type === 'start'
        ? { status: 'running', remainingSeconds: event.durationSeconds }
        : state;

    case 'running':
      switch (event.type) {
        case 'pause':
          return { status: 'paused', remainingSeconds: state.remainingSeconds };
        case 'tick':
          return state.remainingSeconds > 1
            ? { status: 'running', remainingSeconds: state.remainingSeconds - 1 }
            : { status: 'finished' };
        default:
          return state;
      }

    case 'paused':
      return event.type === 'resume'
        ? { status: 'running', remainingSeconds: state.remainingSeconds }
        : state;

    case 'finished':
      return state;

    // 'cancelled' has no case, so `state` is not `never` here.
    // Add `case 'cancelled': return state;` above and the error goes away.
    default: {
      const unreachable: never = state;
      return unreachable;
    }
  }
};

console.log(transition({ status: 'idle' }, { type: 'start', durationSeconds: 3 }));

Inside our tick case, the condition state.remainingSeconds > 1 determines whether the timer has more than one second left. If true, the next TimerState keeps the running status, with remainingSeconds decremented by one. When remainingSeconds is 1, the function returns a new TimerState with status: 'finished'.

We’re also isolating our timer logic from the clock, which lends itself well to testing.

Transitions in actionTypeScript 5.9.3 · strict · with timer.ts
import { transition, type TimerState } from './timer';

const idle: TimerState = { status: 'idle' };

const running = transition(idle, { type: 'start', durationSeconds: 2 });
console.log(running); // { status: 'running', remainingSeconds: 2 }

const paused = transition(running, { type: 'pause' });
console.log(paused); // { status: 'paused', remainingSeconds: 2 }

const resumed = transition(paused, { type: 'resume' });
console.log(resumed); // { status: 'running', remainingSeconds: 2 }

const finished = transition(transition(resumed, { type: 'tick' }), { type: 'tick' });
console.log(finished); // { status: 'finished' }

const stillIdle = transition(idle, { type: 'pause' });
console.log(stillIdle); // { status: 'idle' } — pause doesn't apply to an idle timer

// TypeScript rejects this call: 'start' requires durationSeconds.
transition(idle, { type: 'start' });

Inputs and UI actions

The number type still accepts values such as -30, so we need a runtime check to enforce a positive timer duration.

The UI should only offer the option to pause when the timer is running. If pause is still sent while it’s idle, returning the current state is the behavior we intended.

The lesson

TypeScript helps us catch invalid state shapes and missing cases. Our transition function makes sure the timer only follows the valid state transitions we’ve defined.

Footnotes

  1. For historical background, see Michael O. Rabin and Dana Scott, Finite Automata and Their Decision Problems (1959). ↩

Thomas Greco writes about software engineering, life, and what he’s learning and building.