---
id: wiki-2026-0508-structural-typing
title: Structural Typing
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [duck typing, shape typing, structural type system]
duplicate_of: none
source_trust_level: A
confidence_score: 0.93
verification_status: applied
tags: [typescript, type-system, fundamentals]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: tsc
---

# Structural Typing

## 매 한 줄
> **"매 type 의 compatibility 의 name 이 아닌 shape 으로 결정"**. TypeScript / Go 의 핵심 — 매 nominal typing (Java / C#) 의 반대. 매 2026 TS 5.7 의 동일 원칙 — 매 modern web 의 fundamental.

## 매 핵심

### 매 Nominal vs Structural
- **Nominal** (Java/C#): 매 declared name 의 일치 — 매 같은 shape 라도 다른 type 시 incompatible.
- **Structural** (TS/Go): 매 properties / methods 의 shape 의 match 의 compatible — 매 declaration site 의 무관.

### 매 동작 원리
- 매 assignability check: 매 source type 의 모든 required member 의 target type 의 존재 의 확인.
- 매 method signature: 매 parameter 의 contravariant, return 의 covariant.
- 매 excess property checking: 매 object literal 의 special case — 매 추가 property 의 error.

### 매 응용
1. 매 function parameter 의 minimal interface 의 require — 매 flexibility.
2. 매 mock / stub 의 작성 의 자연스러움 — 매 test 의 친화.
3. 매 ad-hoc type 의 inline definition.

## 💻 패턴

### 매 Structural 의 기본
```typescript
interface Point { x: number; y: number; }
class Vector { constructor(public x: number, public y: number) {} }

function dist(p: Point): number {
  return Math.sqrt(p.x ** 2 + p.y ** 2);
}

dist(new Vector(3, 4));  // OK — 매 Vector 의 Point shape 의 satisfy
dist({ x: 3, y: 4 });    // OK — 매 object literal 의 동일
```

### 매 Branded type 의 nominal 의 흉내
```typescript
// 매 structural 의 약점 — 매 같은 shape 의 다른 의미 의 mix
type UserId = string & { __brand: 'UserId' };
type OrderId = string & { __brand: 'OrderId' };

function getUser(id: UserId) { /* ... */ }
const oid = 'order-1' as OrderId;
// getUser(oid);  // 매 ERROR — 매 brand 의 mismatch
```

### 매 Function 의 contravariance
```typescript
type Logger = (msg: string) => void;
const wide: (msg: string | number) => void = (m) => console.log(m);

const log: Logger = wide;  // OK — 매 parameter 의 contravariant
// 매 wide 의 string 도 number 도 받으므로 string-only 의 substitute 가능
```

### 매 Excess property checking 의 우회
```typescript
interface Config { url: string; }

// declareConfig({ url: '/api', timeout: 5000 });  // ERROR — 매 excess
const cfg = { url: '/api', timeout: 5000 };
declareConfig(cfg);  // OK — 매 variable 의 우회 (매 fresh literal 만 check)

function declareConfig(c: Config) { /* ... */ }
```

### 매 Subtyping 의 자동
```typescript
interface Animal { name: string; }
interface Dog { name: string; bark(): void; }

const dogs: Dog[] = [{ name: 'Rex', bark: () => {} }];
const animals: Animal[] = dogs;  // OK — 매 Dog 의 superset 의 자동 subtype
```

### 매 Class 의 structural 의 trap
```typescript
class Cat { meow() {} }
class Lion { meow() {} }

const c: Cat = new Lion();  // OK?? — 매 동일 shape 의 compatible
// 매 nominal 기대 시 private field 의 brand 의 사용
class CatN { #species = 'cat'; meow() {} }
class LionN { #species = 'lion'; meow() {} }
// 매 #private 의 nominal effect — 매 cross-class 의 incompatible
```

### 매 Generic 의 structural 의 활용
```typescript
function pluck<T, K extends keyof T>(arr: T[], key: K): T[K][] {
  return arr.map(x => x[key]);
}
// 매 T 의 shape 의 자유 — 매 keyof T 의 structural inference
const names = pluck([{ name: 'a' }, { name: 'b' }], 'name');
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 일반 type | structural (default) — 매 TS 의 native |
| Domain ID 의 mix 방지 | branded type |
| Strict nominal 필요 | private field / unique symbol brand |
| External library compat | structural — 매 자연스러운 fit |

**기본값**: structural typing 의 활용. 매 ID confusion 의 risk 시 branded type 의 추가.

## 🔗 Graph
- 부모: [[TypeScript]] · [[TypeScript 타입 시스템 (TypeScript Type System)|Type System]]
- 변형: [[Nominal-Typing-in-TypeScript|Nominal Typing]] · [[Duck Typing]]
- 응용: [[Excess_Property_Checking|Excess Property Checking]] · [[ts-brand]]
- Adjacent: [[Discriminated_Unions|Discriminated Unions]] · [[Type Casting]]

## 🤖 LLM 활용
**언제**: TS type error 의 explain, branded type 의 권장, structural vs nominal 의 비교.
**언제 X**: Java/C# 같은 nominal 언어 의 답변 의 mix — 매 언어 의 명시.

## ❌ 안티패턴
- **ID confusion**: 매 UserId / OrderId 의 같은 string — 매 brand 의 추가.
- **Class identity 의 의존**: 매 instanceof 없이 type 만 의 distinguish — 매 trap.
- **Excess 의 silence**: 매 변수 거쳐 우회 후 typo 의 미발견.

## 🧪 검증 / 중복
- Verified (TypeScript Handbook, "Type Compatibility").
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Structural typing FULL 작성 |