State Design Pattern

public interface OrderState {
    default void pay(Order order)    { throw new IllegalTransition("pay", this); }
    default void ship(Order order)   { throw new IllegalTransition("ship", this); }
    default void cancel(Order order) { throw new IllegalTransition("cancel", this); }
}

/** Default methods make ILLEGAL the default — a state opts in to what it allows. */
public final class PaidState implements OrderState {

    @Override public void ship(Order order) {
        warehouse.dispatch(order);
        order.setState(new ShippedState());     // the state names its successor
    }

    @Override public void cancel(Order order) {
        payments.refund(order.receipt());
        inventory.release(order.lines());
        order.setState(new CancelledState());
    }
}

public final class Order {
    private OrderState state = new PendingState();

    void setState(OrderState next) { this.state = next; }

    // The context's methods are one line each, forever.
    public void pay()    { state.pay(this); }
    public void ship()   { state.ship(this); }
    public void cancel() { state.cancel(this); }
}

// Java enums with abstract methods are the compact idiom for small machines,
// and give you serialisation and switch-exhaustiveness for free:
//
//     enum Status {
//         PAID    { void cancel(Order o) { refund(o); o.to(CANCELLED); } },
//         SHIPPED { void cancel(Order o) { startReturn(o); } };
//         abstract void cancel(Order o);
//     }

from __future__ import annotations

from typing import Protocol


class OrderState(Protocol):
    def pay(self, order: Order) -> None: ...
    def ship(self, order: Order) -> None: ...
    def cancel(self, order: Order) -> None: ...


class IllegalTransition(Exception):
    pass


class BaseState:
    """Everything is illegal until a subclass says otherwise."""
    def pay(self, order: Order) -> None:    raise IllegalTransition("pay")
    def ship(self, order: Order) -> None:   raise IllegalTransition("ship")
    def cancel(self, order: Order) -> None: raise IllegalTransition("cancel")


class Paid(BaseState):
    def ship(self, order: Order) -> None:
        warehouse.dispatch(order)
        order.state = Shipped()

    def cancel(self, order: Order) -> None:
        payments.refund(order.receipt)
        inventory.release(order.lines)
        order.state = Cancelled()


class Order:
    def __init__(self) -> None:
        self.state: OrderState = Pending()

    def pay(self) -> None:    self.state.pay(self)
    def cancel(self) -> None: self.state.cancel(self)


# Honest alternative: when the states have no behaviour of their own, a
# TRANSITION TABLE is smaller and easier to test than a class per state —
# and it can be printed, diffed and rendered as a diagram:
#
#     TRANSITIONS = {
#         ("pending", "cancel"): ("cancelled", release_reservation),
#         ("paid",    "cancel"): ("cancelled", refund_and_release),
#         ("shipped", "cancel"): ("returning", start_return),
#     }
#
# Reach for classes when each state carries data or several rich operations;
# reach for the table when the machine is mostly bookkeeping.

#include <memory>
#include <variant>

struct Pending {};
struct Paid    { Receipt receipt; };
struct Shipped { TrackingId tracking; };
struct Delivered {};
struct Cancelled {};

using OrderState = std::variant<Pending, Paid, Shipped, Delivered, Cancelled>;

class Order {
public:
    void cancel() {
        state_ = std::visit(Cancel{*this}, state_);
    }

private:
    struct Cancel {
        Order& order;

        OrderState operator()(Pending)         const { inventory::release(order); return Cancelled{}; }
        OrderState operator()(const Paid& p)   const { payments::refund(p.receipt); return Cancelled{}; }
        OrderState operator()(const Shipped& s) const { returns::start(s.tracking); return Shipped{s}; }
        OrderState operator()(Delivered)       const { throw IllegalTransition{"cancel"}; }
        OrderState operator()(Cancelled)       const { throw IllegalTransition{"cancel"}; }
    };

    OrderState state_{Pending{}};
};

// std::variant + std::visit gives C++ something the classic virtual version
// can't: the compiler REFUSES to build if you add a state and forget an
// overload. Each state can also carry its own data — Paid has a receipt,
// Shipped has a tracking id — which a plain enum cannot express at all.

public abstract record OrderState
{
    public virtual OrderState Pay(Order order)    => throw new IllegalTransition(nameof(Pay));
    public virtual OrderState Cancel(Order order) => throw new IllegalTransition(nameof(Cancel));
}

