State Transitions — State Pattern | OneNoughtOne

0/86

System Design (LLD)Behavioral Patterns

State Pattern

LevelIntermediate

Duration55 mins

TopicBehavioral Patterns

3 / 4

State Transitions

The Heart of the State Machine

The State Pattern creates objects that embody states. But states alone are inert—what brings a state machine to life is transitions . Transitions define how and when an object moves from one state to another, what triggers these movements, and what happens during the change. Transitions are where business rules live. An order can't transition from CREATED to SHIPPED—it must go through PAID and PROCESSING first. A connection can't move from CLOSED to ESTABLISHED without completing the handshake sequence. A document can't be PUBLISHED without first being APPROVED. Understanding transitions deeply is essential for building robust, correct state machines. In this page, we'll explore every facet of state transitions—from basic mechanics to sophisticated patterns for complex scenarios.

What You Will Learn

By the end of this page, you will master state transition mechanics including: who should own transition logic (states vs. context), guarded transitions with preconditions, transition actions and side effects, event-driven transitions, transition validation and error handling, and strategies for complex multi-step transitions.

Transition Fundamentals

A state transition is the movement of an object from one state to another, typically triggered by an event or operation. Every transition has four key components: Source State — The state from which the transition begins Trigger — The event or action that initiates the transition Target State — The state to which the transition leads Actions — Operations executed during the transition (optional) In UML state machine notation, transitions are often expressed as: SourceState --[trigger/action]--> TargetState For example: HAS_COINS --[selectProduct(valid)/dispenseProduct]--> DISPENSING This means: when in HAS_COINS state, if selectProduct is called with a valid selection, execute dispenseProduct and transition to DISPENSING.

Converting Mermaid diagram...

Guards and conditional transitions: Transitions can be guarded —they only occur if a condition is met. The guard is evaluated when the trigger occurs; if it's false, the transition doesn't happen. HAS_COINS --[selectProduct/balance >= price && stock > 0/dispense]--> DISPENSING HAS_COINS --[selectProduct/balance < price]--> HAS_COINS // Stay, inform user Guards are essential for modeling business rules about when transitions are valid.

Deterministic Transitions

In well-designed state machines, the same trigger from the same state should always produce the same result (determinism). If you find yourself needing random or non-deterministic transitions, reconsider whether your states are properly modeled—you may need additional states to capture the conditions that determine different outcomes.

Who Owns Transition Logic?

One of the key design decisions in the State Pattern is where transition logic resides . There are three main approaches, each with distinct trade-offs.

Transition Ownership Strategies

•State-Owned Transitions (Decentralized) — Each state class decides when and where to transition. The state knows its own exit conditions and target states.
•Context-Owned Transitions (Centralized) — The context class manages all transitions. States request transitions, but the context decides whether to execute them.
•Transition Table (Externalized) — Transitions are defined in a separate configuration (table, DSL, or external file). Neither states nor context hardcode transitions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// The state decides when to transition
class HasCoinsState implements VendingMachineState {
    selectProduct(machine: VendingMachine, productId: string): string {
        const price = machine.getPrice(productId);
        
        if (machine.getBalance() >= price && machine.getStock(productId) > 0) {
            // State directly triggers the transition
            machine.setState(new DispensingState(productId));
            return "Dispensing...";
        }
        
        return "Insufficient balance or out of stock.";
    }
}
 
// Advantages:
// - State encapsulates its own knowledge
// - Easy to understand each state in isolation
// - New states don't require context changes
 
// Disadvantages:
// - States must know about other states (coupling)
// - Transition logic scattered across state classes
// - Hard to see full transition graph without reading all states

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
// States return transition requests; context decides
interface TransitionRequest {
    targetState: string;
    payload?: any;
}
 
class HasCoinsState implements VendingMachineState {
    selectProduct(machine: VendingMachine, productId: string): TransitionRequest | null {
        const price = machine.getPrice(productId);
        
        if (machine.getBalance() >= price && machine.getStock(productId) > 0) {
            // State requests transition, doesn't execute it
            return { targetState: "DISPENSING", payload: { productId } };
        }
        
        return null; // No transition
    }
}
 
class VendingMachine {
    private stateFactory: StateFactory;
    
    selectProduct(productId: string): string {
        const request = this.state.selectProduct(this, productId);
        
        if (request) {
            // Context validates and executes the transition
            if (this.isValidTransition(this.state.getName(), request.targetState)) {
                const newState = this.stateFactory.create(request.targetState, request.payload);
                this.setState(newState);
                return "Product selected.";
            } else {
                console.log("Invalid transition blocked");
            }
        }
        
        return "Selection failed.";
    }
    
    private isValidTransition(from: string, to: string): boolean {
        // Central validation logic
        const validTransitions = {
            "IDLE": ["HAS_COINS"],
            "HAS_COINS": ["IDLE", "DISPENSING"],
            "DISPENSING": ["IDLE", "HAS_COINS"],
            // ...
        };
        return validTransitions[from]?.includes(to) ?? false;
    }
}
 
// Advantages:
// - All transition rules in one place
// - Easy to validate, log, or audit transitions
// - States are decoupled from each other
 
