2nd/10_Wiki/Topic_Programming/Frontend/초과 속성 검사 (Excess Property Checks).md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

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

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

interface SquareConfig {
  color?: string;
  width?: number;
  [propName: string]: unknown; // 매 extra property 허용
}

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

3. Type assertion bypass

createSquare({ colour: 'red', width: 100 } as Square); // EPC suppressed (위험)

4. Spread bypass

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

5. React props 의 typo 방지

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

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)

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
• Adjacent: 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