이펙티브 타입스크립트 2판 Day 5: 타입 추론을 방해하지 않는 API 설계

범위: Effective TypeScript 2판 Item 22–27

오늘의 질문: “if로 한 번 확인한 값은 그 뒤에서도 계속 안전하다고 봐도 될까?”

이 글의 원천 앵커

이 글은 기존 Day 5를 다시 쓴 개정판입니다. 이전 글은 추론/넓히기와 유니온 설계를 너무 짧게 묶어 설명했고, 원래 Day 5 범위인 narrowing, alias, context inference, evolving type, async/type flow가 충분히 살아 있지 않았습니다.

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

TypeScript의 narrowing은 코드 흐름을 따라가지만, 모든 런타임 변화를 대신 보장하지 않는다. alias를 만들면 원래 객체와 좁혀진 값의 관계가 흐려질 수 있다. 문맥 타입이 있으면 콜백과 객체 literal의 타입을 더 잘 추론할 수 있다. evolving type은 편하지만, 빈 배열/중간 변수의 의도가 늦게 드러날 수 있다. await, callback, closure를 지나면 “아까 확인한 값”이 여전히 같은 값인지 다시 봐야 한다.

먼저 보는 코드

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

function renderName(user: User) {
  if (user.profile?.name) {
    return user.profile.name.toUpperCase();
  }
  return "익명";
}

이 코드는 자연스럽습니다. if (user.profile?.name) 안에서는 name이 truthy한 문자열로 좁혀집니다. 하지만 조금만 구조가 바뀌면 narrowing이 기대처럼 유지되지 않을 수 있습니다.

function renderName(user: User) {
  const profile = user.profile;

  if (profile?.name) {
    user.profile = undefined;
    return profile.name.toUpperCase();
  }

  return "익명";
}

여기서는 profile이라는 alias가 기존 객체를 붙잡고 있습니다. user.profile을 바꿔도 profile 변수는 이전 객체를 가리킵니다. 이게 의도라면 괜찮지만, 리뷰어는 “지금 좁힌 값이 무엇이고, 이후에 바뀔 수 있는 값은 무엇인가?”를 봐야 합니다.

narrowing은 값의 흐름을 읽는다

TypeScript는 typeof, in, discriminant field, truthy check, equality check 등을 보고 타입을 좁힙니다.

type Result =
  | { status: "loading" }
  | { status: "error"; message: string }
  | { status: "success"; data: User };

function render(result: Result) {
  if (result.status === "success") {
    return result.data.name;
  }
  if (result.status === "error") {
    return result.message;
  }
  return "로딩 중";
}

이런 코드는 리뷰하기 좋습니다. status 하나가 branch를 나누고, 각 branch에서 필요한 필드가 선명합니다. 반대로 truthy check만으로 도메인 의미를 표현하면 헷갈릴 수 있습니다.

if (user.name) {
  render(user.name);
}

이 코드는 undefined와 빈 문자열을 같이 제외합니다. 빈 문자열이 유효한 이름인지, “이름 없음”인지 도메인 규칙에 따라 판단이 달라집니다. narrowing이 편하다고 해서 도메인 의미까지 자동으로 맞아지는 것은 아닙니다.

alias는 읽기 비용을 만든다

alias 자체가 나쁜 건 아닙니다. 오히려 긴 표현을 줄이고, 한 번 좁힌 값을 안정적으로 잡아둘 수 있습니다.

const name = user.profile?.name;

if (typeof name === "string") {
  return name.toUpperCase();
}

이 코드는 좋습니다. 이후에는 user.profile.name을 다시 따라가지 않고, name이라는 지역 값을 다룹니다.

문제는 alias가 원본 객체와 섞일 때입니다.

const options = props.options;

if (options?.theme) {
  updateProps();
  applyTheme(options.theme);
}

updateProps()가 실제로 props.options를 바꾸는지, options가 이전 객체를 붙잡는지, 둘 중 무엇이 의도인지 읽어야 합니다. React 코드에서는 props/state가 렌더 사이에 새 값으로 들어오고, callback은 이전 render의 값을 닫아둘 수 있습니다. JS Quizbook Day 7의 stale closure와 같은 문제입니다.

리뷰 질문은 이겁니다.

좁힌 값은 지역 primitive인가, 객체 참조인가? 원본 객체를 이후에 다시 읽는가? callback/async 경계를 지나도 같은 값을 기대하는가? alias가 의도를 선명하게 하는가, 원본과 복사본처럼 착각하게 하는가?

문맥 타입은 콜백을 살린다

TypeScript는 값이 놓인 문맥을 보고 타입을 추론합니다.

type ButtonProps = {
  onClick: (event: MouseEvent) => void;
};

const props: ButtonProps = {
  onClick(event) {
    console.log(event.clientX);
  },
};

event에 직접 annotation을 쓰지 않아도 ButtonProps의 문맥 덕분에 MouseEvent로 추론됩니다. 이게 context inference입니다.

프론트엔드에서는 컴포넌트 props, event handler, array method callback, form resolver에서 자주 드러납니다.

const names = users.map((user) => user.name);

users가 User[]라면 user는 자연스럽게 User입니다. 콜백마다 user: User를 반복할 필요가 없습니다. 하지만 문맥이 사라지면 추론도 약해집니다.

const handlers = {
  click(event) {
    console.log(event.clientX);
  },
};

