---
id: wiki-2026-0508-초과-속성-검사-excess-property-checks
title: 초과 속성 검사 (Excess Property Checks)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Excess Property Checks, EPC]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [typescript, type-system, frontend]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: tsc
---

# 초과 속성 검사 (Excess Property Checks)

## 매 한 줄
> **"매 object literal 의 typo 잡는 TypeScript 의 strictness gate"**. 매 object literal 을 직접 assign / pass 할 때, target type 에 없는 property 가 있으면 error. 매 typo prevention 의 first line of defense — 그러나 매 변수 indirection 으로 우회 가능.

## 매 핵심

### 매 trigger 조건
- 매 object **literal** 만 적용 — `{ ... }` 직접 assign / argument pass / return.
- 매 변수 binding 후 pass 하면 EPC X (structural subtyping 만 적용).
- 매 type assertion (`as Foo`) 시 EPC X.

### 매 왜 존재
- 매 typo (`color` vs `colour`) 같은 silent bug 방지.
- 매 structural typing 의 hole 메우기 — 매 extra property 는 logically unintended.

### 매 응용
1. Component props 의 typo 방지.
2. API request body 의 unintended field 방지.
3. Config object 의 unknown key 방지.

## 💻 패턴

### 1. Basic EPC trigger
```typescript
interface Square { color: string; width: number; }

function createSquare(s: Square) { /* ... */ }

// Error: 'colour' does not exist in type 'Square'
createSquare({ colour: 'red', width: 100 });

// OK — 매 변수 indirection bypass
const sq = { colour: 'red', width: 100 };
createSquare(sq); // structural — passes
```

### 2. Index signature escape hatch
```typescript
interface SquareConfig {
  color?: string;
  width?: number;
  [propName: string]: unknown; // 매 extra property 허용
}

createSquare({ color: 'red', width: 100, foo: 'bar' }); // OK
```

### 3. Type assertion bypass
```typescript
createSquare({ colour: 'red', width: 100 } as Square); // EPC suppressed (위험)
```

### 4. Spread bypass
```typescript
const extras = { foo: 'bar' };
createSquare({ color: 'red', width: 100, ...extras }); // OK — spread bypasses EPC
```

### 5. React props 의 typo 방지
```tsx
interface ButtonProps { variant: 'primary' | 'secondary'; }

function Button(p: ButtonProps) { return <button>{p.variant}</button>; }

// Error: 'varient' does not exist on type 'ButtonProps'
<Button varient="primary" />;
```

### 6. Discriminated union 의 EPC
```typescript
type Shape =
  | { kind: 'circle'; radius: number }
  | { kind: 'square'; side: number };

const s: Shape = { kind: 'circle', radius: 5, side: 10 };
// Error: 'side' does not exist in type '{ kind: "circle"; radius: number; }'
```

### 7. satisfies operator (modern alt)
```typescript
const config = {
  color: 'red',
  width: 100,
} satisfies Square;
// 매 EPC 적용 + 매 narrowest type preserved
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Object literal direct pass | Rely on EPC (default) |
| Plugin / dynamic config | Index signature `[k: string]: unknown` |
| Test / migration code | Type assertion `as` (last resort) |
| Modern TS 4.9+ | `satisfies` for both EPC + inference |

**기본값**: 매 object literal 직접 pass 의 EPC 의존, 매 variable indirection 회피 (의도 불분명).

## 🔗 Graph
- 부모: [[TypeScript Type System]] · [[Structural Typing]]
- 변형: [[satisfies Operator]] · [[Type Assertion]]
- 응용: [[React Props Typing]] · [[API Contract Validation]]
- Adjacent: [[Index Signatures]] · [[Discriminated Unions]]

## 🤖 LLM 활용
**언제**: TS strict mode 에서 props/config object literal 의 typo 발견 시. `satisfies` migration 권장 시.
**언제 X**: 매 dynamic / runtime-shaped object — 매 schema validation (Zod) 를 prefer.

## ❌ 안티패턴
- **Type assertion 남용**: `as Foo` 로 EPC bypass — 매 type safety 완전 상실.
- **Spread laundering**: `{ ...obj }` 으로 EPC 우회 — 매 typo 가 silently 통과.
- **Index signature 남발**: `[k: string]: any` — 매 EPC 의 효력 무효화.
- **Variable indirection**: 매 의도적으로 EPC 회피 — 매 reviewer 혼란.

## 🧪 검증 / 중복
- Verified (TypeScript Handbook — Object Types / Excess Property Checks).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — EPC trigger/bypass + satisfies modern alt |