Effective typescript

Chapter 1: Getting to Know TypeScript

TypeScript는 JavaScript로 컴파일되는 언어다. 실행되는 것은 TypeScript가 아니라 컴파일된 JavaScript이므로, TypeScript와 JavaScript의 관계를 정확히 이해하는 것이 숙련된 사용의 출발점이다.

Item 1: TypeScript와 JavaScript의 관계 이해하기

TypeScript는 JavaScript의 상위집합(Superset)

• 문법적으로 유효한 모든 JavaScript 프로그램은 TypeScript 프로그램이기도 하다
• 역은 성립하지 않음: TypeScript에는 JavaScript에 없는 타입 애너테이션 문법이 존재한다
• .js 파일을 .ts로 이름만 바꾸어도 유효한 TypeScript가 된다
• 이 점이 점진적 마이그레이션을 가능하게 하는 TypeScript의 핵심 강점이다

function greet(who: string) {
  console.log('Hello', who);
}
// : string 은 TypeScript 전용 문법 → Node.js 에서 직접 실행 불가

타입 애너테이션 없이도 오류 감지

let city = 'new york city';
console.log(city.toUppercase());
//               ~~~~~~~~~~~ Property 'toUppercase' does not exist on type 'string'.
//                           Did you mean 'toUpperCase'?

• TypeScript는 city의 타입을 초기값에서 추론하여 오탈자를 잡아낸다
• 타입 추론(Type Inference)은 TypeScript의 핵심 기능 중 하나다

타입 애너테이션이 더 정확한 오류를 만든다

interface State {
  name: string;
  capital: string; // 'a' 로 spelling
}

const states: State[] = [
  { name: 'Alabama', capitol: 'Montgomery' },
  //                 ~~~~~~~
  // Object literal may only specify known properties,
  // but 'capitol' does not exist in type 'State'.
  // Did you mean to write 'capital'?
];

• 타입 정보 없이는 TypeScript가 “어느 쪽이 맞는 철자인지” 알 수 없어 잘못된 수정 제안을 할 수 있다
• 의도를 명시(타입 선언)할수록 TypeScript가 더 정확한 오류를 잡는다

TypeScript 타입 시스템의 한계: 완전한 건전성(Soundness) 없음

const names = ['Alice', 'Bob'];
console.log(names.toUpperCase());
// 타입 오류는 없지만 런타임에 TypeError 발생!

• TypeScript의 정적 타입과 런타임 실제 타입이 달라질 수 있다
• TypeScript 타입 시스템은 의도적으로 완전 건전하지 않도록 설계되어 있다
• JavaScript의 유연한 런타임 동작을 모델링하는 것이 목표이기 때문이다

핵심 정리

• 모든 JavaScript는 TypeScript이지만, 모든 TypeScript가 JavaScript는 아니다
• TypeScript는 런타임 예외를 일으킬 코드를 정적으로 탐지하려 한다
• 타입 검사를 통과해도 런타임 오류가 발생할 수 있다
• TypeScript는 일부 유효하지만 의심스러운 JavaScript 구문(인자 수 불일치 등)을 허용하지 않는다

Item 2: 사용 중인 TypeScript 옵션 파악하기

TypeScript 컴파일러 옵션이 다르면 동일한 코드도 완전히 다르게 동작한다.

tsconfig.json 사용 권장

