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

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

## 📌 Brief Summary
> 타입 가드(Type Predicates)는 런타임에 반환되는 불리언(boolean) 값을 기반으로 TypeScript의 타입 시스템이 매개변수의 타입을 더 구체적으로 좁힐 수(Narrowing) 있도록 돕는 함수입니다 [1]. 주로 유니언 타입이나 알 수 없는 데이터를 다룰 때 변수가 특정 타입 구조를 만족하는지 검증하기 위해 사용됩니다 [2, 3]. 다만 TypeScript 컴파일러는 타입 가드 내부의 검증 로직이 정확한지까지는 확인하지 않으므로, 개발자 스스로 로직의 정확성을 보장해야 합니다 [1].

---

> 타입 서술어(Type Predicates)는 매개변수가 특정 타입에 해당하는지 여부를 반환 타입을 통해 명시하는 커스텀 타입 가드 함수입니다 [1]. 런타임에는 불리언(boolean) 값을 반환하지만, 타입스크립트 컴파일러는 이 반환 값을 바탕으로 타입 좁히기(Type Narrowing)를 적용합니다 [1]. 주로 반환 타입에 `is` 키워드를 사용하여 정의되며, 런타임 검증 로직과 타입 시스템을 연결하여 변수의 타입을 안전하게 특정하는 데 유용합니다 [1-3].

---

> 타입 서술어(Type Predicates)는 함수의 반환 타입을 통해 특정 매개변수가 특정 타입에 해당하는지 여부를 타입스크립트 컴파일러에 알려주는 함수입니다 [1]. 런타임에는 불리언(boolean) 값을 반환하지만, 타입 시스템은 이 반환 값을 바탕으로 타입 좁히기(Type Narrowing)를 적용합니다 [1]. 개발자는 `is` 키워드를 활용해 커스텀 타입 가드(Type Guard)를 정의할 때 이 기능을 핵심적으로 사용합니다 [2].

---

> 타입 조건자(Type Predicates)는 특정 매개변수가 지정된 타입인지 여부를 나타내는 함수입니다 [1]. 런타임 시점에는 불리언(boolean) 값을 반환하지만, TypeScript의 타입 시스템은 이 반환 값을 인식하여 자동으로 타입 좁히기(Type Narrowing)를 적용합니다 [1]. 일반적으로 커스텀 타입 가드 함수 내에서 `is` 키워드를 사용하여 정의됩니다 [2].

## 📖 Core Content
- **기본 개념과 역할:** 타입 가드 함수는 런타임에는 불리언 값을 반환하지만, 타입 시스템에게는 반환 결과를 바탕으로 타입 좁히기(Type narrowing)를 적용해야 함을 알려주는 역할을 합니다 [1]. `unknown` 변수를 분석하거나 유니언 타입 중에서 특정 타입을 구별할 때, 데이터의 타입을 확신할 수 있게 해주는 안전한 도구로 활용됩니다 [2, 3].
- **사용 문법과 동작:** 커스텀 타입 가드 함수를 정의할 때는 반환 타입 위치에 `is` 키워드(예: `value is Positive`)를 사용하는 특수한 문법을 적용합니다 [1-3]. `if` 조건문 내에서 이 함수를 호출하여 `true`가 반환되면, TypeScript는 해당 조건 블록 내에서 값이 타입 가드가 보장하는 구체적인 타입임을 인지하게 됩니다 [1]. 커스텀 함수 외에도 `typeof`나 `instanceof`, `in` 연산자 역시 타입 가드로 동작하여 자동으로 타입을 좁혀줍니다 [3, 4].
- **Branded Types 생성 및 단언 함수와의 결합:** 브랜디드 타입(Branded Types)처럼 구조적으로 동일하지만 의미가 다른 타입을 명시할 때, 불안전한 `as` 단언(assertion) 대신 타입 가드 함수를 사용하여 유효성을 검증하는 것이 더 안전한 접근법입니다 [1, 5]. 또한 `if` 래퍼(wrapper)를 작성해야 하는 단점을 보완하기 위해, 값이 일치하지 않으면 에러를 던지는 타입 단언 함수(Assertion Functions)와 결합하여 사용하기도 합니다 [6].
- **한계점 및 주의사항:** 타입 가드는 코드 상에서 조건문 래퍼(`if` 구문 등)를 요구하기 때문에 `as` 단언에 비해 작성 공간을 더 차지하고 런타임 로직이 추가된다는 단점이 있습니다 [6]. 무엇보다 TypeScript는 타입 가드의 내부 로직이 실제로 해당 타입의 의도와 정확히 일치하는지를 검사하지 않고 전적으로 코드 작성자에게 책임을 맡기기 때문에, 논리적 오류가 있을 경우 타입 안전성을 위협할 수 있습니다 [1].

---

