핵심 정리

function add(a: number, b: number) {
  return a + b;
}

const total = add(1, 2);
// const broken = add("1", 2);

도입 효과

1) TypeScript는 JavaScript 위의 정적 검사 층이다

TypeScript는 별도 VM이나 새 실행 모델을 도입하지 않습니다. 작성 단계에서 타입 정보를 보고 오류를 잡고, 최종적으로는 JavaScript로 실행됩니다.

const user = { name: "Mina", age: 26 };

function greet(person: { name: string }) {
  return `Hello, ${person.name}`;
}

즉 "TypeScript를 도입한다"는 것은 런타임을 바꾸는 일보다 코드 계약을 더 선명하게 만든다는 뜻에 가깝습니다.

2) 큰 코드베이스일수록 타입이 문서와 검사 역할을 같이 맡는다

함수와 객체가 여러 파일과 팀 사이를 오갈수록 "이 값이 정확히 어떤 모양인가"가 계속 중요해집니다. 타입 선언은 주석이 아니라 호출 계약, 자동완성, 변경 영향 분석을 동시에 담당합니다.

interface User {
  id: string;
  name: string;
  isAdmin: boolean;
}

function renderUser(user: User) {
  return user.name;
}

3) 리팩터링 안정성이 TypeScript의 체감 장점인 경우가 많다

초반에는 문법이 늘어난 것처럼 느껴질 수 있지만, 실제 체감은 "이 이름을 바꿨을 때 어디가 깨지는지"를 빠르게 잡아 주는 데서 많이 옵니다. 특히 prop 구조, API 응답 shape, 함수 시그니처가 자주 변하는 코드에서 차이가 큽니다.

• 함수 인자 이름을 바꾼다
• 객체 필드 구조를 바꾼다
• API 응답 모양이 달라진다

이런 변화가 자주 생기는 코드일수록 "어디가 같이 바뀌어야 하는가"를 빨리 찾는 능력이 중요합니다.

4) 런타임 검증은 여전히 별도로 필요하다

TypeScript는 컴파일 시점 도구이므로, API 응답이나 사용자 입력처럼 런타임에 들어오는 값이 진짜로 맞는지는 따로 확인해야 합니다.

type User = { id: string; name: string };

const raw: unknown = JSON.parse(input);

즉 TypeScript는 "믿을 수 없는 입력"을 자동으로 안전하게 만들어 주는 도구가 아닙니다.

type User = { id: string; name: string };

const raw: unknown = JSON.parse(input);
if (
  typeof raw === "object" &&
  raw !== null &&
  "id" in raw &&
  "name" in raw
) {
  const user = raw as User;
  console.log(user.name);
}

5) 도입 판단은 복잡성보다 변경 비용에서 보는 편이 낫다

작은 스크립트 하나면 JavaScript만으로도 충분할 수 있습니다. 반대로 코드가 오래 살아남고, 여러 사람이 만지고, 구조가 자주 바뀌는 프로젝트라면 TypeScript의 이득이 빠르게 커집니다.

언제 도입할까

TypeScript를 도입할 때 볼 점

• 새 런타임을 도입하는가: 아니다
• 실행 전 설계 오류를 더 빨리 잡는가: 그렇다
• 타입이 문서와 계약 역할을 하는가: 그렇다
• 외부 입력이 자동으로 안전해지는가: 아니다
• 변경이 잦고 협업이 큰가: TypeScript 이점이 커진다

주의할 점

// ❌ JSON.parse 결과를 바로 믿음
const user = JSON.parse(input) as { name: string };
console.log(user.name.toUpperCase());

// ✅ 외부 입력은 unknown으로 보고 런타임 확인을 설계
const raw: unknown = JSON.parse(input);
if (typeof raw === "object" && raw !== null && "name" in raw) {
  console.log(String((raw as { name: unknown }).name).toUpperCase());
}