---
category: Unified
tags: [auto-consolidated, technical-documentation]
title: [[Excess Property Checking|Excess Property Checking]]
last_updated: 2026-05-02
---

# [[Excess Property Checking|Excess Property Checking]]

## 📌 Brief Summary
> TypeScript의 Excess Property Checking(과잉 속성 체크)은 객체 리터럴이 다른 변수에 할당되거나 함수의 인수로 전달될 때 예상치 못한 초과 속성을 감지하고 타입 에러를 표출하는 기능이다 [1-3]. 이는 TypeScript의 기본 동작인 구조적 타이핑([[Structural Typing|Structural Typing]]) 규칙을 더 엄격하게 적용하는 예외적인 사례로 볼 수 있다 [1]. 개발자가 속성 이름에 오타를 내는 등의 실수로 인해 발생할 수 있는 의도치 않은 런타임 오류를 방지하기 위해 존재한다 [4-6].

---

> "너 정체가 뭐야? 시키지 않은 건 하지 마." 객체 리터럴을 변수에 할당하거나 함수 인자로 전달할 때, 정의되지 않은 추가 속성이 포함되어 있으면 타입 에러를 발생시켜 오타나 실수(Mistyping)를 방지하는 TypeScript의 안전장치다.

---

> TypeScript의 과잉 속성 체크(Excess Property Checking, EPC)는 객체 리터럴이 다른 변수에 직접 할당되거나 함수의 인자로 전달될 때, 대상 타입에 정의되지 않은 속성이 포함되어 있는지를 엄격하게 검사하는 기능이다[1-4]. 이는 구조적 타이핑([[Structural Typing|Structural Typing]])의 유연함으로 인해 속성 이름의 오타나 잘못된 데이터가 유입되어 발생하는 런타임 오류를 컴파일 시점에 방지하는TypeScript의 핵심 방어 기제로 작동한다[5-7].

---

> 과잉 속성 체크(Excess Property Checking)는 TypeScript에서 객체 리터럴을 다른 변수에 직접 할당하거나 함수의 인자로 전달할 때, 예상치 못한(정의되지 않은) 잉여 속성이 포함되어 있는지 엄격하게 검사하여 에러를 발생시키는 기능입니다 [1-4]. 구조적 타이핑의 유연성 속에서 발생할 수 있는 오타나 잘못된 속성 전달 실수를 컴파일 시점에 포착하여 런타임 오류를 방지하는 첫 번째 방어선 역할을 합니다 [5-7].

---

> 초과 속성 검사(Excess Property Checking)는 TypeScript에서 객체 리터럴을 다른 변수에 직접 할당하거나 함수의 인수로 전달할 때, 예상치 못한(정의되지 않은) 속성이 객체에 포함되어 있는지 감지하여 에러를 발생시키는 기능입니다 [1-5]. 이는 개발자가 속성 이름에 오타를 내거나 잘못된 속성을 전달하는 실수를 방지하여 의도치 않은 런타임 동작을 막기 위해 존재합니다 [6-8]. 하지만 객체를 중간 변수에 먼저 할당한 후 전달하면 구조적 타이핑의 원칙에 따라 이 검사를 우회하게 되는 특징이 있습니다 [6, 9, 10].

## 📖 Core Content
* **동작 원리와 목적**
  TypeScript의 타입 시스템은 기본적으로 객체가 요구되는 최소한의 속성만 가지고 있다면 호환성을 허용하는 구조적 타이핑(Structural Typing, 일명 덕 타이핑)을 따른다 [7-9]. 그러나 대상 타입에 직접 객체 리터럴을 할당하거나 함수의 인자로 객체 리터럴을 넘길 때는 특별히 Excess Property Checking이 발동하여 선언되지 않은 잉여 속성이 있는지 엄격하게 검사한다 [1, 3, 6, 10-12]. 이는 개발자가 초과 속성을 전달하려는 의도가 없을 것이라고 가정하여 오타(예: `color` 대신 `colour`) 등의 실수를 컴파일 시점에 포착하기 위함이다 [4-6, 9].

* **한계점 및 우회 문제**
  Excess Property Checking은 객체 리터럴을 중간 변수(intermediate variable)에 먼저 할당한 뒤 다른 변수나 인수로 전달할 경우에는 작동하지 않는다는 맹점이 있다 [1, 3, 4, 12, 13]. 중간 변수를 사용할 때 대상 타입과 최소 하나의 속성이라도 일치한다면, TypeScript는 초과 속성이 있더라도 에러를 발생시키지 않는다 [14]. (만약 공통 속성이 하나도 없다면 '약한 타입 검사(Weak Type Detection)' 규칙에 의해 에러가 발생한다 [3, 15]). 또한 명시적인 반환 타입 어노테이션이 없는 문맥적인 할당에서도 에러를 제대로 잡아내지 못하는 한계가 보고된 바 있다 [16]. 

