DIL: 이펙티브 타입스크립트

스터디: 월간 CS, https://github.com/monthly-cs/2024-05-effective-typescript
작성일: 2024-06-01
작성자: dusunax

---

아이템 35: 데이터가 아닌, API와 명세를 보고 타입 만들기 Avoid Types Based on Anecdotal Data

프로젝트 외부의 타입

• 파일 형식, API, 명세 specification
• 타입을 작성하지 않고 자동 생성 (명세를 참고해서 생성)

예시: DefinitelyTyped에 포함된 타입 정의 파일 사용하기

• 라이브러리: 명세를 기반으로 타입을 작성해서, 현재까지 경험한 데이터 뿐만 아니라 모든 값에 대해 작동한다는 확신을 가질 수 있다.
• API: API 명세로부터 타입을 생성할 수 있다면 그렇게 하기.
• GraphQL
  • 자체적으로 타입이 잘 정의된 API
  • 타입스크립트와 비슷한 타입 시스템 사용. 모든 쿼리와 인터페이스 명세하는 스키마로 이루어짐
  • 특정 쿼리에 타입을 생성할 수 있다. (null 여부 모델링)

// 명시적 차단 + 오류 발생
const { geometry } = f;
if (geometry) {
  if (geometry.type === "GeometryCollection") {
    // 태그된 유니온
    // GeometryCollection를 명시적으로 차단, 에러 throw!
    throw new Error("GeometryCollections are not supported.");
  }
  // 정제된 타입에 한해서 참조를 허용
  helper(geometry.coordinates); // OK
}

// 조건 분기 + 헬퍼 함수 분리
const geometryHelper = (g: Geometry) => {
  if (g.type === "GeometryCollection") {
    g.geometries.forEach(geometryHelper);
  } else {
    helper(g.coordinates); // OK
  }
};

const { geometry } = f;
if (geometry) {
  geometryHelper(geometry);
}

GraphQL

query getLicense($owner:String!, $name:String!){ // GraphQL의 String 타입. nullable이라 null 아님 단언
  repository(owner: $owner, name: $name){
    description
    licenseInfo {
      spdxId
      name
    }
  }
}

Apollo

• graphQL 쿼리를 타입스크립트 타입으로 변환해주는 도구

$ apollo client:codegen \ // Apollo CLI의 코드 생성 명령어
  --endpoint https://api.github.com/graphql \ // endpoint 요기서 스키마를 얻음
  --include license.graphql \ // 타입 생성에 포함할 GraphQL 파일
  --target typescript // TypeScript 타입 정의로 변환

• codegen
  • 쿼리 매개변수와 응답 인터페이스 생성
  • 주석을 JSDoc으로 변환하여 편집기에서 확인할 수 있도록 함

명세 정보나 공식 스키마가 없다면?

• 데이터로부터 타입을 생성해야함
  • quicktype 같은 도구를 사용할 수 있지만, 생성된 타입이 실제 데이터와 일치하지 않을 수 있다.
• 우리는 이미 자동 타입 생성을 사용하고 있다.
  • ex) 브라우저 DOM API 타입
  • 복잡한 시스템을 정확히 모델링하고, 타입스크립트가 오류나 실수를 잡을 수 있도록 하기

아이템 36: 해당 분야의 용어로 타입 이름 짓기 Name Types Using the Language of Your Problem Domain

• (Two Hard Things) There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton

Naming

• 이름 짓기는 타입 설계에서 중요함
  • 의도를 명확히 하고, 추상화 수준을 높인다
• 속성에 대한 의미를 분명하게 하기

// 모호한 타입
interface Animal {
  name: string; // 이름인지 학명인지?
  endangered: boolean; // 멸종 / 멸종 위기 / 멸종 위기 아님
  habitat: string; // 범위가 너무 넓다. 뜻이 모호함
}

// 분명하게 하기
interface Animal {
  commonName: string;
  genus: string;
  species: string;
  status: ConservationStatus;
  climates: KoppenClimate[];
}
type ConservationStatus = "EX" | "EW" | "CR" | "EN" | "VU" | "NT" | "LC";
type KoppenClimate =
  | "Af"
  | "Am"
  | "As"
  | "Aw"
  | "BSh"
  | "BSk"
  | "BWh"
  | "BWk"
  | "Cfa"
  | "Cfb"
  | "Cfc"
  | "Csa"
  | "Csb"
  | "Csc"
  | "Cwa"
  | "Cwb"
  | "Cwc"
  | "Dfa"
  | "Dfb"
  | "Dfc"
  | "Dfd"
  | "Dsa"
  | "Dsb"
  | "Dsc"
  | "Dwa"
  | "Dwb"
  | "Dwc"
  | "Dwd"
  | "EF"
  | "ET";