* **작동 방식과 문법 구성:**
  타입 서술어는 함수 반환 타입에 `매개변수명 is 타입명` 형태의 문법을 사용합니다(예: `test is string`, `value is Percentage`) [2, 3]. 코드 내에서 이 함수가 참(`true`)을 반환하는 조건문(`if` 블록 등) 내부로 진입하면, 타입스크립트는 해당 매개변수의 타입을 지정된 구체적인 타입으로 좁혀서(narrowing) 인식하게 됩니다 [1, 3]. 

* **주요 활용 사례 (브랜디드 타입 검증):**
  구조적 타이핑 시스템의 한계를 극복하기 위해 고안된 브랜디드 타입(Branded Types)이나 불투명 타입(Opaque Types)을 다룰 때 핵심적인 역할을 합니다 [1, 2]. 예를 들어, 일반 숫자 타입(`number`) 중에서 '양수(`Positive`)'나 '백분율(`Percentage`)'과 같이 특별한 제약이 부여된 타입인지 확인할 때, 이 조건들을 검사하는 로직을 타입 서술어로 만들어 안전한 논리적 게이트를 구축할 수 있습니다 [1, 2].

* **설계상의 한계와 위험성:**
  타입 서술어는 `as` 타입 단언(Type Assertions)보다 본질적으로 더 안전하다고 볼 수는 없습니다. 타입스크립트 컴파일러는 타입 서술어 함수 내부의 검증 로직이 주장하는 타입의 의도와 실제로 일치하는지 검사하지 않으며, 전적으로 코드를 작성한 개발자의 논리에 의존하기 때문입니다 [1]. 

* **가독성과 코드 공간 문제:**
  타입 서술어 함수를 사용하려면 필연적으로 `if (isPositive(value)) { ... }`와 같이 조건부 래퍼(conditional wrappers) 코드를 작성해야 합니다 [4]. 이는 단순한 `as` 단언보다 더 많은 코드 공간을 차지하고 런타임 로직을 추가하게 만듭니다 [4]. 이러한 단점을 피하고 가독성을 높이기 위해, 조건 불일치 시 에러를 던지는 '타입 단언 함수(Assertion Functions)'를 추출하여 함께 활용하기도 합니다 [4, 5].

---

*   **구문 및 동작 원리**: 
    타입 서술어는 함수의 반환 타입 자리에 `매개변수명 is 특정타입`의 구문을 사용하여 정의합니다 [1, 2]. 예를 들어 `function isPercentage(x: number): x is Percentage`와 같이 작성하면, 이 함수가 `true`를 반환할 때 타입스크립트는 매개변수 `x`를 명시된 `Percentage` 타입으로 좁혀서 인식합니다 [3]. 이를 통해 `if` 문과 같은 조건부 블록 내부에서 해당 타입임이 보장된 상태로 코드를 작성할 수 있습니다 [1].
*   **주요 활용 시나리오**: 
    유니언 타입([[Union Types|Union Types]])으로 묶인 여러 타입 중 특정 타입을 안전하게 구분해내야 할 때 유용하게 쓰입니다 [2]. 또한, 런타임 검사 함수에 적용되어 특정 값이 브랜디드 타입(Branded Types) 또는 불투명 타입(Opaque Types)의 인스턴스로 취급될 수 있는지 검증하고 타입 시스템과 연결하는 다리 역할을 합니다 [1, 3, 4].
*   **안정성의 한계**: 
    타입 서술어는 마법처럼 모든 타입 오류를 막아주지는 않습니다. 타입스크립트 컴파일러는 타입 서술어 내부의 실제 로직이 해당 타입의 의도와 정확히 일치하는지까지는 검사하지 않습니다 [1]. 따라서 이는 근본적으로 `as` 타입 단언(Type Assertion)과 유사한 수준의 타입 안정성을 가지며, 로직의 정확성은 전적으로 코드를 작성하는 개발자에게 달려 있습니다 [1].
*   **사용 시의 단점 및 보완**: 
    `as` 단언문에 비해 `if` 조건문 래퍼(wrapper)를 의무적으로 작성해야 하므로 코드가 차지하는 공간이 늘어나고 런타임 로직이 추가된다는 단점이 있습니다 [5]. 이러한 가독성 저하를 해결하기 위해, 조건이 맞지 않으면 에러를 던져버리는 타입 단언 함수(Type Assertion Functions)를 타입 서술어와 결합하여 코드를 간결하게 구성하기도 합니다 [5, 6].

---

