TypeScript โปรเจกต์: finite state machine ที่ type-safe
state machine ที่ compiler บังคับว่า “จาก state นี้ ทำ event ไหนได้บ้าง” และ “event นี้พา state ไปไหน” — invalid transition เป็น compile error
ตัวอย่าง: order lifecycle
draft ──submit──> pending ──pay──> paid ──ship──> shipped ──deliver──> delivered
│ │
└───cancel───> cancelled <───cancel───┘src/machine.ts — generic state machine
// state และ event เป็น discriminated union (มี `type`)
type StateLike = { type: string };
type EventLike = { type: string };
// transition map: จาก state type ไหน + event type ไหน → state ใหม่
type TransitionMap<S extends StateLike, E extends EventLike> = {
[ST in S["type"]]?: {
[ET in E["type"]]?: (
state: Extract<S, { type: ST }>,
event: Extract<E, { type: ET }>,
) => S;
};
};
export class StateMachine<S extends StateLike, E extends EventLike> {
constructor(
private state: S,
private transitions: TransitionMap<S, E>,
) {}
getState(): S {
return this.state;
}
can(eventType: E["type"]): boolean {
const stateTransitions = this.transitions[this.state.type as S["type"]];
return stateTransitions !== undefined && eventType in stateTransitions;
}
send(event: E): S {
const stateTransitions = this.transitions[this.state.type as S["type"]];
const handler = stateTransitions?.[event.type as E["type"]];
if (!handler) {
throw new Error(
`ไม่สามารถทำ "${event.type}" จาก state "${this.state.type}"`,
);
}
// @ts-expect-error - type ของ handler ถูกแล้วในตอนสร้าง transitions
this.state = handler(this.state, event);
return this.state;
}
}src/order.ts — order machine
import { StateMachine } from "./machine.js";
// --- states ---
export type OrderState =
| { type: "draft"; items: string[] }
| { type: "pending"; items: string[]; total: number }
| { type: "paid"; items: string[]; total: number; paidAt: string }
| { type: "shipped"; items: string[]; trackingNo: string }
| { type: "delivered"; deliveredAt: string }
| { type: "cancelled"; reason: string };
// --- events ---
export type OrderEvent =
| { type: "submit" }
| { type: "pay"; method: string }
| { type: "ship"; trackingNo: string }
| { type: "deliver" }
| { type: "cancel"; reason: string };
export function createOrderMachine(items: string[]) {
return new StateMachine<OrderState, OrderEvent>(
{ type: "draft", items },
{
draft: {
submit: (state) => ({
type: "pending",
items: state.items,
total: state.items.length * 100, // state: { type: "draft"; items: string[] }
}),
cancel: (_state, event) => ({ type: "cancelled", reason: event.reason }),
},
pending: {
pay: (state, event) => ({
type: "paid",
items: state.items,
total: state.total, // state: { type: "pending"; ...; total: number }
paidAt: new Date().toISOString(),
}),
cancel: (_state, event) => ({ type: "cancelled", reason: event.reason }),
},
paid: {
ship: (state, event) => ({
type: "shipped",
items: state.items,
trackingNo: event.trackingNo, // event: { type: "ship"; trackingNo: string }
}),
},
shipped: {
deliver: () => ({
type: "delivered",
deliveredAt: new Date().toISOString(),
}),
},
// delivered, cancelled = ไม่มี transition (terminal state)
},
);
}ใช้งาน
import { createOrderMachine } from "./order.js";
const order = createOrderMachine(["เสื้อ", "กางเกง", "หมวก"]);
console.log(order.getState().type); // "draft"
order.send({ type: "submit" });
console.log(order.getState());
// { type: "pending", items: [...], total: 300 }
order.send({ type: "pay", method: "credit_card" });
console.log(order.getState().type); // "paid"
order.send({ type: "ship", trackingNo: "TH123456" });
console.log(order.getState());
// { type: "shipped", items: [...], trackingNo: "TH123456" }
// ❌ invalid transition — compile OK แต่ throw ตอน runtime
order.send({ type: "pay", method: "cash" });
// Error: ไม่สามารถทำ "pay" จาก state "shipped"
// ✅ เช็คก่อนส่ง
if (order.can("deliver")) {
order.send({ type: "deliver" });
}type safety ที่ได้
// event ที่ไม่มีใน OrderEvent → compile error
order.send({ type: "refund" });
// ~~~~~~~~~~~~~~~~~ Argument not assignable to OrderEvent
// ใน transition handler — state และ event narrow ตาม key
{
paid: {
ship: (state, event) => {
state.total; // ✅ state: { type: "paid"; ...; total: number }
event.trackingNo; // ✅ event: { type: "ship"; trackingNo: string }
state.trackingNo; // ❌ Error — paid state ไม่มี trackingNo
return { type: "shipped", items: state.items, trackingNo: event.trackingNo };
// ต้อง return OrderState ที่ valid
},
},
}
// exhaustive check ของ state
function render(state: OrderState): string {
switch (state.type) {
case "draft": return `ร่าง (${state.items.length} ชิ้น)`;
case "pending": return `รอชำระ ${state.total} บาท`;
case "paid": return `ชำระแล้ว`;
case "shipped": return `จัดส่ง #${state.trackingNo}`;
case "delivered": return `ได้รับแล้ว`;
case "cancelled": return `ยกเลิก: ${state.reason}`;
default: {
const _exhaustive: never = state; // เพิ่ม state ใหม่แล้วลืม case → error
return _exhaustive;
}
}
}test
import { describe, it, expect } from "vitest";
import { createOrderMachine } from "./order.js";
describe("order state machine", () => {
it("happy path", () => {
const order = createOrderMachine(["a", "b"]);
order.send({ type: "submit" });
expect(order.getState().type).toBe("pending");
order.send({ type: "pay", method: "card" });
expect(order.getState().type).toBe("paid");
order.send({ type: "ship", trackingNo: "T1" });
order.send({ type: "deliver" });
expect(order.getState().type).toBe("delivered");
});
it("cancel จาก pending", () => {
const order = createOrderMachine(["a"]);
order.send({ type: "submit" });
order.send({ type: "cancel", reason: "เปลี่ยนใจ" });
const state = order.getState();
expect(state.type).toBe("cancelled");
if (state.type === "cancelled") {
expect(state.reason).toBe("เปลี่ยนใจ");
}
});
it("invalid transition throw", () => {
const order = createOrderMachine(["a"]);
expect(() => order.send({ type: "ship", trackingNo: "T1" })).toThrow(/ไม่สามารถ/);
});
it("can() บอก transition ที่ทำได้", () => {
const order = createOrderMachine(["a"]);
expect(order.can("submit")).toBe(true);
expect(order.can("pay")).toBe(false);
});
});จุดที่ใช้ความรู้จากบทก่อน
| ส่วน | บท |
|---|---|
| discriminated union (state + event) | 7 |
Extract<S, { type: ST }> — narrow union ด้วย key | 15, 16 |
mapped type { [ST in S["type"]]?: ... } | 13, 14 |
indexed access S["type"], E["type"] | 13 |
generic class StateMachine<S, E> | 12 |
exhaustive never check | 23 |
| Vitest table-ish test | 34 |
ต่อยอด
- guard — เงื่อนไขก่อน transition (
canTransition: (state, event) => boolean) - side effect / action — รันเมื่อเข้า state (
onEnter) - history — เก็บ transition log
- XState — library เต็มรูปแบบ (parallel state, nested, actor model) — ใช้เมื่อ machine ซับซ้อน
- visualize — export เป็น mermaid / dot graph
เรื่องที่คนมักพลาด
- state ไม่มี discriminant —
{ items, total }แทน{ type: "pending", items, total }— narrow ไม่ได้ - transition handler return state ผิด shape — compiler จับ (return type ต้องเป็น
S) - ไม่มี terminal state —
delivered/cancelledไม่ควรมี transition (ไม่ใส่ใน map) can()ไม่เช็คก่อนsend()ในโค้ดที่ event มาจากภายนอก — throw; เช็คหรือ try/catch@ts-expect-errorในตัว library — จำเป็นเพราะ TS ตาม generic mapped type ลึก ๆ ไม่ไหว; type ที่ boundary (transitions object) ถูกต้อง- แก้ state โดยตรง (
machine.state.total = ...) — bypass machine; state ควร immutable, สร้างใหม่ใน handler
สรุป
- state + event เป็น discriminated union (
{ type: "..." }+ payload) - TransitionMap = mapped type
{ [ST in State["type"]]?: { [ET in Event["type"]]?: handler } } - handler รับ
Extract<State, {type: ST}>+Extract<Event, {type: ET}>— narrow อัตโนมัติ, ต้อง return valid state send(event)— event นอกEventunion = compile error; invalid transition = runtime throw (เช็คcan()ก่อน)switch (state.type)+never= exhaustive rendering- XState เมื่อ machine ซับซ้อน (nested, parallel, actor)
บทถัดไป โปรเจกต์ form validation library — generic schema builder ที่ infer type จาก schema