2nd/10_Wiki/Topics/Frontend/과잉 속성 체크(EPC).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-과잉-속성-체크-epc	과잉 속성 체크(EPC)	10_Wiki/Topics	verified	self	Excess Property Check EPC TypeScript 초과 속성 검사	none	A	0.92	applied	typescript type-system structural-typing frontend		2026-05-10	pending	language framework TypeScript tsc 5.x

과잉 속성 체크(EPC)

매 한 줄

"매 object literal 을 매 직접 assign 할 때 매 declared shape 외 매 extra property 을 매 reject". TypeScript 의 매 structural typing 은 매 기본적으로 매 width subtype 을 매 허용하지만, 매 object literal 의 매 fresh literal type 은 매 EPC 라는 매 특수 검사 의 매 통과 의 필요. 매 2026 의 TS 5.x 의 매 동일 동작 의 유지, 매 satisfies / 매 as const 의 매 EPC 회피의 X.

매 핵심

매 EPC 트리거 조건

• 매 fresh object literal (매 변수 의 매 binding X)
• 매 declared type 의 매 존재 (매 parameter, 매 assignment target, 매 return)
• 매 declared type 의 매 superset 의 X 인 매 property 의 매 포함

매 EPC 우회 패턴

• 매 변수 의 매 intermediate binding (매 freshness 의 lose)
• 매 type assertion (as T) — 매 권장 X
• 매 index signature ([k: string]: unknown)

매 응용

1. 매 API option object 의 매 typo 방지.
2. 매 React props 의 매 unknown prop 차단.
3. 매 config schema 의 매 strict validation.

💻 패턴

EPC 발동 (기본)

interface ButtonProps {
  label: string;
  onClick: () => void;
}

function render(props: ButtonProps) {}

// ❌ Error: Object literal may only specify known properties, and 'icon' does not exist in type 'ButtonProps'
render({ label: "Save", onClick: () => {}, icon: "💾" });

Intermediate binding 우회 (의도적이지 않은 경우 위험)

const extra = { label: "Save", onClick: () => {}, icon: "💾" };
render(extra); // ✅ 통과 — fresh 아니어서 EPC 미발동, structural width subtyping 만 검사

satisfies 와 EPC

// satisfies 도 EPC 적용 — extra property reject
const config = {
  label: "Save",
  onClick: () => {},
  // icon: "💾", // ❌ EPC error
} satisfies ButtonProps;

Index signature 로 의도적 허용

interface FlexibleProps {
  label: string;
  [key: string]: unknown;
}

function render2(p: FlexibleProps) {}
render2({ label: "Save", extra: 123 }); // ✅

Discriminated union 과 EPC

type Action =
  | { type: "add"; value: number }
  | { type: "remove"; id: string };

function dispatch(a: Action) {}

// ❌ EPC: 'value' 와 'id' 동시 존재 reject
dispatch({ type: "add", value: 1, id: "x" });

React props 에 적용

type Props = { name: string };
function Hello(props: Props) { return <p>{props.name}</p>; }

// ❌ EPC: 'age' is not in Props
<Hello name="Ada" age={36} />;

회피 안티패턴 (지양)

// ❌ as 캐스팅 — 런타임 typo 방치
render({ label: "Save", onClick: () => {}, icon: "💾" } as ButtonProps);

매 결정 기준

상황	Approach
API option literal	EPC 활용 — typo 차단
동적 prop forward	spread + 명시 typing
외부 라이브러리 객체	satisfies 우선, as 회피
의도된 extra metadata	index signature 도입

기본값: EPC 의 매 의존, 매 as 캐스팅 의 X, 매 satisfies 의 매 우선.

🔗 Graph

• 부모: TypeScript Type System · Structural Typing
• 변형: Width Subtyping · Fresh Literal Types
• 응용: satisfies Operator · React Props Typing
• Adjacent: Discriminated Unions · Index Signatures

🤖 LLM 활용

언제: 매 object literal 직접 전달 시 매 typo / 매 stale prop 의 매 정적 차단 의 필요. 언제 X: 매 plugin / 매 forward props / 매 metadata pass-through — 매 index signature 또는 매 generic constraint 의 매 권장.

❌ 안티패턴

• as 캐스팅 의존: EPC 무력화, 런타임 버그 양산.
• @ts-ignore 로 무시: 검사 의도 자체 의 폐기.
• 모든 type 에 [k: string]: unknown: EPC 의 효과 의 상실.

🧪 검증 / 중복

• Verified (TypeScript Handbook — Object Literals & Excess Property Checks, TS 5.4+).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — EPC trigger / 우회 패턴 / satisfies 의 동작 정리