- **작동 원리 및 문법:** 타입 조건자는 `is` 키워드를 사용하는 커스텀 타입 가드 함수를 통해 정의할 수 있습니다 [2]. 함수가 불리언 값을 반환할 때, 조건문 내부에서 TypeScript 컴파일러가 해당 변수의 타입을 더 구체적인 타입으로 좁히게(narrowing) 만듭니다 [1, 2].
- **주요 활용 (브랜디드 타입 검증):** 구조적으로 동일해 보이는 타입들을 의도에 따라 구분해야 할 때(예: 브랜디드 타입 인스턴스 검증) 타입 조건자를 활용하면 유용합니다 [1]. 예를 들어, `isPositive(value)`라는 타입 조건자 함수를 사용하여 값이 양수인지 확인하면, `if (isPositive(value))` 블록 내부에서 TypeScript는 해당 값을 `Positive` 타입으로 안전하게 취급합니다 [1]. 
- **한계 및 타입 안전성(Type Safety) 주의:** 타입 조건자는 무조건적으로 타입 안정성을 보장하지 않으며, 내부적으로는 `as` 타입 단언(Type Assertion)과 크게 다르지 않은 수준의 안정성을 가집니다 [1]. TypeScript는 타입 조건자 함수 내부의 논리가 실제 타입의 의도와 정확히 일치하는지 검증하지 않으며, 전적으로 코드를 작성한 개발자의 논리에 의존합니다 [1].
- **사용상의 단점:** 타입 조건자 함수를 사용하려면 `if`문과 같은 조건부 래퍼(Conditional Wrappers)를 작성해야 하므로, `as` 단언문에 비해 코드가 차지하는 공간이 늘어나고 런타임 로직이 추가되는 단점이 있습니다 [3]. 다만, 이를 개선하기 위해 타입 단언 함수(Type Assertion Function)와 함께 사용하여 유효성을 검증하고 에러를 발생시키는 패턴으로 발전시킬 수 있습니다 [3].

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

---

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

---

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

---

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

## 🔗 Knowledge Connections
- **Related Topics:** Type Narrowing, Branded Types, [[Union Types|Union Types]]
- **Projects/Contexts:** [[알 수 없는 외부 데이터 검증 (unknown types)|알 수 없는 외부 데이터 검증 (unknown types]], 유니언 타입 식별 및 상태 분기 처리
- **Contradictions/Notes:** 브랜디드 타입 등의 값을 강제할 때 타입 가드가 `as` 단언에 비해 "종종 더 안전한 방법"으로 소개되기도 하나 [5], 정작 컴파일러가 타입 가드의 내부 구현 로직을 검증해 주지 않기 때문에 본질적으로는 `as` 단언보다 훨씬 더 타입에 안전하다고 볼 수는 없다는 주의 사항이 함께 언급됩니다 [1].

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

---

---

- **Related Topics:** Type Guards (타입 가드), Type Narrowing (타입 좁히기), Branded Types (브랜디드 타입), Type Assertion Functions (타입 단언 함수)
- **Projects/Contexts:** 복잡한 유니온 타입 사이에서 특정 타입을 구별해 내거나, 숫자 및 문자열 같은 원시 타입에 제약을 부여한 브랜디드 타입의 런타임 값 유효성을 검증하고 타입스크립트 시스템에 이를 인지시킬 때 활용됩니다 [1-3].
- **Contradictions/Notes:** 타입 서술어는 컴파일러가 알아서 타입을 안전하게 보장해 줄 것이라는 착각을 일으키기 쉽지만, 실제로는 함수 내부의 구현 로직을 타입스크립트가 검증하지 않으므로 개발자의 실수(잘못된 논리 작성)에 취약하다는 점을 주의해야 합니다 [1].

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

---

---

- **Related Topics:** [[타입 좁히기 (Type Narrowing)|타입 좁히기(Type Narrowing]], 타입 가드(Type Guards), 브랜디드 타입(Branded Types), [[타입 단언 (Type Assertions)|타입 단언(Type Assertions]]
- **Projects/Contexts:** 타입스크립트 애플리케이션의 런타임 값 검증 및 커스텀 타입 보장 구조 설계
- **Contradictions/Notes:** 타입 서술어는 타입을 좁혀주는 훌륭한 도구이지만, 그 자체로 내부 로직의 무결성을 타입스크립트가 검증해 주지 않기 때문에 개발자가 검증 로직을 잘못 작성하면 `as` 단언처럼 타입 시스템에 치명적인 거짓 정보(타입 오류)를 제공할 위험이 있습니다 [1].

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

---

---

- **Related Topics:** [[타입 좁히기 (Type Narrowing)|타입 좁히기(Type Narrowing]], 브랜디드 타입(Branded Types), 타입 단언(Type Assertions), [[타입 가드 (Type Guards)|타입 가드(Type Guards]]
- **Projects/Contexts:** TypeScript의 안전한 타입 검증 및 커스텀 타입 가드 설계
- **Contradictions/Notes:** 타입 조건자는 타입을 안전하게 좁히기 위한 유용한 도구로 사용되지만, 실제로는 TypeScript 컴파일러가 내부 로직의 정확성을 검증해주지 않으므로 `as` 단언문(Type Assertion)보다 본질적으로 더 타입-안전(type-safe)하다고 볼 수는 없습니다 [1].

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

---
