Discriminated Unions ב-TypeScript: הסבר על Tagged Unions

discriminated union (שנקרא גם tagged union) הוא union של טיפוסי אובייקט שלכולם יש מאפיין אחד משותף, התגית, עם ערך ליטרלי שונה בכל איבר. בדיקה של התגית אומרת ל-TypeScript איזה איבר יש לכם, והמאפיינים האחרים של האיבר הזה נהיים זמינים.

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

בתוך case "circle", קריאה של shape.width הייתה שגיאת קומפילציה, כי לאיבר של העיגול אין width. התגית היא מידע רגיל: בזמן ריצה היא סתם מאפיין מחרוזת, וה-switch הוא JavaScript רגיל.

מה הופך union ל-discriminated

צמצום לפי התגית עובד כששלושה תנאים מתקיימים:

1. כל איבר הוא טיפוס אובייקט.
2. לכל איבר יש את אותו שם מאפיין (ה-discriminant). השם תלוי בכם: kind, type, status ו-tag נפוצים.
3. בכל איבר, למאפיין הזה יש טיפוס ליטרלי: ליטרל של מחרוזת, מספר או בוליאני, או 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 };

אם איבר אחד מצהיר על התגית כ-string רגיל במקום ליטרל, השוואת התגית כבר לא מצמצמת את ה-union, ומאפיינים ספציפיים לאיבר נשארים לא נגישים (TS2339).

צמצום לפי התגית

כל בדיקה על התגית ש-TypeScript מבינה מצמצמת את האובייקט: switch, if/else, === ו-!==, אפילו תגית שחולצה ב-destructuring, כל עוד היא 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
}

גם בדיקה של מאפיין עם "radius" in shape מצמצמת, אבל השוואה של תגית קריאה יותר ומאפשרת בדיקה ממצה.

בדיקות ממצות

היתרון הגדול ביותר של הדפוס מתגלה כשה-union גדל. עם טיפוס החזרה מפורש ובלי default, TypeScript יודעת שה-switch חייב לכסות כל תגית, ולכן איבר חדש בלי case הוא שגיאת קומפילציה:

// 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'.

ההודעה הזו לא אומרת איזה מקרה חסר. פונקציית העזר assertNever כן אומרת, והיא גם זורקת בזמן ריצה אם מידע מבחוץ (JSON, לקוח ישן יותר) נושא תגית שלפי הטיפוסים לא יכולה להתקיים:

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?)

הוסיפו סטטוס חמישי בלי case והשורה assertNever(state) תדווח Argument of type '{ status: "..."; ... }' is not assignable to parameter of type 'never', עם שם האיבר. עוד על זה בעמוד never.

להפוך מצבים בלתי אפשריים לבלתי אפשריים

RequestState שלמעלה מחליף מבנה נפוץ וחלש יותר:

// 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" };

עם שדות אופציונליים, "טוען עם מידע ועם שגיאה" עובר בדיקת טיפוסים, וכל קורא צריך לנחש אילו צירופים באמת יכולים לקרות. עם ה-discriminated union, data קיים רק במצב success ו-error רק ב-error, ולכן קוד שקורא את state.data חייב להוכיח קודם שהוא במצב success. הטיפוס עצמו מתעד את המצבים התקינים.

תיאור תוצאות: הצלחה או כישלון

תגית בוליאנית מספיקה ל"זה עבד או לא". טיפוס ה-Result הזה הוא חלופה נפוצה לזריקת חריגות בכישלונות צפויים כמו קלט לא תקין:

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

הקורא לא יכול לקרוא את result.value בלי לבדוק קודם את result.ok, וזו בדיוק הבדיקה שקל לשכוח עם חריגות או עם החזרת null.

מכונות מצבים ו-Reducers

שני discriminated unions, אחד למצבים ואחד לפעולות, מתארים מכונת מצבים. reducer עושה switch על הפעולה ומחזיר את המצב הבא; הקומפיילר בודק שכל אובייקט שמוחזר הוא מצב תקין:

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" } עובר קומפילציה רק כי state צומצם קודם לאיבר של playing, ולכן העותק נושא את track ואת position. החזרה של { name: "paused" } לבד הייתה שגיאה: מצב paused צריך track. זה אותו מבנה שבו משתמשים reducers של Redux ו-useReducer ב-React.

מלכודת ההרחבה

התגית חייבת להישאר טיפוס ליטרלי. לאובייקט שנבנה לתוך משתנה בלי הערת טיפוס, התגית מורחבת ל-string, ואז הוא לא מתאים לאף איבר:

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

הכלל שמאחורי זה, שמאפיינים שניתנים לשינוי מורחבים, מוסבר בעמוד literal types.