---
category: Unified
tags: [auto-consolidated, technical-documentation]
title: [[타입 가드 (Type Guards)|타입 가드 (Type Guards]]
last_updated: 2026-05-02
---

# [[타입 가드 (Type Guards)|타입 가드 (Type Guards]]

## 📌 Brief Summary
> 타입 가드(Type Guards)는 TypeScript에서 `unknown` 변수나 유니온(Union) 타입 변수의 실제 타입을 안전하게 판별하고 확신할 수 있게 해주는 기법입니다 [1, 2]. 이를 통해 TypeScript의 제어 흐름 분석(Control Flow [[Analysis|Analysis]])이 실행되어, 특정 조건문 블록 내에서 변수의 가능한 타입을 좁혀(Narrowing) 안전하게 속성에 접근할 수 있도록 돕습니다 [2, 3].

---

> 타입 가드(Type Guards)는 TypeScript에서 유니언(Union) 타입이나 `unknown` 타입의 변수를 다룰 때 특정 타입을 구별해 내기 위해 사용되는 메커니즘입니다 [1, 2]. 런타임에 실행되는 검사를 바탕으로 TypeScript의 타입 시스템이 자동으로 타입을 좁히도록(Narrowing) 유도합니다 [1, 3]. 이를 통해 개발자는 알 수 없는 변수를 분석할 때 해당 변수의 타입을 확신을 가지고 안전하게 식별할 수 있습니다 [4].

## 📖 Core Content
- **기본 타입 가드 (Built-in Type Guards):**
  - **`typeof` 검사:** `typeof v === "typename"` ("number", "string", "boolean", "symbol" 등)과 같은 형태를 평가하여 TypeScript가 해당 스코프 내에서 타입을 자동으로 좁힙니다 [2, 3].
  - **`instanceof` 검사:** 우변에 생성자 함수를 두어 해당 객체가 특정 프로토타입에 속하는지 확인하고 타입을 좁힙니다 [2, 3].
  - **`in` 연산자 및 동등성 검사:** 객체 내 특정 속성의 존재 여부(`in`)나 값의 동등성을 검사하여 타입을 좁히는 데 활용할 수 있습니다 [3, 4].

- **사용자 정의 타입 가드 (Custom Type Guards / Type Predicates):**
  - 일반 함수와 유사하지만, 반환 타입에 `is` 키워드를 사용하는 특수한 구문(예: `pet is Fish`, `value is Positive`)을 갖는 함수를 정의할 수 있습니다 [2, 5].
  - 이러한 함수(타입 서술어)가 런타임에 참(true)을 반환하면, TypeScript 타입 시스템은 조건문 내부에서 해당 파라미터가 명시된 타입이라고 인지하고 타입을 좁힙니다 [2, 5].
  - **주의점:** TypeScript는 타입 서술어 함수의 내부 로직이 실제로 해당 타입의 의도를 정확히 따르는지 검증하지 않습니다 [5]. 따라서 코드를 작성하는 개발자가 로직의 정확성을 전적으로 책임져야 하며, 잘못 작성될 경우 `as` 단언문(assertion)보다 크게 더 안전하지 않을 수 있습니다 [5].

- **사용 목적:**
  - `unknown` 타입의 데이터를 다루거나, 여러 타입이 섞인 유니온 타입([[Union Types|Union Types]])을 처리할 때 반복적인 타입 단언(Type Assertions)을 피하고 예측 가능한 코드를 작성하기 위해 사용됩니다 [1, 2].

---

- **커스텀 타입 가드 (타입 서술어, Type Predicates):** 커스텀 타입 가드는 일반 함수와 유사하게 동작하지만, 반환 값에 `is` 키워드를 활용하는 특수한 구문을 가집니다 [1, 5]. 이 함수는 런타임에 불리언(boolean) 값을 반환하며, 타입 시스템은 이 반환 값을 근거로 매개변수가 특정 타입인지 판단하여 타입을 좁힙니다 [3].
- **내장 타입 가드 (`typeof` 및 `instanceof`):** 커스텀 함수 외에도 TypeScript는 `typeof` 및 `instanceof` 연산자를 활용한 검사를 타입 가드로 자동 인식합니다 [1]. `typeof`를 통해 `"number"`, `"string"` 등의 원시 타입을 좁힐 수 있으며, `instanceof`를 사용할 경우 우변의 생성자 함수 프로토타입을 기준으로 타입을 좁혀줍니다 [1].
- **`unknown` 및 유니언(Union) 타입 제어:** 유니언 타입을 다룰 때 반복적이고 이상적이지 않은 타입 단언(Type assertions)을 피하기 위해 타입 가드가 필요합니다 [1]. 특히 `unknown` 타입의 변수는 `typeof`, `instanceof` 또는 커스텀 타입 가드를 통해 먼저 타입을 좁히지 않으면 사용할 수 없으므로, 안전한 코드 작성을 위해 필수적으로 사용됩니다 [2].
- **식별 가능한 유니언([[Discriminated Unions|Discriminated Unions]])과의 활용:** 식별 가능한 유니언 패턴을 처리할 때도 재사용이 가능한 전용 타입 가드를 생성하여 더욱 안전하게 타입을 검증할 수 있습니다 [6].

## ⚖️ Trade-offs & Caveats
- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
- **정책 변화:** Design & Experience 분야의 자동 자산화 수행.

---

- **과거 데이터와의 충돌:** 자동화 엔진에 의해 매핑된 지식으로, 추후 정밀 검증 필요.
- **정책 변화:** Programming & Language 분야의 자동 자산화 수행.

## 🔗 Knowledge Connections
- **Related Topics:** Type Narrowing, [[Union Types|Union Types]], Type Predicates, unknown type
- **Projects/Contexts:** 외부 API의 불확실한(unknown) 데이터 검증 로직, 복잡한 유니온 타입 분기 처리
- **Contradictions/Notes:** 사용자 정의 타입 가드는 타입 좁히기에 매우 유용하지만, TypeScript가 내부 판별 로직의 논리적 오류를 잡아주지 못하기 때문에 개발자의 부주의로 인해 타입 안정성이 훼손될 위험이 존재합니다 [5].

---
*Last updated: 2026-04-18*

---

---

- **Related Topics:** Type Narrowing, Type Predicates, Unknown Type, [[Discriminated Unions|Discriminated Unions]]
- **Projects/Contexts:** API 응답 등 외부의 불확실한 데이터 구조 검증 및 처리
- **Contradictions/Notes:** 타입 서술어(Type predicates) 형태의 커스텀 타입 가드는 타입 단언(as assertions)보다 훨씬 타입에 안전한 편은 아니며, TypeScript는 타입 가드 내부의 논리가 해당 브랜드 타입의 의도와 완벽히 일치하는지까지 검증하지 않으므로 전적으로 코드 작성자에게 책임이 위임됩니다 [3].

---
*Last updated: 2026-04-18*

---
