🛡️ 03. 타입 좁히기(Narrowing): 알 수 없는 에러 객체를 길들이기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분(전체) / 핵심 파트만: 8분

🗺️ 이 문서의 흐름
[무엇이든 될 수 있는 unknown의 공포] → [TS를 납득시키는 4가지 가드(Guard)] → [최종 병기: 식별 가능한 유니언]

🎯 이 문서를 다 읽으면 할 수 있는 것

• try...catch의 error 객체가 왜 자동으로 any나 unknown이 되는지 이해한다.
• typeof, in, instanceof 연산자로 타입을 좁히는 원리(Control Flow Analysis)를 체득한다.
• 영수네 커뮤니티의 복잡한 API 에러를 "식별 가능한 유니언" 패턴으로 완벽하게 분기 처리할 수 있다.

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 🎨 영숙 ( UX 리뷰어 ): "영철 님, 로그인 실패할 때 얼럿 창이 왜 자꾸 [object Object] Error 라고 뜨나요? 비밀번호가 틀린 건지, 계정이 없는 건지 사용자한테 예쁜 메시지로 알려줘야죠!"
• 🐣 영철 ( 런타임 경계를 다루는 중 ): "저도 그러고 싶은데... catch (err)로 떨어지는 이 err 값이 무슨 타입인지 TS가 아예 몰라요. 속성에 접근하려고만 하면 계속 빨간 줄이 떠요."
• 🦁 영호 ( 리드 ): "영철 님, 세상의 모든 예외가 우리가 만든 규칙대로만 터질까요? TS가 unknown으로 막아둔 건 오히려 축복입니다. 이제 이 거친 야생마를 타입 좁히기(Narrowing) 로 조련해 볼 시간입니다."

🤔 왜 알아야 하는가: '모른다'는 것을 인정하기

실무에서 가장 많이 마주하는 두 가지 타입 스크립트 에러 상황이 있습니다.

1. DOM 요소를 찾았는데 그게 null일 수도 있을 때 (obj is possibly 'null')
2. try...catch 블록이나 외부 API에서 알 수 없는 에러가 터졌을 때 (Object is of type 'unknown')

과거의 영철이(그리고 1년 차 시절의 우리)는 이럴 때 일단 as any 나 as MyCustomError를 넣어버리고 퇴근하곤 했습니다.

// 과거의 영철이가 짠 위험한 에러 처리
} catch (err) {
  // TS: "나는 err가 뭔지 올라. string일 수도 있고, Error 객체일 수도 있어!"
  // 🐣 과거의 영철: "백엔드에서 준 MyApiError일 테니 일단 강제하자."
 
  alert((err as MyApiError).message); // NetworkError였다면 message가 없어서 사용자 안내가 깨질 수 있음
}

안전한 프론트엔드 환경을 구축하려면 타입스크립트에게 "이 값은 확실히 OOO야" 라고 증명하는 과정(Control Flow Analysis) 을 밟아야 합니다. 이 증명 과정이 바로 타입 좁히기(Narrowing) 입니다.

🔍 1. 가장 흔한 방패: typeof와 Truthiness

가장 원시적이지만 빈번하게 쓰이는 가드(Guard)입니다. 자바스크립트의 피도 눈물도 없는 런타임 연산자인 typeof를 TS도 똑똑하게 인식합니다.

🐣 영철이의 게시판 ID 파싱기

function printBoardId(id: string | number | null) {
  // 1. Truthiness narrowing: null 제거
  if (!id) {
    console.log("ID가 제공되지 않았습니다.");
    return;
  }
 
  // 이 시점에서 TS는 id가 (string | number) 임을 안다!
 
  // 2. typeof narrowing: string과 number 분리
  if (typeof id === "string") {
    // 여기서 id는 무조건 string!
    console.log(`문자열 ID입니다: ${id.toUpperCase()}`);
  } else {
    // 여기서 id는 무조건 number!
    console.log(`숫자 ID입니다: ${id.toFixed(2)}`);
  }
}

💡 주의할 점: JS의 태생적 한계로 typeof null === "object" 이고, typeof [] === "object" 입니다. 배열이나 커스텀 객체를 구별할 때는 typeof가 전혀 쓸모가 없다는 것을 명심해야 합니다.