// Disadvantages:
// - Context becomes more complex
// - States lose some encapsulation
// - Changes to transitions require modifying context

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
// Transitions defined declaratively
const transitionTable: TransitionDefinition[] = [
    {
        from: "IDLE",
        trigger: "insertCoin",
        to: "HAS_COINS",
        action: (ctx, payload) => ctx.addToBalance(payload.amount)
    },
    {
        from: "HAS_COINS",
        trigger: "selectProduct", 
        to: "DISPENSING",
        guard: (ctx, payload) => 
            ctx.getBalance() >= ctx.getPrice(payload.productId) &&
            ctx.getStock(payload.productId) > 0,
        action: (ctx, payload) => ctx.dispense(payload.productId)
    },
    {
        from: "HAS_COINS",
        trigger: "refund",
        to: "IDLE",
        action: (ctx) => ctx.returnBalance()
    },
    // ... all transitions defined here
];
 
class StateMachine {
    private currentState: string;
    private transitions: TransitionDefinition[];
    
    constructor(initialState: string, transitions: TransitionDefinition[]) {
        this.currentState = initialState;
        this.transitions = transitions;
    }
    
    dispatch(trigger: string, payload?: any): boolean {
        const transition = this.transitions.find(t =>
            t.from === this.currentState &&
            t.trigger === trigger &&
            (t.guard?.(this.context, payload) ?? true)
        );
        
        if (transition) {
            transition.action?.(this.context, payload);
            this.currentState = transition.to;
            return true;
        }
        
        return false;
    }
}
 
// Advantages:
// - Complete transition graph visible in one place
// - Transitions can be loaded from config files
// - Easy to visualize, test, and modify
// - Supports tooling (diagram generation, validation)
 
// Disadvantages:
// - More infrastructure needed
// - Less natural OOP design
// - Actions become callbacks, not methods

Choosing an Approach

For most applications, start with state-owned transitions (decentralized). It's the most natural fit for the State Pattern. Move to centralized or externalized approaches when: you need global transition validation, transitions are defined by non-developers, or you need runtime-modifiable transitions.

Transition Actions and Side Effects

Transitions often need to perform actions beyond simply changing state. These actions can occur at different points in the transition lifecycle: Exit Actions — Executed when leaving the source state Transition Actions — Executed during the transition itself Entry Actions — Executed when entering the target state Understanding when to use each type is crucial for correctly modeling behavior.

Converting Mermaid diagram...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
interface State {
    getName(): string;
    
    // Lifecycle hooks
    onEnter?(context: Context): void;
    onExit?(context: Context): void;
    
    // State-specific operations
    handle(context: Context, event: Event): void;
}
 
class PaidState implements State {
    getName(): string { return "PAID"; }
    
    onEnter(context: Order): void {
        // Entry action: Things that happen when entering PAID
        context.sendConfirmationEmail();
        context.reserveInventory();
        context.schedulePaymentCapture();
        console.log("Entered PAID state - confirmation sent");
    }
    
    onExit(context: Order): void {
        // Exit action: Cleanup when leaving PAID
        context.capturePayment();  // Finalize the payment hold
        console.log("Exiting PAID state - payment captured");
    }
    
    handle(context: Order, event: Event): void {
        if (event.type === "START_PROCESSING") {
            // Transition action: happens during the transition
            context.assignToWarehouse();
            context.createPickingList();
            
            // Trigger the transition
            context.setState(new ProcessingState());
        }
    }
}
 
class Context {
    private state: State;
    
    setState(newState: State): void {
        // Execute exit actions on current state
        this.state.onExit?.(this);
        
        // Transition complete, update state reference
        const oldState = this.state;
        this.state = newState;
        
        // Execute entry actions on new state
        this.state.onEnter?.(this);
        
        console.log(`Transitioned: ${oldState.getName()} → ${newState.getName()}`);
    }
}

When to Use Each Action Type
Action Type	When to Use	Examples
Exit Actions	Cleanup, resource release, finalization at source state	Release locks, save state, complete pending operations
Transition Actions	Logic that depends on both source and target state	Logging the transition, calculating durations, audit trails
Entry Actions	Initialization, resource acquisition at target state	Start timers, acquire locks, send notifications, schedule tasks

Action Failure Handling

What happens if an entry action fails? You're in a problematic state: you've left the source but failed to enter the target. Design strategies include: making actions idempotent, using transactions, or designing compensating actions. Never leave the state machine in an inconsistent state.

Guarded Transitions

Guarded transitions only execute when a precondition is satisfied. Guards are essential for modeling business rules that constrain state changes based on runtime conditions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
class UnderReviewState implements DocumentState {
    // Guard: Document can only be approved if all reviewers have approved
    approve(doc: Document, reviewer: Reviewer): string {
        // Check the guard condition
        if (!doc.allReviewersApproved()) {
            return "Cannot approve: not all reviewers have signed off.";
        }
        
        // Additional guards can be chained
        if (doc.hasUnresolvedComments()) {
            return "Cannot approve: unresolved comments exist.";
        }
        
        if (!reviewer.hasApprovalAuthority()) {
            return "Cannot approve: insufficient authority.";
        }
        
        // All guards passed - execute transition
        doc.setApprover(reviewer);
        doc.setApprovedAt(new Date());
        doc.setState(new ApprovedState());
        
        return "Document approved successfully.";
    }
    
    reject(doc: Document, reason: string): string {
        // Guard: Must provide a reason for rejection
        if (!reason || reason.trim().length < 10) {
            return "Cannot reject: meaningful reason required (min 10 chars).";
        }
        
        doc.setRejectionReason(reason);
        doc.setState(new DraftState());  // Back to draft for revision
        
        return "Document rejected. Author notified.";
    }
}

