User-defined type guard란 무엇인가요?

Question

Accepted Answer

**User-defined type guard**는 반환 타입이 **타입 술어(type predicate)**(`x is T`)인 함수입니다. `true`를 반환하면 컴파일러는 호출 코드에서 인자를 `T`로 narrowing합니다 — 커스텀 런타임 검사를 캡슐화하게 해줍니다.

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

// 마법은 단순한 `boolean`이 아니라 반환 타입 `pet is Cat`에 있음
function isCat(pet: Cat | Dog): pet is Cat {
  return "meow" in pet;
}

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

`pet is Cat` 술어가 없으면, `boolean`을 반환하는 `isCat`은 `pet`을 narrowing하지 *못합니다* — 컴파일러는 `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; // ✅ User로 안전하게 타이핑
```

## 주의점

컴파일러는 당신의 술어를 **신뢰**합니다 — 본문의 로직이 틀리면 안전하지 않은 narrowing이 됩니다. 복잡한 shape에는 스키마 검증기(zod)가 올바른 가드를 대신 생성해줍니다.

## 왜 중요한가

Type guard는 임의의 런타임 검사를 재사용 가능한 narrowing 함수로 바꾸게 해줍니다 — API/경계에서 `unknown` 데이터를 검증하고, 단순한 `typeof`/`in` 검사만으로 충분하지 않을 때 union의 멤버를 구별하는 데 필수입니다.