Ch.11 선언 파일
타입스크립트는 별도로 타입 형태를 선언할 수 있다.
타입 선언은 파일 이름이 .d.ts 확장자로 끝나는 선언 파일에 작성된다.
선언 파일은 일반적으로 프로젝트 내에서 작성되고, 컴파일된 npm 패키지로 빌드 및 배포되거나 독립 실행형 typings 패키지로 공유된다.
11.1 선언 파일
.d.ts 선언 파일은 런타임 코드를 포함할 수 없다는 제약 사항을 제외하고 .ts 파일과 유사하게 작동한다.
.d.ts 파일에는 사용 가능한 런타임 값, 인터페이스, 모듈, 일반적인 타입의 설명만 포함된다.
다른 타입스크립트 파일과 마찬가지로 임포트해서 사용 가능하다.
선언 파일은 타입만 선언할 수 있는 코드 영역을 의미하는 앰비언트 컨텍스트를 생성한다.
11.2 런타임 값 선언
선언 파일은 함수 또는 변수 같은 런타임 값을 생성하지 않지만, declare 키워드를 사용해 이러한 구조체가 존재한다고 선언할 수 있다. 이렇게 하면 웹 페이지의 <script> 태그 같은 일부 외부 작업이 특정 타입의 이름을 사용해 값을 생성했음을 타입 시스템에 알린다.
declare로 변수를 선언하면, 초깃값이 허용되지 않는다는 점을 제외하고 일반적인 변수 선언과 동일 구문을 사용한다.
함수와 클래스도 본문 없이 유사하게 선언된다.
declare 키워드를 사용한 타입 선언은 .d.ts 선언 파일에서 사용하는 게 가장 일반적이지만 선언 파일 외부에서도 사용할 수 있다. 모듈이나 스크립트 파일에서도 declare 키워드를 사용 가능하며, 특히 전역으로 사용 가능한 변수가 해당 파일에서만 사용되어야 하는 경우 유용하다.
11.2.1 전역 변수
import 또는 export 문이 없는 타입스크립트 파일은 모듈이 아닌 스트립트로 취급되기에 선언된 모든 구문이 전역으로 사용된다. 이러한 동작 이점을 이용해 타입을 전역으로 선언할 수 있다. 전역 선언 파일은 어플리케이션의 모든 파일에 걸쳐서 사용 가능한 전역 타입 또는 변수 선언에 특히 유용하다.
.d.ts 파일에 선언된 전역 타입에 자동으로 접근할 수 없는 경우 .d.ts 파일이 아무것도 내보내거나 가져오지 않았는지 확인해야 한다. 하나의 export로도 전체 파일을 전역으로 사용할 수 없게 만들 수 있다.
11.2.2 전역 인터페이스 병합
인터페이스 또한 변수와 같이 전역으로 사용할 수 있다.
11.2.3 전역 확장
전역 파일로 만드는 것이 만능은 아니다. 때로는 모듈 파일의 타입이 전역으로 사용되어야 하는 경우도 있다.
declare global 코드 블록 구문을 사용해 해당 블록의 내용이 전역 컨텍스트에 있다고 선언할 수 있다.
전역 선언과 모듈 선언이 잘 작동하도록 랭글링 하는 것은 까다로울 수 있다. 하지만 declare와 global 키워드를 잘 사용하면 전역으로 사용가능한 타입의 정의를 설명할 수 있다.
11.3 내장된 선언
11.3.1 라이브러리 선언
자바스크립트 런타임에 존재하는 내장된 전역 객체(Array, Function 같은) 는 lib.[target].d.ts 파일 이름으로 선언된다. 여기서 target은 ES5, ES2020과 같이 프로젝트에서 대상으로 하는 자바스크립트의 최소 지원 버전이다.
내장된 라이브러리 선언 파일, lib 파일은 자바스크립트의 내장된 API 전체를 나타내기에 상당히 크다.
lib 파일은 타입스크립트 npm 패키지의 일부로 배포되며 node_modules/typescript/lib.es5.d.ts와 같은 경로의 패키지 내부에서 찾을 수 있다.
라이브러리 target
타입스크립트는 제공된 target 설정에 따라 적절한 lib 파일을 포함한다. 자바스크립트 최신 버전에 대한 연속적인 lib 파일들은 인터페이스 병합을 사용해 서로 빌드된다. 타입스크립트 프로젝트는 target으로 지정한 자바스크립트 버전의 모든 최소 버전 lib 파일을 포함한다. 예를들어 es2016인 프로젝트에 lib.es5.d.ts, lib.es2015.d.ts, lib.es.2016.d.ts까지 모두 포함된다.
11.3.2 DOM 선언
DOM 타입이라고 하는 웹 브라우저 타입은 localStoarge 같은 API와 웹 브라우저에서 주로 사용하는 HTMLElement와 같은 타입 형태를 다룬다. DOM 타입은 lib.dom.d.ts 파일과, 다른 lib.*.d.ts 선언 파일에도 저장된다.
많은 내장 전역 타입처럼 전역 DOM 타입은 종종 전역 인터페이스로 설명된다.
lib 컴파일러 옵션을 재정의하지 않는 타입스크립트는 DOM 타입을 기본으로 포함한다.
11.4 모듈 선언
선언 파일의 또 다른 중요 기능은 모듈의 상태를 설명하는 기능이다. 모듈의 문자열 앞 declare 키워드는 모듈의 내용을 타입 시스템에 알리는 기능을 한다. (자주 쓰면 안됨)
11.4.1 와일드카드 모듈 선언
모듈 선언은 자바스크립트와 타입스크립트 파일 확장자가 아닌 특정 파일의 내용을 코드로 가져올 수 있음을 웹 어플리케이션에 알리기 위해 사용된다. 모듈 선언으로 하나의 * 와일드카드를 포함해 해당 패턴과 일치하는 모든 모듈을 나타낼 수 있다.
예를들어 create-react-app 과 같이 많은 웹 프로젝트는 CSS 모듈을 지원하며 CSS 파일에서 런타임에 사용할 수 있는 객체로 스타일을 가져온다. 기본적으로 { [i: string] : string } 타입의 객체를 내보내는 *.module.css과 같은 패턴으로 모듈을 정의한다.
와일드카드 모듈을 사용해 로컬 파일을 나타내는 방식은 타입 안정성을 완벽하게 보장하지는 않는다.
11.5 패키지 타입
11.5.1 선언
타입스크립트는 입력된 파일에 대한 .d.ts 출력 파일과 자바스크립트 출력 파일을 함께 생성하는 선언 옵션을 제공한다.
index.ts 파일이 제공된다고 가정했을때 module은 선언 옵션을 사용해 .d.ts와 .js 파일을 생성한다.
(P.241 - 242)
11.5.2 패키지 타입 의존성
타입스크립트는 프로젝트의 node_modules 의존성 내부에서 번들로 제공되는 .d.ts 파일을 감지하고 활용할 수 있다. 이러한 파일은 해당 패키지에서 내보낸 타입 형태에 대해 마치 동일 프로젝트에서 작성된것처럼 타입 시스템에 알린다.
11.5.3 패키지 타입 노출
프로젝트가 npm에 배포되고 사용자를 위한 타입을 제공하려면 패키지의 package.json 파일에 types 필드를 추가해 루트 선언 파일을 가리킨다. types 필드는 main 필드와 유사하게 작동하고, 종종 동일한 것처럼 보이지만 .js 확장자 대신 .d.ts 확장자를 사용한다.
types 필드가 패키지의 packages.json에 존재하지 않으면, 타입스크립트는 ./index.d.ts를 기본값으로 지정한다. 이런 방식은 types 필드가 지정되지 않은 경우 ./index.js 파일을 패키지의 기본 진입점으로 가정하는 npm의 기본 동작을 반영한 것이다.
11.6 DefinitelyTyped
모든 프로젝트가 타입스크립트로 작성된 것은 아니다.
타입스크립트 프로젝트는 해당 패키지에서 모듈의 타입 형태를 알려야 한다. 오래된 라이브러리의 경우 자바스크립트로만 작성되어 타입 형태가 없거나 미비하다. 이러한 점을 보완하기 위해 타입스크립트 팀과 커뮤니티는 깃허브에 DefinitelyTyped라는 거대한 저장소를 만들어 관련된 패키지 정의를 기록하고 있다. 저장소에는 변경 제안 검토 및 업데이트 게시와 관련된 자동화 부분, 수천 개의 .d.ts 정의 패키지가 포함되어 있다.
DT 패키지는 타입을 제공하는 패키지와 동일한 이름으로 npm에 @types 범위로 게시된다.
package.json 파일에서 보던 코드가 이 부분과 관련된 내용이다.
11.6.1 타입 사용 가능성
인기있는 자바스크립트 패키지는 자체적으로 타입이 제공되거나 DefinitelyTyped를 통해 타입을 제안할 수 있다.
11.7 마치며
.d.ts로 선언 파일 생성하기
declare 키워드로 타입과 값 선언하기
전역 변수, 전역 인터페이스 병합 및 전역 확장을 사용해서 전역 타입 변경하기
타입스크립트의 내장 target, 라이브러리 및 DOM 선언 구성과 사용법
와일드카드 모듈을 포함한 모듈 타입 선언하기
타입스크립트가 패키지에서 타입을 선택하는 방법
타입을 포함하지 않는 패키지에 대해 DefinitelyTyped를 사용해 타입 얻기
Last updated
Was this helpful?