🛡️ 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)이었다면? -> Undefined 폭탄!
}

안전한 프론트엔드 환경을 구축하려면 타입스크립트에게 "이 값은 확실히 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 (예: "method": "KAKAO" | "method": "CARD") 필드를 추가하여, "식별 가능한 유니언(Discriminated Unions)" 패턴으로 전환한다.

💡 상세 해설:

• 원리 설명: 속성의 유무(in 연산자)로 5개나 되는 타입을 좁히는 것은 유지보수 관점에서 죄악입니다. 각 인터페이스에 고정된 리터럴 문자열 속성(method나 type 등)을 만들고, 이를 기준 삼아 switch나 if 문으로 분기하면 컴파일러가 알아서 타입을 매끈하게 좁혀줍니다.
• 오답 피드백: "영철 님, 나중에 토스페이먼츠가 추가되면 in 연산자 로직을 처음부터 다 뜯어고칠 건가요? 기준점(Tag) 하나만 박아두면 TS가 모든 걸 다 해줍니다."
• 📌 핵심 기억법: 객체의 모양이 3개 이상 달라지기 시작하면, 무조건 명찰(고유한 텍스트 필드) 부터 하나 박고 시작하자!

🐣 영철이의 퇴근 일기

💡 "알 수 없는 에러(unknown)는 TS가 날 괴롭히려는 게 아니라, 세상의 무수한 예외로부터 날 보호해 주는 안전벨트였다."

그동안 catch(error: any)로 편하게 살았던 나날을 사죄합니다... 영숙 님이 왜 그렇게 화를 냈는지 이제 조금 알 것 같다. 내가 any로 마법을 부린답시고 에러 처리를 뭉뚱그려 놓았으니 유저는 바보 같은 팝업만 봐야 했던 거다.
오늘 영호 리드 님이 보여준 '식별 가능한 유니언' 코드는 정말 충격적이었다. 그저 필드 하나에 명찰표 달아줬을 뿐인데, switch 문 안에서 TS가 척척 타입을 알아내서 어시스트를 해주는 걸 보니 전율마저 돌았다.
내일 출근하자마자 결제 모듈 분기문 다 엎고 저걸로 싹 리팩토링해야지. 아, 오늘은 진짜 똑똑해진 기분이다 ㅋㅋㅋ 코딩 존잼!