🛡️ 2. 객체를 구별하는 두 가지 칼: in 과 instanceof

그럼 영철이의 근본적인 고민, "알 수 없는 에러 객체"는 어떻게 구별할까요? 여기서 in 피연산자와 instanceof가 등판합니다.

케이스 A: instanceof (클래스로 찍어낸 객체일 때)

JS의 내장 Error 클래스나 커스텀 클래스를 구별할 때 강력합니다.

} catch (err) {
  // err는 기본적으로 unknown 타입
 
  if (err instanceof TypeError) {
    console.log("변수 타입 런타임 에러!", err.message);
  } else if (err instanceof Error) {
    console.log("일반적인 JS 에러!", err.message);
  } else {
    // 문자열을 던질 수도, 쌩 객체를 던질 수도 있는 야수 같은 JS의 런타임
    console.log("알 수 없는 예외 발생: ", err);
  }
}

케이스 B: in 연산자 (속성의 존재 유무로 객체 판별)

백엔드에서 오는 JSON 응답 같은 순수 객체(Plain Object)는 클래스가 아닙니다. 이때는 "특정 프로퍼티가 이 객체 안에(in) 있느냐?" 로 좁혀냅니다.

type BackendError = { statusCode: number; developerMessage: string };
type ValidationError = { invalidFields: string[]; userMessage: string };
 
function handleApiError(error: BackendError | ValidationError) {
  // 🦁 영호: "error 안에 'statusCode' 가 존재한다면, 그건 BackendError 야!"
  if ("statusCode" in error) {
    console.log(`서버에서 ${error.statusCode} 에러를 뱉었습니다.`);
  } else {
    // 남은 건 하나뿐이니 여기선 무조건 ValidationError!
    console.log(`입력값이 잘못되었습니다: ${error.invalidFields.join(', ')}`);
  }
}

👑 3. 5년 차의 최종 병기: 식별 가능한 유니언 (Discriminated Unions)

in 연산자도 좋지만, 권한(권한A, 권한B, 권한C...)이나 복잡한 상태(로딩, 성공, 실패)가 3~4개 이상 넘어가면 코드가 굉장히 지저분해집니다.
이럴 때 사용하는 아키텍처 레벨의 패턴이 바로 식별 가능한 유니언(Discriminated Unions, 또는 Tagged Unions) 입니다. 리덕스의 액션 객체나 React의 useReducer가 바로 이 패턴을 씁니다.

영수네 커뮤니티 채팅 상태 관리기

핵심은 공통된 이름의 리터럴 타입(Tag) 을 심어두는 것입니다. 이를 보통 type, kind, status라고 부릅니다.

// 1. 각각의 객체에 'status' 라는 이름표(Tag)를 명확한 리터럴 문자열로 달아줍니다.
interface LoadingState {
  status: "loading"; // 식별자
}
 
interface SuccessState {
  status: "success"; // 식별자
  chatMessages: string[];
}
 
interface ErrorState {
  status: "error"; // 식별자
  errorMessage: string;
}
 
// 2. 이들을 하나의 유니언(Union)으로 묶습니다.
type ChatState = LoadingState | SuccessState | ErrorState;

이제 영철이는 switch 문 하나로 TS를 완벽하게 통제할 수 있습니다.

function renderChatUI(state: ChatState) {
  // 🦁 영호: "TS는 switch 문의 'status'를 보는 순간, 남은 가지치기를 완벽하게 해냅니다."
  switch (state.status) {
    case "loading":
      // state는 LoadingState 로 좁혀짐!
      return `<p>로딩 중...</p>`;
 
    case "success":
      // state는 자동으로 SuccessState 가 되어 chatMessages에 안전하게 접근 가능!
      return `<ul>${state.chatMessages.map(m => `<li>${m}</li>`).join('')}</ul>`;
 
    case "error":
      // state는 자동으로 ErrorState!
      return `<p color="red">${state.errorMessage}</p>`;
 
    default:
      // (보너스) 모든 케이스를 다루었는지 확인하는 Exhaustiveness Check
      // 여기에 도달한다면 우리는 무언가 심각한 실수를 한 것입니다.
      const _exhaustiveCheck: never = state;
      return _exhaustiveCheck;
  }
}

