이펙티브 타입스크립트 2판 Day 14: JS에서 TS로 옮길 때 먼저 좁혀야 할 경계

범위: Effective TypeScript 2판 Item 79–83

오늘의 질문: “JavaScript 프로젝트를 TypeScript로 바꾸는 일은 파일 확장자를 .ts로 바꾸는 일일까?”

이 글의 원천 앵커

마지막 범위는 마이그레이션입니다. TypeScript를 처음부터 쓰는 프로젝트보다, 이미 돌아가는 JavaScript를 점진적으로 옮기는 프로젝트가 더 어렵습니다. 기존 런타임 의미를 깨지 않으면서 타입 경계를 좁혀야 하기 때문입니다.

이번 글에서 잃으면 안 되는 포인트는 이겁니다.

낡은 JavaScript 문법을 먼저 현대화하면 타입 전환 비용이 줄어든다. @ts-check와 JSDoc은 JS 파일 안에서도 타입 피드백을 준다. allowJs는 혼합 상태를 허용하지만, 영구 방치하면 경계가 흐려진다. 모듈별 마이그레이션은 입출력 계약부터 좁혀야 한다. noImplicitAny는 마지막에 켜는 엄격 옵션이 아니라, 새 구멍을 막는 품질 게이트가 될 수 있다.

먼저 보는 코드

function getUserName(user) {
  return user.profile.name.trim();
}

작은 함수처럼 보이지만 이 코드에는 많은 가정이 숨어 있습니다.

user는 객체다. profile이 있다. name은 문자열이다. trim을 호출해도 된다. 실패하면 throw해도 된다.

파일을 user.ts로 바꾸면 타입 에러가 생깁니다. 여기서 급하게 any를 붙이면 마이그레이션은 빨라 보이지만, 실제로는 기존 불확실성을 타입 시스템 안으로 들여오는 겁니다.

function getUserName(user: any) {
  return user.profile.name.trim();
}

이건 TypeScript로 옮긴 코드가 아니라, JavaScript의 불확실성을 any로 포장한 코드에 가깝습니다.

1단계: JS 현대화로 런타임 의미를 선명하게 만들기

마이그레이션 전에 오래된 JS 습관을 줄이면 타입 전환이 쉬워집니다.

var user = getUser();
if (user && user.profile && user.profile.name) {
  console.log(user.profile.name);
}

현대적인 JS로 먼저 바꾸면 의도가 더 잘 보입니다.

const user = getUser();
const name = user?.profile?.name;

if (typeof name === "string") {
  console.log(name);
}

이 변화는 타입스크립트만을 위한 게 아닙니다. var를 줄이고, 모듈 경계를 ESM으로 정리하고, optional chaining/nullish coalescing을 쓰면 런타임 의미가 선명해집니다. Day 13의 Module 글과도 이어집니다. CJS/ESM이 뒤섞인 상태에서 TS 전환을 시작하면 타입보다 로더/번들러 문제가 먼저 터질 수 있습니다.

리뷰 질문은 이렇습니다.

TS 전환 전에 JS 자체의 의미가 충분히 선명한가? 오래된 문법 때문에 타입이 불필요하게 넓어지는가? this, prototype, module side effect 같은 런타임 동작을 이해하지 못한 채 타입만 붙이고 있지 않은가?

2단계: @ts-check와 JSDoc으로 먼저 신호를 보기

모든 파일을 한 번에 .ts로 바꾸지 않아도 타입 피드백을 받을 수 있습니다.

// @ts-check

/**
 * @param {{ id: string, name: string }} user
 * @returns {string}
 */
export function getDisplayName(user) {
  return user.name.trim();
}

JSDoc은 “TS를 못 쓰는 임시방편”이 아닙니다. JS 파일을 유지해야 하는 상황에서 public contract를 드러내는 도구가 됩니다. 특히 라이브러리 코드, 빌드 설정, 레거시 script, 점진 전환 중인 파일에서 유용합니다.

다만 JSDoc도 만능은 아닙니다.

타입이 복잡해지면 TS 파일보다 읽기 어렵다. 런타임 검증을 대신하지 않는다. 문서와 실제 코드가 어긋날 수 있다. 팀이 JSDoc 타입 문법을 읽을 수 있어야 한다.

그래서 JSDoc은 최종 목적지라기보다, “어디가 불확실한지 먼저 드러내는 스캐너”처럼 쓰는 편이 좋습니다.

3단계: allowJs는 혼합 상태를 위한 장치다

allowJs를 켜면 TS 프로젝트 안에서 JS 파일을 함께 다룰 수 있습니다.

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true
  }
}

이 설정은 큰 프로젝트를 한 번에 옮기지 않아도 되게 합니다. 하지만 혼합 상태는 관리하지 않으면 오래 갑니다. .js, .jsx, .ts, .tsx가 섞인 채 규칙이 없으면 팀은 어떤 파일에 어느 정도 타입 엄격도를 기대해야 하는지 알기 어렵습니다.

