TypeScript Union Tipler: | Operatörü ve Örnekler

Bir union tip alternatifleri | ile listeler: string | number tipindeki bir değer ya bir string ya da bir sayıdır. Union'lar, TypeScript'in meşru olarak birden fazla biçim alabilen değerleri tanımlama yoludur ve derleyici, o biçime özgü bir şeyi kullanmadan önce hangi biçime sahip olduğunuzu kontrol etmenizi ister.

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

typeof kontrolünün her dalında id tek bir tipe sahiptir. Bu adıma daraltma (narrowing) denir ve union'ları pratik kılan da budur.

Yalnızca Ortak Üyelere İzin Verilir

Daraltmadan önce yalnızca union'ın her üyesinin desteklediği şeyleri kullanabilirsiniz. toString() hem string'lerde hem sayılarda vardır, bu yüzden sorun yoktur; toUpperCase() ise yalnızca string'lerde vardır:

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

İkinci satır, özelliği eksik olan üyeyi adıyla söyler. Aynı kural diğer yönde de geçerlidir: bir string | number değeri string olarak tiplenmiş bir parametreye verilemez (TS2345), çünkü bir sayı olabilir. Bir union daha fazla değer kabul eder ve karşılığında siz kontrol edene kadar onlarla daha az şey yapmanıza izin verir.

Bir Union'ı Daraltmak

Daraltma sıradan JavaScript kontrollerini kullanır. TypeScript kontrol akışını izler ve elendikçe üyeleri çıkarır, böylece son kontrolden sonra yalnızca bir üye kalır:

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)

Daraltma biçimlerinin tam listesi tip daraltma sayfasında.

Literal Tiplerin Union'ları

Literal değerlerin bir union'ı, izin verilen değerlerin kapalı bir kümesidir. Gerçek kodda en yaygın union budur:

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

Bir literal ile karşılaştırmak daraltır: if (current === "error") sonrasında else dalı current değerinin diğer üç değerden biri olduğunu bilir. Literal union'lar pek çok kod tabanında enum'ların yerini alır; as const ve böyle bir union'ı bir diziden türetmek için literal tipler sayfasına bakın.

Nesne Tiplerinin Union'ları

Üyeler nesne tipleri olduğunda, hepsinin paylaştığı özellikler doğrudan kullanılabilir. Geri kalanlar için özelliğin var olduğunu in ile kontrol edin:

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

Birkaç nesne biçiminden oluşan union'lar için daha temiz kalıp, kind: "cat" / kind: "fish" gibi ortak bir literal özelliktir. O tek özelliği kontrol etmek nesnenin tamamını daraltır ve onun üzerindeki bir switch kapsamlılık açısından kontrol edilebilir. Bu kalıp bir discriminated union'dır.

Diziler ve Union'lar

Parantezlerin nereye konduğu anlamı tamamen değiştirir:

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

Bir (string | number)[] üzerinde dolaşırken her eleman union'dır ve yukarıdaki reduce callback'inde olduğu gibi daraltma gerektirir. map ve filter gibi metotlar bir string[] | number[] üzerinde de çalışır; callback string | number alır.

null ve undefined ile Union'lar

En yaygın union "bir değer ya da hiçbir şey"dir: string | null, User | undefined. Array.prototype.find ve Map.prototype.get bunu döndürür ve opsiyonel bir name?: string özelliği string | undefined olarak okunur. Bunları ?., ?? ve null kontrolleriyle ele almanın kendi sayfası var: null ve undefined.

Mevcut bir union'dan tip düzeyinde üye çıkarmak için yerleşik yardımcıları kullanın: Exclude<"a" | "b" | "c", "a"> sonucu "b" | "c", NonNullable<string | null> sonucu da string olur.