const snowLeopard: Animal = {
  commonName: "Snow Leopard", // 일반적인 명칭
  genus: "Panthera", // 학명
  species: "Uncia", // 종
  status: "VU", // 동물 보호 등급에 대한 IUGN의 표준 분류 체계인 ConservationStatus 타입 (취약종 Vulnerable)
  climates: ["ET", "EF", "Dfd"], // 쾨펜 기후 분류 (고산대 alpine, 아고산대 subalpine)
};

유념

• 자체적으로 용어를 만들지 말고, 해당 분야에 이미 존재하는 용어를 사용한다
  • 오랫동안 다듬어져 왔으며, 현장에서 사용되고 있음
  • 사용자와의 소통에 유리하고 타입의 명확성을 올릴 수 있다
• 전문 분야의 용어는 정확하게 사용해야 한다.

Todo

• 동일한 의미를 나타낼 때, 같은 용어 사용하기
• 모호하고 의미 없는 이름 피하기
  • ex) data, info, thing, item, object, entity
• 데이터 자체가 무엇인지 고려하기
  • ex) INodeLis가 아니라 Directory. 추상화의 수준 높여서 충돌 위험성 줄이기

Things to Remember

• Reuse names from the domain of your problem where possible to increase the readability and level of abstraction of your code. Make sure you use domain terms accurately.
  • 가독성과 추상화를 높이는 이름을 재사용하고, 도메인의 용어를 정확하게 사용하기
• Avoid using different names for the same thing: make distinctions in names meaningful.
  • 같은 의미에 다른 이름 붙이지 않기. 용어를 구분하기
• Avoid vague names like "Info" or "Entity." Name types for what they are, rather than for their shape.
  • 모호한 이름 붙이지 않기. 데이터 형태보다, 데이터 자체가 무엇인지 고려하기

아이템 37: 공식 명칭에는 상표를 붙이기 Consider Brands for Nominal Typing

• 구조적 타이핑 특성 때문에 코드가 이상한 결과가 나오는 경우가 있다.

interface Vector2D {
  x: number;
  y: number;
}
function calculateNorm(p: Vector2D) {
  return Math.sqrt(p.x ** 2 + p.y ** 2);
}

calculateNorm({ x: 3, y: 4 }); // OK, result is 5
const vec3D = { x: 3, y: 4, z: 1 };
calculateNorm(vec3D); // OK! result is also 5 // 하지만 오류가 나는 것이 수학적으로 이치에 맞다.

명목 타입/공식 명칭 Nominal typing

• 값의 타입이 구조가 아닌 명시적인 선언에 의해 결정되는 시스템
  • 구조적 타이핑(구조에 따라 타입이 결정되는 시스템)과 대조된다.

Branding 상표 기법

• _brand, __brand

예시A: 상표로 타입 정제하기

type AbsolutePath = string & { _brand: "abs" };
function listAbsolutePath(path: AbsolutePath) {
  // ...
}
function isAbsolutePath(path: string): path is AbsolutePath {
  return path.startsWith("/");
}

console.log(isAbsolutePath("order/orderId")); // false
console.log(isAbsolutePath("/order/orderId")); // true

• string이면서 {_brand: 'abs'}를 가지는 객체를 생성할 수는 없다! (완전히 타입 시스템 영역)

function f(path: string) {
  if (isAbsolutePath(path)) {
    // if 체크로 타입을 정제 refine, 단언문을 지양하자
    listAbsolutePath(path); // AbsolutePath
  }
  listAbsolutePath(path); // AbsolutePath 아님
  //               ~~~~ Argument of type 'string' is not assignable to
  //                    parameter of type 'AbsolutePath'
}

예시B

• 목록에서 한 요소를 찾기 위한 이진 검색
  • 목록이 정렬되어야 있어야 한다.

function binarySearch<T>(xs: T[], x: T): boolean {
  let low = 0,
    high = xs.length - 1;
  while (high >= low) {
    const mid = low + Math.floor((high - low) / 2);
    const v = xs[mid];
    if (v === x) return true;
    [low, high] = x > v ? [mid + 1, high] : [low, mid - 1];
  }
  return false;
}

// 정렬된 리스트인지 확인하기 위해 상표 기법을 사용할 것
type SortedList<T> = T[] & { _brand: "sorted" };

