Apakah itu user-defined type guard?

Question

Accepted Answer

Sebuah **user-defined type guard** ialah fungsi yang jenis pulangannya ialah **type predicate** (`x is T`). Apabila ia memulangkan `true`, pengkompil menyempitkan argumen kepada `T` dalam kod pemanggil — membolehkan anda merangkumkan pemeriksaan runtime tersuai.

```ts
interface Cat { meow(): void; }
interface Dog { bark(): void; }

// the magic is the return type `pet is Cat`, not just `boolean`
function isCat(pet: Cat | Dog): pet is Cat {
  return "meow" in pet;
}

function speak(pet: Cat | Dog) {
  if (isCat(pet)) {
    pet.meow(); // ✅ narrowed to Cat
  } else {
    pet.bark(); // ✅ narrowed to Dog
  }
}
```

Tanpa predicate `pet is Cat`, `isCat` yang memulangkan `boolean` *tidak* akan menyempitkan `pet` — pengkompil masih akan melihat `Cat | Dog` di dalam `if`. Predicate itulah yang mengajarnya.

## Mengesahkan data luaran yang tidak diketahui

```ts
interface User { id: number; name: string; }

function isUser(x: unknown): x is User {
  return (
    typeof x === "object" && x !== null &&
    typeof (x as any).id === "number" &&
    typeof (x as any).name === "string"
  );
}

const data: unknown = await res.json();
if (isUser(data)) data.name; // ✅ safely typed as User
```

## Peringatan

Pengkompil **mempercayai** predicate anda — jika logik badan fungsi salah, anda akan mendapat penyempitan yang tidak selamat. Untuk bentuk yang kompleks, sebuah pengesah skema (zod) menjana guard yang betul untuk anda.

## Mengapa ia penting

Type guard membolehkan anda menukar pemeriksaan runtime sewenang-wenangnya menjadi fungsi penyempitan yang boleh diguna semula — penting untuk mengesahkan data `unknown` di sempadan API dan untuk membezakan ahli sesuatu union apabila pemeriksaan `typeof`/`in` yang mudah tidak mencukupi dengan sendirinya.