Declaration Files & JSDoc

Declaration 파일은 타입이 정의되지 않은 JS 모듈을 불러올때, 에러를 방지하기 위해 해당 파일의 모양을 설명해주는 파일이다.

프로젝트 진행중 많은 라이브러리를 사용하게 되고, 대부분이 자바스크립트로 만들어져있다.

타입스크립트 프로젝트라면 설치되는 JS라이브러리(모듈) 파일을 읽을 수 없다.

JS에는 타입이 정의되지 않으므로 컴파일 에러가 발생한다.

이를 방지하고자 많은 JS라이브러리 대부분은 .d.ts라와 같은 확장자의 Declation파일이 존재한다.

해당 파일은 TypsScript에게 자신이 속한 JS 모듈파일을 설명함으로써 에러가 나지않고 동작된다.

 

[myPackage.d.ts] 정의 파일 추가

/**
 * 타입스크립트에게 타입을 설명하기위한 정의 파일
 */
interface Config {
  url: string;
}
declare module "myPackage" { // module이름은 t/js파일명과 같아야 import시 해당 정의를 읽어들인다
  function init(config: Config): boolean;
  function exit(code: number): number;
}

.d.ts 확장자로 파일을 만들어준다. (.ts로 만들어도 되지만 declare 정의되었다는 의미의 d를 추가한것)

declare module키워드를 사용하며, 이름은 해당 모듈 파일명과 일치해야한다 (myPacage.js의 myPackage)

 

 

[myPackage.js] 모듈 파일 추가

export function init(config) {
  return true;
}
export function exit(code) {
  return code + 1;
}

 

[index.js] 함수 읽을 파일 추가

import {init, exit} from "myPackage";
init({
  url: "true"
})
exit(1)

 문법에 맞춰 import한뒤 함수를 호출한다.

import문의 함수명 혹은 선언후 함수명 위에 마우스 호버시 선언한 정의 나오고,
ctrl키를 누른 상태에서 클릭 하면 해당 모듈 정의파일의 정의된 위치로 이동하게된다.

 

---

[JSDoc]

.d.ts 파일이 없는 경우 JS파일 읽기

 

[index.js] import문에서 모듈명 앞에 상대경로를 추가한다.

import {init, exit} from "./myPackage"; // myPackage.js를 직접 불러온다. (myPackage.d.ts가 없을경우 에러발생하지않음)
init({
  url: "true"
})
exit(1)

 

 

[tsconfig.json] 자바스크립트 허용옵션 추가

{
  /* ...생략... */
  "compilerOptions": {
    /* ...생략... */
    "allowJs": true, // 자바스크립트를 허용한다.
  },
}

import문에서 컴파일 에러가 발생하지 않게 된다.

 

 

[myPackage.js] 자바스크립트에 타입스크립트 Protection(보호장치)

//@ts-check //타입스크립트 파일에게 자바스크립트 파일을 확인하라는 알림
export function init(config) {
  return true;
}
export function exit(code) {
  return code + 1;
}

 

@ts-check에 의해 TypeScript가 오류를 발생시키도록 하는것이다.

즉, JS파일의 타입이 지정되지 않았으므로 타입스크립트의 보호장치에 의해 컴파일 에러를 확인할 수 있게 되는것이다.

 

 

[myPackage.js] JSDoc을 활용하여 자바스크립트에 타입 지정

// @ts-check //타입스크립트 파일에게 현재 자바스크립트 파일을 확인하라는 알림

/**
 * Initializes the project
 * @param {object} config 
 * @param {boolean} config.debug //config파일 안에는 debug라는 boolean타입의 속성이 존재
 * @param {string} config.url //config파일 안에는 debug라는 boolean타입의 속성이 존재
 * @returns boolean
 */
export function init(config) {
  return true;
}

/**
 * Exits the program
 * @param {number} code 
 * @returns number
 */
export function exit(code) {
  return code + 1;
}

Comment를 통해 TypeScript에 알린다!

 

보다 더 상세하게 타입을 알수 있음!