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

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

---

타입 선언과 @type

• 의존성 관리는 어렵다.
• 타입 선언문 => 프로젝트 + TS 커뮤니티 기여

아이템 45: devDependencies에 typescript와 @types 추가하기 Put TypeScript and @types in devDependencies

• npm, node package manager는 JS 생태계에서 필수적
• package.json: 프로젝트가 의존하고 있는 라이브러리의 버전을 지정하는 방법

의존성 종류

• dependencies
  • 전이 의존성 transitive dependencies
  • 다른 사용자가 해당 프로젝트를 설치한다면 함께 설치된다
• devDependencies:
  • 런타임에는 필요없는 라이브러리
  • 다른 사용자가 해당 프로젝트를 설치하면 devDependencies는 제외된다.
  • ex) 테스트 프레임워크
• peerDependencies:
  • 런타임에 필요하지만, 의존성을 직접 관리하지 않는 라이브러리
  • ex) 플러그인

타입스크립트와 의존성

• 타입스크립트는 개발 도구일 뿐이고, 타입 정보는 런타임에 속하지 않기 때문에 타입 관련 라이브러리는 일반적으로 devDependencies에 속한다

타입스크립트 자체 의존성

• TS를 시스템 레벨로 설치할 수 있지만 추천하지 않는 이유
  • 팀원이 동일한 버전을 사용한다는 보장이 없음
  • 프로젝트 셋업에 별도에 단계가 추가됨
• global 설치 x => devDependencies에 넣자
• npx로 devDependencies의 타입스크립트 컴파일러 실행할 수 있음 npx tsc

타입 의존성 @types

• DefinitelyTyped에서 타입 정보를 얻을 수 있다.
• npm 레지스트리의 @types스코프에 공개된다.
  • ex) @types/jquery, @types/lodash
  • 타입 정보만 포함하고 있으며, 구현제는 포함하지 않음
• 타입 의존성은 devDependencies에 있어야 한다.

Things to Remember

• Understand the difference between dependencies and devDependencies in package.json.
  • dependencies & devDependencies 차이점 알기
• Put TypeScript in your project's devDependencies. Don't install TypeScript system-wide.
  • 시스템 레벨로 설치하지 말고 프로젝트 단위로 설치하기 (devDependencies)
• Put @types dependencies in devDependencies, not dependencies.
  • devDependencies에 타입 의존성 @types 설치하기

아이템 46: 타입 선언과 관련된 세 가지 버전 이해하기 Understand the Three Versions Involved in Type Declarations

타입스크립트와 버전

• 라이브러리의 버전
• 타입 선언의 버전 @types
• 타입스크립트의 버전

설치하기

• 특정 라이브러리를 dependencies로 설치
• 타입 정보를 devDependencies로 설치

$ npm install react
+ react@16.8.6

$ npm install --save-dev @types/react
+ @types/react@16.8.19
// 타입 선언이 16.8.x의 API를 나타낸다.
// 메이저와 마이너가 일치하지만, 패치버전은 일치하지 않는다!

// 시멘틱 버저닝에 따라 패치 버전은 공개 API의 사양을 변경하지 않기 때문
// 즉, @types의 패치 버전은 타입 선언 자차의 버그/누락 사항 수정으로 인한 업데이트

타입 정보가 별도로 관리될 때의 문제점

A. 라이브러리를 업데이트하고, 타입 선언을 업데이트 하지 않는 경우

• 새로운 기능 사용 시, 타입 오류
• 하위 호환성이 깨지는 업데이트가 있었을 시, 런타임 오류
• 타입 선언 버전이 준비되지 않았다면? 보강을 사용하여 프로젝트 자체에 추가하거나, 타입 선언을 직접 작성하여 기여할 수 있다.

B. 라이브러리보다 타입 선언이 최신인 경우

• 타입 정보 없이 라이브러리를 사용하다가, 타입 선언을 설치하려 할 때 발생
• 타입 체커는 최신 API를 기준으로 코드를 검사하지만, 런타임에 쓰이는 것이 과거 버전
• 라이브러리 버전과 맞도록 타입 선언의 버전을 내린다

C. 프로젝트에서 사용하는 TS보다 라이브러리에서 필요로하는 TS 버전이 높을 때

