04 타입 설계

타입 시스템의 큰 장점 중 하나는 데이터 타입을 명확히 알 수 있어 코드를 이해하기 쉽다는 것입니다.

아이템 28 유효한 상태만 표현하는 타입을 지향하기

타입을 잘 설계하면 코드는 직관적으로 작성할 수 있습니다. 그러나 타입 설계가 엉망이라면 어떠한 기억이나 문서도 도움이 되지 못합니다.

효과적으로 타입을 설계하려면, 유효한 상태만 표현할 수 있는 타입을 만들어 내는 것이 가장 중요합니다.

페이지를 선택하면, 페이지의 내용을 로드하고 화면에 표시합니다. 페이지의 상태는 다음처럼 설계했습니다.

interface State {
  pageText: string;
  isLoading: boolean;
  error?: string;
}

페이지를 그리는 renderPage 함수를 작성할 때는 상태 객체의 필드를 전부 고려해서 상태 표시를 분기해야 합니다.

function renderPage(state: State) {
  if (state.error) {
    return `Error! Unable to load ${currentPage}: ${state.error}`;
  } else if (state.isLoading) {
    return `Loading ${currentPage}...`;
  }

  return `<h1>${currentPage}</h1>\n${state.pageText}`;
}

분기 조건이 명확히 분리되어 있지 않다는 것을 알 수 있습니다. isLoading이 true이고 동시에 error 값이 존재하면 로딩 중인 상태인지 오류가 발생한 상태인지 명확히 구분할 수 없습니다. 필요한 정보가 부족하기 때문입니다.

페이지를 전환하는 changePage 함수는 다음과 같습니다.

async function changePage(state: State, newPage: string) {
  state.isLoading = true;
  try {
    const response = await fetch(getUrlForPage(newPage));
    if (!response.ok) {
      throw new Error(`Unable to load ${newPage}: ${response.statusText}`);
    }
    const text = await response.text();
    state.isLoading = false;
    state.pageText = text;
  } catch (e) {
    state.error = "" + e;
  }
}

changePage에는 많은 문제점이 있습니다. 몇 가지 정리해 보면 다음과 같습니다.

• 오류가 발생했을 때 state.isLoading을 false로 설정하는 로직이 빠짐
• state.error를 초기화하지 않았기 때문에, 페이지 전환 중에 로딩 메시지 대신 과거의 오류 메시지를 보여준다.
• 페이지 로딩 중에 사용자가 페이지를 바꿔 버리면 어떤 일이 벌어질지 예상하기 어렵다.

문제는 상태 값의 두 가지 속성이 동사에 정보가 부족하거나, 두 가지 속성이 충돌할 수 있다는 것입니다. State 타입은 isLoading이 true이면서 동시에 error 값이 설정되는 무효한 상태를 허용합니다.

다음은 애플리케이션의 상태를 좀 더 제대로 표현한 방법입니다.

interface RequestPending {
  state: "pending";
}
interface RequestError {
  state: "error";
  error: string;
}
interface RequestSuccess {
  state: "ok";
  pageText: string;
}
type RequestState = RequestPending | RequestError | RequestSuccess;

interface State {
  currentPage: string;
  requests: { [page: string]: RequestState };
}

네트워크 요청 과정 각각의 상태를 명시적으로 모델링하는 유니온을 사용했습니다. 상태를 나타내는 타입의 코드 길이가 서너 배 길어지긴 했지만 무효한 상태를 허용하지 않도록 크게 개선되었습니다. 페이지는 발생하는 모든 요청의 상태로서, 명시적으로 모델링되었습니다. 그 결과로 개선된 renderPage와 changePage 함수는 쉽게 구현할 수 있습니다.

function renderPage(state: State) {
  const { currentPage } = state;
  const requestState = state.requests[currentPage];
  switch (requestState.state) {
    case "pending":
      return `Loading ${currentPage}...`;
    case "error":
      return `Error! Unable to load ${currentPage}: ${requestState.error}`;
    case "ok":
      return `<h1>${currentPage}</h1>\n${requestState.pageText}`;
  }
}