마이그레이션 PR에서 봐야 할 건 파일 확장자 수가 아닙니다.

어떤 폴더부터 옮기는가? 새 파일은 TS로만 받는가? JS 파일에 @ts-check를 붙이는 기준이 있는가? allowJs를 언제 줄일지 계획이 있는가? 타입 에러를 skipLibCheck, any, // @ts-ignore로 덮고 있지 않은가?

allowJs는 다리입니다. 다리를 건너는 계획이 없으면 프로젝트 구조가 영구히 애매해집니다.

4단계: 모듈별로 입출력 계약부터 좁히기

마이그레이션은 아래에서 위로, 또는 밖에서 안으로만 정해지는 게 아닙니다. 중요한 것은 경계입니다.

// price.js
export function formatPrice(value, currency) {
  if (currency === "KRW") return `${value.toLocaleString()}원`;
  return `$${value.toFixed(2)}`;
}

이 파일을 옮길 때 함수 내부부터 세밀하게 타입을 붙이기보다, 먼저 입출력을 고정합니다.

type Currency = "KRW" | "USD";

export function formatPrice(value: number, currency: Currency): string {
  if (currency === "KRW") return `${value.toLocaleString()}원`;
  return `$${value.toFixed(2)}`;
}

그다음 호출 지점에서 깨지는 곳을 봅니다. 어떤 호출자는 currency를 그냥 string으로 들고 있을 수 있습니다. 어떤 호출자는 value가 API에서 온 문자열일 수 있습니다. 이때 타입 에러는 귀찮은 방해물이 아니라, 경계가 어디서 흐려졌는지 알려주는 지도입니다.

AI가 만든 migration PR에서 특히 자주 보이는 나쁜 패턴은 이것입니다.

export function formatPrice(value: any, currency: any): any {
  // 기존 코드 그대로
}

겉으로는 TS 파일이 됐지만 타입 경계는 하나도 좁아지지 않았습니다. 이런 PR은 “변환량”은 많아도 신뢰도는 거의 올라가지 않습니다.

noImplicitAny는 새 구멍을 막는 게이트다

noImplicitAny를 켜면 타입스크립트가 추론하지 못한 암묵적 any를 에러로 봅니다.

function handleChange(event) {
  console.log(event.target.value);
}

이 함수의 event는 암묵적 any가 됩니다. 작은 코드에서는 편하지만, 프로젝트가 커지면 any가 타입 시스템의 검문을 우회하는 통로가 됩니다.

function handleChange(event: React.ChangeEvent<HTMLInputElement>) {
  console.log(event.target.value);
}

noImplicitAny를 처음부터 전역으로 켜면 오래된 프로젝트에서는 너무 많은 에러가 날 수 있습니다. 그렇다고 영원히 끄면 새 코드도 계속 구멍을 만듭니다. 현실적인 전략은 단계적 게이트입니다.

새로 작성하는 TS 파일에서는 noImplicitAny를 지킨다. 마이그레이션한 폴더부터 엄격도를 올린다. 임시 any에는 TODO와 제거 기준을 단다. unknown으로 받을 수 있는 외부 값은 any 대신 unknown을 쓴다. @ts-ignore는 사유 없이 늘리지 않는다.

핵심은 “strict를 켰다/안 켰다”가 아니라, 타입 시스템을 우회하는 새 구멍을 더 이상 만들지 않는 것입니다.

AI migration PR을 리뷰하는 기준

AI는 파일 확장자 변경, annotation 추가, import 정리 같은 반복 작업을 잘합니다. 하지만 그럴듯한 migration PR일수록 리뷰 기준이 필요합니다.

좋은 migration은 diff가 큰 PR이 아닙니다. 경계를 하나씩 좁히고, 깨지는 호출 지점을 드러내고, 런타임 동작을 그대로 유지하는 PR입니다.

시리즈를 닫으며

Effective TypeScript 2판을 프론트엔드 코드 리뷰 관점으로 읽으면 결론은 하나로 모입니다.

타입은 런타임을 바꾸지 않는다. 타입은 값의 가능한 집합을 줄인다. 좋은 모델은 불가능한 상태를 표현하지 않는다. 외부 입력은 경계에서 좁혀야 한다. public API 타입은 사용자 경험이다. 마이그레이션은 코드의 신뢰 경계를 조금씩 좁히는 일이다.

JS Quizbook과도 이어집니다. JavaScript 런타임 모델을 모르면 TypeScript migration도 겉만 바뀝니다. this, module, closure, async timing, object reference를 이해해야 타입이 실제 코드 의미와 맞게 붙습니다.

Day 14 타입 리뷰 퀴즈