이 객체가 어떤 계약을 만족해야 하는지 없으면 event는 암묵적 any가 될 수 있습니다. 해결은 “모든 콜백에 타입을 쓰자”가 아니라, 객체 전체가 놓인 계약을 알려주는 것입니다.

type Handlers = {
  click: (event: MouseEvent) => void;
};

const handlers: Handlers = {
  click(event) {
    console.log(event.clientX);
  },
};

evolving type은 편하지만 의도가 늦게 보인다

빈 배열에서 시작해 값을 넣으면 TypeScript가 타입을 진화시키는 경우가 있습니다.

const ids = [];
ids.push("a");
ids.push("b");

작은 함수 안에서는 괜찮습니다. 하지만 중간에 조건이 많아지면 “이 배열에는 결국 무엇이 들어가는가?”가 늦게 드러납니다.

const items = [];

if (includeUsers) {
  items.push({ type: "user", id: user.id });
}

if (includeTeams) {
  items.push({ type: "team", id: team.id });
}

이럴 때는 의도를 먼저 세우는 편이 낫습니다.

type SearchItem = { type: "user"; id: string } | { type: "team"; id: string };

const items: SearchItem[] = [];

지역 계산에서는 추론이 좋지만, 도메인 리스트나 공개 반환값에서는 타입을 먼저 잡는 게 리뷰에 유리합니다.

async 경계는 narrowing을 다시 의심하게 만든다

가장 위험한 착각은 “확인했으니까 나중에도 안전하다”입니다.

let currentUser: User | null = null;

async function saveProfile() {
  if (!currentUser) return;

  await saveDraft();
  return currentUser.id;
}

TypeScript가 이 코드를 어떻게 좁히는지와 별개로, 런타임에서는 await saveDraft() 동안 다른 코드가 currentUser = null로 바꿀 수 있습니다. 모듈 스코프 mutable state, React ref, 외부 store를 다룰 때 특히 그렇습니다.

더 안전한 방식은 좁힌 값을 지역 상수로 붙잡는 것입니다.

async function saveProfile() {
  const user = currentUser;
  if (!user) return;

  await saveDraft();
  return user.id;
}

이 코드는 “저장 시작 시점의 user로 처리한다”는 의도를 드러냅니다. 반대로 항상 최신 user가 필요하다면 await 뒤에 다시 읽고 다시 확인해야 합니다.

Item 22–27을 코드 리뷰 언어로 다시 묶기

이번 범위는 각각 따로 보면 작은 팁처럼 보입니다. 그런데 리뷰에서는 하나의 질문으로 합쳐집니다.

이 타입은 어디서 좁혀졌고, 그 좁혀진 사실은 어디까지 믿을 수 있는가?

책의 Item 흐름을 프론트엔드 코드 리뷰 언어로 바꾸면 이렇게 볼 수 있습니다.

예를 들어 이런 helper는 보기에는 깔끔하지만, 타입 정보를 충분히 되돌려주지 않습니다.

type Admin = { role: "admin"; permissions: string[] };
type Member = { role: "member"; teamId: string };
type Account = Admin | Member;

function isAdminLike(account: Account) {
  return account.role === "admin";
}

function render(account: Account) {
  if (isAdminLike(account)) {
    return account.permissions.join(", ");
  }
}

사람은 isAdminLike라는 이름을 보고 admin으로 좁혀졌다고 느낍니다. 하지만 TypeScript 입장에서는 boolean을 돌려주는 함수일 뿐입니다. 이 helper가 타입 흐름의 일부라면 type predicate가 필요합니다.

function isAdmin(account: Account): account is Admin {
  return account.role === "admin";
}

function render(account: Account) {
  if (isAdmin(account)) {
    return account.permissions.join(", ");
  }
}

여기서 중요한 건 “타입 가드를 쓰자”라는 암기가 아닙니다. helper를 만들 때 런타임 판정만 숨길지, 타입 정보까지 호출자에게 돌려줄지 결정해야 한다는 점입니다.

나쁜 narrowing보다 위험한 건 애매한 상태 모델이다

Day 5는 다음 Day 6의 유효 상태 모델링으로 이어집니다. narrowing을 아무리 잘해도 상태 자체가 애매하면 리뷰는 계속 어려워집니다.

type FormState = {
  loading: boolean;
  error?: string;
  data?: User;
};

function renderForm(state: FormState) {
  if (state.loading) return "불러오는 중";
  if (state.error) return state.error;
  if (state.data) return state.data.profile?.name ?? "이름 없음";
  return "대기";
}

이 코드는 narrowing을 쓰지만, 동시에 loading: false, error: "...", data: 가 함께 존재할 수도 있습니다. TypeScript가 각 branch에서 타입을 좁혀도 “이 상태 조합이 가능한가?”라는 질문은 남습니다.

type FormState =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "error"; message: string }
  | { status: "success"; data: User };

이렇게 바꾸면 narrowing이 단순한 방어 코드가 아니라 상태 모델의 결과가 됩니다. Day 5에서 배울 점은 “확인하고 쓰기”이고, Day 6에서 이어질 점은 “확인이 덜 필요한 상태로 설계하기”입니다.

프론트엔드 코드 리뷰 체크리스트

Day 5의 결론은 “타입스크립트의 narrowing을 믿지 말자”가 아닙니다. 오히려 narrowing을 제대로 쓰려면 값의 수명, alias, 문맥, async 경계를 같이 읽어야 한다는 쪽에 가깝습니다.

Day 5 타입 리뷰 퀴즈