Type Guard TypeScript: Cara Mengecek Tipe Sebuah Object

Type guard adalah pemeriksaan saat runtime yang dipahami TypeScript, sehingga tipe di dalam cabang yang diperiksa ikut dipersempit. typeof, instanceof dan in adalah type guard bawaan; untuk hal lain, kamu menulis fungsi yang tipe kembaliannya berupa type predicate, value is Type.

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

Saat runtime, isUser hanya mengembalikan boolean biasa. Tipe kembalian value is User memberi tahu compiler apa yang dibuktikan oleh hasil true, lalu setiap if (isUser(x)) mempersempit x menjadi User.

Type Guard Bawaan

Pemeriksaan berikut mempersempit tipe tanpa fungsi bantu apa pun:

Semuanya berjalan sebagai JavaScript biasa. Yang ditambahkan TypeScript adalah penyempitannya: ia membaca pemeriksaan itu dan menyesuaikan tipe di setiap cabang. Daftar lengkap bentuknya ada di halaman type narrowing. Type guard buatan sendiri dipakai untuk pemeriksaan yang tidak muat dalam satu ekspresi, atau yang ingin kamu pakai ulang.

Menulis Type Predicate

Type predicate berbentuk parameterName is Type dan menggantikan boolean sebagai tipe kembalian. Penyempitannya bekerja ke dua arah: true mempersempit ke Type, dan false membuang Type dari union.

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[])

Memberikan type guard ke filter menghasilkan array dengan tipe yang benar. Sejak TypeScript 5.5, compiler juga menyimpulkan predicate dari arrow function sederhana, jadi pets.filter((p) => p.kind === "cat") mengembalikan Cat[] tanpa type guard bernama.

Tipe predicate harus cocok dengan tipe parameternya: function f(x: string): x is number adalah error TS2677, A type predicate's type must be assignable to its parameter's type.

Compiler Memercayai Type Guard Kamu

TypeScript memeriksa bahwa type guard mengembalikan boolean. TypeScript tidak memeriksa apakah boolean itu benar. Type guard yang mengembalikan true untuk nilai yang salah membuat tipenya berbohong, dan program gagal saat runtime tanpa error kompilasi.

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) melempar TypeError: Cannot read properties of undefined (reading 'toFixed') saat runtime. Compiler menerima data.price sebagai number karena type guard berkata begitu. Periksa setiap property yang diandalkan oleh sisa kode, dan buat type guard tetap kecil, teruji, dan dekat dengan tipe yang dijelaskannya.

Mengecek Apakah Object Punya Tipe Tertentu

Inilah pertanyaan di balik sebagian besar type guard buatan sendiri: data datang sebagai unknown (dari JSON.parse, fetch, localStorage, sebuah pesan) dan kamu perlu tahu apakah data itu cocok dengan interface-mu. Resepnya:

1. typeof value === "object" && value !== null (sebuah object, bukan null).
2. "prop" in value untuk setiap property wajib. Pada unknown, in menambahkan property itu ke tipenya sebagai unknown.
3. typeof value.prop === "..." (atau type guard bersarang) untuk tipe setiap property.
4. Array.isArray(value.items) && value.items.every(isItem) untuk array.

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

Untuk bentuk yang besar atau bersarang dalam, menulis pemeriksaan seperti ini dengan tangan jadi melelahkan. Library schema seperti Zod atau Valibot memungkinkan kamu menjelaskan bentuknya sekali dan memberimu pemeriksaan runtime sekaligus tipe TypeScript-nya.

Assertion Function: asserts value is Type

Assertion function melempar error kalau pemeriksaannya gagal dan selesai seperti biasa kalau berhasil. Tipe kembaliannya adalah asserts value is Type (atau asserts condition), dan semua kode setelah pemanggilan sudah dipersempit, tanpa perlu if.

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
}

Ada satu aturan yang sering menjebak: assertion function harus dipanggil lewat nama yang punya tipe eksplisit. Arrow function const tanpa anotasi, const check = (v: unknown): asserts v is string => {...}, memberi error TS2775 di tempat pemanggilan, Assertions require every name in the call target to be declared with an explicit type annotation. Pakai deklarasi function, atau beri anotasi tipe fungsi pada konstanta itu.

Type Guard vs Assertion vs Cast

Type assertion (as) mengubah tipe tanpa memeriksa apa pun. Di batas tempat data datang dari luar, type guard atau assertion function adalah versi aman dari ide yang sama.

Type Guard Berbasis this di Class

Sebuah method bisa mempersempit object tempat ia dipanggil dengan this is Type. Ini berguna dalam hierarki class:

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
}