본문으로 건너뛰기

TypeScript 노트

TypeScript 노트

TypeScript 5.x 기준

타입 좁히기(narrowing), 제네릭 함정, 유틸리티 타입 활용, `satisfies` 연산자 등 실무 TypeScript 패턴을 정리했다. `any` 없이 안전하게 타입을 다루는 흐름 위주다.

자주 만나는 타입 함정

실무에서 반복되는 TypeScript 에러 패턴

타입 에러 메시지별로 원인과 해결 패턴을 정리했다. 증상이 비슷하면 이 목록을 먼저 확인한다.

trap / 01

`unknown` 타입 narrowing 실패

symptom
`Type 'unknown' is not assignable to type 'string'` — unknown 값을 바로 사용하려다 발생.
fix
`typeof val === 'string'` 또는 사용자 정의 타입 가드(`val is string`)로 좁힌다.
노트 전체 읽기
trap / 02

`any` 전이 문제

symptom
외부 라이브러리에서 `any` 타입이 들어오면 주변 타입이 모두 `any`로 오염된다.
fix
경계에서 `unknown`으로 받고 내부에서 narrowing한다. `as unknown as TargetType` 단언은 최후 수단.
노트 전체 읽기
trap / 03

제네릭 추론 실패

symptom
`Type 'T' does not satisfy the constraint` 또는 추론이 `unknown`으로 떨어지는 현상.
fix
제네릭 파라미터에 명시적 타입을 전달하거나 함수 시그니처의 제약 조건(constraint)을 좁힌다.
노트 전체 읽기
trap / 04

Discriminated union 처리 누락

symptom
switch-case에서 처리되지 않은 case가 생겨도 타입 에러가 나지 않는 경우.
fix
default 절에 `const _exhaustive: never = action` 패턴을 추가해 누락을 컴파일 타임에 잡는다.
노트 전체 읽기
trap / 05

옵셔널 체이닝 타입 확장 누락

symptom
`?.` 연산자 사용 후 반환 타입이 `undefined`를 포함하는데 처리하지 않아 타입 에러 발생.
fix
옵셔널 체이닝 결과에 `?? defaultValue` 또는 명시적 `undefined` 체크를 추가한다.
노트 전체 읽기
trap / 06

인터섹션 타입 충돌

symptom
두 타입을 `&`로 합쳤을 때 동일 프로퍼티의 타입이 `never`가 되어 할당 불가 에러 발생.
fix
겹치는 프로퍼티를 `Omit<A, keyof B> & B` 패턴으로 제거하고 합친다.
노트 전체 읽기

타입 좁히기 흐름

단계별 narrowing 순서

  1. 01

    1. typeof / instanceof 체크

    원시 타입은 `typeof`, 클래스 인스턴스는 `instanceof`로 먼저 좁힌다.

    if (typeof val === 'string') { /* val: string */ }
  2. 02

    2. in 연산자로 프로퍼티 확인

    객체 타입 union에서 특정 프로퍼티 존재 여부로 분기한다.

    if ('message' in err) { /* err has message */ }
  3. 03

    3. 사용자 정의 타입 가드

    위 두 가지로 안 될 때 `val is Type` 반환 타입을 가진 함수를 만든다.

    function isApiError(val: unknown): val is ApiError {
      return typeof val === 'object' && val !== null && 'code' in val;
    }
  4. 04

    4. never로 exhaustive check

    union의 모든 케이스를 처리했는지 컴파일 타임에 확인한다.

    function assertNever(x: never): never {
      throw new Error('Unexpected value: ' + x);
    }

관련 데브로그 글

TypeScript 관련 노트

글 읽기
아직 TypeScript 관련 글이 없다. 데브로그 전체를 확인한다.

TypeScript 자주 묻는 것들

주제별 FAQ

  • 공식 TypeScript Handbook이 가장 정확하다. 이 노트는 거기서 다루지 않는 실무 함정 패턴과 에러 해결 위주다. 기초를 먼저 익히고 오는 것을 권장한다.