* **보완 전략 (`satisfies` 및 커스텀 타입)**
  객체 리터럴을 중간 변수를 통해 전달하면서 발생하는 우회 문제를 극복하기 위해 TypeScript 4.9에서 도입된 `satisfies` 연산자를 활용할 수 있다 [17, 18]. `satisfies` 연산자는 객체의 구체적인 값 형태를 유지하면서도 대상 타입에 정의되지 않은 초과 속성을 엄격히 걸러내어 타입 안전성을 보장한다 [18-21]. 또한, 제네릭과 `never` 타입을 결합하여 대상 인터페이스와 실제 입력을 비교하고 잉여 속성을 잡아내는 재귀적 유틸리티 타입을 만들어 수동으로 초과 속성을 찾아낼 수도 있지만, 이는 타입 검사 성능에 부정적인 영향을 미칠 수 있어 주의해서 사용해야 한다 [22-24].

---

- **Object Literal Restriction**: 변수에 미리 담지 않고 직접 `{...}` 형태로 넘길 때만 발동함.
- **[[Structural Typing|Structural Typing]] Exception**: TypeScript는 기본적으로 구조적 타이핑을 따르지만, 리터럴 할당 시에는 '엄격한 타입 일치'를 요구하여 버그를 줄임.
- **Bypassing Methods**:
    - 변수에 할당 후 전달.
    - 타입 단언(`as AnyType`) 사용.
    - 인덱스 시그니처(`[key: string]: any`) 추가.

---

- **도입 배경 및 목적**: TypeScript는 기본적으로 객체의 형태(구조)가 일치하면 타입의 호환성을 인정하는 구조적 타이핑(덕 타이핑) 원칙을 따른다[7-9]. 그러나 대상 타입의 속성을 충족하더라도 오타(예: `color` 대신 `colour`를 입력)와 같은 실수로 잉여 속성이 포함되면 의도치 않은 런타임 동작이 발생할 수 있다[5, 6]. 이러한 한계를 보완하기 위해 TypeScript는 객체 리터럴에 대해 예외적으로 더 엄격한 잣대를 들이대는 '과잉 속성 체크'를 수행한다[1, 5].
- **동작 방식과 한계 (우회 현상)**: 과잉 속성 체크는 객체 리터럴이 변수에 직접 할당되거나 인자로 전달되는 특수한 경우에만 작동한다[3, 5]. 만약 변수를 먼저 선언한 후 이를 다른 타입에 간접적으로 할당하거나 제네릭 타입 매개변수를 사용하는 경우, 두 객체 사이에 최소 하나의 공통 속성만 존재한다면 과잉 속성 체크가 작동하지 않는다[10-12]. 이는 시스템이 "최소 요건 충족"이라는 구조적 타이핑의 기본 원칙으로 되돌아가기 때문이다[12]. (단, 선택적 속성만 가진 '약한 타입(Weak Type)'의 경우에는 공통 속성이 아예 없으면 에러를 발생시키는 약한 타입 탐지가 작동한다[13, 14].)
- **우회로 인한 부작용**: 간접 할당 등을 통해 과잉 속성 체크가 우회되면, 예상치 못한 잉여 데이터가 객체 내부에 숨어들 수 있다[12]. 이는 React 컴포넌트 등에서 유효하지 않은 속성이 DOM으로 넘어가 경고를 발생시키거나, 불필요한 리렌더링을 유발하고 런타임 시 보안 유출의 원인이 되기도 한다[12, 15]. 
- **`satisfies` 연산자를 통한 방비**: `as` 키워드를 이용한 타입 캐스팅([[Type Casting|Type Casting]])은 과잉 속성 체크를 수행하지 않아 잠재적인 에러를 유발할 수 있다[16]. 이 같은 취약점을 보완하기 위해 TypeScript 4.9에 도입된 `satisfies` 연산자는 객체가 특정 인터페이스나 타입을 만족하는지 엄격히 검사하여 과잉 속성의 유입을 컴파일 단계에서 차단한다[17, 18]. 더불어 객체의 구체적인 값(리터럴 타입 등)을 유지해 정밀한 타입 추론과 타입 좁히기(Narrowing)를 돕는 혁신적인 수비 전략으로 활용된다[18-20].

---