async function changePage(state: State, newPage: string) {
  state.requests[newPage] = { state: "pending" };
  state.currentPage = newPage;
  try {
    const response = await fetch(getUrlForPage(newPage));
    if (!response.ok) {
      throw new Error(`Unable to load ${newPage}: ${response.statusText}`);
    }
    const pageText = await response.text();
    state.requests[newPage] = { state: "ok", pageText };
  } catch (e) {
    state.requests[newPage] = { state: "error", error: "" + e };
  }
}

처음에 등장했던 renderPage와 changePage의 모호함은 완전히 사라졌습니다. 현재 페이지가 무엇인지 명확하며, 모든 요청은 정확히 하나의 상태로 맞아 떨어집니다.

타입을 설계할 때는 어떤 값들을 포함하고 어떤 값들을 제외할지 신중하게 생각해야 합니다. 유효한 상태를 표현하는 값만 허용한다면 코드를 작성하기 쉬워지고 타입 체크가 용이해집니다. 유효한 상태만 허용하는 것은 매우 일반적인 원칙입니다.

요약

• 유효한 상태와 무효한 상태를 둘 다 표현하는 타입은 혼란은 초래하기 쉽고 오류를 유발하게 됩니다.
• 유효한 상태만 표현하는 타입을 지향해야 합니다. 코드가 길어지거나 표현하기 어렵지만 결국은 시간을 절약하고 고통을 줄일 수 있습니다.

아이템 29 사용할 때는 너그럽게, 생성할 때는 엄격하게

함수의 매개변수는 타입의 범위가 넓어도 되지만, 결과를 반환할 때는 일반적으로 타입의 범위가 더 구체적이어야 합니다.

예를 들어 3D 매핑 API는 카메라의 위치를 지정하고 경계 박스의 뷰포트를 계산하는 방법을 제공합니다.

declare function setCamera(camera: CameraOptions): void;
declare function viewportForBounds(bounds: LngLatBounds): CameraOptions;

CameraOptions와 LngLat 타입의 정의는 다음과 같습니다.

interface CameraOptions {
  center?: LngLat;
  zoom?: number;
  bearing?: number;
  pitch?: number;
}
type LngLat =
  | { lng: number; lat: number }
  | { lon: number; lat: number }
  | [number, number];

일부 값은 건드리지 않으면서 동시에 다른 값을 설정할 수 있어야 하므로 CameraOptions의 필드는 모두 선택적입니다. 유사하게 LngLat 타입도 setCamera의 매개변수 범위를 넓혀 줍니다. 이러한 편의성을 제공하여 함수 호출을 쉽게 할 수 있습니다.

viewportForBounds 함수는 또 다른 자유로운 타입을 매개변수로 받습니다.

type LngLatBounds =
  | { northeast: LngLat; southwest: LngLat }
  | [LngLat, LngLat]
  | [number, number, number, number];

이름이 주어진 모서리, 위도/경도 쌍 또는 순서만 맞다면 4-튜플을 사용하여 경계를 지정할 수 있습니다. LngLat는 세 가지 형태를 받을 수 있기에 LngLatBounds의 가능한 형태는 19가지 이상으로 매우 자유로운 타입입니다.

수많은 선택적 속성을 가지는 반환 타입과 유니온 타입은 viewportForBounds를 사용하기 어렵게 만듭니다. 매개변수 타입의 범위가 넓으면 사용하기 펺하지만, 반환 타입의 범위가 넓으면 불편합니다. 즉 사용하기 편리한 API일수록 반환 타입이 엄격합니다.

유니온 타입의 요소별 분기를 위한 한 가지 방법은, 좌표를 위한 기본 형식을 구분하는 것입니다.

interface LngLat {
  lng: number;
  lat: number;
}
type LngLatLike = LngLat | { lon: number; lat: number } | [number, number];

interface Camera {
  center: LngLat;
  zoom: number;
  bearing: number;
  pitch: number;
}
interface CameraOptions extends Omit<Partial<Camera>, "center"> {
  center?: LngLatLike;
}
type LngLatBounds =
  | { northeast: LngLatLike; southwest: LngLatLike }
  | [LngLatLike, LngLatLike]
  | [number, number, number, number];

declare function setCamera(camera: CameraOptions): void;
declare function vewportForBounds(bounds: LngLatBounds): Camera;

Camera가 너무 엄격하므로 조건을 완화하여 느슨한 CameraOptions 타입으로 만들었습니다.

