Discriminated union trong TypeScript: tagged union là gì

Discriminated union (còn gọi là tagged union) là union của các kiểu đối tượng có chung một thuộc tính, gọi là nhãn (tag), với giá trị literal khác nhau ở mỗi thành viên. Kiểm tra nhãn cho TypeScript biết bạn đang có thành viên nào, và các thuộc tính khác của thành viên đó trở nên dùng được.

type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number }
  | { kind: "triangle"; base: number; height: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2; // shape is the circle member here
    case "rect":
      return shape.width * shape.height;
    case "triangle":
      return (shape.base * shape.height) / 2;
  }
}

const shapes: Shape[] = [
  { kind: "circle", radius: 1 },
  { kind: "rect", width: 2, height: 3 },
  { kind: "triangle", base: 4, height: 5 },
];

for (const s of shapes) console.log(s.kind, area(s).toFixed(2));
// circle 3.14
// rect 6.00
// triangle 10.00

Bên trong case "circle", đọc shape.width sẽ là lỗi biên dịch, vì thành viên hình tròn không có width. Nhãn là dữ liệu bình thường: lúc chạy nó chỉ là một thuộc tính chuỗi, và switch là JavaScript thuần.

Điều gì làm nên một discriminated union

Thu hẹp kiểu theo nhãn hoạt động khi thỏa ba điều kiện:

1. Mọi thành viên đều là kiểu đối tượng.
2. Mọi thành viên có cùng một tên thuộc tính (discriminant). Tên do bạn chọn: kind, type, status và tag là các tên phổ biến.
3. Ở mỗi thành viên, thuộc tính đó có kiểu literal: một literal chuỗi, số hoặc boolean, hoặc null/undefined.

type UiEvent =
  | { type: "click"; x: number; y: number }
  | { type: "keypress"; key: string }
  | { type: "scroll"; delta: number };

type ApiResponse =
  | { ok: true; data: string }    // boolean literal tags
  | { ok: false; error: string };

type Message =
  | { version: 1; text: string }  // number literal tags
  | { version: 2; text: string; lang: string };

Nếu một thành viên khai báo nhãn là string thường thay vì literal, việc so sánh nhãn không còn thu hẹp được union, và các thuộc tính riêng của từng thành viên vẫn nằm ngoài tầm với (TS2339).

Thu hẹp kiểu theo nhãn

Mọi phép kiểm tra trên nhãn mà TypeScript hiểu được đều thu hẹp kiểu của đối tượng: switch, if/else, === và !==, kể cả nhãn được destructure miễn là nó là const:

function describe(e: UiEvent): string {
  if (e.type === "click") return `click at ${e.x},${e.y}`;

  const { type } = e;        // destructured tags narrow too
  if (type === "keypress") return `key ${e.key}`;

  return `scroll by ${e.delta}`; // only "scroll" is left
}

Kiểm tra thuộc tính bằng "radius" in shape cũng thu hẹp được, nhưng so sánh nhãn dễ đọc hơn và cho phép kiểm tra đầy đủ.

Kiểm tra đầy đủ

Lợi ích lớn nhất của mẫu này lộ ra khi union lớn dần. Với kiểu trả về tường minh và không có default, TypeScript biết switch phải bao hết mọi nhãn, nên một thành viên mới mà thiếu case là lỗi biên dịch:

// This does not compile: the "square" case is missing
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; width: number; height: number }
  | { kind: "square"; size: number };

function area(shape: Shape): number {
  switch (shape.kind) {
    case "circle":
      return Math.PI * shape.radius ** 2;
    case "rect":
      return shape.width * shape.height;
  }
}

console.log(area({ kind: "square", size: 2 }));

index.ts(7,30): error TS2366: Function lacks ending return statement and return type does not include 'undefined'.

Thông báo đó không nói case nào bị thiếu. Helper assertNever thì có, và nó còn ném lỗi lúc chạy nếu dữ liệu từ bên ngoài (JSON, một client cũ hơn) mang một nhãn mà kiểu nói là không thể tồn tại:

type RequestState<T> =
  | { status: "idle" }
  | { status: "loading"; startedAt: number }
  | { status: "success"; data: T }
  | { status: "error"; error: string; retryable: boolean };

function assertNever(value: never): never {
  throw new Error(`Unexpected state: ${JSON.stringify(value)}`);
}

function render(state: RequestState<string[]>): string {
  switch (state.status) {
    case "idle":
      return "Press load";
    case "loading":
      return `Loading since t=${state.startedAt}`;
    case "success":
      return `Loaded ${state.data.length} items: ${state.data.join(", ")}`;
    case "error":
      return `Failed: ${state.error}${state.retryable ? " (retry?)" : ""}`;
    default:
      return assertNever(state); // state is never here
  }
}

const states: RequestState<string[]>[] = [
  { status: "idle" },
  { status: "loading", startedAt: 1200 },
  { status: "success", data: ["a", "b"] },
  { status: "error", error: "timeout", retryable: true },
];