• 유명 JS 라이브러리의 경우, 타입 정보를 정확히 표현하기 위해 타입 시스템이 개선되고 버전이 올라가는 경향
  • 이런 경우 최신 타입 정보를 위해 타입스크립트의 버전을 올리거나, 라이브러리 타입 선언의 버전을 내리거나, declare module로 타입 정보를 없앤다.
• 라이브러리에서 typesVersions(타입스크립트 버전별로 다른 타입 선언)를 제공하는 경우도 있지만 1% 밖에 안됨
• 특정 버전의 타입 정보 설치하기

  npm install --save-dev @types/lodash@ts3.1
  

D. @type 중복

• @type/foo와 @type/bar
  • 만약 @type/bar가 현재 프로젝트와 호환되지 않는 버전의 @type/foo에 의존한다면 npm은 중첩 폴더에 별도의 버전을 설치해서 문제를 해결하려 한다.
  • 전역 네임스페이스를 가진 타입 선언 모듈이라면 문제가 발생한다. => 종복된 선언, 선언 병합으로 오류
  • npm ls @type/foo를 실행하여 타입 선언 중복을 추적할 수 있다.
• 해결법
  • @type/foo또는 @type/bar를 업데이트하여 서로 버전이 호환되로고 함

번들링하여 타입 선언을 포함하는 경우의 문제점

• TS 라이브러리들을 자체적으로 타입 선언을 포함(번들링)한다.
  • 자체적 타입 선언은 보통 types 필드의 ~.d.ts를 가리킨다

A. 번들된 타입 선언에 오류가 있을 때

• 보강으로 해결할 수 없는 오류가 있을 때 & 공개 시점에는 동작했지만, TS 버전이 올라가면서 오류가 발생하는 경우
• @types를 별도로 사용한다면 버전을 맞출 수 있지만, 번들된 타입이라면 선택이 불가능하다.

B. 프로젝트 내의 타입 선언이, 다른 라이브러리의 타입 선언에 의존할 때

• 보통 의존성은 devDependencies
  • 프로젝트를 공개하여 다른 사용자가 설치하면 devDependencies가 설치되지 않아 타입 오류
• 자바스크립트 사용자는 타입 정보를 설치할 필요가 없다. 타입스크립트 사용자만이 타입 정보를 사용한다.

C. 프로젝트 과거 버전의 타입 선언에 문제가 있는 경우, 패치 업데이트

• 번들링된 타입 선언에서는 어렵지만 @types은 동일 라이브러리의 여러 버전에서 타입 선언을 동시에 유지보수할 수 있는 매커니즘이 있다.

D. 타입 선언의 패치 업데이트를 자주 하기 어렵다.

• DefinitelyTyped는 커뮤니티에서 관리하기 때문에 패치를 적용할 담당자 있음

의존성 관리

• 잘 작성된 타입 선언은 라이브러리를 올바르게 사용하는 방법을 배우는 데 도움이 되고 + 생산성이 크게 향상된다.

• 라이브러리를 공개하는 경우, 타입 선언을 자체적으로 포함하는 것과 DefinitelyTyped에 공개하는 것의 장단점을 비교하기

• 공식 권장사항

  • 라이브러리가 TS로 작성된 경우에만 라이브러리에 포함하기

    • TS로 작성한 라이브러리: 타입스크립트 컴파일러가 타입 선언을 대신해준다
    • JS로 작성한 라이브러리: 직접 작성한 타입 선언은 오류가 있을 가능성이 높고, 업데이트가 필요하다. DefinitelyTyped에 공개해서 관리하도록 맡기는 것이 좋음

Things to Remember

• There are three versions involved in an @types dependency: the library version, the @types version, and the TypeScript version.
  • 의존성 세 가지 버전
    • 라이브러리, @types, 타입스크립트 버전
• Recognize the symptoms of different types of version mismatch.
• If you update a library, make sure you update the corresponding @types.
  • 라이브러리를 업데이트 하는 경우, @types도 업데이트
• Understand the pros and cons of bundling types versus publishing them on DefinitelyTyped. Prefer bundling types if your library is written in TypeScript, and DefinitelyTyped if it is not.
  • 타입 선언을 라이브러리에 포함시키기 vs DefinitelyTyped에 공개하기