function isSorted<T>(xs: T[]): xs is SortedList<T> {
  for (let i = 0; i < xs.length - 1; i++) {
    if (xs[i] > xs[i + 1]) {
      return false;
    }
  }
  return true;
}

function binarySearch<T>(xs: SortedList<T>, x: T): boolean {
  let low = 0,
    high = xs.length - 1;
  while (high >= low) {
    const mid = low + Math.floor((high - low) / 2);
    const v = xs[mid];
    if (v === x) return true;
    [low, high] = x > v ? [mid + 1, high] : [low, mid - 1];
  }
  return false;
}

const array = [2, 0, 5];
isSorted(array) && binarySearch(array, 1);
binarySearch(array, 1); // 오류!

예시C: 상표 붙이기 & 연산 후 사라지는 경우(숫자)

• number 타입에 상표를 붙여도, 산술 연산 후 상표가 없어지기 때문에 사용하기 무리가 있다.
  • 하지만 혼합된 많은 수의 number가 있을 때는, 단위를 문서화하기 위해 사용할 수 있음

type Meters = number & { _brand: "meters" }; // numbe인데 _brand가 "meters"
type Seconds = number & { _brand: "seconds" }; // numbe인데 _brand가 "seconds"

const meters = (m: number) => m as Meters;
const seconds = (s: number) => s as Seconds;

const oneKm = meters(1000);
//    ^? const oneKm: Meters
const oneMin = seconds(60);
//    ^? const oneMin: Seconds

const tenKm = oneKm * 10;
//    ^? const tenKm: number
const v = oneKm / oneMin; // 타입 없어짐
//    ^? const v: number

브랜딩의 다양한 기법

object types

type UserID = { value: number; __brand: "UserID" };
type OrderID = { value: number; __brand: "OrderID" };

function createUserID(value: number): UserID {
  return { value, __brand: "UserID" };
}

function createOrderID(value: number): OrderID {
  return { value, __brand: "OrderID" };
}

const userID: UserID = createUserID(1);
const orderID: OrderID = createOrderID(2);

// 타입 오류: UserID와 OrderID는 서로 호환되지 않습니다.
const anotherOrderID: OrderID = userID;

문자열 기반 열거형 string-based enums

enum Brand {
  UserID = "UserID",
  OrderID = "OrderID",
}

type UserID = { value: number; brand: Brand.UserID };
type OrderID = { value: number; brand: Brand.OrderID };

function createUserID(value: number): UserID {
  return { value, brand: Brand.UserID };
}

function createOrderID(value: number): OrderID {
  return { value, brand: Brand.OrderID };
}

const userID: UserID = createUserID(1);
const orderID: OrderID = createOrderID(2);

// 타입 오류: UserID와 OrderID는 서로 호환되지 않습니다.
const anotherOrderID: OrderID = userID;

private fields

class UserID {
  private __brand: "UserID" = "UserID"; // 클래스의 프라이빗 필드 사용
  constructor(public value: number) {}
}
class OrderID {
  private __brand: "OrderID" = "OrderID";
  constructor(public value: number) {}
}

const userID = new UserID(1);
const orderID = new OrderID(2);

// 타입 오류: UserID와 OrderID는 서로 호환되지 않습니다.
const anotherOrderID: OrderID = userID; // 프라이빗 필드가 없으면 오류가 발생하지 않음

unique symbols

class UserID {
  private __brand: "UserID" = "UserID";
  constructor(public value: number) {}
}

class OrderID {
  private __brand: "OrderID" = "OrderID";
  constructor(public value: number) {}
}

const userID = new UserID(1);
const orderID = new OrderID(2);

// 타입 오류: UserID와 OrderID는 서로 호환되지 않습니다.
const anotherOrderID: OrderID = userID;

Things to Remember

• With nominal typing, a value has a type because you say it has a type, not because it has the same shape as that type.
  • 명목 타입 > 실제 값을 가지고 있기 때문이 아니라, 해당 타입이라고 했기 때문에 그 타입
  • 구조적 타이핑 <-> 명목 타입
• Consider attaching brands to distinguish primitive and object types that are semantically distinct but structurally identical.
  • 원시형이나 오브젝트 타입이 의미가 다르지만 구조가 동일한 경우, 브랜딩을 고려하자.
  • 타입스크립트는 구조적 타이핑을 사용하기 때문에, 값을 세밀하게 구분하지 못하는 점
  • 타입 시스템에서 동작하지만 런타임에 상표를 검사하는 것과 동일한 효과를 얻을 수 있다.
• Be familiar with the various techniques for branding: properties on object types, string-based enums, private fields, and unique symbols.
  • 브랜딩의 다양한 기법을 알아두기