State

State applies when an object behaves differently depending on a mode it is in, and when it changes mode in response to what happens to it. The pattern gives each mode its own object, so the behaviour and the legal transitions live together.

Structurally it is Strategy. The difference is intent and it has real consequences: a strategy is chosen from outside and does not change itself; a state decides its own successor.

The problem: status flags and scattered checks

class Order {
  cancel() {
    if (this.status === 'shipped')   throw new Error('cannot cancel a shipped order');
    if (this.status === 'cancelled') throw new Error('already cancelled');
    if (this.status === 'delivered') throw new Error('cannot cancel a delivered order');
    this.status = 'cancelled';
  }
  ship() {
    if (this.status !== 'paid') throw new Error('cannot ship an unpaid order');
    this.status = 'shipped';
  }
  refund() { /* five more checks */ }
}

The rules are real and the encoding is bad:

• The state machine is not written anywhere. It is distributed across the guard clauses of six methods, and reconstructing it means reading all of them.
• Adding a state means auditing every method. Introducing partially_refunded requires finding every check that must now consider it, and missing one is a silent bug.
• Nothing prevents an invalid assignment. order.status = 'delivered' from anywhere skips every rule.
• The legal transitions cannot be shown, tested or documented as a whole.

The pattern

stateDiagram-v2
    [*] --> Pending
    Pending --> Paid: payment captured
    Pending --> Cancelled: cancel
    Paid --> Shipped: dispatch
    Paid --> Cancelled: cancel
    Shipped --> Delivered: delivery confirmed
    Shipped --> Returned: return requested
    Delivered --> Returned: return requested
    Cancelled --> [*]
    Returned --> [*]

Each state becomes an object that knows what it permits:

const Paid = {
  name: 'paid',
  cancel: (order) => Cancelled,
  ship:   (order) => Shipped,
  refund: (order) => { throw new IllegalTransition('refund', 'paid'); },
};

const Shipped = {
  name: 'shipped',
  cancel: () => { throw new IllegalTransition('cancel', 'shipped'); },
  deliver: () => Delivered,
};

The order delegates: this.state = this.state.cancel(this). There are no status comparisons anywhere, and the machine in the diagram above is now readable in the code.

What this buys, precisely

Adding a state is additive. A new state object declares what it permits. Existing states are unchanged unless they gain a transition into the new one — and where they should, the compiler or an exhaustiveness test says so.

Illegal transitions become impossible rather than checked. Shipped has no cancel that succeeds, so there is no code path that cancels a shipped order regardless of what a caller attempts.

The machine is testable as a machine. You can enumerate states and events and assert the whole transition table, which is a far stronger test than a handful of guard-clause cases.

Behaviour beyond legality lives with the state. A Shipped order calculates delivery estimates; a Pending one does not. Under a status flag, that logic is another set of conditionals.

Where it costs more than it saves

Two states. A boolean does not need a machine. Draft and published with one transition is a field.

Behaviour that does not vary. If every method behaves identically in every state and only the legality differs, a transition table is simpler than a set of objects: a map from (state, event) to the next state, with one function checking it.

States that are really combinations. If an order can be simultaneously "paid", "partially shipped" and "under review", these are orthogonal facts, not one machine. Multiplying them into PaidPartiallyShippedUnderReview is the subclass explosion under a new name — model them as separate fields, or as separate small machines.

Who owns the transition

Two arrangements, and the choice matters more than it first appears.

The state returns its successor, as above. The knowledge of what follows what lives in the state, which is cohesive but means each state knows about others — and a cycle of imports is common.

A transition table owned by the machine, with states holding only behaviour. The whole machine is readable in one place and states stay independent, at the cost of splitting "what is legal" from "what happens".

For a machine with genuinely different behaviour per state, the first is usually better. For a machine that is mostly about legality — most workflow and approval systems — the second is clearer, and it makes the table something a non-engineer can review.

Check your understanding

Common mistakes

A machine for two states. A boolean with one transition is a field.

Combining orthogonal dimensions into one machine. Three independent facts become eight states and then sixteen.

Public status assignment. If anything can set the field directly, every rule is optional.

Storing the state object rather than its name. The database becomes coupled to class names.

A lenient loader. An unknown stored value silently becoming a default is a silent data change.

States named for implementation phases. processing and updating are not domain states, and they attract logic that belongs elsewhere.

Transitions with side effects hidden inside them. A state change that also sends an email makes the machine untestable in isolation; emit an event and let a subscriber react.

Practice

Key takeaways

• State gives each mode its own object, so behaviour and legal transitions live together instead of being scattered across guard clauses.
• It differs from Strategy in that a state decides its own successor — transitions are part of the model.
• Illegal transitions become impossible rather than checked, and the machine becomes testable as a whole.
• Two states do not need a machine, and orthogonal facts are not one machine — combining independent dimensions multiplies states.
• Persist the state name, not the object, and fail loudly on an unknown value or a removed state silently rewrites data.
• Put rules in the state objects when behaviour differs, in a central table when only legality differs — the table is reviewable by the people who own the policy.
• Keep side effects out of transitions; emit an event instead, or the machine cannot be tested or replayed.

Further reading

• Erich Gamma, Richard Helm, Ralph Johnson and John Vlissides, Design Patterns: Elements of Reusable Object-Oriented Software (Addison-Wesley, 1994).
• David Harel, "Statecharts: A Visual Formalism for Complex Systems" (Science of Computer Programming, 1987) — orthogonal and hierarchical states.
• Martin Fowler, Domain-Specific Languages (Addison-Wesley, 2010) — state machines expressed as data.
• Eric Evans, Domain-Driven Design (Addison-Wesley, 2003) — modelling lifecycle in the ubiquitous language.
• Scott Wlaschin, Domain Modeling Made Functional (Pragmatic Bookshelf, 2018) — states as distinct types.