Language/TypeScript
[TypeScript] Declaration File & JSDoc
by eess
2024. 8. 7.
Declaration File
- TypeScript 선언 파일은 주로 JavaScript로 작성된 라이브러리나 모듈을 TypeScript에서 사용할 때 필요합니다.
- 선언 파일은 .d.ts 확장자를 가지며 동일한 이름의 라이브러리나 모듈의 타입을 정의합니다. Visual Studio Code와 같은 통합개발환경(IDE)에서는 선언 파일을 불러와서 보여주기 때문에 바로 타입을 확인할 수 있습니다.
- TypeScript는 JavaScript 코드도 같이 쓸 수 있도록 허용하지만, 타입 정의가 없다면 사실 TypeScript를 쓰는 의미가 없습니다. 따라서 TypeScript에서 선언 파일은 꼭 필요합니다.
- tsconfig.json에 "strict": true 를 설정하면 선언 파일이 없는 JavaScript 패키지에 대해 오류가 발생하며 컴파일도 할 수 없습니다. 이때 {패키지명}.d.ts 파일을 작성해주면 오류가 해결됩니다.
// index.ts
import { exit, init } from "myPackage";
init({ url: "x" });
exit(1);
// myPackage.js
export function init(config) {
return true;
}
export function exit(code) {
return code + 1;
}
// myPackage.d.ts
interface Config {
url: string;
}
declare module "myPackage" {
function init(config: Config): boolean;
function exit(code: number): number;
}
JSDoc
- 사실 오픈 소스에 기여하는 것이 아닌 이상 직접 선언 파일을 작성할 일은 많지 않을 것입니다...
- TypeScript로 마이그레이션 하는 경우와 같이, 하나의 프로젝트 안에서 JavaScript 파일과 TypeScript 파일이 함께 쓰이는 경우를 마주치게 됩니다.
- 타입 선언 파일을 작성하지 않고, TypeScript와 JavaScript를 함께 쓸 수 없을까요?
1. tsconfig.json 파일에 "allowJs": true 옵션 추가
{
"include": ["src"],
"compilerOptions": {
"outDir": "build",
"target": "ES6",
"strict": true,
"allowJs": true
}
}
2. JSDoc 작성
- JavaScript 파일은 그대로 유지하면서 TypeScript가 제공하는 보호 장치를 사용하고 싶다면 JSDoc을 사용하면 됩니다.
- 순수한 JavaScript 코드 안에서
@ts-check를 주석으로 추가하면 TypeScript처럼 타입 및 에러 체크가 가능합니다.
- 그 다음 JSDoc 형식의 주석을 작성하면 됩니다.
- 이렇게 할 경우 실제 서비스 중인 프로젝트라면 당장 오류가 날 걱정은 하지 않아도 될 것입니다.
// @ts-check
/**
* Initialize the project
* @param {object} config
* @param {string} config.url
* @returns {boolean}
*/
export function init(config) {
return true;
}
/**
* Exits then program
* @param {number} code
* @returns {number}
*/
export function exit(code) {
return code + 1;
}
참고