for (const s of states) console.log(render(s));
// Press load
// Loading since t=1200
// Loaded 2 items: a, b
// Failed: timeout (retry?)

Thêm trạng thái thứ năm mà không có case, dòng assertNever(state) sẽ báo Argument of type '{ status: "..."; ... }' is not assignable to parameter of type 'never', nêu rõ tên thành viên. Xem thêm ở trang never.

Loại bỏ những trạng thái không thể xảy ra

RequestState ở trên thay cho một cách mô tả phổ biến nhưng yếu hơn:

// Every combination is allowed, including nonsense
type LooseState<T> = {
  loading: boolean;
  data?: T;
  error?: string;
};

const nonsense: LooseState<string[]> = { loading: true, data: ["a"], error: "timeout" };

Với các thuộc tính tùy chọn, trạng thái "đang tải mà vừa có dữ liệu vừa có lỗi" vẫn qua được kiểm tra kiểu, và mọi người đọc code phải đoán xem tổ hợp nào thật sự có thể xảy ra. Với discriminated union, data chỉ tồn tại ở trạng thái success và error chỉ có ở trạng thái error, nên code đọc state.data trước hết phải chứng minh nó đang ở trạng thái success. Bản thân kiểu đã mô tả các trạng thái hợp lệ.

Mô hình hóa kết quả: thành công hoặc thất bại

Một nhãn boolean là đủ cho "thành công hay không". Kiểu Result này là một cách phổ biến thay cho việc ném ngoại lệ với những thất bại có thể lường trước, như đầu vào không hợp lệ:

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

function parsePort(text: string): Result<number> {
  const n = Number(text);
  if (!Number.isInteger(n)) return { ok: false, error: `"${text}" is not a whole number` };
  if (n < 1 || n > 65535) return { ok: false, error: `${n} is out of range` };
  return { ok: true, value: n };
}

for (const input of ["8080", "http", "70000"]) {
  const result = parsePort(input);
  if (result.ok) {
    console.log("port", result.value);   // result.value exists only here
  } else {
    console.log("error:", result.error); // result.error exists only here
  }
}
// port 8080
// error: "http" is not a whole number
// error: 70000 is out of range

Nơi gọi không thể đọc result.value mà không kiểm tra result.ok trước, đó chính là phép kiểm tra rất dễ quên khi dùng ngoại lệ hoặc trả về null.

State machine và reducer

Hai discriminated union, một cho trạng thái và một cho action, mô tả một state machine. Reducer dùng switch theo action và trả về trạng thái tiếp theo; trình biên dịch kiểm tra rằng mỗi đối tượng trả về là một trạng thái hợp lệ:

type State =
  | { name: "idle" }
  | { name: "playing"; track: string; position: number }
  | { name: "paused"; track: string; position: number };

type Action =
  | { type: "play"; track: string }
  | { type: "pause" }
  | { type: "resume" }
  | { type: "stop" };

function reduce(state: State, action: Action): State {
  switch (action.type) {
    case "play":
      return { name: "playing", track: action.track, position: 0 };
    case "pause":
      return state.name === "playing" ? { ...state, name: "paused" } : state;
    case "resume":
      return state.name === "paused" ? { ...state, name: "playing" } : state;
    case "stop":
      return { name: "idle" };
  }
}

const actions: Action[] = [{ type: "play", track: "Intro" }, { type: "pause" }, { type: "resume" }, { type: "stop" }];

let state: State = { name: "idle" };
for (const a of actions) {
  state = reduce(state, a);
  console.log(a.type.padEnd(6), "->", state.name);
}
// play   -> playing
// pause  -> paused
// resume -> playing
// stop   -> idle

{ ...state, name: "paused" } biên dịch được chỉ vì state đã được thu hẹp về thành viên đang phát trước đó, nên bản sao mang theo track và position. Chỉ trả về { name: "paused" } sẽ là lỗi: trạng thái tạm dừng cần có bài hát. Đây cũng là cách reducer của Redux và useReducer trong React được viết.

Cái bẫy mở rộng kiểu

Nhãn phải giữ nguyên kiểu literal. Một đối tượng được tạo vào một biến không có chú thích kiểu sẽ bị mở rộng nhãn thành string, và khi đó nó không khớp với thành viên nào:

type Shape = { kind: "circle"; radius: number } | { kind: "rect"; width: number; height: number };
declare function area(shape: Shape): number;

const c = { kind: "circle", radius: 2 }; // kind: string
area(c);
// error TS2345: Argument of type '{ kind: string; radius: number; }' is not assignable to parameter of type 'Shape'.

const ok1: Shape = { kind: "circle", radius: 2 };        // annotate the variable
const ok2 = { kind: "circle", radius: 2 } as const;      // or keep the literal with as const
area({ kind: "circle", radius: 2 });                     // or build it where Shape is expected

Quy tắc gốc rễ, rằng thuộc tính có thể thay đổi sẽ bị mở rộng kiểu, được giải thích ở trang literal type.