TypeScript Type Guard: Bir Nesnenin Tipini Kontrol Etmek

Type guard, TypeScript'in anladığı bir çalışma zamanı kontrolüdür; bu yüzden kontrol edilen dalın içinde tipi daraltır. typeof, instanceof ve in yerleşik guard'lardır; geri kalan her şey için dönüş tipi bir type predicate olan, value is Type, bir fonksiyon yazarsınız.

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "age" in value && typeof value.age === "number"
  );
}

const inputs: unknown[] = [{ name: "Ada", age: 36 }, { name: "Bob" }, "Ada", null];

for (const input of inputs) {
  if (isUser(input)) {
    console.log(`${input.name} is ${input.age}`); // input: User
  } else {
    console.log("not a user:", input);
  }
}

isUser çalışma zamanında düz bir boolean döndürür. value is User dönüş tipi derleyiciye true sonucunun neyi kanıtladığını söyler ve ardından her if (isUser(x)) ifadesi x değerini User tipine daraltır.

Yerleşik Type Guard'lar

Bu kontroller hiçbir yardımcı fonksiyon olmadan daraltır:

Hepsi sıradan JavaScript olarak çalışır. TypeScript'in eklediği daraltmadır: kontrolü okur ve her daldaki tipi ayarlar. Biçimlerin tam listesi tip daraltma sayfasında. Özel bir guard, tek bir ifadeye sığmayan ya da yeniden kullanmak istediğiniz kontroller içindir.

Bir Type Predicate Yazmak

Bir type predicate parameterName is Type biçimindedir ve dönüş tipi olarak boolean yerine geçer. Daraltma iki yönde çalışır: true sonucu Type tipine daraltır, false ise Type tipini bir union'dan çıkarır.

type Cat = { kind: "cat"; meow: () => string };
type Dog = { kind: "dog"; bark: () => string };
type Pet = Cat | Dog;

function isCat(pet: Pet): pet is Cat {
  return pet.kind === "cat";
}

function speak(pet: Pet): string {
  if (isCat(pet)) {
    return pet.meow(); // pet: Cat
  }
  return pet.bark();   // pet: Dog (Cat was ruled out)
}

const pets: Pet[] = [
  { kind: "cat", meow: () => "meow" },
  { kind: "dog", bark: () => "woof" },
];

console.log(pets.map(speak));             // [ 'meow', 'woof' ]
console.log(pets.filter(isCat).length);   // 1 (and the result is typed Cat[])

Bir guard'ı filter metoduna vermek doğru tiplenmiş bir dizi verir. TypeScript 5.5'ten beri derleyici basit arrow function'lardan da bir predicate çıkarır, bu yüzden pets.filter((p) => p.kind === "cat") isimli bir guard olmadan Cat[] döndürür.

Predicate'in tipi parametrenin tipine uymalıdır: function f(x: string): x is number TS2677 hatasıdır, A type predicate's type must be assignable to its parameter's type.

Derleyici Guard'ınıza Güvenir

TypeScript bir guard'ın boolean döndürdüğünü kontrol eder. Boolean'ın doğru olduğunu kontrol etmez. Yanlış değerler için true döndüren bir guard tiplerin yalan söylemesine yol açar ve program hiçbir derleme hatası olmadan çalışma zamanında başarısız olur.

interface Product {
  title: string;
  price: number;
}

// Wrong: only checks title, never price
function isProduct(value: unknown): value is Product {
  return typeof value === "object" && value !== null && "title" in value;
}

const data: unknown = { title: "Lamp" };

if (isProduct(data)) {
  console.log(data.title); // Lamp
  try {
    console.log(data.price.toFixed(2)); // compiles, but throws at run time
  } catch (e) {
    console.log(e instanceof Error ? e.message : e);
    // Cannot read properties of undefined (reading 'toFixed')
  }
}

data.price.toFixed(2) çalışma zamanında TypeError: Cannot read properties of undefined (reading 'toFixed') fırlatır. Derleyici data.price değerini bir number olarak kabul etti, çünkü guard öyle söyledi. Kodun geri kalanının güvendiği her özelliği kontrol edin; guard'ları küçük, test edilmiş ve tanımladıkları tipe yakın tutun.