public sealed record Pending : OrderState
{
    public override OrderState Pay(Order order)    => new Paid(Payments.Charge(order));
    public override OrderState Cancel(Order order) { Inventory.Release(order); return new Cancelled(); }
}

public sealed record Paid(Receipt Receipt) : OrderState
{
    public override OrderState Cancel(Order order)
    {
        Payments.Refund(Receipt);
        Inventory.Release(order);
        return new Cancelled();
    }
}

public sealed class Order
{
    private OrderState _state = new Pending();

    public void Pay()    => _state = _state.Pay(this);
    public void Cancel() => _state = _state.Cancel(this);
}

// Returning the next state instead of mutating the context makes transitions
// pure and trivially testable: Assert.IsType<Cancelled>(new Paid(r).Cancel(o)).
//
// For anything with more than a handful of states, a library (Stateless) buys
// you guard clauses, entry/exit actions and a DOT graph of the machine — and a
// picture of your state machine is worth a great deal in a design review.

// A plain object of state handlers. No classes needed, and the whole machine is
// visible in one screen — which is itself a feature.

const states = {
  pending: {
    pay: order => { payments.charge(order); return 'paid' },
    cancel: order => { inventory.release(order); return 'cancelled' },
  },
  paid: {
    ship: order => { warehouse.dispatch(order); return 'shipped' },
    cancel: order => {
      payments.refund(order.receipt)
      inventory.release(order)
      return 'cancelled'
    },
  },
  shipped: {
    cancel: order => { returns.start(order); return 'returning' },
  },
  delivered: {},        // nothing is legal here
}

export const send = (order, event) => {
  const handler = states[order.status]?.[event]
  if (!handler) throw new IllegalTransition(order.status, event)
  order.status = handler(order)
  return order
}

// XState is the serious version of this for front-end work: statecharts with
// guards, nested states, entry/exit actions and a visualiser. Once a machine
// has more than about six states, a diagram you can look at beats any amount of
// carefully-named code.

package orders

// Go has no inheritance, so a State is an interface and each state is a type.
// Returning the next state (rather than mutating) keeps every transition pure.

type State interface {
	Cancel(*Order) (State, error)
	Ship(*Order) (State, error)
}

type Paid struct{ Receipt Receipt }

func (p Paid) Ship(o *Order) (State, error) {
	if err := warehouse.Dispatch(o); err != nil {
		return p, err            // stay put on failure
	}
	return Shipped{}, nil
}

func (p Paid) Cancel(o *Order) (State, error) {
	if err := payments.Refund(p.Receipt); err != nil {
		return p, err
	}
	inventory.Release(o)
	return Cancelled{}, nil
}

type Delivered struct{}

func (Delivered) Cancel(*Order) (State, error) { return Delivered{}, ErrIllegalTransition }

// Note the error return doing work no exception-based version gets for free:
// a failed transition returns the CURRENT state, so a payment failure can't
// leave the order in a half-moved position.
//
// Go's other famous state machine is Rob Pike's lexer: a state is a FUNCTION
// that returns the next state function — `type stateFn func(*lexer) stateFn` —
// and the whole scanner is a loop calling `state = state(l)`.

type OrderState =
  | { status: 'pending' }
  | { status: 'paid'; receipt: Receipt }
  | { status: 'shipped'; tracking: TrackingId }
  | { status: 'delivered' }
  | { status: 'cancelled'; reason: string }

// Each state carries exactly the data that state has — `tracking` doesn't
// exist on a pending order, so no code can read it by accident.

export function cancel(state: OrderState, order: Order): OrderState {
  switch (state.status) {
    case 'pending':
      inventory.release(order)
      return { status: 'cancelled', reason: 'user' }
    case 'paid':
      payments.refund(state.receipt)          // typed: receipt exists here
      inventory.release(order)
      return { status: 'cancelled', reason: 'user' }
    case 'shipped':
      returns.start(state.tracking)           // typed: tracking exists here
      return state
    case 'delivered':
    case 'cancelled':
      throw new IllegalTransition('cancel', state.status)
  }
}

// This is the strongest version of the pattern available in any of the seven
// languages. Add 'partiallyShipped' to the union and EVERY function that
// switches on status becomes a compile error until you handle it — the exact
// bug that the six-switches design ships to production silently.