---
id: wiki-2026-0508-타입-단언-type-assertions
title: 타입 단언(Type Assertions)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [Type Assertion, as-cast, 타입 캐스팅]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [typescript, type-system, architecture]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: TS 5.7+
---

# 타입 단언(Type Assertions)

## 매 한 줄
> **"매 컴파일러에게 'I know better' 라고 선언하는 escape hatch."**. TS 컴파일러의 type narrowing 으로 도달 못하는 type 을 개발자가 직접 단언하는 메커니즘. 매 `as Type` syntax (TSX-safe) 와 `<Type>value` (legacy) 두 형태. Runtime 검증 X — 매 단순 compile-time 표시.

## 매 핵심

### 매 단언 vs 변환
- **Type Assertion**: 매 compile-time only. 매 runtime 코드 생성 X.
- **Type Conversion**: 매 runtime transformation (e.g. `Number(x)`, `String(x)`).
- 매 혼동 주의 — `as number` 는 매 conversion 의 X.

### 매 안전 등급
- **Safe**: 매 narrower → wider (subtype → supertype). 매 implicit 가능.
- **Unsafe**: 매 wider → narrower. 매 explicit assertion 필요.
- **Forbidden**: 매 incompatible types. 매 `as unknown as Target` double-cast 강제.

### 매 응용
1. DOM API 의 element type 좁히기 (`querySelector` result).
2. Discriminated union 의 case narrowing.
3. JSON.parse 의 결과 typing.
4. Library type definition 의 gap 메우기.

## 💻 패턴

### Pattern 1 — DOM narrowing
```typescript
const input = document.getElementById('email') as HTMLInputElement;
input.value = 'user@example.com';
// HTMLElement 에는 .value X — 매 assertion 필요.
```

### Pattern 2 — `as const` (literal narrowing)
```typescript
const config = {
  mode: 'production',
  retries: 3,
} as const;
// type: { readonly mode: 'production'; readonly retries: 3 }
// 매 not { mode: string; retries: number }.
```

### Pattern 3 — Satisfies operator (TS 4.9+, 매 권장 대안)
```typescript
type Routes = Record<string, { path: string; auth: boolean }>;

const routes = {
  home: { path: '/', auth: false },
  admin: { path: '/admin', auth: true },
} satisfies Routes;
// 매 routes.home 의 literal type 보존 + Routes 호환성 검증.
// `as Routes` 는 literal type 손실 — satisfies 가 매 superior.
```

### Pattern 4 — Non-null assertion
```typescript
function getUser(id: string): User | undefined { /* ... */ }

const user = getUser('123')!;
// 매 ! 는 'this is not null/undefined' 의 단언.
// 매 strictNullChecks 환경에서만 의미 있음.
```

### Pattern 5 — Double assertion (escape hatch)
```typescript
interface Cat { meow(): void; }
interface Dog { bark(): void; }

const cat: Cat = { meow: () => {} };
const dog = cat as unknown as Dog;
// cat as Dog 는 error — 매 incompatible.
// as unknown 으로 일단 wide 로 넓힌 뒤 narrow.
// 매 anti-pattern signal — 매 design 재검토.
```

### Pattern 6 — Type predicate (assertion 보다 권장)
```typescript
function isString(value: unknown): value is string {
  return typeof value === 'string';
}

const value: unknown = 'hello';
if (isString(value)) {
  value.toUpperCase(); // 매 narrowed safely.
}
// 매 runtime check + compile-time narrowing.
// 매 `as string` 보다 safe.
```

### Pattern 7 — Const assertion in arrays
```typescript
const tuple = [1, 'hello', true] as const;
// type: readonly [1, 'hello', true]
// 매 not (number | string | boolean)[].

type First = typeof tuple[0]; // 1 (literal).
```

### Pattern 8 — JSON.parse typing
```typescript
interface ApiResponse { id: number; name: string; }

const json = '{"id": 1, "name": "Alice"}';
const data = JSON.parse(json) as ApiResponse;
// 매 unsafe — runtime 검증 X.
// 매 권장: zod / valibot schema validation.

import { z } from 'zod';
const schema = z.object({ id: z.number(), name: z.string() });
const safe = schema.parse(JSON.parse(json)); // 매 runtime + type safe.
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Object literal 의 type 검증 + literal 보존 | `satisfies` |
| Runtime check 가능 | Type predicate (`is T`) |
| DOM API result narrowing | `as` (불가피) |
| Const config / tuple | `as const` |
| Incompatible types 강제 | `as unknown as T` (매 last resort) |
| External JSON / API | zod / valibot |

**기본값**: 매 type predicate 또는 `satisfies`. `as` 는 매 last resort.

## 🔗 Graph
- 변형: [[타입 가드 (Type Predicates)]] · [[Satisfies Operator]]
- 응용: [[Discriminated_Unions|Discriminated Unions]] · [[Branded Types]]

## 🤖 LLM 활용
**언제**: 매 narrow 가 불가능한 context (DOM API, JSON parse, library gap) 에서 매 explicit 단언.
**언제 X**: 매 type guard 로 표현 가능한 경우. 매 `as any` 의 남용 — type system 우회.

## ❌ 안티패턴
- **`as any` 남용**: 매 type system 의 무력화. 매 `unknown` + type guard 로 대체.
- **Lying assertion**: 매 `value as User` 인데 실제로는 매 partial — runtime crash 의 원인.
- **Double cast 일상화**: 매 `as unknown as T` 가 흔하다면 매 design 결함.
- **`as const` 누락**: 매 literal type 필요 시 widening 으로 의도 손실.

## 🧪 검증 / 중복
- Verified (TypeScript Handbook 2026, TS 5.7).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Type Assertions 의 8 patterns + satisfies vs as 비교 |
