ユーザー定義の型ガードとは何ですか?

Question

ユーザー定義の型ガードとは何ですか?

Accepted Answer

**ユーザー定義の型ガード**とは、戻り値の型が**型述語**(`x is T`)である関数のことです。この関数が `true` を返すと、コンパイラは呼び出し側のコードで引数を `T` に絞り込みます。これにより、カスタムな実行時チェックをカプセル化できます。

```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
  }
}
```

`pet is Cat` という述語がなければ、`boolean` を返す `isCat` では `pet` は絞り込まれず、コンパイラは `if` の中でも依然として `Cat | Dog` のままだと見なします。コンパイラに教えるのはこの述語です。

## 未知の外部データの検証

```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
```

## 注意点

コンパイラはあなたの述語を**信頼**します。本体のロジックが間違っていると、安全でない絞り込みが行われます。複雑な形状の場合は、スキーマバリデーター(zod)が正しいガードを生成してくれます。

## なぜ重要なのか

型ガードを使うと、任意の実行時チェックを再利用可能な絞り込み関数に変換できます。API などの境界で `unknown` データを検証する場合や、単純な `typeof`/`in` チェックだけでは不十分な場合にユニオンのメンバーを区別するために不可欠です。