Guard design principles: Guards should be side-effect free — They evaluate conditions but don't change state. A guard that modifies data creates unpredictable behavior. Guards should be fast — They're evaluated on every trigger attempt. Expensive database queries in guards slow down every operation. Guards should be deterministic — Given the same context state, a guard should always return the same result. Failed guards should be informative — Instead of boolean results, return error messages explaining why the guard failed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// Instead of simple boolean guards, use descriptive results
interface GuardResult {
    allowed: boolean;
    reason?: string;
}
 
class PaymentPendingState implements OrderState {
    private canTransitionToPaid(order: Order): GuardResult {
        if (order.getPaymentStatus() !== "CAPTURED") {
            return { 
                allowed: false, 
                reason: "Payment not yet captured by processor" 
            };
        }
        
        if (order.getFraudScore() > 80) {
            return { 
                allowed: false, 
                reason: "Order flagged for fraud review" 
            };
        }
        
        if (order.hasInventoryConflict()) {
            return { 
                allowed: false, 
                reason: "Inventory no longer available" 
            };
        }
        
        return { allowed: true };
    }
    
    confirmPayment(order: Order): string {
        const guardResult = this.canTransitionToPaid(order);
        
        if (!guardResult.allowed) {
            order.logBlockedTransition("PAID", guardResult.reason);
            return `Payment confirmation blocked: ${guardResult.reason}`;
        }
        
        order.setState(new PaidState());
        return "Payment confirmed, order processing.";
    }
}

Composite Guards

