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 ด้วย key15, 16
mapped type { [ST in S["type"]]?: ... }13, 14
indexed access S["type"], E["type"]13
generic class StateMachine<S, E>12
exhaustive never check23
Vitest table-ish test34

ต่อยอด

  • 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 นอก Event union = 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