Bir Nesnenin Belirli Bir Tipte Olup Olmadığını Kontrol Etmek

Çoğu özel guard'ın arkasındaki soru budur: veri unknown olarak gelir (JSON.parse, fetch, localStorage, bir mesaj üzerinden) ve interface'inizle eşleşip eşleşmediğini bilmeniz gerekir. Tarif:

1. typeof value === "object" && value !== null (bir nesne, null değil).
2. Her zorunlu özellik için "prop" in value. unknown üzerinde in, özelliği tipe unknown olarak ekler.
3. Her özelliğin tipi için typeof value.prop === "..." (ya da iç içe bir guard).
4. Diziler için Array.isArray(value.items) && value.items.every(isItem).

interface Order {
  id: string;
  lines: { sku: string; qty: number }[];
}

function isLine(v: unknown): v is Order["lines"][number] {
  return typeof v === "object" && v !== null &&
    "sku" in v && typeof v.sku === "string" &&
    "qty" in v && typeof v.qty === "number" && Number.isInteger(v.qty);
}

function isOrder(v: unknown): v is Order {
  return typeof v === "object" && v !== null &&
    "id" in v && typeof v.id === "string" &&
    "lines" in v && Array.isArray(v.lines) && v.lines.every(isLine);
}

const good: unknown = JSON.parse('{"id":"A1","lines":[{"sku":"pen","qty":2}]}');
const bad: unknown = JSON.parse('{"id":"A2","lines":[{"sku":"pen","qty":"2"}]}');

console.log(isOrder(good), isOrder(bad)); // true false
if (isOrder(good)) console.log(good.lines[0].qty * 3); // 6

Büyük veya derin iç içe biçimlerde bunları elle yazmak yorucu hale gelir. Zod veya Valibot gibi şema kütüphaneleri biçimi bir kez tanımlamanıza izin verir ve size hem çalışma zamanı kontrolünü hem de TypeScript tipini verir.

Assertion Fonksiyonları: asserts value is Type

Bir assertion fonksiyonu kontrol başarısız olursa hata fırlatır, aksi halde normal şekilde döner. Dönüş tipi asserts value is Type (veya asserts condition) olur ve çağrıdan sonraki her şey, bir if gerekmeden daraltılır.

function assertIsString(value: unknown, name: string): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`${name} must be a string, got ${typeof value}`);
  }
}

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

function greet(input: unknown, count: number | null): string {
  assertIsString(input, "input");
  assert(count !== null, "count is required");
  // input: string, count: number
  return input.toUpperCase().repeat(count);
}

console.log(greet("hi", 2)); // HIHI

try {
  greet(42, 1);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // input must be a string, got number
}

İnsanları şaşırtan bir kural var: bir assertion fonksiyonu, açık bir tipe sahip bir ad üzerinden çağrılmalıdır. Notasyonsuz bir const arrow function, const check = (v: unknown): asserts v is string => {...}, çağrı yerinde TS2775 hatası verir: Assertions require every name in the call target to be declared with an explicit type annotation. Bir function bildirimi kullanın ya da sabite bir fonksiyon tipi notasyonu yazın.

Guard'lar, Assertion'lar ve Cast'ler

Bir type assertion (as) hiçbir şeyi kontrol etmeden tipi değiştirir. Verinin dışarıdan geldiği bir sınırda, aynı fikrin güvenli sürümü bir guard ya da bir assertion fonksiyonudur.

Sınıflarda this Tabanlı Guard'lar

Bir metot, this is Type ile üzerinde çağrıldığı nesneyi daraltabilir. Sınıf hiyerarşilerinde kullanışlıdır:

class FileNode {
  constructor(public name: string) {}
  isDirectory(): this is DirectoryNode {
    return this instanceof DirectoryNode;
  }
}

class DirectoryNode extends FileNode {
  children: FileNode[] = [];
}

function count(node: FileNode): number {
  return node.isDirectory() ? node.children.length : 0; // node: DirectoryNode in the true branch
}