요약

• 보통 매개변수 타입은 반환 타입에 비해 범위가 넓은 경향이 있습니다. 선택적 속성과 유니온 타입은 반환 타입보다 매개변수 타입에 더 일반적입니다.
• 매개변수와 반환 타입의 재사용을 위해서 기본 형태(반환 타입)와 느슨한 형태(매개변수 타입)를 도입하는 것이 좋습니다.

아이템 30 문서에 타입 정보를 쓰지 않기

/**
 * 전경색(forground) 문자열을 반환합니다.
 * 0 개 또는 1 개의 매개변수를 받습니다.
 * 매개변수가 없을 때는 표준 전경색을 반환합니다.
 * 매개변수가 있을 때는 특정 페이지의 전경색을 반환합니다.
 */
function getForgroundColor(page?: string) {
  return page === "login" ? { r: 127, g: 127, b: 127 } : { r: 0, g: 0, b: 0 };
}

함수의 입력과 출력의 타입을 코드로 표현하는 것이 주석보다 더 나은 방법이라는 것은 자명합니다.

그리고 타입 구문은 타입스크립트 컴파일러가 체크해 주기 때문에, 절대로 구현체와의 정합성이 어긋나지 않습니다.

요약

• 주석과 변수명에 타입 정보를 적는 것은 피해야 합니다. 타입 선언이 중복되는 것으로 끝나면 다행이지만 최악의 경우는 타입 정보에 모순이 발생하게 됩니다.
• 타입이 명확하지 않은 경우는 변수명에 단위 정보를 포함하는 것을 고려하는 것이 좋습니다.(예를들어 timeMs 또는 temperatureC)

아이템 31 타입 주변에 null 값 배치하기

값이 전부 null이거나 전부 null이 아닌 경우로 분명히 구분된다면, 값이 섞여 있을 때보다 다루기 쉽습니다. 타입에 null을 추가하는 방식으로 이러한 경우를 모델링할 수 있습니다.

숫자들의 최솟값과 최댓값을 계산하는 extent 함수를 가정해 보겠습니다.

function extent(nums: number[]) {
  let min, max;
  for (const num of nums) {
    if (!min) {
      min = num;
      max = num;
    } else {
      min = Math.min(min, num);
      max = Math.max(max, num);
    }
  }
  return [min, max];
}

이 코드는 타입 체커를 통과하고, 반환 타입은 number[]로 추론됩니다. 그러나 여기에는 버그와 함께 설계적 결함이 있습니다.

• 최솟값이나 최댓값이 0인 경우, 값이 덧씌워져 버립니다. 예를 들어, extent([0, 1, 2])의 결과는 [0, 2]가 아니라 [1, 2]가 됩니다.
• nums 배열이 비어 있다면 함수는 [undefined, undefined]를 반환합니다. undefined를 포함하는 객체는 다루기 어렵고 절대 권장하지 않습니다.

strictNullChecks 설정을 켜면 앞의 두 가지 문제점이 드러납니다.

function extent(nums: number[]) {
  let min, max;
  for (const num of nums) {
    if (!min) {
      min = num;
      max = num;
    } else {
      min = Math.min(min, num);
      max = Math.max(max, num);
      // ~ 'number' | undefined 형식의 인수는 'number' 형식의 매개변수에 할당될 수 없습니다.
    }
  }
  return [min, max];
}

더 나은 해법을 찾아보겠습니다. min과 max를 한 객체 안에 넣고 null이거나 null이 아니게 하면 됩니다.

function extent(nums: number[]) {
  let result: [number, number] | null = null;
  for (const num of nums) {
    if (!result) {
      result = [num, num];
    } else {
      result = [Math.min(num, result[0]), Math.max(num, result[1])];
    }
  }
  return result;
}

반환 타입이 [number, number] | null 이 되어서 사용하기 더 수월해졌습니다. null이 아님 단언(!)을 사용하면 min과 max를 얻을 수 있습니다.

null과 null이 아닌 값을 섞어서 사용하면 클래스에서도 문제가 생깁니다.

class UserPosts {
  user: UserInfo | null;
  posts: Post[] | null;

  constructor() {
    this.user = null;
    this.posts = null;
  }