For complex guard conditions, consider extracting guards into separate classes or functions. This enables reuse (same guard for multiple transitions), easier testing (test guards in isolation), and clearer naming (the guard's name explains the business rule).

Event-Driven Transitions

In many systems, transitions are triggered by events rather than direct method calls. This approach decouples the trigger mechanism from the state logic and enables more flexible event sourcing and processing architectures.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
// Events are first-class objects with types and payloads
interface StateEvent {
    type: string;
    payload?: any;
    timestamp: Date;
    source?: string;
}
 
// Each state handles events and returns the next state
interface State {
    handleEvent(context: Context, event: StateEvent): State | null;
}
 
class IdleState implements State {
    handleEvent(machine: VendingMachine, event: StateEvent): State | null {
        switch (event.type) {
            case "COIN_INSERTED":
                machine.addToBalance(event.payload.amount);
                return new HasCoinsState();
                
            case "ADMIN_RESTOCK":
                machine.restockInventory(event.payload.items);
                return null; // Stay in current state
                
            case "POWER_OFF":
                return new PoweredOffState();
                
            default:
                console.log(`IDLE: Ignoring unknown event ${event.type}`);
                return null;
        }
    }
}
 
class StateMachine {
    private state: State;
    private eventQueue: StateEvent[] = [];
    
    dispatch(event: StateEvent): void {
        console.log(`[Event] ${event.type} at ${event.timestamp}`);
        
        const nextState = this.state.handleEvent(this.context, event);
        
        if (nextState !== null) {
            this.transition(nextState);
        }
    }
    
    // Support for async event processing
    async dispatchAsync(event: StateEvent): Promise<void> {
        this.eventQueue.push(event);
        await this.processQueue();
    }
    
    private async processQueue(): Promise<void> {
        while (this.eventQueue.length > 0) {
            const event = this.eventQueue.shift()!;
            this.dispatch(event);
        }
    }
}
 
// Usage
machine.dispatch({ type: "COIN_INSERTED", payload: { amount: 100 }, timestamp: new Date() });
machine.dispatch({ type: "PRODUCT_SELECTED", payload: { id: "COLA" }, timestamp: new Date() });

Benefits of Event-Driven Transitions

•Decoupling — Event producers don't need to know about state machine internals. They just emit events.
•Event Sourcing — All state transitions can be recorded as events, enabling replay, debugging, and auditing.
•Async Processing — Events can be queued and processed asynchronously, supporting temporal decoupling.
•External Integration — Events from external systems (webhooks, message queues) integrate naturally.
•Testing — Test by replaying recorded or synthetic event sequences.
•Time-Based Transitions — Timeout events can trigger transitions (e.g., session expiry).

Event Ordering

Event-driven systems must handle event ordering carefully. What if PAYMENT_RECEIVED arrives before ORDER_CREATED due to race conditions? Design states to handle out-of-order events gracefully, or use infrastructure that guarantees ordering.

Complex Transition Scenarios

Real-world state machines often have complex transition requirements that go beyond simple A\toB transitions. Let's examine advanced patterns for handling these scenarios.

Complex Transition Patterns

•Hierarchical States — States within states (e.g., PROCESSING contains PICKING, PACKING, SHIPPING sub-states).
•Parallel Regions — Multiple independent state machines running simultaneously (e.g., order fulfillment AND payment processing).
•History States — Returning to a previously active state (e.g., resuming where we left off).
•Deferred Events — Events that should be processed later, not discarded (e.g., request received during initialization).
•Self-Transitions — Transitions from a state back to itself, triggering entry/exit actions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
// ProcessingState contains sub-states
abstract class ProcessingSubState implements State {
    abstract getName(): string;
    abstract handle(order: Order, event: Event): State | null;
    
    // Common behavior for all processing sub-states
    cancel(order: Order): State {
        order.releaseInventory();
        order.initiateRefund();
        return new CancelledState();
    }
}
 
class PickingState extends ProcessingSubState {
    getName() { return "PROCESSING.PICKING"; }
    
    handle(order: Order, event: Event): State | null {
        if (event.type === "PICKING_COMPLETE") {
            return new PackingState();
        }
        if (event.type === "ITEM_UNAVAILABLE") {
            order.notifyCustomer("Item unavailable");
            return new BackorderedState();
        }
        return null;
    }
}
 
class PackingState extends ProcessingSubState {
    getName() { return "PROCESSING.PACKING"; }
    
    handle(order: Order, event: Event): State | null {
        if (event.type === "PACKAGING_COMPLETE") {
            return new ShippingState();
        }
        return null;
    }
}
 
class ShippingState extends ProcessingSubState {
    getName() { return "PROCESSING.SHIPPING"; }
    
    handle(order: Order, event: Event): State | null {
        if (event.type === "SHIPPED") {
            return new ShippedState();  // Exit processing hierarchy
        }
        return null;
    }
}
 
// The parent state delegates to current sub-state
class ProcessingState implements State {
    private subState: ProcessingSubState;
    
    constructor() {
        this.subState = new PickingState();  // Initial sub-state
    }
    
    getName() { return this.subState.getName(); }
    
    handle(order: Order, event: Event): State | null {
        // Try sub-state first
        const nextSubState = this.subState.handle(order, event);
        
        if (nextSubState instanceof ProcessingSubState) {
            this.subState = nextSubState;
            return null; // Stay in ProcessingState
        }
        
        return nextSubState; // Exit to a different top-level state
    }
    
    cancel(order: Order): State {
        return this.subState.cancel(order);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// Self-transition: State transitions to itself, triggering actions
class WaitingForPaymentState implements State {
    private retryCount: number = 0;
    private readonly MAX_RETRIES = 3;
    
    handle(order: Order, event: Event): State | null {
        if (event.type === "PAYMENT_RETRY") {
            this.retryCount++;
            
            if (this.retryCount >= this.MAX_RETRIES) {
                order.notifyPaymentFailed();
                return new CancelledState();
            }
            
            // Self-transition: return same state type (new instance)
            // This triggers exit/entry actions again
            return new WaitingForPaymentState(); // Fresh retry counter
        }
        
        if (event.type === "PAYMENT_SUCCESS") {
            return new PaidState();
        }
        
        return null;
    }
    
    onEnter(order: Order): void {
        order.attemptPaymentCapture();
        order.scheduleRetryTimer(30000); // 30 second retry
    }
    
    onExit(order: Order): void {
        order.cancelRetryTimer();
    }
}

Keep It Simple When Possible

These advanced patterns add complexity. Use them when genuinely needed—when the domain truly has hierarchical states or parallel processes. Don't introduce complexity to handle simple scenarios. Many state machines work perfectly with flat state structures.

Transition Validation and Error Handling

Robust state machines must handle invalid transitions gracefully. What happens when code attempts a transition that shouldn't occur? How do we ensure the state machine never reaches an illegal state?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// Strategy 1: Silent rejection (return null/same state)
class ShippedState implements State {
    cancel(order: Order): State {
        // Can't cancel a shipped order - stay in current state
        console.log("Cannot cancel shipped order");
        return this; // Return same state, no transition
    }
}
 
// Strategy 2: Exception on invalid transition
class DeliveredState implements State {
    cancel(order: Order): never {
        throw new IllegalStateTransitionError(
            "DELIVERED",
            "CANCELLED",
            "Cannot cancel after delivery. Use return process instead."
        );
    }
}
 
// Strategy 3: Validation layer in context
class OrderContext {
    private readonly validTransitions: Map<string, Set<string>> = new Map([
        ["CREATED", new Set(["PAYMENT_PENDING", "CANCELLED"])],
        ["PAYMENT_PENDING", new Set(["PAID", "CANCELLED"])],
        ["PAID", new Set(["PROCESSING", "CANCELLED"])],
        ["PROCESSING", new Set(["SHIPPED", "CANCELLED"])],
        ["SHIPPED", new Set(["DELIVERED", "RETURN_REQUESTED"])],
        ["DELIVERED", new Set(["RETURN_REQUESTED", "COMPLETED"])],
        // Terminal states have no valid transitions
        ["CANCELLED", new Set()],
        ["COMPLETED", new Set()],
    ]);
    
    setState(newState: State): void {
        const currentStateName = this.state.getName();
        const newStateName = newState.getName();
        
        const allowedTargets = this.validTransitions.get(currentStateName);
        
        if (!allowedTargets?.has(newStateName)) {
            const error = new IllegalStateTransitionError(
                currentStateName,
                newStateName,
                `Transition not allowed. Valid targets from ${currentStateName}: ${[...allowedTargets || []].join(", ")}`
            );
            
            // Log for monitoring
            this.logger.error("Invalid state transition attempted", {
                from: currentStateName,
                to: newStateName,
                orderId: this.orderId,
            });
            
            throw error;
        }
        
        // Valid transition - proceed
        this.executeTransition(newState);
    }
}

When to Use Silent Rejection

•User-facing operations where invalid attempts are expected
•Event-driven systems where events might arrive out of order
•Idempotent operations (re-triggering is harmless)
•When the caller should continue despite rejection

When to Use Exceptions

•Internal operations where invalid transitions indicate bugs
•When the caller must handle the failure explicitly
•Critical flows where silent failure is dangerous
•When you want stack traces for debugging

Never Silently Corrupt State

The worst outcome is proceeding with a transition that leaves the system in an inconsistent state. If guards fail, entry actions fail, or invariants break—stop immediately. A thrown exception is infinitely better than corrupted data.

System Design (LLD)Behavioral Patterns

State Pattern

LevelIntermediate

Duration55 mins

TopicBehavioral Patterns

3 / 4

State Transitions

The Heart of the State Machine

The State Pattern creates objects that embody states. But states alone are inert—what brings a state machine to life is transitions . Transitions define how and when an object moves from one state to another, what triggers these movements, and what happens during the change. Transitions are where business rules live. An order can't transition from CREATED to SHIPPED—it must go through PAID and PROCESSING first. A connection can't move from CLOSED to ESTABLISHED without completing the handshake sequence. A document can't be PUBLISHED without first being APPROVED. Understanding transitions deeply is essential for building robust, correct state machines. In this page, we'll explore every facet of state transitions—from basic mechanics to sophisticated patterns for complex scenarios.

What You Will Learn

By the end of this page, you will master state transition mechanics including: who should own transition logic (states vs. context), guarded transitions with preconditions, transition actions and side effects, event-driven transitions, transition validation and error handling, and strategies for complex multi-step transitions.

Transition Fundamentals

A state transition is the movement of an object from one state to another, typically triggered by an event or operation. Every transition has four key components: Source State — The state from which the transition begins Trigger — The event or action that initiates the transition Target State — The state to which the transition leads Actions — Operations executed during the transition (optional) In UML state machine notation, transitions are often expressed as: SourceState --[trigger/action]--> TargetState For example: HAS_COINS --[selectProduct(valid)/dispenseProduct]--> DISPENSING This means: when in HAS_COINS state, if selectProduct is called with a valid selection, execute dispenseProduct and transition to DISPENSING.

Converting Mermaid diagram...

Guards and conditional transitions: Transitions can be guarded —they only occur if a condition is met. The guard is evaluated when the trigger occurs; if it's false, the transition doesn't happen. HAS_COINS --[selectProduct/balance >= price && stock > 0/dispense]--> DISPENSING HAS_COINS --[selectProduct/balance < price]--> HAS_COINS // Stay, inform user Guards are essential for modeling business rules about when transitions are valid.

Deterministic Transitions

In well-designed state machines, the same trigger from the same state should always produce the same result (determinism). If you find yourself needing random or non-deterministic transitions, reconsider whether your states are properly modeled—you may need additional states to capture the conditions that determine different outcomes.

Who Owns Transition Logic?

One of the key design decisions in the State Pattern is where transition logic resides . There are three main approaches, each with distinct trade-offs.

Transition Ownership Strategies

•State-Owned Transitions (Decentralized) — Each state class decides when and where to transition. The state knows its own exit conditions and target states.
•Context-Owned Transitions (Centralized) — The context class manages all transitions. States request transitions, but the context decides whether to execute them.
•Transition Table (Externalized) — Transitions are defined in a separate configuration (table, DSL, or external file). Neither states nor context hardcode transitions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// The state decides when to transition
class HasCoinsState implements VendingMachineState {
    selectProduct(machine: VendingMachine, productId: string): string {
        const price = machine.getPrice(productId);
        
        if (machine.getBalance() >= price && machine.getStock(productId) > 0) {
            // State directly triggers the transition
            machine.setState(new DispensingState(productId));
            return "Dispensing...";
        }
        
        return "Insufficient balance or out of stock.";
    }
}
 
// Advantages:
// - State encapsulates its own knowledge
// - Easy to understand each state in isolation
// - New states don't require context changes
 
// Disadvantages:
// - States must know about other states (coupling)
// - Transition logic scattered across state classes
// - Hard to see full transition graph without reading all states

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
// States return transition requests; context decides
interface TransitionRequest {
    targetState: string;
    payload?: any;
}
 
class HasCoinsState implements VendingMachineState {
    selectProduct(machine: VendingMachine, productId: string): TransitionRequest | null {
        const price = machine.getPrice(productId);
        
        if (machine.getBalance() >= price && machine.getStock(productId) > 0) {
            // State requests transition, doesn't execute it
            return { targetState: "DISPENSING", payload: { productId } };
        }
        
        return null; // No transition
    }
}
 
class VendingMachine {
    private stateFactory: StateFactory;
    
    selectProduct(productId: string): string {
        const request = this.state.selectProduct(this, productId);
        
        if (request) {
            // Context validates and executes the transition
            if (this.isValidTransition(this.state.getName(), request.targetState)) {
                const newState = this.stateFactory.create(request.targetState, request.payload);
                this.setState(newState);
                return "Product selected.";
            } else {
                console.log("Invalid transition blocked");
            }
        }
        
        return "Selection failed.";
    }
    
    private isValidTransition(from: string, to: string): boolean {
        // Central validation logic
        const validTransitions = {
            "IDLE": ["HAS_COINS"],
            "HAS_COINS": ["IDLE", "DISPENSING"],
            "DISPENSING": ["IDLE", "HAS_COINS"],
            // ...
        };
        return validTransitions[from]?.includes(to) ?? false;
    }
}
 
// Advantages:
// - All transition rules in one place
// - Easy to validate, log, or audit transitions
// - States are decoupled from each other
 
// Disadvantages:
// - Context becomes more complex
// - States lose some encapsulation
// - Changes to transitions require modifying context

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
// Transitions defined declaratively
const transitionTable: TransitionDefinition[] = [
    {
        from: "IDLE",
        trigger: "insertCoin",
        to: "HAS_COINS",
        action: (ctx, payload) => ctx.addToBalance(payload.amount)
    },
    {
        from: "HAS_COINS",
        trigger: "selectProduct", 
        to: "DISPENSING",
        guard: (ctx, payload) => 
            ctx.getBalance() >= ctx.getPrice(payload.productId) &&
            ctx.getStock(payload.productId) > 0,
        action: (ctx, payload) => ctx.dispense(payload.productId)
    },
    {
        from: "HAS_COINS",
        trigger: "refund",
        to: "IDLE",
        action: (ctx) => ctx.returnBalance()
    },
    // ... all transitions defined here
];
 
class StateMachine {
    private currentState: string;
    private transitions: TransitionDefinition[];
    
    constructor(initialState: string, transitions: TransitionDefinition[]) {
        this.currentState = initialState;
        this.transitions = transitions;
    }
    
    dispatch(trigger: string, payload?: any): boolean {
        const transition = this.transitions.find(t =>
            t.from === this.currentState &&
            t.trigger === trigger &&
            (t.guard?.(this.context, payload) ?? true)
        );
        
        if (transition) {
            transition.action?.(this.context, payload);
            this.currentState = transition.to;
            return true;
        }
        
        return false;
    }
}
 
// Advantages:
// - Complete transition graph visible in one place
// - Transitions can be loaded from config files
// - Easy to visualize, test, and modify
// - Supports tooling (diagram generation, validation)
 
// Disadvantages:
// - More infrastructure needed
// - Less natural OOP design
// - Actions become callbacks, not methods

Choosing an Approach

For most applications, start with state-owned transitions (decentralized). It's the most natural fit for the State Pattern. Move to centralized or externalized approaches when: you need global transition validation, transitions are defined by non-developers, or you need runtime-modifiable transitions.

Transition Actions and Side Effects

Transitions often need to perform actions beyond simply changing state. These actions can occur at different points in the transition lifecycle: Exit Actions — Executed when leaving the source state Transition Actions — Executed during the transition itself Entry Actions — Executed when entering the target state Understanding when to use each type is crucial for correctly modeling behavior.

Converting Mermaid diagram...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
interface State {
    getName(): string;
    
    // Lifecycle hooks
    onEnter?(context: Context): void;
    onExit?(context: Context): void;
    
    // State-specific operations
    handle(context: Context, event: Event): void;
}
 
class PaidState implements State {
    getName(): string { return "PAID"; }
    
    onEnter(context: Order): void {
        // Entry action: Things that happen when entering PAID
        context.sendConfirmationEmail();
        context.reserveInventory();
        context.schedulePaymentCapture();
        console.log("Entered PAID state - confirmation sent");
    }
    
    onExit(context: Order): void {
        // Exit action: Cleanup when leaving PAID
        context.capturePayment();  // Finalize the payment hold
        console.log("Exiting PAID state - payment captured");
    }
    
    handle(context: Order, event: Event): void {
        if (event.type === "START_PROCESSING") {
            // Transition action: happens during the transition
            context.assignToWarehouse();
            context.createPickingList();
            
            // Trigger the transition
            context.setState(new ProcessingState());
        }
    }
}
 
class Context {
    private state: State;
    
    setState(newState: State): void {
        // Execute exit actions on current state
        this.state.onExit?.(this);
        
        // Transition complete, update state reference
        const oldState = this.state;
        this.state = newState;
        
        // Execute entry actions on new state
        this.state.onEnter?.(this);
        
        console.log(`Transitioned: ${oldState.getName()} → ${newState.getName()}`);
    }
}

When to Use Each Action Type
Action Type	When to Use	Examples
Exit Actions	Cleanup, resource release, finalization at source state	Release locks, save state, complete pending operations
Transition Actions	Logic that depends on both source and target state	Logging the transition, calculating durations, audit trails
Entry Actions	Initialization, resource acquisition at target state	Start timers, acquire locks, send notifications, schedule tasks

Action Failure Handling

What happens if an entry action fails? You're in a problematic state: you've left the source but failed to enter the target. Design strategies include: making actions idempotent, using transactions, or designing compensating actions. Never leave the state machine in an inconsistent state.

Guarded Transitions

Guarded transitions only execute when a precondition is satisfied. Guards are essential for modeling business rules that constrain state changes based on runtime conditions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
class UnderReviewState implements DocumentState {
    // Guard: Document can only be approved if all reviewers have approved
    approve(doc: Document, reviewer: Reviewer): string {
        // Check the guard condition
        if (!doc.allReviewersApproved()) {
            return "Cannot approve: not all reviewers have signed off.";
        }
        
        // Additional guards can be chained
        if (doc.hasUnresolvedComments()) {
            return "Cannot approve: unresolved comments exist.";
        }
        
        if (!reviewer.hasApprovalAuthority()) {
            return "Cannot approve: insufficient authority.";
        }
        
        // All guards passed - execute transition
        doc.setApprover(reviewer);
        doc.setApprovedAt(new Date());
        doc.setState(new ApprovedState());
        
        return "Document approved successfully.";
    }
    
    reject(doc: Document, reason: string): string {
        // Guard: Must provide a reason for rejection
        if (!reason || reason.trim().length < 10) {
            return "Cannot reject: meaningful reason required (min 10 chars).";
        }
        
        doc.setRejectionReason(reason);
        doc.setState(new DraftState());  // Back to draft for revision
        
        return "Document rejected. Author notified.";
    }
}

Guard design principles: Guards should be side-effect free — They evaluate conditions but don't change state. A guard that modifies data creates unpredictable behavior. Guards should be fast — They're evaluated on every trigger attempt. Expensive database queries in guards slow down every operation. Guards should be deterministic — Given the same context state, a guard should always return the same result. Failed guards should be informative — Instead of boolean results, return error messages explaining why the guard failed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// Instead of simple boolean guards, use descriptive results
interface GuardResult {
    allowed: boolean;
    reason?: string;
}
 
class PaymentPendingState implements OrderState {
    private canTransitionToPaid(order: Order): GuardResult {
        if (order.getPaymentStatus() !== "CAPTURED") {
            return { 
                allowed: false, 
                reason: "Payment not yet captured by processor" 
            };
        }
        
        if (order.getFraudScore() > 80) {
            return { 
                allowed: false, 
                reason: "Order flagged for fraud review" 
            };
        }
        
        if (order.hasInventoryConflict()) {
            return { 
                allowed: false, 
                reason: "Inventory no longer available" 
            };
        }
        
        return { allowed: true };
    }
    
    confirmPayment(order: Order): string {
        const guardResult = this.canTransitionToPaid(order);
        
        if (!guardResult.allowed) {
            order.logBlockedTransition("PAID", guardResult.reason);
            return `Payment confirmation blocked: ${guardResult.reason}`;
        }
        
        order.setState(new PaidState());
        return "Payment confirmed, order processing.";
    }
}

Composite Guards

For complex guard conditions, consider extracting guards into separate classes or functions. This enables reuse (same guard for multiple transitions), easier testing (test guards in isolation), and clearer naming (the guard's name explains the business rule).

Event-Driven Transitions

In many systems, transitions are triggered by events rather than direct method calls. This approach decouples the trigger mechanism from the state logic and enables more flexible event sourcing and processing architectures.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
// Events are first-class objects with types and payloads
interface StateEvent {
    type: string;
    payload?: any;
    timestamp: Date;
    source?: string;
}
 
// Each state handles events and returns the next state
interface State {
    handleEvent(context: Context, event: StateEvent): State | null;
}
 
class IdleState implements State {
    handleEvent(machine: VendingMachine, event: StateEvent): State | null {
        switch (event.type) {
            case "COIN_INSERTED":
                machine.addToBalance(event.payload.amount);
                return new HasCoinsState();
                
            case "ADMIN_RESTOCK":
                machine.restockInventory(event.payload.items);
                return null; // Stay in current state
                
            case "POWER_OFF":
                return new PoweredOffState();
                
            default:
                console.log(`IDLE: Ignoring unknown event ${event.type}`);
                return null;
        }
    }
}
 
class StateMachine {
    private state: State;
    private eventQueue: StateEvent[] = [];
    
    dispatch(event: StateEvent): void {
        console.log(`[Event] ${event.type} at ${event.timestamp}`);
        
        const nextState = this.state.handleEvent(this.context, event);
        
        if (nextState !== null) {
            this.transition(nextState);
        }
    }
    
    // Support for async event processing
    async dispatchAsync(event: StateEvent): Promise<void> {
        this.eventQueue.push(event);
        await this.processQueue();
    }
    
    private async processQueue(): Promise<void> {
        while (this.eventQueue.length > 0) {
            const event = this.eventQueue.shift()!;
            this.dispatch(event);
        }
    }
}
 
// Usage
machine.dispatch({ type: "COIN_INSERTED", payload: { amount: 100 }, timestamp: new Date() });
machine.dispatch({ type: "PRODUCT_SELECTED", payload: { id: "COLA" }, timestamp: new Date() });

Benefits of Event-Driven Transitions

•Decoupling — Event producers don't need to know about state machine internals. They just emit events.
•Event Sourcing — All state transitions can be recorded as events, enabling replay, debugging, and auditing.
•Async Processing — Events can be queued and processed asynchronously, supporting temporal decoupling.
•External Integration — Events from external systems (webhooks, message queues) integrate naturally.
•Testing — Test by replaying recorded or synthetic event sequences.
•Time-Based Transitions — Timeout events can trigger transitions (e.g., session expiry).

Event Ordering

Event-driven systems must handle event ordering carefully. What if PAYMENT_RECEIVED arrives before ORDER_CREATED due to race conditions? Design states to handle out-of-order events gracefully, or use infrastructure that guarantees ordering.

Complex Transition Scenarios

Real-world state machines often have complex transition requirements that go beyond simple A\toB transitions. Let's examine advanced patterns for handling these scenarios.

Complex Transition Patterns

•Hierarchical States — States within states (e.g., PROCESSING contains PICKING, PACKING, SHIPPING sub-states).
•Parallel Regions — Multiple independent state machines running simultaneously (e.g., order fulfillment AND payment processing).
•History States — Returning to a previously active state (e.g., resuming where we left off).
•Deferred Events — Events that should be processed later, not discarded (e.g., request received during initialization).
•Self-Transitions — Transitions from a state back to itself, triggering entry/exit actions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
// ProcessingState contains sub-states
abstract class ProcessingSubState implements State {
    abstract getName(): string;
    abstract handle(order: Order, event: Event): State | null;
    
    // Common behavior for all processing sub-states
    cancel(order: Order): State {
        order.releaseInventory();
        order.initiateRefund();
        return new CancelledState();
    }
}
 
class PickingState extends ProcessingSubState {
    getName() { return "PROCESSING.PICKING"; }
    
    handle(order: Order, event: Event): State | null {
        if (event.type === "PICKING_COMPLETE") {
            return new PackingState();
        }
        if (event.type === "ITEM_UNAVAILABLE") {
            order.notifyCustomer("Item unavailable");
            return new BackorderedState();
        }
        return null;
    }
}
 
class PackingState extends ProcessingSubState {
    getName() { return "PROCESSING.PACKING"; }
    
    handle(order: Order, event: Event): State | null {
        if (event.type === "PACKAGING_COMPLETE") {
            return new ShippingState();
        }
        return null;
    }
}
 
class ShippingState extends ProcessingSubState {
    getName() { return "PROCESSING.SHIPPING"; }
    
    handle(order: Order, event: Event): State | null {
        if (event.type === "SHIPPED") {
            return new ShippedState();  // Exit processing hierarchy
        }
        return null;
    }
}
 
// The parent state delegates to current sub-state
class ProcessingState implements State {
    private subState: ProcessingSubState;
    
    constructor() {
        this.subState = new PickingState();  // Initial sub-state
    }
    
    getName() { return this.subState.getName(); }
    
    handle(order: Order, event: Event): State | null {
        // Try sub-state first
        const nextSubState = this.subState.handle(order, event);
        
        if (nextSubState instanceof ProcessingSubState) {
            this.subState = nextSubState;
            return null; // Stay in ProcessingState
        }
        
        return nextSubState; // Exit to a different top-level state
    }
    
    cancel(order: Order): State {
        return this.subState.cancel(order);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// Self-transition: State transitions to itself, triggering actions
class WaitingForPaymentState implements State {
    private retryCount: number = 0;
    private readonly MAX_RETRIES = 3;
    
    handle(order: Order, event: Event): State | null {
        if (event.type === "PAYMENT_RETRY") {
            this.retryCount++;
            
            if (this.retryCount >= this.MAX_RETRIES) {
                order.notifyPaymentFailed();
                return new CancelledState();
            }
            
            // Self-transition: return same state type (new instance)
            // This triggers exit/entry actions again
            return new WaitingForPaymentState(); // Fresh retry counter
        }
        
        if (event.type === "PAYMENT_SUCCESS") {
            return new PaidState();
        }
        
        return null;
    }
    
    onEnter(order: Order): void {
        order.attemptPaymentCapture();
        order.scheduleRetryTimer(30000); // 30 second retry
    }
    
    onExit(order: Order): void {
        order.cancelRetryTimer();
    }
}

Keep It Simple When Possible

These advanced patterns add complexity. Use them when genuinely needed—when the domain truly has hierarchical states or parallel processes. Don't introduce complexity to handle simple scenarios. Many state machines work perfectly with flat state structures.

Transition Validation and Error Handling

Robust state machines must handle invalid transitions gracefully. What happens when code attempts a transition that shouldn't occur? How do we ensure the state machine never reaches an illegal state?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// Strategy 1: Silent rejection (return null/same state)
class ShippedState implements State {
    cancel(order: Order): State {
        // Can't cancel a shipped order - stay in current state
        console.log("Cannot cancel shipped order");
        return this; // Return same state, no transition
    }
}
 
// Strategy 2: Exception on invalid transition
class DeliveredState implements State {
    cancel(order: Order): never {
        throw new IllegalStateTransitionError(
            "DELIVERED",
            "CANCELLED",
            "Cannot cancel after delivery. Use return process instead."
        );
    }
}
 
// Strategy 3: Validation layer in context
class OrderContext {
    private readonly validTransitions: Map<string, Set<string>> = new Map([
        ["CREATED", new Set(["PAYMENT_PENDING", "CANCELLED"])],
        ["PAYMENT_PENDING", new Set(["PAID", "CANCELLED"])],
        ["PAID", new Set(["PROCESSING", "CANCELLED"])],
        ["PROCESSING", new Set(["SHIPPED", "CANCELLED"])],
        ["SHIPPED", new Set(["DELIVERED", "RETURN_REQUESTED"])],
        ["DELIVERED", new Set(["RETURN_REQUESTED", "COMPLETED"])],
        // Terminal states have no valid transitions
        ["CANCELLED", new Set()],
        ["COMPLETED", new Set()],
    ]);
    
    setState(newState: State): void {
        const currentStateName = this.state.getName();
        const newStateName = newState.getName();
        
        const allowedTargets = this.validTransitions.get(currentStateName);
        
        if (!allowedTargets?.has(newStateName)) {
            const error = new IllegalStateTransitionError(
                currentStateName,
                newStateName,
                `Transition not allowed. Valid targets from ${currentStateName}: ${[...allowedTargets || []].join(", ")}`
            );
            
            // Log for monitoring
            this.logger.error("Invalid state transition attempted", {
                from: currentStateName,
                to: newStateName,
                orderId: this.orderId,
            });
            
            throw error;
        }
        
        // Valid transition - proceed
        this.executeTransition(newState);
    }
}

When to Use Silent Rejection

•User-facing operations where invalid attempts are expected
•Event-driven systems where events might arrive out of order
•Idempotent operations (re-triggering is harmless)
•When the caller should continue despite rejection

When to Use Exceptions

•Internal operations where invalid transitions indicate bugs
•When the caller must handle the failure explicitly
•Critical flows where silent failure is dangerous
•When you want stack traces for debugging

Never Silently Corrupt State

The worst outcome is proceeding with a transition that leaves the system in an inconsistent state. If guards fail, entry actions fail, or invariants break—stop immediately. A thrown exception is infinitely better than corrupted data.

State Transitions

The Heart of the State Machine

Transition Fundamentals

Who Owns Transition Logic?

Transition Actions and Side Effects

Guarded Transitions

Event-Driven Transitions

Complex Transition Scenarios

Transition Validation and Error Handling

There’s more to understand.

State Transitions

The Heart of the State Machine

Transition Fundamentals

Who Owns Transition Logic?

Transition Actions and Side Effects

Guarded Transitions

Event-Driven Transitions

Complex Transition Scenarios

Transition Validation and Error Handling

There’s more to understand.