식별 가능한 유니언은 "에러가 나지 않는 우아한 분기 처리"의 상징입니다. 데이터 구조를 설계할 때부터 kind, type 같은 명확한 심볼을 만들어 두는 습관을 들이세요!

📝 마무리 퀴즈

Q1. typeof 연산자를 활용하여 데이터의 타입을 좁힐 때, typeof value === "object"라는 검증 로직이 가진 치명적인 약점은 무엇인가요?

✅ 정답: null이나 배열(Array)도 object로 반환되기 때문에 이들을 일반 객체와 구별할 수 없다는 점입니다.

💡 상세 해설:

• 자바스크립트의 오랜 버그이자 스펙으로, typeof null은 "object"를 반환합니다.
• 따라서 일반적인 객체(Dictionary)인 줄 알고 좁혔다가 TypeError: Cannot read properties of null을 마주하게 됩니다. 객체를 좁힐 때는 반드시 value !== null 같은 Truthiness 검증이 먼저 선행되어야 합니다.

Q2. 순수한 객체(Plain Object) 두 개가 유니언으로 묶여있을 때(type A = { x: number } | { y: string }), 이를 안전하게 구별할 수 있는 연산자는 무엇인가요?

✅ 정답: in 연산자입니다. (예: "x" in obj)

💡 상세 해설:

• 클래스 인스턴스라면 instanceof를 쓰면 되지만, 서버에서 API 응답으로 내려온 JSON 객체는 특정 클래스의 인스턴스가 아니기 때문에 instanceof가 작동하지 않습니다.
• 특정 프로퍼티(x)가 객체 안(in)에 존재하는지를 런타임에 확인함으로써 TS에게 이게 어떤 타입인지 납득시킬 수 있습니다.

Q3. [영철이의 테스트 타임: 아키텍처 설계 딜레마] 영철이가 영수네 쇼핑몰의 결제 수단을 관리하고 있습니다. 카카오페이, 네이버페이, 신용카드 등 5가지 결제 수단이 있고, 각 결제 수단마다 요구하는 데이터 폼(cardNumber vs authUrl 등)이 아예 다릅니다. 이걸 하나의 컴포넌트에서 분기 처리하려는데 영철이는 in 연산자를 5번이나 쓰면서 "이 코드는 스파게티가 되어가고 있어요"라고 호소합니다. 영호 리드라면 어떤 패턴으로 데이터 설계를 리팩토링할까요?

✅ 정답: 모든 결제 타입 객체에 공통된 method 필드를 추가하고, 식별 가능한 유니언(Discriminated Unions)으로 전환한다.

💡 상세 해설:

• 속성의 유무(in 연산자)만으로 5개 타입을 구분하면 새 결제 수단이 추가될 때마다 조건문이 흔들립니다.
• 각 타입에 method: "KAKAO" | "NAVER" | "CARD" 같은 고정 리터럴 필드를 두고 switch (payment.method)로 분기하면, TS가 각 케이스에서 필요한 필드를 정확히 좁혀줍니다.
• 객체의 모양이 여러 갈래로 나뉘기 시작하면, 먼저 공통 식별자(Tag)를 설계하는 것이 유지보수에 유리합니다.

🐣 영철이의 퇴근 일기

오늘은 unknown이 귀찮은 빨간 줄이 아니라 안전한 출발점이라는 걸 배웠다. 예외는 우리가 만든 클래스만 던지는 게 아니고, 네트워크 문제나 브라우저 API처럼 전혀 다른 모양으로도 들어온다.

영숙 님이 말한 "[object Object]" 팝업도 결국 내가 에러를 좁히지 않고 대충 문자열로 밀어낸 결과였다. typeof, in, instanceof로 확인한 뒤 사용자 메시지와 개발자 로그를 나누면 UX도 디버깅도 같이 좋아진다.

💡 "unknown은 막힌 길이 아니라 확인하고 지나가라는 표지판이다. 좁힌 뒤에 접근하면 타입도 사용자 메시지도 함께 선명해진다."

결제 수단 분기에는 method 필드를 먼저 추가해보려고 한다. 조건문을 늘리는 대신 데이터 구조에 식별자를 심으면, 다음 결제 수단이 들어와도 리뷰에서 확인할 지점이 훨씬 분명해질 것 같다.