instanceof di TypeScript: Narrowing Class dan Error

value instanceof SomeClass adalah pemeriksaan JavaScript yang berjalan saat runtime: hasilnya true kalau SomeClass.prototype ada di prototype chain object tersebut, yang berarti object itu dibuat dengan new SomeClass (atau dengan sebuah subclass). TypeScript mempersempit tipe value menjadi SomeClass di dalam pemeriksaan itu.

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

Pakai instanceof untuk object yang dibuat dari class, dan typeof untuk tipe primitif. Di sini keduanya dibutuhkan: instanceof memisahkan Date, lalu typeof membagi sisanya.

Narrowing Class Buatanmu Sendiri

instanceof mempersempit tipe menjadi class tersebut di cabang true dan menghapusnya di cabang false, jadi union dari beberapa class bisa ditangani satu per satu.

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

Instance subclass juga lolos pemeriksaan untuk parent-nya: kalau Square extends Rect, maka new Square(2) instanceof Rect bernilai true. Uji class yang paling spesifik lebih dulu kalau cabang-cabangnya berbeda.

Subclass Error di catch

Pemakaian instanceof yang paling umum ada di dalam catch. Dengan strict, nilai yang ditangkap bertipe unknown (apa pun bisa di-throw), dan instanceof adalah cara untuk kembali ke error yang bertipe.

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);
    }
  }
}

Output:

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

class X extends Error bekerja dengan instanceof di setiap target yang didukung TypeScript 7 (ES2015 ke atas). Saran lama untuk memanggil Object.setPrototypeOf(this, X.prototype) di constructor berlaku untuk kode yang dikompilasi ke ES5, target yang sudah dihapus dari TypeScript 7.

instanceof Tidak Bekerja dengan Interface atau Type

Interface dan type alias hanya ada untuk compiler. Setelah kompilasi, tidak ada nilai User untuk dibandingkan, jadi TypeScript menolak pemeriksaan itu:

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

Compiler melaporkan index.ts(8,24): error TS2693: 'User' only refers to a type, but is being used as a value here. Ada dua cara memperbaikinya. Periksa bentuknya sendiri dengan type guard, yaitu fungsi yang mengembalikan value is User:

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

Atau, kalau kodemu sendiri yang membuat object-object ini, jadikan User sebuah class dan buat object-nya dengan new; dengan begitu instanceof bekerja. Halaman type guard membahas predicate dan assertion function secara detail.

Tipe yang Benar Bukan Berarti Instance yang Benar

TypeScript membandingkan tipe berdasarkan struktur: object literal dengan member yang sama seperti sebuah class bisa di-assign ke tipe class itu. instanceof tidak melihat struktur. Ia menelusuri prototype chain, dan object yang tidak pernah dibuat dengan new akan gagal walaupun compiler menerimanya sebagai tipe tersebut.

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

Baris terakhir itu penting. structuredClone, JSON.parse(JSON.stringify(...)), dan pesan antar-worker semuanya mengembalikan object biasa tanpa prototype class, walaupun tipe statisnya masih bisa menyatakan Point. Kalau instance class melewati batas seperti itu, bangun ulang object-nya (new Point(copy.x, copy.y)) sebelum mengandalkan instanceof atau method-nya.

instanceof dan Tipe Primitif

Tipe primitif (string, number, boolean...) bukan object dan tidak punya prototype chain, jadi "hi" instanceof String bernilai false. TypeScript menandai kesalahan ini kalau bisa: dengan nilai bertipe string di sisi kiri, instanceof menghasilkan error TS2358, The left-hand side of an 'instanceof' expression must be of type 'any', an object type or a type parameter. Pakai typeof untuk tipe primitif.

Nilai dari Realm Lain

instanceof membandingkan dengan satu object constructor tertentu. Kode yang berjalan di realm lain (sebuah iframe, atau context vm di Node) punya Array, Error, dan Date sendiri, jadi array yang dibuat di sana gagal pada instanceof Array di sini. Hal yang sama terjadi kalau dua salinan dari satu package npm sama-sama ada di node_modules: setiap salinan punya class sendiri, dan instance dari salinan yang satu gagal pada instanceof terhadap salinan yang lain. Untuk array, Array.isArray bekerja lintas realm. Untuk tipe buatanmu sendiri, memeriksa sebuah properti (dengan type guard, atau field kind) menghindari masalah ini sepenuhnya.