Discriminated Union TypeScript: Penjelasan Tagged Union

Discriminated union (disebut juga tagged union) adalah union dari object type yang semuanya punya satu property yang sama, yaitu tag, dengan nilai literal yang berbeda di setiap anggota. Memeriksa tag-nya memberi tahu TypeScript anggota mana yang sedang kamu pegang, dan property lain dari anggota itu menjadi bisa diakses.

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

Di dalam case "circle", membaca shape.width akan menjadi error kompilasi, karena anggota circle tidak punya width. Tag-nya adalah data biasa: saat runtime ia hanyalah property string, dan switch-nya adalah JavaScript biasa.

Apa yang Membuat Sebuah Union Menjadi Discriminated

Penyempitan berdasarkan tag berhasil kalau tiga syarat ini terpenuhi:

1. Setiap anggota adalah object type.
2. Setiap anggota punya nama property yang sama (discriminant). Namanya bebas: kind, type, status, dan tag adalah yang umum.
3. Di setiap anggota, property itu bertipe literal: literal string, number, atau boolean, atau 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 };

Kalau satu anggota mendeklarasikan tag sebagai string biasa, bukan literal, membandingkan tag tidak lagi mempersempit union, dan property khusus anggota tetap tidak bisa dijangkau (TS2339).

Mempersempit Berdasarkan Tag

Pemeriksaan apa pun pada tag yang dipahami TypeScript akan mempersempit objeknya: switch, if/else, === dan !==, bahkan tag hasil destructuring selama ia berupa 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
}

Memeriksa keberadaan property dengan "radius" in shape juga mempersempit, tetapi membandingkan tag lebih jelas dibaca dan memungkinkan pemeriksaan menyeluruh.

Pemeriksaan Menyeluruh

Manfaat terbesar pola ini terlihat saat union-nya bertambah. Dengan tipe kembalian yang eksplisit dan tanpa default, TypeScript tahu bahwa switch harus mencakup setiap tag, jadi anggota baru tanpa case menjadi error kompilasi:

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

Pesan itu tidak menyebutkan case mana yang terlewat. Helper assertNever menyebutkannya, dan juga melempar error saat runtime kalau data dari luar (JSON, client versi lama) membawa tag yang menurut tipenya tidak mungkin ada:

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

Tambahkan status kelima tanpa case, dan baris assertNever(state) melaporkan Argument of type '{ status: "..."; ... }' is not assignable to parameter of type 'never', dengan menyebutkan anggotanya. Penjelasan lebih lanjut ada di halaman never.

Membuat State yang Mustahil Benar-benar Mustahil

RequestState di atas menggantikan bentuk yang umum tetapi lebih lemah:

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

Dengan field opsional, "sedang loading dengan data dan error" lolos pemeriksaan tipe, dan setiap pembaca harus menebak kombinasi mana yang benar-benar bisa terjadi. Dengan discriminated union, data hanya ada di state success dan error hanya di error, jadi kode yang membaca state.data harus membuktikan dulu bahwa ia berada di state success. Tipenya sendiri mendokumentasikan state yang valid.

Memodelkan Hasil: Berhasil atau Gagal

Tag boolean sudah cukup untuk "berhasil atau tidak". Tipe Result ini adalah alternatif umum dari melempar exception untuk kegagalan yang memang diperkirakan, seperti input yang tidak valid:

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

Pemanggil tidak bisa membaca result.value tanpa memeriksa result.ok lebih dulu, dan itulah pemeriksaan yang mudah terlupa kalau memakai exception atau nilai kembalian null.

State Machine dan Reducer

Dua discriminated union, satu untuk state dan satu untuk action, mendeskripsikan sebuah state machine. Reducer melakukan switch pada action dan mengembalikan state berikutnya; compiler memeriksa bahwa setiap objek yang dikembalikan adalah state yang valid:

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" } hanya lolos kompilasi karena state sudah dipersempit menjadi anggota playing lebih dulu, sehingga salinannya membawa track dan position. Mengembalikan { name: "paused" } saja akan menjadi error: state paused butuh track. Ini bentuk yang sama yang dipakai reducer Redux dan useReducer di React.

Jebakan Pelebaran Tipe

Tag-nya harus tetap bertipe literal. Objek yang dibuat ke dalam variabel tanpa anotasi akan dilebarkan tag-nya menjadi string, lalu tidak cocok dengan anggota mana pun:

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

Aturan dasarnya, bahwa property yang bisa diubah akan dilebarkan tipenya, dijelaskan di halaman tipe literal.