- **구조적 타이핑의 보완 장치**: TypeScript는 기본적으로 객체가 요구되는 최소한의 속성을 가지고 있다면 타입 호환성을 인정하는 구조적 타이핑([[Structural Typing|Structural Typing]], 일명 덕 타이핑)을 사용합니다 [7, 8]. 그러나 이 유연성으로 인해 `color`를 `colour`로 잘못 입력하는 등의 오타가 발생해도 호환되는 것으로 판단될 위험이 있습니다 [6]. TypeScript는 객체 리터럴을 직접 다루는 상황에서는 개발자가 잉여 속성을 전달할 의도가 없었을 것이라 간주하여 더 엄격한 과잉 속성 체크를 적용해 실수를 방지합니다 [5-7].
- **발동 조건 및 한계 (우회로)**: 과잉 속성 체크는 "객체 리터럴"이 대상 타입에 직접 할당되거나 인수로 전달될 때만 특별하게 동작합니다 [3-5]. 만약 객체 리터럴을 먼저 중간 변수에 선언 및 할당한 뒤, 해당 변수를 대상 타입에 간접적으로 할당하면 이 기능은 작동하지 않습니다 [3, 5, 9, 10]. 변수를 거치게 되면 구조적 타이핑의 기본 원칙인 "최소 요건 충족"으로 돌아가기 때문에, 대상 타입과 최소 하나의 속성만 겹치면 초과 속성이 존재하더라도 에러를 발생시키지 않게 됩니다 [10, 11].
- **잠재적 위험과 `satisfies`를 통한 해결**: 간접 할당을 통해 과잉 속성 체크를 우회하게 될 경우, React 컴포넌트에 유효하지 않은 속성이 전달되거나 불필요한 리렌더링이 발생하는 등 런타임 버그의 원인이 될 수 있습니다 [10, 12, 13]. 이를 해결하기 위해 TypeScript 4.9에 도입된 `satisfies` 연산자를 활용할 수 있습니다 [14]. `satisfies`는 객체의 구체적인 타입(리터럴 타입 등)을 잃지 않고 유지하면서도, 대상 인터페이스의 요구사항을 엄격하게 검사하여 간접 할당 시에도 과잉 속성을 효과적으로 차단합니다 [14, 15].

---

* **발동 조건 및 목적**
  TypeScript는 기본적으로 속성의 구조만 맞으면 타입이 호환된다고 보는 구조적 타이핑([[Structural Typing|Structural Typing]]) 시스템을 따릅니다 [11]. 그러나 객체 리터럴이 변수에 직접 할당되거나 인수로 전달되는 특수한 상황에서는 TypeScript가 더 엄격하게 동작하여 초과 속성 검사를 실행합니다 [1, 4, 6]. 이 기능은 `color`를 `colour`로 입력하는 것과 같은 오타를 잡아내며, 해당 상황에서 개발자가 초과 속성을 의도적으로 전달할 확률이 극히 낮다고 가정하여 런타임 에러를 사전에 차단합니다 [6-8].

* **검사의 한계 (우회 메커니즘)**
  객체 리터럴을 중간 변수에 먼저 할당한 뒤 이를 다른 변수나 함수에 전달하면, 초과 속성 검사가 작동하지 않습니다 [6, 9]. 두 객체가 최소 하나 이상의 공통 속성만 가지고 있다면 "최소 요건 충족"이라는 구조적 타이핑 원칙이 적용되기 때문입니다 [6, 9, 10]. 이러한 방식은 [[JavaScript|JavaScript]]의 유연한 패턴을 지원하지만, 동시에 불필요하거나 잘못된 속성이 런타임에 유입되어 부작용(예: React 컴포넌트의 의도치 않은 리렌더링, 잘못된 DOM 속성 전달)을 일으키는 원인이 될 수 있습니다 [10, 12].

* **완화 및 방어 전략**
  * **`satisfies` 연산자의 활용:** TypeScript 4.9에서 도입된 `satisfies` 연산자를 사용하면 간접 할당 과정에서도 엄격한 속성 검사를 수행할 수 있습니다. 이를 통해 구체적인 값(리터럴 타입 등)을 유지하면서 대상 타입에 정의되지 않은 초과 속성이 들어오는 것을 원천 차단합니다 [13, 14].
  * **커스텀 제네릭 타입 활용:** 더 엄격한 수동 검사가 필요한 경우, 제네릭 매개변수(`T`)와 예상 타입(`Shape`)을 비교하여 예상 타입에 없는 속성을 `never` 타입으로 강제 할당하는 방식을 사용할 수 있습니다 [15, 16]. 중첩된 깊은 객체 구조에 대해서는 재귀적 타입을 활용해 초과 속성을 감지해냅니다 [17, 18].