  async init(userId: string) {
    return Promise.all(][
      async () => this.user = await fetchUser(userId),
      async () => this.posts = await fetchPostsForUser(userId)
    ]);
  }

  getUserName() {
    // ...?
  }
}

속성값의 불확실성이 클래스의 모든 메서드에 나쁜 영향을 미칩니다. 결국 null 체크가 난무하고 버그를 양산하게 됩니다. 설계를 개선해 보겠습니다. 필요한 데이터가 모두 준비된 후에 클래스를 만들도록 바꿔 보겠습니다.

class UserPosts {
  user: UserInfo;
  posts: Post[];

  constructor(user: UserInfo, posts: Post[]) {
    this.user = user;
    this.posts = posts;
  }

  static async init(userId: string): Promise<UserPosts> {
    const [user, posts] = await Promise.all([
      fetchUser(userId),
      fetchPostsForUser(userId),
    ]);
    return new UserPosts(user, posts);
  }

  getUserName() {
    return this.user.name;
  }
}

요약

• 한 값의 null 여부가 다른 값의 null 여부에 암시적으로 관련되도록 설계하면 안 됩니다.
• API 작성 시에는 반환 타입을 큰 객체로 만들고 반환 타입 전체가 null이거나 null이 아니게 만들어야 합니다. 사람과 타입 체커 모두에게 명료한 코드가 될 것입니다.
• 클래스를 만들 때는 필요한 모든 값이 준비되었을 때 생성하여 null이 존재하지 않도록 하는 것이 좋습니다.
• strictNullChecks를 설정하면 코드에 많은 오류가 표시되겠지만, null 값과 관련된 문제점을 찾아낼 수 있기 때문에 반드시 필요합니다.

아이템 32 유니온의 인터페이스보다는 인터페이스의 유니온을 사용하기

유니온 타입의 속성을 가지는 인터페이스를 작성 중이라면, 혹시 인터페이스의 유니온 타입을 사용하는 게 더 알맞는지 검토해 봐야 합니다.

interface Layer {
  layout: FillLayout | LineLayout | PointLayout;
  paint: FillPaint | LinePaint | PointPaint;
}

layout 속성은 모양이 그려지는 방법과 위치를 제어하는 반면, paint 속성은 스타일을 제어합니다. layout이 LineLayout 타입이면서 paint 속성이 FillPaint 타입인 것은 말이 되지 않습니다.

더 나은 방법으로 모델링 하려면 각각 타입의 계층을 분리된 인터페이스로 둬야 합니다.

interface FillLayer {
  layout: FillLayout;
  paint: FillPaint;
}
interface LineLayer {
  layout: LineLayout;
  paint: LinePaint;
}
interface PointLayer {
  layout: PointLayout;
  paint: PointPaint;
}
type Layer = FillLayer | LineLayer | PointLayer;

이런 형태로 Layer를 정의하면 layout과 paint 속성이 잘못된 조합으로 섞이는 경우를 방지할 수 있습니다.

interface FillLayer {
  type: "fill";
  layout: FillLayout;
  paint: FillPaint;
}
interface LineLayer {
  type: "line";
  layout: LineLayout;
  paint: LinePaint;
}
interface PointLayer {
  type: "point";
  layout: PointLayout;
  paint: PointPaint;
}

type 속성은 '태그'이며 런타임에 어떤 타입이 Layer가 사용되는지 판단하는 데 쓰입니다. 어떤 데이터 타입을 태그된 유니온으로 표현할 수 있다면, 보통은 그렇게 하는 것이 좋습니다. 또는 여러 개의 선택적 필드가 동시에 값이 있거나 동시에 undefined인 경우도 태그된 유니온 패턴이 잘 맞습니다.

interface Person {
  name: string;
  // 다음은 둘 다 동시에 있거나 동시에 없습니다.
  placeOfBirth?: string;
  dateOfBirth?: Date;
}

두 개의 속성을 하나의 설계로 모으는 것이 더 나은 설계입니다. 이 방법은 null 값을 경계로 두는 방법과 비슷합니다.

interface Person {
  name: string;
  birth?: {
    place: string;
    date: Date;
  };
}

이제 place만 있고 date가 없는 경우에는 오류가 발생합니다.

Person 객체를 매개변수로 받는 함수는 birth 하나만 체크하면 됩니다.

