TypeScripttypescriptstate-machinedesign-patternsproduction-ready

Type-Safe Finite State Machine

A compile-time-checked state machine that prevents invalid transitions and enforces correct event handling through TypeScript's type system.

type StateConfig = {
  [state: string]: {
    [event: string]: string;
  };
};

type StateFrom<T extends StateConfig> = keyof T & string;
type EventFrom<T extends StateConfig, S extends StateFrom<T>> = keyof T[S] & string;
type TransitionTarget<T extends StateConfig, S extends StateFrom<T>, E extends EventFrom<T, S>> = T[S][E] & string;

interface MachineContext<T extends StateConfig> {
  state: StateFrom<T>;
  history: { from: string; to: string; event: string; timestamp: number }[];
  data: Map<string, unknown>;
}

type TransitionHandler<T extends StateConfig> = (
  context: MachineContext<T>,
  event: string
) => void | Promise<void>;

export class StateMachine<T extends StateConfig> {
  private context: MachineContext<T>;
  private onEnterHandlers = new Map<string, TransitionHandler<T>>();
  private onExitHandlers = new Map<string, TransitionHandler<T>>();
  private onTransitionHandlers: TransitionHandler<T>[] = [];

  constructor(
    private readonly config: T,
    initialState: StateFrom<T>
  ) {
    this.context = {
      state: initialState,
      history: [],
      data: new Map(),
    };
  }

  get currentState(): StateFrom<T> {
    return this.context.state;
  }

  get history() {
    return [...this.context.history];
  }

  onEnter(state: StateFrom<T>, handler: TransitionHandler<T>): this {
    this.onEnterHandlers.set(state, handler);
    return this;
  }

  onExit(state: StateFrom<T>, handler: TransitionHandler<T>): this {
    this.onExitHandlers.set(state, handler);
    return this;
  }

  onTransition(handler: TransitionHandler<T>): this {
    this.onTransitionHandlers.push(handler);
    return this;
  }

  canTransition<S extends StateFrom<T>>(state: S, event: EventFrom<T, S>): boolean {
    return event in (this.config[state] ?? {});
  }

  async send<S extends StateFrom<T>, E extends EventFrom<T, S>>(
    event: E extends EventFrom<T, typeof this.context.state> ? E : never
  ): Promise<StateFrom<T>> {
    const currentState = this.context.state;
    const transitions = this.config[currentState];

    if (!transitions || !(event in transitions)) {
      throw new Error(`Invalid transition: ${currentState} + ${event}`);
    }

    const nextState = transitions[event as string] as StateFrom<T>;

    // Execute exit handler
    const exitHandler = this.onExitHandlers.get(currentState);
    if (exitHandler) await exitHandler(this.context, event);

    // Record transition
    this.context.history.push({
      from: currentState,
      to: nextState,
      event,
      timestamp: Date.now(),
    });

    // Update state
    this.context.state = nextState;

    // Execute transition handlers
    for (const handler of this.onTransitionHandlers) {
      await handler(this.context, event);
    }

    // Execute enter handler
    const enterHandler = this.onEnterHandlers.get(nextState);
    if (enterHandler) await enterHandler(this.context, event);

    return nextState;
  }

  setData(key: string, value: unknown): void {
    this.context.data.set(key, value);
  }

  getData<V>(key: string): V | undefined {
    return this.context.data.get(key) as V | undefined;
  }
}

title: "Type-Safe Finite State Machine" description: "A compile-time-checked state machine that prevents invalid transitions and enforces correct event handling through TypeScript's type system." category: "TypeScript" language: "typescript" tags: ["typescript", "state-machine", "design-patterns", "production-ready"] createdAt: "2025-03-15" updatedAt: "2025-04-01"

Overview

A finite state machine with compile-time transition validation. The state configuration object defines all valid transitions, and TypeScript ensures you cannot send events that are not valid for the current state.

Code

const machine = new StateMachine(stateConfig, "initial");
machine.onEnter("active", handler);
await machine.send("activate"); // Only valid events compile

Notes

  • Invalid transitions are caught by the type system before runtime
  • onEnter and onExit hooks handle side effects (notifications, logging, cleanup)
  • The history array provides a full audit trail of all state transitions
  • The data map stores context that persists across transitions (user info, order details)
  • Use as const on the config object to get literal type inference for state/event names