* **관련 린트(Lint) 규칙 제안**
  변수 할당 시에도 초과 속성 검사가 누락되는 것을 막기 위해 `[[ESLint|ESLint]]-plugin`에 `no-excess-properties`라는 규칙이 제안된 바 있습니다 [19]. 그러나 TypeScript에서는 모든 객체가 본질적으로 "부정확성(inexact)"을 허용하는 구조적 타이핑에 의존하며, 과잉 속성이 실제 버그로 이어지는 경우가 드물다는 점, 그리고 커뮤니티의 수요가 부족하다는 점 때문에 해당 제안은 채택되지 않고 닫혔습니다 [20-22].

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

---

- 이 기능은 때때로 "덕 타이핑(Duck Typing)이라며 왜 안 돼?"라며 초보자들을 당황하게 만든다. 하지만 이는 리터럴 객체 생성 시 발생할 수 있는 오타(예: `colour` vs `color`)를 런타임 이전 단계에서 원천 봉쇄하기 위한 의도적인 설계다.

---

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

---

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

---

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

## 🔗 Knowledge Connections
- **Related Topics:** [[Structural Typing|Structural Typing]], satisfies Operator, Weak Type Detection
- **Projects/Contexts:** TypeScript TypeSystem, [[ESLint|ESLint]] Rule Proposals (no-excess-properties)
- **Contradictions/Notes:** 소스 [25]에 따르면, Facebook의 Flow처럼 초과 속성을 허용하지 않는 정확한 객체 타입(`Exact<T>`) 구문을 TypeScript에도 도입하자는 오랜 제안이 있었으나, TypeScript 팀은 Excess Property Checking 자체를 더 똑똑하게 개선하는 방향을 선호한다. 한편, ESLint의 린트 룰을 통해 초과 속성 검사를 강제하려는 시도에 대해서는, TypeScript의 모든 객체가 본질적으로 구조적 타이핑에 의해 "inexact"한 특성을 갖기 때문에 린트 룰 적용 시 노이즈(False Positive)가 과도하게 발생할 수 있다는 반론이 제기된다 [26, 27].

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

---

---

- Related: Structural-Typing-vs-Nominal-Typing , TypeScript-Best-Practices
- Concept: Type-Guard

---

- **Related Topics:** 구조적 타이핑 (Structural Typing), [[satisfies 연산자|satisfies 연산자]], 타입 캐스팅 (Type Casting), [[약한 타입 탐지 (Weak Type Detection)|약한 타입 탐지 (Weak Type Detection]]
- **Projects/Contexts:** 철벽 수비대" - TypeScript 타입 시스템 (인터페이스 설계), [[React 컴포넌트 Props 검증|React 컴포넌트 Props 검증]]
- **Contradictions/Notes:** 객체 리터럴을 직접 할당할 때는 과잉 속성 체크가 발동되어 에러를 반환하지만, 중간 변수를 통해 간접 할당될 때는 구조적 타이핑 원칙이 적용되어 과잉 속성이 존재해도 에러가 발생하지 않는 모순적 동작을 보인다[1, 3, 5, 12]. 또한 `as` 연산자는 과잉 속성을 무시하고 할당을 허용하지만, `satisfies` 연산자는 초과된 속성에 대해 엄격한 검증을 강제한다[16, 21].

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

---

---

- **Related Topics:** [[구조적 타이핑(Structural Typing)|구조적 타이핑(Structural Typing]], satisfies 연산자, [[약한 타입 검사(Weak Type Detection)|약한 타입 검사(Weak Type Detection]]
- **Projects/Contexts:** [[TypeScript의 인터페이스 및 객체 타입 설계|TypeScript의 인터페이스 및 객체 타입 설계]], [[React 컴포넌트 Props 전달 및 상태 관리|React 컴포넌트 Props 전달 및 상태 관리]]
- **Contradictions/Notes:** TypeScript는 구조적 타이핑을 핵심 철학으로 삼지만, "객체 리터럴"에 대해서만 과잉 속성 체크라는 예외적으로 엄격한 잣대를 적용합니다. 이로 인해 값을 직접 전달할 때와 중간 변수를 거쳐 전달할 때의 타입 검사 결과가 달라지는 동작 방식의 차이가 존재합니다 [3, 5, 11].

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

---

---

- **Related Topics:** 구조적 타이핑 (Structural Typing), [[satisfies 연산자|satisfies 연산자]]
- **Projects/Contexts:** typescript-eslint
- **Contradictions/Notes:** TypeScript는 근본적으로 속성 집합의 포함 관계만 확인하는 '구조적 타이핑' 원칙을 따르지만, 객체 리터럴을 직접 다루는 맥락에서는 이러한 유연성을 예외적으로 차단하고 '초과 속성 검사'라는 더 엄격한 잣대를 적용한다는 점에서 뚜렷한 동작의 대비를 보입니다 [1, 6, 11].

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

---