---
id: wiki-2026-0508-타입-단언-type-assertion
title: 타입 단언(Type Assertion)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Type Assertion, as casting, TypeScript Assertion]
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
---

# 타입 단언(Type Assertion)

## 매 한 줄
> **"매 compiler 에게 'I know better' 라고 선언하는 escape hatch"**. 매 `value as Type` syntax — runtime 변환 X, compile-time 의 type 만 narrow/widen. 매 type guard 가 부족할 때 사용하나, 매 `unknown`/`satisfies` 의 prefer. 매 잘못 쓰면 type system 의 hole 생성.

## 매 핵심

### 매 두 가지 syntax
- `value as Type` — modern, JSX-safe, 권장.
- `<Type>value` — legacy, JSX 와 충돌.

### 매 동작
- 매 compile-time 만 — emit 된 JS 에서 사라짐 (runtime no-op).
- 매 type 의 신뢰 책임이 compiler → 개발자로 transfer.
- 매 sufficiently overlapping types 만 허용 — 완전 unrelated 시 double assertion (`as unknown as T`) 필요.

### 매 응용
1. DOM API 의 `Element` → `HTMLInputElement` narrowing.
2. JSON.parse 결과의 typing.
3. Discriminated union 의 explicit narrowing.

## 💻 패턴

### 1. DOM element narrowing
```typescript
const input = document.getElementById('email') as HTMLInputElement;
input.value = 'a@b.com'; // OK — 매 'value' on HTMLInputElement
```

### 2. const assertion (literal narrowing)
```typescript
const config = { mode: 'dark', size: 'lg' } as const;
// type: { readonly mode: 'dark'; readonly size: 'lg' }
```

### 3. Non-null assertion
```typescript
const el = document.querySelector('.foo')!; // Element (not null)
```

### 4. JSON.parse typing (위험 — validate prefer)
```typescript
interface User { id: number; name: string; }
const user = JSON.parse(raw) as User; // 매 unsafe — runtime validation 부재
// Better:
const user = UserSchema.parse(JSON.parse(raw)); // Zod
```

### 5. Double assertion (불가피한 경우)
```typescript
const x = (someValue as unknown) as TargetType;
// 매 last-resort — 매 review 시 reject 권장
```

### 6. Type assertion vs satisfies
```typescript
type Color = 'red' | 'green' | 'blue';

const c1 = 'red' as Color; // 매 literal 정보 상실 → Color
const c2 = 'red' satisfies Color; // 매 'red' literal preserved + Color 검증
```

### 7. Discriminated union narrowing (asserts)
```typescript
type Shape = { kind: 'circle'; r: number } | { kind: 'square'; s: number };

function isCircle(s: Shape): s is Extract<Shape, { kind: 'circle' }> {
  return s.kind === 'circle';
}
// 매 user-defined type guard prefer over `s as ...`
```

### 8. asserts function (TS 3.7+)
```typescript
function assertString(v: unknown): asserts v is string {
  if (typeof v !== 'string') throw new Error('not string');
}
const x: unknown = '...';
assertString(x);
x.toUpperCase(); // OK — narrowed
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| DOM API 결과 narrow | `as HTMLXxxElement` (필요악) |
| JSON / external data | Zod / valibot validation |
| Const value preserve | `as const` |
| Non-null guarantee | Type guard prefer, `!` only when proven |
| Discriminated union | User-defined guard / `switch (kind)` |
| Modern literal type | `satisfies` |

**기본값**: 매 type assertion 의 X — 매 type guard / `satisfies` / runtime validation 의 prefer.

## 🔗 Graph
- 부모: [[TypeScript Type System]]
- 변형: [[Const Assertion]] · [[Non-null Assertion]] · [[satisfies Operator]]
- 응용: [[DOM Typing]] · [[Type Guards]] · [[asserts Functions]]
- Adjacent: [[Excess Property Checks]] · [[Zod Validation]] · [[Discriminated Unions]]

## 🤖 LLM 활용
**언제**: 매 DOM API narrowing, `as const` 의 literal preservation 시.
**언제 X**: 매 external data shaping — Zod 의 prefer. 매 double assertion (`as unknown as T`) 권장 X.

## ❌ 안티패턴
- **Validate 없는 JSON cast**: `JSON.parse(x) as User` — 매 runtime 의 type 보장 부재.
- **Double assertion 남용**: `as unknown as T` — 매 type system 의 완전 우회.
- **Non-null assertion 남발**: `el!.foo` — 매 null bug 의 silent ship.
- **as 로 union narrow**: `s as { kind: 'circle' }` — 매 user-defined guard 가 정답.

## 🧪 검증 / 중복
- Verified (TypeScript Handbook — Everyday Types / Narrowing).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — assertion variants + satisfies/asserts modern alternatives |