타입의 구조를 손 댈 수 없는 상황이면, 앞서 다룬 인터페이스의 유니온을 사용해서 속성 사이의 관계를 모델링할 수 있습니다.

interface Name {
  name: string;
}
interface PersonWithBirth extends Name {
  placeOfBirth: string;
  dateOfBirth: Date;
}
type Person = Name | PersonWithBirth;

요약

• 유니온 타입의 속성을 여러 개 가지는 인터페이스에서는 속성 간의 관계가 분명하지 않기 때문에 실수가 자주 발생하므로 주의해야 합니다.
• 유니온의 인터페이스보다 인터페이스의 유니온이 더 정확하고 타입스크립트가 이해하기도 좋습니다.
• 타입스크립트가 제어 흐름을 분석할 수 있도록 타입에 태그를 넣는 것을 고려해야 합니다. 태그된 유니온은 타입스크립트와 매우 잘 맞기 때문에 자주 볼 수 있는 패턴입니다.

아이템 33 string 타입보다 더 구체적인 타입 사용하기

interface Album {
  artist: string;
  title: string;
  releaseDate: string; // YYYY-MM-DD
  recordingType: string; // 'live' 또는 'studio'
}

Album 타입에 엉뚱한 값을 설정할 수 있습니다.

const kindOfBlue: Album = {
  artist: "Miles Davis",
  title: "Kind of Blue",
  releaseDate: "August 17th, 1959",
  recordingType: "Studio",
};

오류를 방지하기 위해 타입의 범위를 좁히는 방법을 생각해봐야 합니다.

type RecordingType = "studio" | "live";

interface Album {
  artist: string;
  title: string;
  releaseDate: Date;
  recordingType: RecordingType;
}

요약

• '문자역을 남발하여 선언된' 코드를 피합시다. 모든 문자열을 할당할 수 있는 string 타입보다는 더 구체적인 타입을 사용하는 것이 좋습니다.
• 변수의 범위를 보다 정확하게 표현하고 싶다면 string 타입보다는 문자열 리터럴 타입의 유니온을 사용하면 됩니다. 타입 체크를 더 엄격히 할 수 있고 생산성을 향상시킬 수 있습니다.
• 객체의 속성 이름을 함수 매개변수로 받을 때는 string보다 keyof T를 사용하는 것이 좋습니다.

아이템 34 부정확한 타입보다는 미완성 타입을 사용하기

타입을 정제(refine)할 때, 불쾌한 골짜기 은유를 생각해보면 도움이 될 수 있습니다. 일반적으로 any 값은 매우 추상적인 타입은 정제하는 것이 좋습니다. 그러나 타입이 구체적으로 정제된다고 해서 정확도가 무조건 올라가지는 않습니다. 타입에 의존하기 시작하면 부정확함으로 인해 발생하는 문제는 더 커질 것입니다.

요약

• 타입 안전성에서 불쾌한 골짜기는 피해야 합니다. 타입이 없는 것보다 잘못된게 더 나쁩니다.
• 정확하게 타입을 모델링할 수 없다면, 부정확하게 모델링하지 말아야 합니다. 또한 any와 unknown를 구별해서 사용해야 합니다.

아이템 35 데이터가 아닌, API와 명세를 보고 타입 만들기

요약

• 코드의 구석 구석까지 타입 안전성을 얻기 위해 API 또는 데이터 형식에 대한 타입 생성을 고려해야 합니다.
• 데이터에 드러나지 않는 예외적인 경우들이 문제가 될 수 있기 때문에 데이터보다는 명세로부터 코드를 생성하는 것이 좋습니다.

아이템 36 해당 분야의 용어로 타입 이름 짓기

컴퓨터 과학에서 어려운 일은 단 두 가지뿐이다. 캐시 무효화와 이름 짓기

• 필 칼튼(Phill Karlton)

동물들의 데이터베이스를 구축한다고 가정해 보겠습니다. 이를 표현하기 위한 인터페이스는 다음과 같습니다.

interface Animal {
  name: string;
  endangered: boolean;
  habitat: string;
}
const leopard: Animal = {
  name: "Snow Leopard",
  endangered: false,
  habitat: "tundra",
};

이 코드에는 네 가지 문제가 있습니다.

