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 compileNotes
- Invalid transitions are caught by the type system before runtime
onEnterandonExithooks handle side effects (notifications, logging, cleanup)- The history array provides a full audit trail of all state transitions
- The
datamap stores context that persists across transitions (user info, order details) - Use
as conston the config object to get literal type inference for state/event names