{
  "compilerOptions": {
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

• 커맨드라인 플래그(tsc --noImplicitAny)보다 tsconfig.json을 사용할 것
• 팀원과 도구 모두 동일한 설정을 공유하기 위해 필요하다
• tsc --init으로 기본 설정 파일을 생성할 수 있다

noImplicitAny: 암묵적 any 차단

// noImplicitAny: off 일 때 → 정상 통과 (any로 추론됨)
function add(a, b) {
  return a + b;
}
// 에디터에서 hover하면: function add(a: any, b: any): any

// noImplicitAny: on 일 때 → 오류 발생
function add(a, b) {
  //         ~    Parameter 'a' implicitly has an 'any' type
  //            ~ Parameter 'b' implicitly has an 'any' type
  return a + b;
}

// 수정 방법: 명시적 타입 선언
function add(a: number, b: number) {
  return a + b;
}

• 신규 프로젝트는 반드시 noImplicitAny를 켜고 시작할 것
• JavaScript → TypeScript 마이그레이션 중에만 임시로 끌 수 있다

strictNullChecks: null/undefined를 별도 타입으로 취급

// strictNullChecks: off 일 때
const x: number = null; // OK

// strictNullChecks: on 일 때
const x: number = null;
//    ~ Type 'null' is not assignable to type 'number'

// null을 허용하려면 명시
const x: number | null = null; // OK

• null/undefined 관련 런타임 오류(“undefined is not an object”)를 방지하는 핵심 옵션이다
• 신규 프로젝트에서 TypeScript를 써본 경험이 있다면 반드시 켜야 한다
• noImplicitAny보다 나중에 켜도 된다

strict 모드와 추가 옵션들

• strict를 켜면 noImplicitAny, strictNullChecks 외 여러 검사 옵션이 한번에 활성화된다
• tsc --init으로 생성한 프로젝트는 기본적으로 strict 모드다
• noUncheckedIndexedAccess: 배열/객체 인덱스 접근 결과를 T | undefined로 취급 (strict보다 엄격)

const tenses = ['past', 'present', 'future'];
tenses.toUpperCase();
// noUncheckedIndexedAccess 시: Object is possibly 'undefined'.

핵심 정리

• TypeScript 컴파일러 옵션은 언어의 핵심 동작에 영향을 준다
• tsconfig.json으로 설정을 관리하라
• JavaScript 마이그레이션 중이 아니라면 noImplicitAny를 켜라
• strictNullChecks로 null/undefined 관련 런타임 오류를 예방하라
• 궁극적으로 strict를 목표로 해야 한다

Item 3: 코드 생성은 타입과 독립적임을 이해하기

tsc(TypeScript 컴파일러)는 두 가지 독립적인 일을 한다:

1. TypeScript/최신 JavaScript → 구버전 JavaScript로 트랜스파일
2. 타입 오류 검사

이 두 동작은 완전히 독립적이다. 타입이 런타임 코드에 영향을 줄 수 없다.

런타임에 TypeScript 타입을 체크할 수 없다

interface Square { width: number; }
interface Rectangle extends Square { height: number; }
type Shape = Square | Rectangle;

function calculateArea(shape: Shape) {
  if (shape instanceof Rectangle) {
    //                 ~~~~~~~~~ 'Rectangle' only refers to a type,
    //                           but is being used as a value here
    return shape.height * shape.width;
  }
}

• interface와 type은 컴파일 시 **완전히 제거(erasable)**된다
• instanceof는 런타임 연산자 → 타입이 아닌 값(생성자 함수)에만 사용 가능

해결책 1: 프로퍼티 존재 확인(속성 체크)

function calculateArea(shape: Shape) {
  if ('height' in shape) {
    return shape.width * shape.height;
    //     ^? (parameter) shape: Rectangle
  } else {
    return shape.width * shape.width;
  }
}

해결책 2: 태그드 유니온(Tagged/Discriminated Union)

interface Square {
  kind: 'square';
  width: number;
}
interface Rectangle {
  kind: 'rectangle';
  height: number;
  width: number;
}
type Shape = Square | Rectangle;

function calculateArea(shape: Shape) {
  if (shape.kind === 'rectangle') {
    return shape.width * shape.height;
    //     ^? (parameter) shape: Rectangle
  } else {
    return shape.width * shape.width;
    //     ^? (parameter) shape: Square
  }
}

• kind 같은 태그 프로퍼티를 통해 런타임에도 타입 정보를 복원할 수 있다
• 태그드 유니온(= 판별 유니온, Discriminated Union)은 TypeScript에서 매우 흔한 패턴이다

해결책 3: class 사용 (타입 + 값 동시 도입)

class Square {
  constructor(public width: number) {}
}
class Rectangle extends Square {
  constructor(width: number, public height: number) { super(width); }
}
type Shape = Square | Rectangle;

function calculateArea(shape: Shape) {
  if (shape instanceof Rectangle) {  // OK! class는 런타임에 값(생성자)으로 존재
    return shape.width * shape.height;
  } else {
    return shape.width * shape.width;
  }
}

• class는 타입과 값을 동시에 도입한다
• interface는 타입만 도입한다

타입 오류가 있어도 출력이 생성된다

$ cat test.ts
let x = 'hello';
x = 1234;

$ tsc test.ts
test.ts:2:1 - error TS2322: Type '1234' is not assignable to type 'string'

$ cat test.js
var x = 'hello';
x = 1234;
# 오류가 있어도 JS 파일이 생성됨!

• TypeScript 오류는 C/Java의 컴파일 오류가 아니라 경고에 가깝다
• 오류 시 출력을 막으려면 noEmitOnError 옵션을 사용하라
• “TypeScript가 컴파일 안 된다”는 표현은 기술적으로 틀렸다; 정확한 표현은 **“타입 체크에 실패한다”**이다

타입 연산은 런타임 값에 영향을 주지 못한다

function asNumber(val: number | string): number {
  return val as number; // 타입 단언은 런타임에서 아무 변환도 안 함!
}

// 컴파일된 JS:
function asNumber(val) {
  return val; // 그냥 그대로 반환
}

// 실제로 변환하려면:
function asNumber(val: number | string): number {
  return Number(val); // 런타임 JavaScript 변환 필요
}

런타임 타입은 선언 타입과 다를 수 있다

interface LightApiResponse {
  lightSwitchValue: boolean;
}
async function setLight() {
  const result: LightApiResponse = await response.json();
  setLightSwitch(result.lightSwitchValue);
  // API가 실제로 string을 반환하면? 런타임에 예상치 못한 동작 발생!
}

TypeScript 타입 기반 함수 오버로딩은 불가 (단, 타입 레벨 오버로드는 가능)

// 구현 중복 오류 발생:
function add(a: number, b: number) { return a + b; } // ~~~ Duplicate
function add(a: string, b: string) { return a + b; } // ~~~ Duplicate

// 올바른 방법: 타입 시그니처는 여러 개, 구현은 하나
function add(a: number, b: number): number;
function add(a: string, b: string): string;
function add(a: any, b: any) {
  return a + b;
}
const three = add(1, 2);   // ^? const three: number
const twelve = add('1', '2'); // ^? const twelve: string

핵심 정리

• TypeScript 타입은 런타임 동작에 영향을 줄 수 없다
• 타입 오류가 있어도 코드(“컴파일”)가 생성된다
• 런타임에 타입 정보가 필요하다면 태그드 유니온, 속성 체크 등을 사용하라
• class는 타입과 런타임 값 모두를 도입한다
• TypeScript 타입은 런타임 성능에 영향을 주지 않는다 (zero cost)

Item 4: 구조적 타이핑(Structural Typing)에 익숙해지기

JavaScript는 덕 타이핑(Duck Typing) 기반이다: 올바른 프로퍼티를 갖고 있으면 그 타입으로 사용할 수 있다. TypeScript는 이를 **구조적 타입 시스템(Structural Type System)**으로 모델링한다.

구조가 호환되면 할당 가능하다

interface Vector2D {
  x: number;
  y: number;
}

function calculateLength(v: Vector2D) {
  return Math.sqrt(v.x ** 2 + v.y ** 2);
}

interface NamedVector {
  name: string;
  x: number;
  y: number;
}

const v: NamedVector = { x: 3, y: 4, name: 'Pythagoras' };
calculateLength(v);  // OK! Vector2D와 구조가 호환됨

• NamedVector와 Vector2D 사이에 명시적 관계 선언 없이도 호환된다

구조적 타이핑의 함정

interface Vector3D {
  x: number;
  y: number;
  z: number;
}

function normalize(v: Vector3D) {
  const length = calculateLength(v); // Vector2D를 기대하는 함수에 Vector3D 전달 → 오류 없음!
  return { x: v.x / length, y: v.y / length, z: v.z / length };
}

normalize({ x: 3, y: 4, z: 5 });
// 결과: { x: 0.6, y: 0.8, z: 1 } → 길이가 1.4로 잘못됨!

• TypeScript 타입은 “열린(open)” 타입이다 — 선언한 프로퍼티 외에 추가 프로퍼티가 있어도 할당 가능
• “봉인된(sealed/closed)” 타입은 TypeScript의 타입 시스템으로 표현 불가능

Object.keys 루프의 타입 오류

function calculateLengthL1(v: Vector3D) {
  let length = 0;
  for (const axis of Object.keys(v)) {
    const coord = v[axis];
    //            ~~~~~~~ Element implicitly has an 'any' type
    length += Math.abs(coord);
  }
  return length;
}
// v가 { x, y, z, address: '123 Broadway' } 같이 추가 프로퍼티를 가질 수 있으므로
// axis의 타입은 string이 될 수밖에 없고, v[axis]는 항상 number라고 보장할 수 없다

// 더 나은 구현:
function calculateLengthL1(v: Vector3D) {
  return Math.abs(v.x) + Math.abs(v.y) + Math.abs(v.z);
}

클래스도 구조적으로 비교된다

class SmallNumContainer {
  num: number;
  constructor(num: number) {
    if (num < 0 || num >= 10) throw new Error('Out of range');
    this.num = num;
  }
}

const b: SmallNumContainer = { num: 2024 };  // OK! (구조가 맞으면 할당 가능)
// 생성자의 유효성 검사 로직이 실행되지 않음!

구조적 타이핑의 장점: 테스트 용이성

interface DB {
  runQuery: (sql: string) => any[];
}

function getAuthors(database: DB): Author[] {
  const rows = database.runQuery('SELECT first, last FROM authors');
  return rows.map(row => ({ first: row, last: row }));
}

// 테스트 시 PostgresDB 전체를 모킹할 필요 없이 인라인 객체로 대체 가능:
test('getAuthors', () => {
  const authors = getAuthors({
    runQuery(sql: string) {
      return [['Toni', 'Morrison'], ['Maya', 'Angelou']];
    }
  });
  expect(authors).toEqual([
    { first: 'Toni', last: 'Morrison' },
    { first: 'Maya', last: 'Angelou' }
  ]);
});

• PostgresDB가 implements DB를 선언하지 않아도 구조가 맞으면 전달 가능하다
• 인터페이스로 추상화하면 구체 구현(PostgresDB)에 대한 의존 없이 테스트 가능하다

핵심 정리

• TypeScript의 타입은 “열려(open)” 있다: 인터페이스에 명시된 것 이상의 프로퍼티를 가질 수 있다
• 클래스도 구조적 타이핑을 따른다 — 예상한 클래스 인스턴스가 아닐 수 있다
• 구조적 타이핑을 활용하면 단위 테스트 작성이 훨씬 쉬워진다

Item 5: any 타입의 사용 제한하기

TypeScript의 타입 시스템은 **점진적(gradual)**이고 **선택적(optional)**이다. any는 이를 가능하게 하는 핵심이지만, 그 위험성을 반드시 알고 사용해야 한다.

any의 위험성 1: 타입 안전성 없음

let ageInYears: number;
ageInYears = '12' as any; // 타입 체커가 통과시킴
ageInYears += 1;
// 런타임: "121" (number가 아닌 string!)

any의 위험성 2: 함수 계약 파기

function calculateAge(birthDate: Date): number {
  // ...
}

let birthDate: any = '1990-01-19'; // string인데 any로 선언
calculateAge(birthDate); // OK → 하지만 런타임 오류 가능

any의 위험성 3: 언어 서비스 비활성화

interface Person {
  first: string;
  last: string;
}

const formatName = (p: Person) => `${p.first} ${p.last}`;
//   → p.first, p.last에 대해 자동완성, 리네임 등 언어 서비스 완전 지원

const formatNameAny = (p: any) => `${p.first} ${p.last}`;
//   → 자동완성 없음, 리네임해도 반영 안 됨, 타입 체커 도움 없음

• any는 자동완성, 심볼 리네임, 타입 추론 등 에디터 언어 서비스를 모두 잃게 만든다

any의 위험성 4: 타입 정의를 감추고 리팩터링 시 버그를 만든다

interface ComponentProps {
  onSelectItem: (item: any) => void; // any 사용
}

• item의 타입이 바뀌어도 TypeScript가 알려주지 못한다
• 올바른 타입을 지정했다면 리팩터링 시 관련된 모든 곳에서 오류를 잡을 수 있다

any는 타입 설계를 감춘다

• 프로그램의 타입들을 잘 정의하는 것은 협업과 유지보수성의 핵심이다
• any를 남용하면 그 설계가 감춰지고 문서로서의 코드 가치가 사라진다

핵심 정리

• any는 TypeScript를 사실상 disable한다
• any에는 타입 안전성이 없다
• any를 사용하면 함수의 타입 계약을 파기할 수 있다
• any 심볼에는 언어 서비스가 동작하지 않는다
• any는 리팩터링 시 버그를 감춘다
• any는 타입 시스템의 신뢰도를 떨어뜨린다

Chapter 2: TypeScript’s Type System

TypeScript의 타입 시스템은 매우 강력하고 표현력이 높다. 이 챕터는 타입 시스템의 기계적 원리를 깊이 이해하는 데 집중한다.

Item 6: 에디터로 타입 시스템 탐구하기

TypeScript를 설치하면 두 가지 실행 파일이 생긴다:

• tsc: TypeScript 컴파일러
• tsserver: TypeScript 언어 서버 (에디터에 언어 서비스를 제공)

에디터는 타입 시스템을 탐구하는 최고의 도구다.

에디터로 할 수 있는 일들

• 심볼에 호버: TypeScript가 추론한 타입을 즉시 확인
• 함수에 호버: 추론된 반환 타입 확인
• 조건문 내 변수에 호버: 타입 내로잉(narrowing) 과정 확인

function foo(value: string | string[]) {
  if (Array.isArray(value)) {
    value;
    // ^? (parameter) value: string[]
  } else {
    value;
    // ^? (parameter) value: string
  }
}

• 메서드 체인 중간 타입 확인: 제네릭 타입의 흐름을 추적
• 타입 오류 통해 타입 시스템 학습: 직접 오류를 마주하며 언어 특성 이해

에디터 오류 예시: null 처리

function getElement(elOrId: string | HTMLElement | null): HTMLElement {
  if (typeof elOrId === 'object') {
    return elOrId;
    // ~~~ Type 'HTMLElement | null' is not assignable to type 'HTMLElement'
    // 이유: typeof null === 'object' 이므로 null이 걸러지지 않음!
  } else if (elOrId === null) {
    return document.body;
  }
  return document.getElementById(elOrId)!;
}

• typeof null === 'object' 라는 JavaScript 특성을 에디터 오류를 통해 배울 수 있다

핵심 정리

• 에디터를 통해 TypeScript가 어떤 타입을 추론하는지 항상 확인하라
• 에디터의 타입 표시를 보면서 widening, narrowing에 대한 직관을 키워라
• 타입 오류는 언어를 배우는 도구이기도 하다

Item 7: 타입을 값의 집합으로 생각하기

TypeScript에서 타입은 **가능한 값의 집합(domain)**이다. 이 관점으로 타입 연산의 의미가 분명해진다.

타입 계층: 집합 크기 기준

const x: never = 12; // ~ Type 'number' is not assignable to type 'never'.

type A = 'A';
type B = 'B';
type AB = 'A' | 'B';
type AB12 = 'A' | 'B' | 12;

const a: AB = 'A';   // OK
const c: AB = 'C';   // ~ Type '"C"' is not assignable to type 'AB'

assignable의 의미: 부분집합

• 값과 타입의 관계 → “값이 타입의 멤버인가?”
• 타입과 타입의 관계 → “한 타입이 다른 타입의 부분집합인가?”

const ab: AB = Math.random() < 0.5 ? 'A' : 'B'; // OK: {'A','B'} ⊆ {'A','B'}
const ab12: AB12 = ab;  // OK: {'A','B'} ⊆ {'A','B',12}

declare let twelve: AB12;
const back: AB = twelve;
// ~~~~ Type 'AB12' is not assignable to type 'AB'
// 이유: {12}가 {'A','B'}의 부분집합이 아님

교차(intersection)와 유니온(union)의 직관

interface Person { name: string; }
interface Lifespan { birth: Date; death?: Date; }
type PersonSpan = Person & Lifespan;

// PersonSpan에 속하는 값은 name과 birth를 모두 가져야 함
const ps: PersonSpan = {
  name: 'Alan Turing',
  birth: new Date('1912/06/23'),
  death: new Date('1954/06/07'),
};  // OK

핵심 인사이트: A & B의 값은 A의 프로퍼티와 B의 프로퍼티를 모두 가진다. 반면 A | B의 keyof는 두 타입 모두에 확실히 존재하는 키만 포함한다.

type K = keyof (Person | Lifespan);
//   ^? type K = never
// 이유: Person | Lifespan의 값에 확실히 있는 키가 없음

// 공식 관계:
// keyof (A & B) = (keyof A) | (keyof B)
// keyof (A | B) = (keyof A) & (keyof B)

extends는 “부분집합”

interface Person { name: string; }
interface PersonSpan extends Person {
  birth: Date;
  death?: Date;
}
// PersonSpan의 모든 값은 Person의 부분집합
// (PersonSpan이 더 좁은 집합)

• extends로 필드를 좁혀서(더 구체화해서) 재정의할 수 있다

interface NullyStudent {
  name: string;
  ageYears: number | null;
}
interface Student extends NullyStudent {
  ageYears: number; // number | null → number로 좁힘: OK!
}

interface StringyStudent extends NullyStudent {
  //      ~~~~~~~~~~~~~~
  ageYears: number | string; // number | null → number | string로 확장: 오류!
}

핵심 정리

• TypeScript 타입은 값의 집합(domain)이다
• never는 공집합, 리터럴 타입은 단원소 집합, unknown은 전체집합
• A & B 타입의 값은 A와 B 양쪽의 프로퍼티를 가진다
• A | B 타입에 대해 keyof하면 공통 키만 남는다 (never가 될 수도 있음)
• extends와 assignable은 “부분집합”을 의미한다

Item 8: 심볼이 타입 공간인지 값 공간인지 구분하기

TypeScript에는 **타입 공간(type space)**과 **값 공간(value space)**이 공존한다. 같은 이름이 두 공간에 각각 존재할 수 있다.

두 공간의 기본 구조

// 타입 공간의 심볼 (컴파일 후 사라짐)
interface Cylinder {
  radius: number;
  height: number;
}

// 값 공간의 심볼 (컴파일 후 남음)
const Cylinder = (radius: number, height: number) => ({ radius, height });

• 같은 이름 Cylinder가 서로 다른 공간에 존재하며 아무 관계도 없다
• instanceof Cylinder는 값(함수)을 체크하므로 타입 Cylinder가 아닌 함수 Cylinder를 참조한다

공간 판별 방법

flowchart TD
    A[심볼 위치] --> B{type / interface 선언 내?}
    B -->|Yes| C[타입 공간]
    B -->|No| D{const / let / var 선언?}
    D -->|Yes| E[값 공간]
    D -->|No| F{: 다음 or as 다음?}
    F -->|Yes| C
    F -->|No| G{= 다음?}
    G -->|Yes| E

interface Person { first: string; last: string; }
const jane: Person = { first: 'Jane', last: 'Jacobs' };
//    값공간  타입공간  값공간

같은 연산자, 다른 의미

type T1 = typeof jane;    // Person (TypeScript 타입)
const v1 = typeof jane;   // "object" (런타임 문자열)

type T2 = typeof email;   // (to: Person, subject: string, ...) => Response
const v2 = typeof email;  // "function" (런타임 문자열)

인덱스 접근도 다르다

const first: Person['first'] = jane['first']; // jane.first도 가능
//    값 공간              타입 공간
// Person['first']는 타입 (string)
// jane['first']는 값 ('Jane')

type PersonEl = Person['first' | 'last'];
//   ^? type PersonEl = string

type Tuple = [string, number, Date];
type TupleEl = Tuple[number];
//   ^? type TupleEl = string | number | Date

class와 enum은 양쪽 공간 모두 도입

class Cylinder {
  constructor(public radius: number, public height: number) {}
}

// 타입 공간: shape 타입으로 사용 가능
// 값 공간: instanceof 연산자로 사용 가능
function calculateVolume(shape: unknown) {
  if (shape instanceof Cylinder) {
    shape;
    // ^? (parameter) shape: Cylinder
    shape.radius;
    // ^? (property) Cylinder.radius: number
  }
}

구조 분해 시 타입/값 혼동 주의

// 잘못된 예: to, subject, body를 변수명으로 해석함
function email({
  to: Person,       // 'Person'이라는 변수를 만들려 함 → 오류
  subject: string,  // 'string'이라는 변수를 만들려 함 → 오류
  body: string
}) { /* ... */ }

// 올바른 예: 타입과 구조분해를 분리
function email(
  { to, subject, body }: { to: Person; subject: string; body: string }
) { /* ... */ }

핵심 정리

• TypeScript에는 타입 공간과 값 공간이 공존한다; 에디터와 TypeScript playground로 감각을 익혀라
• 모든 값은 정적 타입을 가지지만 타입 공간의 구성체는 런타임에 존재하지 않는다
• class, enum은 타입과 값 모두를 도입한다
• typeof, this, extends 등 많은 연산자와 키워드가 공간에 따라 다른 의미를 가진다

Item 9: 타입 단언보다 타입 애너테이션을 선호하기

TypeScript에서 변수에 타입을 부여하는 두 가지 방법:

interface Person { name: string; }

const alice: Person = { name: 'Alice' };  // 타입 애너테이션 (Type Annotation)
const bob = { name: 'Bob' } as Person;    // 타입 단언 (Type Assertion)

차이: 안전성 체크 여부

// 타입 애너테이션: 값이 타입에 맞는지 검증
const alice: Person = {};
// ~~~~~ Property 'name' is missing in type '{}' but required in type 'Person'

// 타입 단언: 체커를 침묵시킴 — 개발자가 "내가 더 잘 안다"고 선언
const bob = {} as Person; // No error

// 잉여 프로퍼티 체크도 단언은 무시함
const alice: Person = {
  name: 'Alice',
  occupation: 'TypeScript developer'
  // ~~~~~~~~~ Object literal may only specify known properties...
};

const bob = {
  name: 'Bob',
  occupation: 'JavaScript developer'
} as Person; // No error

화살표 함수에서의 타입 애너테이션

// 단언 방법 (권장하지 않음):
const people = ['alice', 'bob', 'jan'].map(name => ({ name } as Person));

// 반환 타입을 직접 지정하는 방법 (권장):
const people = ['alice', 'bob', 'jan'].map(
  (name): Person => ({ name })
); // Type is Person[]

// 외부 타입으로 체크하는 방법도 가능:
const people: Person[] = ['alice', 'bob', 'jan'].map(name => ({ name }));

주의: (name): Person은 “name의 타입을 추론하고 반환 타입을 Person으로 지정”하는 것이다. (name: Person)은 “name의 타입이 Person”이라는 전혀 다른 의미다.

타입 단언이 적합한 경우

개발자가 TypeScript보다 더 많은 컨텍스트 정보를 갖고 있을 때:

document.querySelector('#myButton')?.addEventListener('click', e => {
  e.currentTarget
  // ^? (property) Event.currentTarget: EventTarget | null
  // 우리는 #myButton이 button 요소임을 알고 있음
  const button = e.currentTarget as HTMLButtonElement;
  //    ^? const button: HTMLButtonElement
});

non-null 단언

const el = document.getElementById('foo'); // HTMLElement | null
const el2 = document.getElementById('foo')!; // HTMLElement (null 아님을 단언)

• !를 접미사로 붙이면 해당 값이 null/undefined가 아님을 단언한다
• 단언이 틀리면 런타임 오류 발생 → 값이 null일 수 없다는 확신이 있을 때만 사용

as는 관련 없는 타입 간에는 사용 불가

const el = document.getElementById('foo') as Person;
// ~~~ Conversion of type 'HTMLElement | null' to type 'Person' may be a mistake
// 두 타입이 서로 겹치는 부분이 없음

• HTMLElement와 Person은 공통 프로퍼티가 없어 단언 불가
• 우회 방법: unknown을 중간에 삽입 (as unknown as Person) — 하지만 이는 매우 위험한 패턴이다

핵심 정리

• 타입 단언보다 타입 애너테이션을 선호하라
• 화살표 함수의 추론 타입이 의도와 다를 때는 반환 타입을 명시하라
• 타입 단언은 TypeScript보다 개발자가 더 많은 정보를 가질 때만 사용하라
• non-null 단언(!)은 null이 아님을 확신할 때만 사용하라

Item 10: 객체 래퍼 타입 피하기 (String, Number, Boolean, Symbol, BigInt)

JavaScript의 원시 타입에는 원시값과 객체 래퍼가 각각 존재한다.

원시값과 래퍼의 차이

// 원시 string 타입
const s: string = 'hello';

// String 객체 래퍼 (대문자)
const S: String = new String('hello');

typeof 'hello'        // "string"
typeof new String()   // "object"

'hello' === new String('hello') // false!

• 원시값에서 메서드를 호출하면('hello'.toUpperCase()) JavaScript가 자동으로 래퍼 객체로 변환 후 메서드를 호출하고 다시 버린다

TypeScript에서 래퍼 타입 사용의 문제

function getStringLen(foo: String) {
  return foo.length;
}

getStringLen('hello');       // OK (string → String 자동 변환)
getStringLen(new String('hello')); // OK

// 반대는 안 됨!
function isGreeting(phrase: String) {
  return ['hello', 'good day'].includes(phrase);
  //                                    ~~~~~~
  // Argument of type 'String' is not assignable to parameter of type 'string'
}

• string은 String에 할당 가능하지만, String은 string에 할당 불가
• 항상 소문자 원시 타입(string, number, boolean)을 사용할 것

주의: 일부 래퍼는 new 없이 사용 가능

const bigInt = BigInt(1234n);  // OK, BigInt()는 new 없이 사용
const sym = Symbol('sym');     // OK, Symbol()도 new 없이 사용

• String(), Number(), Boolean()을 new 없이 호출하면 원시값으로 변환하는 함수로 동작한다
• TypeScript에서 Symbol, BigInt에 대한 타입으로 대문자 버전을 사용할 수도 있지만, 소문자를 쓰는 것이 더 안전하다

핵심 정리

• 타입 애너테이션에는 항상 소문자 원시 타입(string, number, boolean)을 사용하라
• 대문자 래퍼 타입(String, Number, Boolean)은 거의 사용할 일이 없다

Item 11: 잉여 프로퍼티 체크와 타입 체크를 구분하기

구조적 타이핑(Item 4)에 따르면, 추가 프로퍼티가 있는 객체는 더 좁은 타입에 할당 가능해야 한다. 그러나 TypeScript는 객체 리터럴을 직접 변수에 대입하거나 함수에 전달할 때 추가 검사를 수행한다 — 이것이 **잉여 프로퍼티 체크(Excess Property Checking)**다.

잉여 프로퍼티 체크가 발동하는 경우

interface Room {
  numDoors: number;
  ceilingHeightFt: number;
}

const r: Room = {
  numDoors: 1,
  ceilingHeightFt: 10,
  elephant: 'present',
  // ~~~~~~~ Object literal may only specify known properties,
  //         and 'elephant' does not exist in type 'Room'
};

잉여 프로퍼티 체크가 발동하지 않는 경우 (임시 변수 경유)

const obj = {
  numDoors: 1,
  ceilingHeightFt: 10,
  elephant: 'present',  // 오류 없음!
};
const r: Room = obj;  // OK — 구조적 타이핑으로만 체크됨

• 객체 리터럴을 직접 타입이 지정된 변수에 할당할 때만 잉여 프로퍼티 체크가 발동한다
• 임시 변수를 거치면 잉여 프로퍼티 체크는 우회되고 구조적 타이핑만 적용된다

함수 인자에서도 동일하게 동작

function setDarkMode(options: { title: string; darkMode?: boolean }) {
  // ...
}

setDarkMode({ title: 'TypeScript', darkMode: true });       // OK
setDarkMode({ title: 'TypeScript', darkmode: true });       // 오류! (darkmode ≠ darkMode)
// ~~~~~~~ Object literal may only specify known properties

const options = { title: 'TypeScript', darkmode: true };
setDarkMode(options); // OK! 잉여 프로퍼티 체크 우회

잉여 프로퍼티 체크의 한계

• 약한(weak) 타입에도 유사한 검사가 적용된다: 모든 프로퍼티가 선택적인 타입
• 타입 단언(as)을 사용하면 잉여 프로퍼티 체크가 적용되지 않는다

const r: Room = {
  numDoors: 1,
  ceilingHeightFt: 10,
  elephant: 'present',
} as Room; // No error (타입 단언 → 잉여 프로퍼티 체크 비활성)

핵심 정리

• 잉여 프로퍼티 체크는 구조적 타이핑과는 별개의 추가 검사다
• 객체 리터럴을 직접 할당할 때만 발동한다; 임시 변수를 경유하면 우회된다
• 타입 단언이나 인덱스 시그니처를 사용하면 비활성화된다

Item 12: 함수 표현식 전체에 타입 적용하기

TypeScript에서 함수는 두 가지 방식으로 선언할 수 있다:

// 함수 문(Function Statement)
function rollDice1(sides: number): number { /* ... */ }

// 함수 표현식(Function Expression)
const rollDice2 = function(sides: number): number { /* ... */ };
const rollDice3 = (sides: number): number => { /* ... */ };

함수 타입을 전체에 적용하면 중복을 줄일 수 있다

type BinaryFn = (a: number, b: number) => number;

const add: BinaryFn = (a, b) => a + b;
const sub: BinaryFn = (a, b) => a - b;
const mul: BinaryFn = (a, b) => a * b;
const div: BinaryFn = (a, b) => a / b;
// a, b 파라미터 타입을 반복하지 않아도 됨

• 파라미터 타입을 반복하지 않아도 되므로 DRY 원칙 적용 가능
• 함수 구현에 실수가 있으면 오류가 한 곳에서만 발생

기존 함수의 타입 재사용: typeof fn

async function checkedFetch(input: RequestInfo, init?: RequestInit): Promise<Response> {
  const response = await fetch(input, init);
  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }
  return response;
}

// typeof 로 fetch의 타입을 그대로 가져와 사용:
const checkedFetch: typeof fetch = async (input, init) => {
  const response = await fetch(input, init);
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response;
};

• typeof fetch를 사용하면 fetch 시그니처가 바뀌어도 타입이 자동으로 동기화된다
• 타입이 파라미터에서 추론되므로 파라미터 타입을 따로 선언할 필요가 없다

라이브러리의 함수 타입 재사용

// MouseEventHandler 같은 라이브러리 타입을 직접 활용
const handleClick: MouseEventHandler = (e) => {
  // e의 타입이 자동으로 MouseEvent로 추론됨
};

핵심 정리

• 파라미터 타입과 반환 타입을 반복하는 대신, 함수 전체에 타입을 적용하라
• 같은 시그니처를 가진 여러 함수가 있다면 함수 타입을 정의해서 공유하라
• 다른 함수의 시그니처를 따르려면 typeof fn을 활용하라

Item 13: type과 interface의 차이 알기

TypeScript에서 타입을 이름짓는 두 가지 방법:

type TState = { name: string; capital: string; };
interface IState { name: string; capital: string; }

공통점

• 인덱스 시그니처, 함수 타입, 제네릭, 확장(extends/&), 클래스 구현 모두 가능
• 대부분 상황에서 서로 대체 가능

interface에서만 가능한 것: 선언 병합(Declaration Merging)

interface IState { name: string; capital: string; }
interface IState { population: number; }

const wyoming: IState = {
  name: 'Wyoming',
  capital: 'Cheyenne',
  population: 578_000,
}; // OK — 두 선언이 합쳐짐

• 라이브러리의 타입을 **보강(augment)**할 때 유용하다
• 하지만 일반 코드에서 같은 이름을 두 번 선언하면 의도치 않은 병합이 발생할 수 있다

type에서만 가능한 것들

// 1. 유니온 타입
type StringOrNumber = string | number;

// 2. 튜플 타입 (더 깔끔한 문법)
type Pair = [number, number];
type StringList = string[];
type NamedNums = [string, ...number[]];

// 3. 매핑된 타입, 조건부 타입 등 복잡한 타입 연산
type Readonly<T> = { readonly [K in keyof T]: T[K]; };

• interface로도 튜플을 흉내낼 수 있지만 length 등의 메서드가 없어서 불완전하다

언제 무엇을 쓸까?

• 기본 원칙: 가능하면 interface를 사용하고, 유니온 타입이나 복잡한 타입 연산이 필요하면 type을 사용
• 라이브러리 공개 API: interface 선호 (사용자가 선언 병합으로 확장 가능)
• 프로젝트 내부 타입: 둘 중 하나로 일관성 있게 사용하면 됨
• 이름에 I/T 접두사는 비권장 (IState, TState처럼 쓰지 말 것 — 안티패턴)

핵심 정리

• type과 interface의 차이를 알고, 각 상황에 맞는 것을 선택하라
• interface는 선언 병합이 가능하다
• type은 유니온, 튜플, 복잡한 타입 연산에서 더 유연하다
• 프로젝트 내에서 일관된 스타일을 유지하라

Item 14: 변이(Mutation)와 관련된 오류를 방지하기 위해 readonly 사용하기

readonly는 프로퍼티나 배열이 수정되지 않아야 함을 타입 시스템으로 강제한다.

배열의 readonly

function arraySum(arr: readonly number[]) {
  let sum = 0, num;
  while ((num = arr.pop()) !== undefined) {
    //             ~~~ Property 'pop' does not exist on type 'readonly number[]'
    sum += num;
  }
  return sum;
}

• readonly number[]는 number[]의 메서드 중 배열을 변경하는 것들(push, pop 등)을 제거한 타입이다
• number[]는 readonly number[]에 할당 가능하지만, 역은 불가

const a: number[] = [1, 2, 3];
const b: readonly number[] = a;  // OK
const c: number[] = b;
//    ~ Type 'readonly number[]' is not assignable to type 'number[]'

readonly와 const의 차이

const arr = [1, 2, 3]; // arr 변수 자체를 재할당 불가, 하지만 내부 변경은 가능
arr.push(4); // OK!

const readonlyArr: readonly number[] = [1, 2, 3];
readonlyArr.push(4); // 오류!

• const: 변수 바인딩이 변경 불가 (재할당 불가)
• readonly: 객체/배열의 내부 값 변경 불가

객체의 readonly 프로퍼티

interface Outer {
  inner: {
    x: number;
  }
}
const o: Readonly<Outer> = { inner: { x: 0 }};
o.inner = { x: 1 }; // 오류! inner 자체를 바꿀 수 없음
o.inner.x = 1;       // OK! 얕은(shallow) readonly → inner 안의 값은 변경 가능

주의: readonly와 Readonly<T>는 얕은(shallow) 불변성만 보장한다. 깊은 불변성을 원한다면 별도 라이브러리(예: ts-essentials의 DeepReadonly)가 필요하다.

함수 파라미터에 readonly 적용 → 의도 명확화

function printTriangles(n: number) {
  const nums: number[] = [];
  for (let i = 0; i <= n; i++) {
    nums.push(i);
    console.log(arraySum(nums)); // arraySum이 nums를 변경한다면 버그!
  }
}

// arraySum을 readonly로 선언하면 내부 변경 의도가 없음을 명시하고
// 실수로 변경 시 컴파일 오류로 잡을 수 있다
function arraySum(arr: readonly number[]) {
  let sum = 0;
  for (const num of arr) sum += num;
  return sum;
}

핵심 정리

• 함수가 파라미터를 변경하지 않는다면 readonly로 선언하라
• readonly는 타입 오류를 더 명확하게 만들고, 코드의 의도를 문서화한다
• readonly는 얕은 불변성만 보장한다
• const와 readonly의 차이: const는 바인딩, readonly는 내부 값

Item 15: 타입 연산과 제네릭으로 반복 줄이기

DRY(Don’t Repeat Yourself) 원칙은 타입에도 동일하게 적용된다.

타입 반복 줄이기: typeof로 값에서 타입 추출

const INIT_OPTIONS = {
  width: 640,
  height: 480,
  color: '#00FF00',
  label: 'VGA',
};

// 위 값의 구조를 수동으로 중복 선언하지 말고:
type Options = typeof INIT_OPTIONS;
//   ^? type Options = { width: number; height: number; color: string; label: string; }

함수 반환 타입 추출: ReturnType

function getUserInfo(userId: string) {
  return { userId, name, age };
}

type UserInfo = ReturnType<typeof getUserInfo>;
// 함수 시그니처가 바뀌어도 UserInfo가 자동으로 동기화됨

extends로 인터페이스 필드 재사용

interface Person { firstName: string; lastName: string; }
interface PersonWithBirthDate extends Person { birth: Date; }
// Person의 필드를 반복하지 않아도 됨

인덱싱으로 타입 참조

interface State {
  userId: string;
  pageTitle: string;
  recentFiles: string[];
  pageContents: string;
}

// 일부 필드를 갖는 타입 정의 시 직접 참조:
type TopNavState = {
  userId: State['userId'];
  pageTitle: State['pageTitle'];
  recentFiles: State['recentFiles'];
};

매핑된 타입(Mapped Types)으로 더 간결하게

// Pick 유틸리티 타입
type TopNavState = Pick<State, 'userId' | 'pageTitle' | 'recentFiles'>;

Partial을 활용한 업데이트 파라미터

interface Options {
  width: number;
  height: number;
  color: string;
  label?: string;
}

// OptionsUpdate 직접 만들기 (매핑된 타입)
type OptionsUpdate = { [k in keyof Options]?: Options[k] };
// 또는 표준 라이브러리 사용:
class UIWidget {
  constructor(init: Options) { /* ... */ }
  update(options: Partial<Options>) { /* ... */ }
}

키 이름 변환: as 절 활용 (매핑된 타입)

interface ShortToLong {
  q: 'search';
  n: 'numberOfResults';
}
type LongToShort = { [k in keyof ShortToLong as ShortToLong[k]]: k };
//   ^? type LongToShort = { search: "q"; numberOfResults: "n"; }

keyof 관계

type OptionsKeys = keyof Options;
//   ^? type OptionsKeys = "width" | "height" | "color" | "label"

동형(Homomorphic) 매핑된 타입

• K in keyof T 형태의 매핑된 타입은 readonly, ? 수식어와 JSDoc을 원본 타입에서 복사해온다
• Pick, Partial 등의 표준 유틸리티 타입은 모두 동형이다

interface Customer {
  /** 고객 호칭 */
  title?: string;
  /** 시스템에 등록된 전체 이름 */
  readonly name: string;
}

type PickTitle = Pick<Customer, 'title'>;
//   ^? type PickTitle = { title?: string }  → optional 수식어 보존됨

type PickName = Pick<Customer, 'name'>;
//   ^? type PickName = { readonly name: string }  → readonly 보존됨

추상화 주의: 잘못된 DRY

// 나쁜 예: id와 name이 우연히 같은 타입일 뿐, 의미상 같은 것이 아님
interface Product { id: number; name: string; priceDollars: number; }
interface Customer { id: number; name: string; address: string; }

// 이런 추상화는 하지 말 것:
interface NamedAndIdentified { id: number; name: string; }

• 타입이 구조적으로 같더라도 의미가 다르면 공통 기반 타입을 추출하는 것은 조기 추상화가 될 수 있다
• 이름짓기 어려운 타입은 유용하지 않은 추상화일 가능성이 높다

핵심 정리

• DRY 원칙은 타입에도 적용된다
• 타입 이름을 직접 짓는 대신 반복을 피하라; extends로 인터페이스 필드를 재사용하라
• Partial, Readonly, Pick, Record 같은 표준 유틸리티 타입을 활용하라
• 함수의 반환 타입을 이름 짓고 싶다면 ReturnType을 사용하라
• 잘 네이밍되지 않는 타입 추상화는 오히려 코드를 경직시킬 수 있다

Item 16: 인덱스 시그니처보다 더 정밀한 대안 선호하기

인덱스 시그니처의 문제점

type Rocket = { [property: string]: string };
const rocket: Rocket = {
  name: 'Falcon 9',
  variant: 'v1.0',
  thrust: '4,940 kN',
};  // OK

// 문제들:
// 1. 빈 객체도 허용: {}도 Rocket 타입
// 2. 어떤 key도 허용: rocket['notExist']가 string | undefined가 아닌 string으로 추론됨
// 3. 특정 키만 허용 불가: 'name', 'variant', 'thrust' 외에도 모두 허용됨
// 4. 값의 타입이 달라질 수 없음: 모든 값이 string이어야 함

대안 1: 정확히 알고 있다면 interface 사용

interface Rocket {
  name: string;
  variant: string;
  thrust_kN: number;
}
const falconHeavy: Rocket = {
  name: 'Falcon Heavy',
  variant: 'v1',
  thrust_kN: 15_200
};

대안 2: 런타임에 키를 알 수 없는 경우 → Record 또는 Map 사용

// 키와 값의 타입만 알고 실제 키가 몇 개인지 모를 때
type WordCounts = Record<string, number>;

// 또는 특정 키 집합을 유니온으로 제한:
type RGB = Record<'red' | 'green' | 'blue', number>;

대안 3: 키 타입을 유니온으로 제한

// 특정 key들만 허용하고 싶다면
type Vec3D = { [k in 'x' | 'y' | 'z']: number };
// type Vec3D = { x: number; y: number; z: number; } 와 동일

// 키에 따라 값 타입이 달라진다면 (매핑된 타입 + 조건부 타입)
type ABC = { [k in 'a' | 'b' | 'c']: k extends 'b' ? string : number };
// ^? type ABC = { a: number; b: string; c: number; }

핵심 정리

• 인덱스 시그니처는 런타임까지 키를 알 수 없을 때만 사용하라
• 가능하다면 interface, Record, 또는 매핑된 타입 같은 더 정밀한 대안을 사용하라

Item 17: 숫자형 인덱스 시그니처 피하기

JavaScript에서 객체의 키는 **항상 문자열(또는 Symbol)**이다. 숫자로 인덱싱하면 JavaScript가 자동으로 문자열로 변환한다.

const xs = [1, 2, 3];
xs          // 1
xs['0']        // 1 — 같은 결과!
Object.keys(xs) // ['0', '1', '2'] — 문자열로 반환!

TypeScript에서 배열 타입과 숫자 인덱스

TypeScript는 배열 인덱싱에 number 타입을 요구한다:

const xs = [1, 2, 3];
const x0 = xs;    // OK
const x1 = xs['1'];  // ~ Element implicitly has an 'any' type

• 이는 TypeScript가 만든 편의상의 픽션이다; 실제 런타임에서는 문자열로 변환된다
• for...in 루프로 배열을 순회하면 키가 문자열로 나온다

숫자형 인덱스 시그니처의 혼란

function get<T>(array: T[], k: string): T {
  return array[k];
  //           ~ Element implicitly has an 'any' type because
  //             index expression is not of type 'number'
}

권장 대안

// Array, 튜플, ArrayLike 등을 사용하라
// 숫자 인덱스만 필요하고 push 등의 메서드가 필요 없다면:
function checkedAccess<T>(xs: ArrayLike<T>, i: number): T {
  if (i < 0 || i >= xs.length) {
    throw new Error(`Attempt to access ${i} which is past end of array.`);
  }
  return xs[i];
}

배열 순회 방법 선택

const xs = [1, 2, 3];

// 인덱스가 필요 없다면:
for (const x of xs) { /* x는 number */ }

// 인덱스와 값이 모두 필요하다면:
xs.forEach((x, i) => { /* x는 number, i는 number */ });

// 인덱스로 중간에 루프를 멈춰야 한다면:
for (let i = 0; i < xs.length; i++) { /* i는 number, xs[i]는 number */ }

// 피할 것: for...in (인덱스가 string으로 나옴)
for (const k in xs) {
  // k의 타입은 string!
}

핵심 정리

• JavaScript(따라서 TypeScript도)의 배열은 사실 객체이며 키는 문자열이다
• TypeScript에서 숫자형 인덱스는 편의상 제공되는 픽션이다
• 배열 순회에는 for...of, forEach, 또는 for 루프를 사용하라; for...in은 피하라
• 인덱스 타입에 숫자를 넣는 시그니처가 필요하다면 ArrayLike를 고려하라

Chapter 3: 타입 추론과 제어 흐름 분석

TypeScript는 강력한 타입 추론 시스템을 갖추고 있다. 숙련된 개발자는 타입 어노테이션을 적게 쓰되 효과적으로 사용하며, 초보자는 불필요한 어노테이션으로 코드를 도배하는 경향이 있다. 변수는 코드의 “위치”에 따라 다른 타입을 가질 수 있으며, 이 변화 과정을 제어 흐름 분석(control flow analysis) 이라 한다.

Item 18: 추론 가능한 타입에 어노테이션을 남발하지 말라

핵심 원칙: TypeScript가 이미 알고 있는 타입을 다시 명시하는 것은 소음(noise)이다.

• 불필요한 어노테이션의 예:

// 나쁜 예
let x: number = 12;

// 좋은 예
let x = 12; // TypeScript가 number로 추론

• 객체나 배열도 마찬가지로 타입 추론이 잘 동작한다:

// 불필요하게 장황한 버전
const person: { name: string; born: { where: string; when: string } } = {
  name: 'Sojourner Truth',
  born: { where: 'Swartekill, NY', when: 'c.1797' },
};

// 충분한 버전 - TypeScript가 동일하게 추론
const person = {
  name: 'Sojourner Truth',
  born: { where: 'Swartekill, NY', when: 'c.1797' },
};

• 타입 추론이 리팩토링을 쉽게 만든다. Product.id 타입을 number에서 string으로 바꿀 때, 함수 본체에 명시적 어노테이션이 없으면 변경 없이 통과한다:

// id 타입이 string으로 변경되어도 에러 없음
function logProduct(product: Product) {
  const { id, name, price } = product; // 타입 추론에 맡김
  console.log(id, name, price);
}

어노테이션이 여전히 필요한 경우:

• 함수/메서드 파라미터 (기본값이 있는 경우 제외)
• 객체 리터럴 정의 시: 초과 프로퍼티 검사(excess property check)를 활성화하고, 에러 위치를 정의 지점에 고정한다

const elmo: Product = {
  name: 'Tickle Me Elmo',
  id: '048188 627152',
  price: 28.99,
};

• 함수 반환 타입: 다음 중 하나라도 해당하면 명시한다
  • 여러 return 구문이 있는 경우
  • 공개 API의 일부인 경우
  • 명명된 반환 타입을 사용하고 싶은 경우

실수 방지 예시: getQuote 함수에 Promise<number> 반환 타입을 명시하면, 캐시에서 number를 직접 반환하는 실수를 함수 내부에서 잡아낼 수 있다. 명시하지 않으면 에러가 호출 지점에서 터진다.

기억할 것:

• 이상적인 TypeScript 코드: 함수/메서드 시그니처에는 타입 어노테이션, 본체의 지역 변수에는 타입 어노테이션 없음
• linter 규칙 no-inferrable-types(typescript-eslint)를 사용하면 불필요한 어노테이션을 자동으로 잡아낼 수 있다

Item 19: 다른 타입에는 다른 변수를 사용하라

핵심 통찰: 변수의 값은 바뀔 수 있지만 타입은 일반적으로 바뀌지 않는다.

// 자바스크립트에서는 가능하지만 TypeScript에서는 에러
let productId = '12-34-56';
fetchProduct(productId);
productId = 123456; // Error: Type 'number' is not assignable to type 'string'
fetchProductBySerialNumber(productId);

• string | number 유니온으로 해결할 수 있지만, 더 좋은 해결책은 별도 변수를 사용하는 것이다:

const productId = '12-34-56';
fetchProduct(productId);

const serial = 123456;
fetchProductBySerialNumber(serial);

별도 변수를 사용했을 때의 이점:

• 두 개의 관련 없는 개념(ID, 시리얼 번호)을 분리
• 더 구체적인 변수명 사용 가능
• 타입 추론 개선, 어노테이션 불필요
• 더 단순한 타입(string, number) 사용
• const로 선언 가능 → 타입 체커와 사람 모두 추론이 쉬워짐

섀도잉(shadowing)과의 구분: 블록 스코프로 같은 이름을 재사용하는 것은 TypeScript는 괜찮지만 사람이 혼란스러워진다. no-shadow linter 규칙으로 금지하는 팀이 많다.

기억할 것: 타입이 바뀌는 변수를 피하라. 다른 개념에 다른 이름을 사용하면 코드가 명확해진다. let보다 const를 훨씬 많이 사용해야 한다.

Item 20: 변수가 타입을 얻는 방식을 이해하라

TypeScript가 리터럴 값에서 타입을 결정하는 과정을 넓히기(widening) 라고 한다.

넓히기 문제 예시:

interface Vector3 { x: number; y: number; z: number; }
function getComponent(vector: Vector3, axis: 'x' | 'y' | 'z') {
  return vector[axis];
}

let x = 'x'; // TypeScript는 string으로 추론 (not 'x')
let vec = { x: 10, y: 20, z: 30 };
getComponent(vec, x); // Error: Argument of type 'string' is not assignable to parameter of type '"x" | "y" | "z"'

넓히기를 제어하는 4가지 방법:

1. const 사용: 더 좁은 타입으로 추론

const x = 'x'; // 타입: 'x' (string 아님)

1. 명시적 타입 어노테이션:

const obj: { x: string | number } = { x: 1 };

1. as const 어서션: 가장 좁은 타입, 모든 프로퍼티를 readonly로 만듦

const obj1 = { x: 1, y: 2 };         // { x: number; y: number }
const obj2 = { x: 1, y: 2 } as const; // { readonly x: 1; readonly y: 2 }

const arr1 = [1, 2, 3];         // number[]
const arr2 = [1, 2, 3] as const; // readonly [1, 2, 3]

1. satisfies 연산자: 타입 조건을 만족시키면서 넓히기를 방지하고 정확한 키를 유지

type Point = [number, number];
const capitals = {
  ny: [-73.75, 42.65],
  ca: [-121.49, 38.58],
} satisfies Record<string, Point>;
// capitals.ny는 number[] 아닌 [number, number]로 추론
// capitals.pr → 컴파일 에러 (존재하지 않는 키)

satisfies vs 타입 어노테이션: 어노테이션(const c: Record<string, Point> = ...)은 c.pr이 Point로 보여 런타임 에러를 놓칠 수 있지만, satisfies는 정확한 키를 유지하면서 타입 검사를 수행한다.

기억할 것: TypeScript의 넓히기 동작을 이해하고, const, 타입 어노테이션, as const, satisfies로 동작을 조절하라.

Item 21: 객체는 한 번에 만들어라

TypeScript에서 변수의 타입은 일반적으로 바뀌지 않으므로, 객체를 조각조각 만드는 패턴은 에러를 유발한다.

// 에러 발생
const pt = {};
pt.x = 3; // Error: Property 'x' does not exist on type '{}'
pt.y = 4; // Error

// 올바른 방법
const pt: Point = { x: 3, y: 4 };

여러 객체를 합칠 때: Object.assign 대신 spread 문법을 사용한다:

const pt = { x: 3, y: 4 };
const id = { name: 'Pythagoras' };

// 나쁜 예
const namedPoint = {};
Object.assign(namedPoint, pt, id);
namedPoint.name; // Error

// 좋은 예
const namedPoint = { ...pt, ...id };
namedPoint.name; // OK, string으로 추론

조건부로 프로퍼티를 추가할 때는 spread와 falsy 값을 활용한다:

declare let hasMiddle: boolean;
const firstLast = { first: 'Harry', last: 'Truman' };
const president = {
  ...firstLast,
  ...(hasMiddle ? { middle: 'S' } : {}),
};
// 타입: { middle?: string; first: string; last: string }

기억할 것: 객체는 한 번에 만들어라. { ...a, ...b } spread 문법으로 타입 안전하게 합쳐라. 조건부 프로퍼티 추가 방법을 알아두어라.

Item 22: 타입 좁히기를 이해하라

좁히기(narrowing/refinement): TypeScript가 넓은 타입에서 더 좁은 타입으로 이동하는 과정이다.

좁히기 방법들:

1. null 체크:

const elem = document.getElementById('what-time-is-it');
// elem: HTMLElement | null
if (elem) {
  elem.innerHTML = 'Party Time'; // elem: HTMLElement
}

1. throw / return으로 분기:

if (!elem) throw new Error('Unable to find');
elem.innerHTML = '...'; // elem: HTMLElement

1. instanceof:

if (search instanceof RegExp) { /* search: RegExp */ }

1. in 연산자를 이용한 프로퍼티 체크:

if ('isGoodForBaking' in fruit) { /* fruit: Apple */ }

1. Array.isArray 같은 내장 함수
2. 태그드 유니온(tagged/discriminated union) - TypeScript에서 가장 강력한 패턴:

interface UploadEvent { type: 'upload'; filename: string; contents: string; }
interface DownloadEvent { type: 'download'; filename: string; }
type AppEvent = UploadEvent | DownloadEvent;

function handleEvent(e: AppEvent) {
  switch (e.type) {
    case 'download': console.log(e.filename); break; // e: DownloadEvent
    case 'upload': console.log(e.contents); break;   // e: UploadEvent
  }
}

1. 사용자 정의 타입 가드(user-defined type guard):

function isInputElement(el: Element): el is HTMLInputElement {
  return 'value' in el;
}

좁히기의 함정들:

• typeof null === 'object'이므로 typeof elem === 'object' 체크는 null을 제거하지 못한다
• !x 체크는 0이나 ''도 걸러내므로 의도치 않게 타입이 좁혀지지 않을 수 있다
• 콜백 내부에서는 좁히기가 무효화될 수 있다: 콜백이 실행되는 시점에 외부 값이 변경될 수 있기 때문이다

기억할 것: TypeScript의 좁히기 방식을 이해하라. 타입 가드와 태그드 유니온을 활용하라. TypeScript가 따라오기 쉽도록 코드를 리팩토링하는 방법을 생각하라.

Item 23: 별칭은 일관되게 사용하라

객체의 프로퍼티에 새 변수(별칭)를 만들면 제어 흐름 분석이 방해받는다.

// 문제: bbox는 별칭이지만 polygon.bbox로 체크
function isPointInPolygon(polygon: Polygon, pt: Coordinate) {
  const box = polygon.bbox;   // BoundingBox | undefined
  if (polygon.bbox) {         // polygon.bbox는 좁혀지지만
    if (pt.x < box.x) {   // box는 여전히 undefined 가능 - Error!
    }
  }
}

// 해결: 별칭으로 일관되게 체크
function isPointInPolygon(polygon: Polygon, pt: Coordinate) {
  const box = polygon.bbox;
  if (box) {                  // box로 체크하면 box도 좁혀짐
    if (pt.x < box.x) {   // OK
    }
  }
}

// 더 좋은 방법: 구조 분해로 이름 일관성 확보
function isPointInPolygon(polygon: Polygon, pt: Coordinate) {
  const { bbox } = polygon;
  if (bbox) {
    const { x, y } = bbox;
    // ...
  }
}

추가 주의사항:

• 별칭이 있을 때 함수 호출은 프로퍼티의 타입 좁히기를 무효화할 수 있다 (함수가 값을 변경할 수도 있기 때문)
• 로컬 변수의 좁히기는 신뢰할 수 있지만, 프로퍼티의 좁히기는 주의가 필요하다
• 변경 가능성이 우려된다면 readonly 버전을 함수에 전달하라

기억할 것: 별칭은 TypeScript의 좁히기를 방해한다. 별칭을 만들었으면 일관되게 사용하라. 함수 호출이 프로퍼티의 타입 좁히기를 무효화할 수 있다는 점을 인지하라.

Item 24: 컨텍스트가 타입 추론에 어떻게 사용되는지 이해하라

TypeScript는 값 자체뿐 아니라 값이 사용되는 컨텍스트(문맥) 도 참고하여 타입을 추론한다. 값을 변수로 분리하면 컨텍스트가 끊겨 예상치 못한 에러가 발생한다.

문자열 리터럴 타입 문제:

type Language = 'JavaScript' | 'TypeScript' | 'Python';
function setLanguage(language: Language) { ... }

setLanguage('JavaScript'); // OK

let language = 'JavaScript'; // 타입: string (넓어짐)
setLanguage(language); // Error: string은 Language에 할당 불가

해결 방법:

// 방법 1: 타입 어노테이션
let language: Language = 'JavaScript';

// 방법 2: const 사용 (리터럴 타입 유지)
const language = 'JavaScript'; // 타입: 'JavaScript'

튜플 타입 문제:

function panTo(where: [number, number]) { ... }
const loc = [10, 20]; // number[] 로 추론
panTo(loc); // Error

// 해결 1: 타입 어노테이션
const loc: [number, number] = [10, 20];

// 해결 2: as const + panTo에 readonly 추가
function panTo(where: readonly [number, number]) { ... }
const loc = [10, 20] as const; // readonly [10, 20]
panTo(loc); // OK

as const의 단점: 실수가 정의 지점이 아니라 사용 지점에서 에러를 낸다.

객체 문제:

type Language = 'JavaScript' | 'TypeScript' | 'Python';
interface GovernedLanguage { language: Language; organization: string; }

const ts = { language: 'TypeScript', organization: 'Microsoft' }; // language: string으로 추론
complain(ts); // Error

// 해결: 타입 어노테이션, as const, 또는 satisfies 사용
const ts: GovernedLanguage = { language: 'TypeScript', organization: 'Microsoft' };

콜백 문제:

// 인라인 형태: 타입 추론 OK
callWithRandomNumbers((a, b) => { // a, b: number로 추론
  console.log(a + b);
});

// 분리하면 컨텍스트 손실
const fn = (a, b) => { // Error: implicit any
  console.log(a + b);
};
// 해결: 파라미터 타입 명시
const fn = (a: number, b: number) => { console.log(a + b); };

기억할 것: 변수 분리가 타입 에러를 유발하면 타입 어노테이션을 추가하라. 진짜 상수라면 as const를 사용하되, 에러가 사용 지점에서 나타날 수 있음을 인지하라. 가능하면 인라인으로 값을 사용하는 것이 어노테이션 필요성을 줄인다.

Item 25: 진화하는 타입을 이해하라

일반적으로 변수의 타입은 선언 시점에 고정되지만, 초기값이 빈 배열([])이거나 null/undefined인 경우 타입이 진화(evolve)한다.

배열의 타입 진화:

function range(start: number, limit: number) {
  const nums = []; // 타입: any[]
  for (let i = start; i < limit; i++) {
    nums.push(i); // 타입: number[]
  }
  return nums; // 타입: number[]
}

• 값을 push할 때마다 타입이 확장된다
• 서로 다른 타입을 push하면 유니온으로 확장: string[] → (string | number)[]
• 이 패턴을 “진화하는 any”, “evolving arrays”, “evolving let” 이라고도 부른다

스칼라 값의 타입 진화:

let value = null; // 타입: any (진화 중)
try {
  value = doSomethingRisky(); // 타입: number (진화됨)
} catch (e) {
  // value: number | null
}

진화가 일어나지 않는 경우:

• concat 메서드는 진화를 트리거하지 않는다
• 함수 호출을 통한 암묵적 any는 진화하지 않는다 (forEach 등)
• for-of가 forEach보다 선호되는 이유 중 하나

주의: 진화하는 타입을 읽기 전에 쓰면 암묵적 any 에러가 발생한다. 더 나은 에러 검사를 원한다면 명시적 타입 어노테이션을 사용하거나, map 같은 함수형 구조를 통해 진화 자체를 피하는 것이 좋다.

Item 26: 타입 흐름을 돕기 위해 함수형 구조와 라이브러리를 활용하라

루프 대신 내장 함수형 메서드와 Lodash 같은 라이브러리를 사용하면 타입 어노테이션 없이도 타입이 자연스럽게 흐른다.

루프 방식 vs 함수형 방식:

// 루프 방식: 타입 어노테이션 필요
let allPlayers: BasketballPlayer[] = [];
for (const players of Object.values(rosters)) {
  allPlayers = allPlayers.concat(players);
}

// 함수형 방식: 어노테이션 불필요, const 사용 가능
const allPlayers = Object.values(rosters).flat();
// 타입: BasketballPlayer[] (자동 추론)

Lodash 체이닝의 타입 안전성:

const bestPaid = _(allPlayers)
  .groupBy(player => player.team)
  .mapValues(players => _.maxBy(players, p => p.salary)!)
  .values()
  .sortBy(p => -p.salary)
  .value();
// 타입: BasketballPlayer[] - 자동으로 정확하게 추론

• 함수형 구조는 불변성(immutability)을 기반으로 매 호출마다 새 값을 반환 → 새 타입도 자연스럽게 생성
• TypeScript 개발 자체가 JavaScript 라이브러리의 동작을 정확히 모델링하려는 시도로 이루어짐

Item 27: 콜백 대신 async 함수를 사용하라

비동기 처리 방식의 발전: 콜백 → Promise → async/await

// 콜백 방식: 타입 추론 어려움, 에러 처리 복잡
fetchURL(url1, (response1) => {
  fetchURL(url2, (response2) => { ... });
});

// async/await 방식: 타입 추론 자연스러움
async function fetchPages() {
  const [response1, response2, response3] = await Promise.all([
    fetch(url1), fetch(url2), fetch(url3)
  ]);
  // 각 response 타입이 Response로 정확히 추론됨
}

• Promise.race와 async/await로 타임아웃 구현:

function timeout(ms: number): Promise<never> {
  return new Promise((_, reject) => setTimeout(() => reject('timeout'), ms));
}
async function fetchWithTimeout(url: string, ms: number) {
  return Promise.race([fetch(url), timeout(ms)]);
  // 반환 타입: Promise<Response> 자동 추론 (Promise<never>와의 유니온에서 never 제거)
}

async 함수의 이점:

• 항상 Promise를 반환하므로 동기/비동기 혼합 반환 실수를 방지
• 타입 흐름이 더 자연스럽고 에러 처리 클래스 전체를 제거
• 함수가 Promise를 반환한다면 async로 선언하라

Item 28: 새로운 추론 지점을 만들기 위해 클래스와 커링을 활용하라

TypeScript의 타입 파라미터 추론은 전부 추론하거나 전부 명시해야 하는 양자택일 방식이다.

문제 상황:

declare function fetchAPI<API, Path extends keyof API>(
  path: Path
): Promise<API[Path]>;

fetchAPI<SeedAPI>('seedstrawberry'); // Error: 타입 인수 2개 필요

해결 1: 클래스 활용

class ApiFetcher<API> {
  fetch<Path extends keyof API>(path: Path): Promise<API[Path]> { ... }
}
const fetcher = new ApiFetcher<SeedAPI>();
fetcher.fetch('seedstrawberry'); // OK

해결 2: 커링 함수 활용 (로컬 타입 별칭도 가능)

declare function apiFetcher<API>(): {
  fetch<Path extends keyof API>(path: Path): Promise<API[Path]>
};
const fetcher = apiFetcher<SeedAPI>();
fetcher.fetch('seedstrawberry'); // OK

커링 방식의 장점: 함수 구현 스코프 내에서 로컬 타입 별칭을 정의할 수 있다. 이는 복잡한 타입 표현식의 반복을 줄인다. 클래스로는 불가능하다.

기억할 것: 여러 타입 파라미터가 있을 때 추론은 전부 아니면 전부다. 부분 추론이 필요하면 클래스나 커링을 사용하라. 로컬 타입 별칭이 필요하다면 커링 방식을 선호하라.

Chapter 4: 타입 설계

“나에게 테이블을 보여주면 플로우차트가 필요 없다. 플로우차트를 보여주면 나는 여전히 미궁이다.” - Fred Brooks

타입을 잘 설계하면 코드의 동작이 명확해지고, 잘못 설계하면 문서나 영리함도 구할 수 없다. 이 챕터는 타입 자체의 설계 원칙을 다룬다.

Item 29: 유효한 상태만 표현하는 타입을 선호하라

타입 설계의 핵심은 유효하지 않은 상태를 표현할 수 없는 타입을 만드는 것이다.

나쁜 설계 예시:

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

• isLoading: true이면서 error가 있는 상태가 가능 → 무효한 상태
• renderPage, changePage 구현 시 무엇을 표시해야 할지 모호함
• 실제 버그: isLoading을 false로 되돌리는 것을 잊거나, 이전 에러가 남아있는 등

좋은 설계 예시 - 태그드 유니온 활용:

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 구현이 자명해짐
• 여러 요청이 동시에 진행되어도 각 요청이 독립적으로 관리됨

에어 프랑스 447편 교훈:

// 나쁜 설계: 두 조종사가 독립적으로 조작 → 평균을 내는 버그 발생
interface CockpitControls {
  leftSideStick: number;
  rightSideStick: number;
}

// 좋은 설계: 실제 에어버스처럼 기계적으로 연결된 단일 상태
interface CockpitControls {
  stickAngle: number; // getStickSetting 함수 자체가 필요 없어짐
}

기억할 것: 유효한 상태와 무효한 상태를 함께 표현하는 타입은 혼란과 버그를 야기한다. 길고 복잡하더라도 유효한 상태만 표현하는 타입을 선택하라.

Item 30: 입력에는 관대하게, 출력에는 엄격하게

Postel의 법칙(견고함의 원칙): 보내는 것에는 보수적으로, 받는 것에는 관대하게.

// 나쁜 예: 19가지 형태의 입력을 허용하지만 출력도 넓음
type LngLatBounds =
  | { northeast: LngLat; southwest: LngLat }
  | [LngLat, LngLat]
  | [number, number, number, number];

declare function viewportForBounds(bounds: LngLatBounds): CameraOptions;
// 반환 타입: center?: LngLat, zoom?: number, bearing?: number ...
// 모든 프로퍼티가 optional → 사용하기 매우 불편

좋은 설계 패턴:

// 입력용 느슨한 타입
type LngLatLike = LngLat | { lon: number; lat: number } | [number, number];
type LngLatBounds = { northeast: LngLatLike; southwest: LngLatLike } | ...;

// 출력용 정확한 타입 (완전히 정의된 Camera)
interface Camera { center: LngLat; zoom: number; bearing: number; pitch: number; }

declare function viewportForBounds(bounds: LngLatBounds): Camera; // 출력은 엄격
declare function setCamera(camera: CameraOptions): void; // 입력은 관대

배열 파라미터의 경우: 단순 이터레이션만 필요하다면 Array 대신 Iterable<T>를 사용하면 제너레이터 표현식도 받을 수 있다:

function sum(xs: Iterable<number>): number { ... }
const zeroToNine = range(10); // Generator
const fortyFive = sum(zeroToNine); // OK

기억할 것: 입력 타입은 출력 타입보다 넓어야 한다. 반환 타입에서 넓은 유니온이나 optional이 많으면 사용이 불편해진다. 반환용 정식 타입(canonical form)과 파라미터용 느슨한 타입(like suffix)을 구분하라.

Item 31: 문서에 타입 정보를 반복하지 말라

코드와 주석이 불일치하면 둘 다 틀린 것이다.

나쁜 예:

/**
 * Returns a string with the foreground color.
 * Takes zero or one arguments.
 */
function getForegroundColor(page?: string) {
  return page === 'login' ? { r: 127, g: 127, b: 127 } : { r: 0, g: 0, b: 0 };
  // 실제로는 string이 아닌 객체를 반환 → 주석이 틀림
}

좋은 예:

/** Get the foreground color for the application or a specific page. */
function getForegroundColor(page?: string): Color { ... }

변경 불가를 선언하는 주석 대신 readonly를 사용하라:

// 나쁜 예: 주석으로 "변경하지 않음" 선언 - 강제되지 않음
/** Does not modify nums. */
function sortNumerically(nums: string[]): string[] {
  return nums.sort((a, b) => Number(a) - Number(b)); // 실제로 in-place 정렬!
}

// 좋은 예: readonly로 TypeScript가 강제하게 함
function sortNumerically(nums: readonly string[]): string[] {
  return nums.toSorted((a, b) => Number(a) - Number(b)); // OK
}

변수명에 타입 정보를 넣지 마라:

• ageNum 대신 age로, 타입은 타입 시스템이 관리
• 단위가 불명확한 경우는 예외: timeMs, temperatureC처럼 단위를 포함하면 명확

Item 32: 타입 별칭에 null이나 undefined를 포함하지 말라

// 나쁜 예: User가 null일 수도 있다는 사실이 이름에서 보이지 않음
type User = { id: string; name: string } | null;
function getCommentsForUser(comments: Comment[], user: User) {
  return comments.filter(c => c.userId === user?.id); // user가 null인지 불명확
}

// 좋은 예: 함수 시그니처에서 명시
function getCommentsForUser(comments: Comment[], user: User | null) {
  return comments.filter(c => c.userId === user?.id);
}

// 불가피하게 nullable 타입 별칭이 필요하다면 이름을 명확하게
type NullableUser = { id: string; name: string } | null;

• 타입 이름을 보면 그것이 무엇을 나타내는지 알 수 있어야 한다
• User라는 이름은 “사용자”를 나타내야지, “사용자 또는 null”을 나타내면 안 된다
• 이 규칙은 타입 별칭의 최상위 레벨에 관한 것이며, 객체 내부의 optional 필드나 null 값은 별개 주제다

Item 33: null 값을 타입의 경계로 밀어내라

strictNullChecks를 켜면 null/undefined 관계가 암묵적으로 얽혀 있을 때 코드가 복잡해진다.

나쁜 설계 - null 값이 내부에 얽혀 있는 경우:

// min이 null이면 max도 null이어야 함 - 하지만 타입에 표현되지 않음
function extent(nums: Iterable<number>) {
  let min, max; // 둘 다 undefined로 시작
  for (const num of nums) {
    if (!min) { min = num; max = num; }
    else {
      min = Math.min(min, num);
      max = Math.max(max, num); // Error: max가 undefined일 수도 있음
    }
  }
  return [min, max]; // (number | undefined)[] - 사용하기 불편
}

좋은 설계 - null을 경계로 밀어낸 경우:

function extent(nums: Iterable<number>): [number, number] | null {
  let minMax: [number, number] | null = null;
  for (const num of nums) {
    if (!minMax) {
      minMax = [num, num];
    } else {
      const [oldMin, oldMax] = minMax;
      minMax = [Math.min(num, oldMin), Math.max(num, oldMax)];
    }
  }
  return minMax;
}
// 클라이언트는 단일 null 체크로 처리 가능
const range = extent([0, 1, 2]);
if (range) {
  const [min, max] = range; // OK
}

클래스에서 null을 경계로 밀어내기:

// 나쁜 예: 생성자에서 null로 초기화 → 모든 메서드에서 null 체크 필요
class UserPosts {
  user: UserInfo | null;
  posts: Post[] | null;
  constructor() { this.user = null; this.posts = null; }
}

// 좋은 예: 데이터가 모두 준비된 후 생성
class UserPosts {
  constructor(public user: UserInfo, public posts: Post[]) {}
  static async init(userId: string): Promise<UserPosts> {
    const [user, posts] = await Promise.all([
      fetchUser(userId),
      fetchPostsForUser(userId),
    ]);
    return new UserPosts(user, posts);
  }
}

Item 34: 유니온을 갖는 인터페이스보다 인터페이스들의 유니온을 선호하라

프로퍼티가 유니온 타입을 가지고 있다면, 별도 인터페이스의 유니온으로 분리하는 것이 더 정확하다.

나쁜 예 - 불일치 조합이 가능:

interface Layer {
  layout: FillLayout | LineLayout | PointLayout;
  paint: FillPaint | LinePaint | PointPaint;
}
// FillLayout + LinePaint 같은 무효 조합이 가능

좋은 예 - 태그드 유니온으로 분리:

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

태그를 추가하면 더욱 강력해진다:

interface FillLayer { type: 'fill'; layout: FillLayout; paint: FillPaint; }
interface LineLayer { type: 'line'; layout: LineLayout; paint: LinePaint; }
type Layer = FillLayer | LineLayer;

function renderLayer(layer: Layer) {
  if (layer.type === 'fill') {
    // layer: FillLayer로 좁혀짐
  }
}

함께 존재하거나 함께 없는 옵셔널 필드도 동일 원칙을 적용:

// 나쁜 예: 관련성이 타입에 표현되지 않음
interface Person {
  name: string;
  placeOfBirth?: string; // 이 둘은 항상 함께 있거나 함께 없어야 함
  dateOfBirth?: Date;
}

// 좋은 예: 관련 필드를 하나의 객체로 묶어 명시
interface Person {
  name: string;
  birth?: { place: string; date: Date };
}

Item 35: string 타입보다 더 정확한 대안을 선호하라

string의 도메인은 매우 넓다. “Moby Dick” 전체 텍스트도 string이다. 더 좁은 타입이 적절한지 항상 물어봐야 한다.

나쁜 예 - “stringly typed” 코드:

interface Album {
  artist: string;
  title: string;
  releaseDate: string; // 'August 17th, 1959'처럼 잘못된 포맷도 가능
  recordingType: string; // 'Studio', 'LIVE' 등 잘못된 값도 가능
}

좋은 예 - 정확한 타입 사용:

type RecordingType = 'studio' | 'live';

interface Album {
  artist: string;
  title: string;
  releaseDate: Date; // 포맷 문제 해결
  recordingType: RecordingType; // 유효하지 않은 값 방지
}

string 대신 keyof T 사용:

// string 사용: any 타입의 문제와 유사
function pluck(records: any[], key: string): any[] {
  return records.map(r => r[key]);
}

// keyof T 사용: 타입 안전, 자동완성 지원
function pluck<T, K extends keyof T>(records: T[], key: K): T[K][] {
  return records.map(r => r[key]);
}

const dates = pluck(albums, 'releaseDate'); // Date[]로 정확히 추론
const bad = pluck(albums, 'recordingDate'); // Error: 유효하지 않은 키

기억할 것: stringly typed 코드를 피하라. 유한한 문자열 집합이라면 유니온 리터럴 타입을 사용하라. 객체의 키라면 string 대신 keyof T를 사용하라.

Item 36: 특수 값에는 별도의 타입을 사용하라

-1, 0, '' 같은 도메인 내 특수 값(in-domain special values)은 TypeScript가 일반 값과 구분하지 못한다.

나쁜 예 - indexOf의 -1 문제:

function splitAround<T>(vals: readonly T[], val: T): [T[], T[]] {
  const index = vals.indexOf(val);
  return [vals.slice(0, index), vals.slice(index + 1)]; // index가 -1이면 버그!
}
splitAround([1, 2, 3, 4, 5], 6); // [1,2,3,4], [1,2,3,4,5] - 이상한 결과

좋은 예 - null을 반환하는 래퍼 함수:

function safeIndexOf<T>(vals: readonly T[], val: T): number | null {
  const index = vals.indexOf(val);
  return index === -1 ? null : index;
}

function splitAround<T>(vals: readonly T[], val: T): [T[], T[]] {
  const index = safeIndexOf(vals, val);
  if (index === null) return [...vals, []]; // 명시적으로 처리 강제
  return [vals.slice(0, index), vals.slice(index + 1)]; // OK
}

• priceDollars: -1 같은 특수 값을 사용하면 strictNullChecks를 끈 것과 유사한 효과 → 타입 체커가 일반 값과 구분하지 못한다
• 의미가 명확하지 않은 경우에는 null/undefined 대신 태그드 유니온을 고려하라

Item 37: 선택적 프로퍼티 사용을 제한하라

optional 프로퍼티는 편의를 위해 추가하기 쉽지만, 숨겨진 비용이 있다.

interface FormattedValue {
  value: number;
  units: string;
  unitSystem?: UnitSystem; // optional 추가 - 기본값은 imperial
}

optional 프로퍼티의 문제점:

• 기본값이 무엇인지 알 수 없으면 실수 유발 (metric이 기본이라고 오해)
• API 사용자가 명시적으로 지정하지 않으면 의도와 다른 동작 발생
• unitSystem이 있어야 하는 경우와 없어도 되는 경우가 혼재되어 타입이 너무 허용적

대안 설계:

// 방법 1: 필수로 만들기 (기존 코드 수정 필요)
interface FormattedValue {
  value: number;
  units: string;
  unitSystem: UnitSystem; // 항상 명시 강제
}

// 방법 2: 태그드 유니온으로 별도 표현
type FormattedValue =
  | { value: number; units: string; unitSystem: 'metric' }
  | { value: number; units: string; unitSystem: 'imperial' };

• optional 프로퍼티는 “있어도 되고 없어도 된다”는 의미이지, “기본값이 있다”는 의미가 아니다
• 관련 있는 프로퍼티 여러 개가 동시에 optional이라면 Item 34의 유니온 인터페이스 패턴을 고려하라

Item 38: 같은 타입의 반복 파라미터를 피하라

// 나쁜 예: 같은 타입 파라미터 반복 → 순서 실수를 TypeScript가 잡지 못함
function recordRelease(title: string, date: string) { ... }
recordRelease(kindOfBlue.releaseDate, kindOfBlue.title); // 순서 바뀌어도 에러 없음

// 좋은 예: 객체로 묶어서 전달
function recordRelease(album: { title: string; date: string }) { ... }

• Item 35의 예시에서 title: string, date: string은 둘 다 string이라 순서 오류를 타입 체커가 잡지 못한다
• 함수 파라미터에서 같은 타입이 여러 개 반복되면 항상 객체로 묶는 것을 고려하라

Item 39: 타입의 차이를 모델링하기보다 단일 타입으로 통합하라

서로 약간 다른 두 타입을 별도로 유지하면 변환 코드와 인지 부하가 증가한다.

예시 - DB 모델과 API 응답 타입의 차이:

// 나쁜 예: 거의 동일한데 별도로 유지
interface UserDB { firstName: string; lastName: string; }
interface UserAPI { first_name: string; last_name: string; } // snake_case

// 두 타입 간 변환 코드가 항상 필요하고 싱크가 맞아야 함

// 좋은 예: 하나의 타입으로 통합
interface User { firstName: string; lastName: string; }
// DB/API 레이어에서 변환 처리

주의사항:

• 타입이 실제로 다른 것(태그드 유니온의 각 케이스 등)은 통합하지 말 것
• 외부 시스템(DB, 외부 API)이 통제권 밖이라면 변환을 명시적으로 모델링하는 것이 나을 수 있다

Item 40: 부정확한 타입보다 덜 정확한 타입을 선호하라

타입 선언의 정확도를 높이려다 틀린 타입을 만들면, 타입이 없는 것보다 더 나쁘다.

예시 - GeoJSON 좌표:

// 시도: 더 정확하게
type GeoPosition = [number, number]; // latitude, longitude만 허용
interface Point { type: 'Point'; coordinates: GeoPosition; }

// 문제: GeoJSON 스펙은 세 번째 요소(고도)도 허용
// → 유효한 GeoJSON이 에러를 낸다 → 사용자가 any로 우회

Mapbox 표현식 타입 정확도의 딜레마:

// 너무 느슨 - 잘못된 표현도 허용
type Expression1 = any;
type Expression2 = number | string | any[];

// 적당히 정확 - 함수명 검사 추가
type FnName = 'case' | 'rgb' | ...;
type CallExpression = [FnName, ...any[]];
type Expression3 = number | string | CallExpression;

// 너무 정밀하게 하려다 오히려 인터페이스가 복잡해지고 에러 메시지도 나빠짐

핵심 원칙:

• “언캐니 밸리(uncanny valley)“를 피하라: 복잡하지만 부정확한 타입은 단순하고 덜 정확한 타입보다 나쁘다
• 정확히 모델링할 수 없다면 부정확하게 모델링하지 말고, any나 unknown으로 한계를 인정하라
• 타입이 정밀해질수록 에러 메시지와 자동완성도 함께 검증하라

Item 41: 문제 도메인의 언어로 타입을 명명하라

“컴퓨터 과학에서 두 가지 어려운 문제가 있다: 캐시 무효화와 이름 짓기.”

잘 선택된 이름은 추상화 수준을 높이고, 잘못된 이름은 잘못된 멘탈 모델을 심어준다.

나쁜 예:

interface Animal {
  name: string;       // 어떤 이름? 학명? 일반명?
  endangered: boolean; // 멸종이면 어떻게? extinct는 해당 안 됨?
  habitat: string;    // 너무 모호
}
const leopard: Animal = {
  name: 'Snow Leopard', // 변수명은 leopard인데 값은 'Snow Leopard'
  endangered: false,    // 실제로 VU(취약) 등급
  habitat: 'tundra',
};

좋은 예:

type ConservationStatus = 'EX' | 'EW' | 'CR' | 'EN' | 'VU' | 'NT' | 'LC'; // IUCN 표준
type KoppenClimate = 'Af' | 'Am' | 'As' | ... ; // 쾨펜 기후 분류

interface Animal {
  commonName: string;         // 구체적
  genus: string;              // 분류학적 명칭
  species: string;
  status: ConservationStatus; // 표준 용어 사용
  climates: KoppenClimate[];  // 표준 분류 체계
}
const snowLeopard: Animal = {
  commonName: 'Snow Leopard',
  genus: 'Panthera',
  species: 'Uncia',
  status: 'VU',
  climates: ['ET', 'EF', 'Dfd'],
};