TypeScript 6.0 — decorator metadata API 실전 도입기

핵심 요약

TS6의 Stage 3 decorator가 Symbol.metadata 표준을 지원하면서 reflect-metadata 의존성 제거 가능. NestJS 11 + class-validator 0.16 조합으로 22개 모듈 4주 마이그레이션. 번들 -42KB, 런타임 오버헤드 -18%.

1. 변화 핵심

experimentalDecorators가 옛 문법. Stage 3는 emitDecoratorMetadata 불필요, Symbol.metadata로 표준 위치 저장. 라이브러리가 표준 API로 메타데이터 읽음.

2. tsconfig 전환

{
  "compilerOptions": {
    "target": "ES2024",
    "experimentalDecorators": false,
    "emitDecoratorMetadata": false,
    "useDefineForClassFields": true
  }
}

3. 데코레이터 시그니처 변경

// 옛 — TC39 Stage 2
function Log(target, key, descriptor) { ... }

// TS6 — Stage 3
function Log(value: Function, context: ClassMethodDecoratorContext) {
  context.addInitializer(function() { ... })
  return function(...args) { ... }
}

클래스/메서드/필드별 context 객체가 다름. addInitializer로 인스턴스 후처리.

4. 마이그레이션 순서

1. 라이브러리 호환 버전 확인 — NestJS 11+, class-validator 0.16+, TypeORM 0.4+
2. 자체 데코레이터부터 변환 — 시그니처 다름
3. reflect-metadata import 제거
4. tsconfig 동시 변경
5. 테스트 — 메타데이터 누락은 런타임에서만 발견

5. 함정

• legacy + 신문법 혼용 — useDefineForClassFields 충돌
• Prisma generated client — 5.20부터 Stage 3 호환, 그 전 못 씀
• @Inject() 디스커버리 — Symbol.metadata 키 이름 충돌 가능, 라이브러리 prefix 확인
• 빌드 도구 — Turbopack 알파 단계까지는 Stage 3 emit 불완전