TypeScript Discriminated Union: Etiketli Union'lar

Discriminated union (etiketli union, tagged union olarak da bilinir), hepsinin ortak bir özelliğe, yani etikete, her üyede farklı bir literal değerle sahip olduğu nesne tiplerinin bir union'ıdır. Etiketi kontrol etmek TypeScript'e hangi üyeye sahip olduğunuzu söyler ve o üyenin diğer özellikleri kullanılabilir hale gelir.

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" içinde shape.width okumak bir derleme hatası olurdu, çünkü daire üyesinin width özelliği yoktur. Etiket sıradan bir veridir: çalışma zamanında sadece bir string özelliktir ve switch düz JavaScript'tir.

Bir Union'ı Discriminated Yapan Nedir

Etiket üzerinden daraltma, üç koşul sağlandığında çalışır:

1. Her üye bir nesne tipidir.
2. Her üye aynı özellik adına (ayırıcıya) sahiptir. Ad size kalmıştır: kind, type, status ve tag yaygındır.
3. Her üyede bu özellik bir literal tipe sahiptir: bir string, number veya boolean literal'i ya da 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 };

Bir üye etiketi literal yerine düz string olarak bildirirse etiketi karşılaştırmak artık union'ı daraltmaz ve üyeye özgü özellikler erişilemez kalır (TS2339).

Etiket Üzerinden Daraltmak

TypeScript'in etiket üzerinde anladığı her kontrol nesneyi daraltır: switch, if/else, === ve !==, hatta const olduğu sürece destructuring ile alınmış bir etiket:

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 ile bir özelliği kontrol etmek de daraltır, ama bir etiketi karşılaştırmak okunması daha kolaydır ve kapsamlı kontrolü mümkün kılar.

Kapsamlı Kontroller

Kalıbın en büyük faydası union büyüdüğünde görünür. Açık bir dönüş tipiyle ve default olmadan TypeScript, switch ifadesinin her etiketi kapsaması gerektiğini bilir; bu yüzden case'i olmayan yeni bir üye bir derleme hatasıdır:

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

Bu mesaj hangi case'in eksik olduğunu söylemez. assertNever yardımcısı söyler; ayrıca dışarıdan gelen veriler (JSON, eski bir istemci) tiplerin var olamaz dediği bir etiket taşırsa çalışma zamanında da hata fırlatır:

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 eklemeden beşinci bir status ekleyin, assertNever(state) satırı üyeyi adıyla belirterek Argument of type '{ status: "..."; ... }' is not assignable to parameter of type 'never' bildirir. Daha fazlası never sayfasında.

İmkansız Durumları İmkansız Kılmak

Yukarıdaki RequestState, yaygın ve daha zayıf bir biçimin yerini alır:

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

Opsiyonel alanlarla "veri ve hatayla birlikte yükleniyor" durumu tip kontrolünden geçer ve her okuyucu hangi kombinasyonların gerçekten olabileceğini tahmin etmek zorunda kalır. Discriminated union ile data yalnızca success durumunda, error da yalnızca error durumunda vardır; bu yüzden state.data okuyan kod önce success durumunda olduğunu kanıtlamalıdır. Tipin kendisi geçerli durumları belgeler.

Sonuçları Modellemek: Başarı ya da Başarısızlık

"Çalıştı ya da çalışmadı" için bir boolean etiket yeterlidir. Bu Result tipi, geçersiz girdi gibi beklenen başarısızlıklar için hata fırlatmaya yaygın bir alternatiftir:

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

Çağıran, önce result.ok kontrolünü yapmadan result.value okuyamaz; exception'larla ya da null dönüşleriyle unutulması kolay olan kontrol de tam olarak budur.

Durum Makineleri ve Reducer'lar

Biri durumlar, biri aksiyonlar için olmak üzere iki discriminated union bir durum makinesini tanımlar. Bir reducer aksiyon üzerinde switch yapar ve sonraki durumu döndürür; derleyici döndürülen her nesnenin geçerli bir durum olduğunu kontrol eder:

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" } yalnızca state önce playing üyesine daraltıldığı için derlenir, böylece kopya track ve position taşır. Tek başına { name: "paused" } döndürmek hata olurdu: duraklatılmış bir durum bir parça (track) gerektirir. Redux reducer'larının ve React'teki useReducer fonksiyonunun kullandığı biçim de budur.

Genişleme Tuzağı

Etiket bir literal tip olarak kalmalıdır. Notasyonsuz bir değişkende oluşturulan bir nesnenin etiketi string tipine genişletilir ve o zaman hiçbir üyeyle eşleşmez:

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

Temeldeki kural, yani değiştirilebilir özelliklerin genişlemesi, literal tipler sayfasında açıklanıyor.