들어가며..
안녕하세요! Ocean입니다.
오늘은 타입스크립트로 개발하면서 만나볼 수 있는 d.ts 파일의 용도와 개념을 정리해 보겠습니다.
참고 글
1. d.ts 파일이란?
d.ts파일의d는 Declaration(선언)을 의미합니다.
선언을 설명하기에 앞서 이와 대조되는 정의(Definition)을 함께 설명하면 좋을 것 같습니다.
선언과 정의의 의미는 이를 서술하는 프로그래밍 언어 마다 상이하지만, 일반적으로 다음을 의미합니다.
선언(Declaration): 컴파일러에게 특정한 엔티티(함수, 변수 등)의 존재를 알리는 것
정의(Definition): 엔티티의 실제 본문(함수의 실제 구현 본문, 변수의 실제 값)
즉, 타입스크립트의 d.ts 파일은 함수나 변수의 구현 세부 내용을 담는 정의 파일이 아니라,
그 형태와 구조, 다시 말해 어떤 이름의 요소가 어떤 타입과 시그니쳐를 가지는지에 대한 정보만을 기술하는 선언 파일입니다.
조금 더 간단히 말하자면, JS 파일에 대한 구현은 없이 타입'만' 설명해 놓은 ts 파일입니다.
2. d.ts 파일은 어떨 때 필요할까?
만약, JS로만 작성된 파일이나 모듈, 라이브러리를 TS 환경에서 사용한다면 어떤 문제가 발생할까요?
타입 정보가 없는 JS 파일들은 ts server가 해당 코드의 타입을 추론하지 못해 any로 처리하게 됩니다.
또한 ts server가 제공해 주는 자동 완성, 타입 검사 등을 모두 사용할 수 없게 되죠.
// math.js
export const add = (a, b) => a + b;
위 함수는 JS 코드로 작성되었습니다. 위 코드를 TS 코드에서 import하여 사용하면 어떻게 될까요?
해당 add 함수는 TS 파일에서 매개변수와 반환값 모두 any로 추론됩니다.
또한 사용할 때 매개변수를 넘기지 않아도, 타입 에러가 나지 않습니다. 사실상 해당 파일을 사용할 때는 타입스크립트가 무용지물이 되는 것이죠 ㅠㅠ
이럴 때, JS 코드를 TS 코드로 마이그레이션하는 수고스러움을 겪지 않고도 d.ts 파일만 추가해서 타입 정보를 제공할 수 있습니다.
// math.d.ts
export declare function add(a: number, b: number): number;
위와 같이, 파일 이름을 math.d.ts 파일로 생성한 후, export declare 키워드와 함께 함수의 타입을 선언합니다.
이제 ts server가 올바르게 타입을 추론합니다!!
이렇게 JS로 개발된 함수를 TS 파일에서 올바르게 사용할 수 있게 됐습니다. 👏👏👏
3. 다양한 상황에서의 d.ts 파일 활용
d.ts 파일은 앞서 설명한 경우 말고도 타입 정보를 제공해야 하는 다양한 상황이 있습니다.
그리고 그 상황에 따라서 문법과 사용법이 살짝 달라지는데, 그 상황들을 설명해 보겠습니다.
1. 같은 모듈 내의 js 파일에 대한 타입 정보 제공
// math.js
export const add = (a, b) => a + b;
// math.d.ts
export declare function add(a:number,b:number):number;
첫번째로 앞서 설명한 예시입니다.
같은 모듈 위치 내에서 JS로 개발된 파일의 타입 정보를 제공할 수 있습니다.
이 때, 파일 이름을 동일하게 가져가면 ts server가 알아서 추론합니다.
2. JS로 개발된 라이브러리의 타입 정보를 제공
// typings/some-lib/index.d.ts
// some-lib.d.ts에 module 키워드로 라이브러리에 대한 타입 정보 제공
declare module 'some-lib' {
export function foo(x: number): string;
export const version: string;
}
// JS로 개발된 라이브러리를 import 가능!
import { foo, version } from 'some-lib';
node modules 내부에 위치한 JS로 개발된 라이브러리를 사용할 때,
module 키워드를 통해서 타입 정보를 제공해줄 수 있습니다.
일반적으로는 위 파일이 @types/ 아래에 위치하면 ts server는 자동으로 추론하지만, 위와 같이 typings라는 폴더 아래 있으면, tsconfig에 include 혹은 typeRoots 속성을 사용해서 ts server에게 알려줘야 합니다.
3. 전역에서 사용하는 함수에 대한 타입 정보를 제공
// <script src="http://a.great.cdn.for/someLib.js"></script>
// 스크립트 태그로 불러온 글로벌 스코프 라이브러리를 사용할 때 타입 추론 제공
// global.d.ts
declare function myLib(a: string): string;
declare function myLib(a: number): number;
module 혹은 export 키워드를 없이 사용하면, 전역 스코프로 추론이 됩니다.
이 때, global.d.ts라는 파일 이름은 전역 선언 파일을 관리하기 위한 관례적 컨벤션이며,
파일 이름과 상관 없어 d.ts 파일 내부에서 declare만 사용하면 전역 스코프로 추론이 됩니다.