Discriminated Unions في TypeScript: شرح الـ 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 مميَّزًا

يعمل التضييق على الوسم عندما تتحقق ثلاثة شروط:

1. كل عضو نوع كائن.
2. كل عضو يملك اسم الخاصية نفسه (المميّز). الاسم متروك لك: 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، و=== و!==، بل والوسم المفكك ما دام 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 ضُيّق أولًا إلى عضو التشغيل، فتحمل النسخة track وposition. أما إعادة { name: "paused" } وحدها فستكون خطأ: حالة الإيقاف تحتاج إلى مقطع. وهذا الشكل نفسه الذي تستخدمه 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

القاعدة الأساسية، أي أن الخصائص القابلة للتغيير تتوسع، مشروحة في صفحة الأنواع الحرفية.