• name은 매우 일반적인 용어입니다. 동물의 학명인지 일반적인 명칭인지 알 수 없습니다.
• endangered 속성이 멸종 위기를 표현하기 위해 boolean 타입을 사용한 것이 이상합니다. 이미 멸종된 동물을 true로 해야 하는지 판단할 수 없습니다. endangered 속성의 의도를 '멸종 위기 또는 멸종'으로 생각한 것일지도 모릅니다.
• 서식지를 나타내는 habitat 속성은 너무 범위가 넓은 string 타입일 뿐만 아니라 서식지라는 뜻 자체도 불분명하기 때문에 다른 속성들보다도 훨씬 모호합니다.
• 객체의 변수명이 leopard이지만, name 속성의 값은 'Snow Leopard'입니다. 객체의 이름과 속성의 name이 다른 의도로 사용된 것인지 불분명합니다.

반면, 다음 코드의 타입 선언은 의미가 분명합니다.

interface Animal {
  commonName: string;
  genus: string;
  species: string;
  status: ConservationStatus;
  climates: KoppenClimate[];
}
type ConservationStatus = "EX" | "EW" | "CR" | "EN" | "VU" | "NT";
type KoppenClimate = "Af" | "Am" | "As" | "Aw" | "BSh" | "BSk" | "BWh" | "BWk";

const snowLeopard: Animal = {
  commonName: "Snow Leopard",
  genus: "Panthera",
  species: "Uncia",
  status: "VU", // 취약종(vulnerable)
  climates: ["ET", "EF", "Dfd"], // 고산대(alpine) 또는 아고산대(subalpine)
};

이 코드는 다음 세 가지를 개선했습니다.

• name은 commonName, genus, species 등 더 구체적인 용어로 대체했습니다.
• endangered는 동물 보호 등급에 대한 IUCN의 표준 분류 체계인 ConservatioinStatus 타입의 status로 변경되었습니다.
• habitat은 기후를 뜻하는 climates로 변경되었으며, 쾨펜 기후 분류를 사용합니다.

데이터를 훨씬 명확하게 표현하고 있습니다. 그리고 정보를 찾기 위해 사람에 의존할 필요가 없습니다. 구체적인 의미를 파악하려면 온라인에서 무수히 많은 정보를 파악할 수 있습니다.

코드로 표현하고자 하는 모든 분야에는 주제를 설명하기 위한 전문 용어들이 있습니다. 자체적으로 용어를 만들어 내려고 하지 말고, 해당 분야에 이미 존재하는 용어를 사용해야 합니다.

타입 속성, 변수에 이름을 붙일 때 명심해야 할 세 가지 규칙이 있습니다.

• 동일한 의미를 나타낼 때는 같은 용어를 사용해야 합니다. 동의어를 사용하면 글을 읽을 때는 좋을 수 있지만, 코드에서는 좋지 않습니다. 정말로 의미적으로 구분이 되어야 하는 경우에만 다른 용어를 사용해야 합니다.
• data, info, thing, item, object, entity 같은 모호하고 의미 없는 이름은 피해야 합니다.
• 이름을 지을 떄는 포함된 내용이나 계산 방식이 아니라 데이터 자체가 데이터 자체가 무엇인지를 고려해야 합니다. 예를 들어 INodeList 보다는 Directory가 더 의미있는 이름입니다. 좋은 이름은 추상화의 수준을 높이고 의도치 않은 충돌의 위험성을 줄여 줍니다.

요약

• 가독성을 높이고, 추상화 수준을 올리기 위해서 해당 분야의 용어를 사용해야 합니다.
• 같은 의미에 다른 이름을 붙이면 안 됩니다. 특별한 의미가 있을 때만 용어를 구분해야 합니다.

아이템 37 공식 명칭에는 상표를 붙이기

요약

• 타입스크립트는 구조적 타이핑(덕 타이핑)을 사용하기 때문에, 값을 세밀하게 구분하지 못하는 경우가 있습니다. 값을 구분하기 위해 공식 명칭이 필요하다면 상표를 붙이는 것을 고려해야 합니다.
• 상표 기법은 타입 시스템에서 동작하지만 런타임에 상표를 검사하는 것과 동일한 효과를 얻을 수 있습니다.