TypeScript instanceof: Sınıfları ve Hataları Daraltmak

value instanceof SomeClass, çalışma zamanında çalışan bir JavaScript kontrolüdür: SomeClass.prototype nesnenin prototip zincirindeyse, yani nesne new SomeClass (veya bir alt sınıf) ile oluşturulduysa true olur. TypeScript kontrolün içinde value değerini SomeClass tipine daraltır.

function formatWhen(when: Date | string | number): string {
  if (when instanceof Date) {
    return when.toISOString().slice(0, 10); // when: Date
  }
  // when: string | number
  return typeof when === "number" ? new Date(when).toISOString().slice(0, 10) : when;
}

console.log(formatWhen(new Date("2024-03-15T10:30:00Z"))); // 2024-03-15
console.log(formatWhen(0));                                // 1970-01-01
console.log(formatWhen("tomorrow"));                       // tomorrow

Sınıflardan oluşturulmuş nesneler için instanceof, primitive'ler için typeof kullanın. Burada ikisi de gerekli: instanceof Date değerini ayırır, sonra typeof kalanı böler.

Kendi Sınıflarınızı Daraltmak

instanceof, true dalında sınıfa daraltır ve false dalında onu çıkarır; böylece sınıflardan oluşan bir union üye üye ele alınabilir.

class Circle {
  constructor(public radius: number) {}
}

class Rect {
  constructor(public width: number, public height: number) {}
}

function area(shape: Circle | Rect): number {
  if (shape instanceof Circle) {
    return Math.PI * shape.radius ** 2; // shape: Circle
  }
  return shape.width * shape.height;    // shape: Rect
}

console.log(area(new Circle(1)).toFixed(3)); // 3.142
console.log(area(new Rect(2, 5)));           // 10

Bir alt sınıf örneği ebeveyni için de kontrolü geçer: Square extends Rect ise new Square(2) instanceof Rect sonucu true olur. Dallar farklıysa önce en özel sınıfı test edin.

catch İçinde Error Alt Sınıfları

instanceof en çok catch içinde kullanılır. strict altında yakalanan değer unknown olur (her şey fırlatılabilir) ve tipli bir hataya geri dönmenin yolu instanceof kullanmaktır.

class NotFoundError extends Error {
  constructor(public path: string) {
    super(`not found: ${path}`);
    this.name = "NotFoundError";
  }
}

function load(path: string): string {
  if (!path.startsWith("/")) throw new TypeError("path must be absolute");
  throw new NotFoundError(path);
}

for (const path of ["/missing.txt", "relative.txt"]) {
  try {
    load(path);
  } catch (err) {
    if (err instanceof NotFoundError) {
      console.log("404:", err.path);            // err: NotFoundError
    } else if (err instanceof Error) {
      console.log(err.name + ":", err.message); // err: Error
    } else {
      console.log("unknown throw", err);
    }
  }
}

Çıktı:

404: /missing.txt
TypeError: path must be absolute

class X extends Error, TypeScript 7'nin desteklediği her target'ta (ES2015 ve sonrası) instanceof ile çalışır. Constructor içinde Object.setPrototypeOf(this, X.prototype) çağırma yönündeki eski tavsiye, TypeScript 7'nin kaldırdığı bir target olan ES5'e derlenen kod içindi.

instanceof Interface'ler veya Tiplerle Çalışmaz

Interface'ler ve type alias'lar yalnızca derleyici için vardır. Derlemeden sonra karşılaştırılacak bir User değeri yoktur, bu yüzden TypeScript kontrolü reddeder:

// This does not compile: User is an interface, and interfaces are erased.
interface User {
  name: string;
  email: string;
}

function greet(value: unknown): string {
  if (value instanceof User) {
    return "Hello, user";
  }
  return "Hello, stranger";
}

console.log(greet({ name: "Ada", email: "ada@example.com" }));

Derleyici index.ts(8,24): error TS2693: 'User' only refers to a type, but is being used as a value here. bildirir. İki çözüm vardır. Biçimi bir type guard ile, yani value is User döndüren bir fonksiyonla kendiniz kontrol edin:

interface User {
  name: string;
  email: string;
}

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

function greet(value: unknown): string {
  return isUser(value) ? `Hello, ${value.name}` : "Hello, stranger";
}

console.log(greet({ name: "Ada", email: "ada@example.com" })); // Hello, Ada
console.log(greet({ name: "Ada" }));                            // Hello, stranger

Ya da bu nesneleri sizin kodunuz oluşturuyorsa User tipini bir sınıf yapın ve onları new ile oluşturun; o zaman instanceof çalışır. Predicate'leri ve assertion fonksiyonlarını type guard'lar sayfası ayrıntılı anlatıyor.

Doğru Tip, Doğru Örnek Değildir

TypeScript tipleri yapıya göre karşılaştırır: bir sınıfla aynı üyelere sahip bir nesne literal'i sınıf tipine atanabilir. instanceof yapıya bakmaz. Prototip zincirinde dolaşır ve hiç new ile oluşturulmamış bir nesne, derleyici onu o tip olarak kabul etse bile kontrolden geçemez.

class Point {
  constructor(public x: number, public y: number) {}
  length(): number {
    return Math.hypot(this.x, this.y);
  }
}

const made = new Point(3, 4);
const literal: Point = { x: 3, y: 4, length: () => 5 }; // accepted: same shape
const copy = structuredClone(made);                      // typed Point, but a plain object

console.log(made instanceof Point);    // true
console.log(literal instanceof Point); // false
console.log(copy instanceof Point);    // false
console.log(typeof copy.length);       // undefined: the method did not survive

Son satır önemlidir. structuredClone, JSON.parse(JSON.stringify(...)) ve worker'lar arasındaki mesajlar, statik tipleri hâlâ Point diyebilse de sınıf prototipi olmayan düz nesneler döndürür. Sınıf örnekleri böyle bir sınırı geçtiğinde, instanceof veya metotlara güvenmeden önce onları yeniden oluşturun (new Point(copy.x, copy.y)).

instanceof ve Primitive'ler

Primitive'ler (string, number, boolean...) nesne değildir ve prototip zincirleri yoktur, bu yüzden "hi" instanceof String sonucu false olur. TypeScript bu hatayı yapabildiğinde işaretler: solda string olarak tiplenmiş bir değer varken instanceof TS2358 hatasıdır, The left-hand side of an 'instanceof' expression must be of type 'any', an object type or a type parameter. Primitive'ler için typeof kullanın.

Farklı Realm'lerden Gelen Değerler

instanceof belirli tek bir constructor nesnesiyle karşılaştırır. Başka bir realm'de (bir iframe veya bir Node vm bağlamı) çalışan kodun kendi Array, Error ve Date nesneleri vardır, bu yüzden orada oluşturulan bir dizi burada instanceof Array kontrolünden geçemez. Aynı npm paketinin iki kopyası node_modules içine düştüğünde de aynısı olur: her kopyanın kendi sınıfı vardır ve birinden gelen bir örnek diğerine karşı instanceof kontrolünden geçemez. Diziler için Array.isArray realm'ler arasında çalışır. Kendi tipleriniz için bir özelliği kontrol etmek (bir type guard ya da bir kind alanı) sorunu tamamen ortadan kaldırır.