Union Type TypeScript: Operator | dan Contohnya

Union type mendaftar beberapa alternatif dengan |: nilai bertipe string | number berupa string atau number. Union adalah cara TypeScript menjelaskan nilai yang memang bisa punya lebih dari satu bentuk, dan compiler mewajibkanmu mengecek bentuk mana yang kamu pegang sebelum memakai apa pun yang khusus untuk bentuk itu.

function formatId(id: string | number): string {
  if (typeof id === "number") {
    return id.toString().padStart(6, "0"); // id is number here
  }
  return id.toUpperCase();                 // id is string here
}

console.log(formatId(42));     // 000042
console.log(formatId("ab-7")); // AB-7

Di dalam setiap cabang pemeriksaan typeof, id hanya punya satu tipe. Langkah itu disebut narrowing, dan itulah yang membuat union praktis dipakai.

Hanya Member Bersama yang Boleh Dipakai

Sebelum narrowing, kamu hanya bisa memakai apa yang didukung setiap anggota union. toString() ada di string maupun number, jadi boleh dipakai; toUpperCase() hanya ada di string:

// This does not compile: numbers have no toUpperCase()
function shout(value: string | number) {
  return value.toUpperCase();
}

console.log(shout("hi"));

index.ts(3,16): error TS2339: Property 'toUpperCase' does not exist on type 'string | number'.
  Property 'toUpperCase' does not exist on type 'number'.

Baris kedua menyebutkan anggota yang tidak punya property itu. Aturan yang sama berlaku ke arah sebaliknya: nilai string | number tidak bisa diberikan ke parameter bertipe string (TS2345), karena nilainya mungkin number. Union menerima lebih banyak nilai, dan sebagai gantinya membatasi apa yang bisa kamu lakukan dengan nilai itu sampai kamu memeriksanya.

Mempersempit Union

Narrowing memakai pemeriksaan JavaScript biasa. TypeScript mengikuti alur kontrol dan membuang anggota yang sudah tersingkir, jadi setelah pemeriksaan terakhir hanya satu anggota yang tersisa:

type Input = string | number | string[] | Date | null;

function normalize(input: Input): string {
  if (input === null) return "(empty)";
  if (typeof input === "string") return input.trim();
  if (typeof input === "number") return input.toFixed(1);
  if (Array.isArray(input)) return input.join(", ");
  return input.toISOString().slice(0, 10); // only Date is left
}

const samples: Input[] = ["  hi  ", 3, ["a", "b"], new Date("2024-03-15T10:30:00Z"), null];
for (const s of samples) console.log(normalize(s));
// hi
// 3.0
// a, b
// 2024-03-15
// (empty)

Daftar lengkap bentuk narrowing ada di halaman type narrowing.

Union dari Tipe Literal

Union dari nilai literal adalah himpunan tertutup dari nilai yang diizinkan. Inilah union yang paling umum dalam kode nyata:

type Status = "idle" | "loading" | "success" | "error";
type Dice = 1 | 2 | 3 | 4 | 5 | 6;
type Toggle = "on" | "off" | boolean; // boolean is itself true | false

let current: Status = "idle";
current = "loading";   // fine
current = "finished";  // error TS2322: Type '"finished"' is not assignable to type 'Status'.

Membandingkan dengan literal akan mempersempit tipe: setelah if (current === "error"), cabang else tahu bahwa current adalah salah satu dari tiga nilai lainnya. Union literal menggantikan enum di banyak codebase; lihat tipe literal untuk as const dan cara menurunkan union seperti itu dari sebuah array.

Union dari Object Type

Ketika anggotanya berupa object type, property yang dimiliki semuanya bisa langsung dipakai. Untuk yang lainnya, cek dulu keberadaan property itu dengan in:

type Cat = { name: string; meow(): string };
type Fish = { name: string; swim(): string };

function act(pet: Cat | Fish): string {
  const intro = `${pet.name}: `; // name exists on both, so it is allowed
  if ("meow" in pet) {
    return intro + pet.meow();   // pet is Cat here
  }
  return intro + pet.swim();     // pet is Fish here
}

const tom: Cat = { name: "Tom", meow: () => "meow" };
const nemo: Fish = { name: "Nemo", swim: () => "swims away" };

console.log(act(tom));  // Tom: meow
console.log(act(nemo)); // Nemo: swims away

Untuk union dari beberapa bentuk object, pola yang lebih rapi adalah property literal bersama seperti kind: "cat" / kind: "fish". Memeriksa satu property itu mempersempit seluruh object, dan switch atas property itu bisa diperiksa kelengkapannya. Pola itu disebut discriminated union.

Array dan Union

Letak tanda kurung mengubah artinya sama sekali:

const mixed: (string | number)[] = [1, "two", 3]; // each element may be either
const eitherOr: string[] | number[] = ["a", "b"]; // all strings OR all numbers

// @ts-expect-error: Type '(string | number)[]' is not assignable to type 'string[] | number[]'.
const bad: string[] | number[] = ["a", 1];

const precedence: string | number[] = "not an array"; // | binds looser than []

console.log(mixed, eitherOr, precedence);
// [ 1, 'two', 3 ] [ 'a', 'b' ] not an array

const total = mixed.reduce<number>((sum, x) => sum + (typeof x === "number" ? x : 0), 0);
console.log(total); // 4

Saat melakukan iterasi pada (string | number)[], setiap elemen bertipe union dan perlu dipersempit, seperti di callback reduce di atas. Method seperti map dan filter juga bekerja pada string[] | number[], dengan callback yang menerima string | number.

Union dengan null dan undefined

Union yang paling umum dari semuanya adalah "sebuah nilai atau tidak ada": string | null, User | undefined. Itulah yang dikembalikan Array.prototype.find dan Map.prototype.get, dan property opsional name?: string terbaca sebagai string | undefined. Cara menanganinya dengan ?., ?? dan pemeriksaan null punya halamannya sendiri: null dan undefined.

Untuk membuang anggota dari union yang sudah ada di tingkat tipe, pakai utility bawaan: Exclude<"a" | "b" | "c", "a"> adalah "b" | "c", dan NonNullable<string | null> adalah string.