[TS] tsconfig.json,정의 파일(d.ts),JSDocs

tsconfig.json파일, 정의 파일(d.ts)과 JSDocs에 대해
공부한 기록을 남기려고 한다.

tsconfig.json

• 먼저 프로젝트를 생성해준다.

$ npm init -y

• 그리고 tsconfig.json 파일을 생성해준다.

//tsconfig.json
{
  "include": ["src"],
  "compilerOptions": {
    "outDir": "build",
    "target": "es6",
    "lib": ["es6"],
  }
}

include

• include는 JS로 컴파일하고 싶은 디렉터리를 지정할 수 있는 배열이다.
• 컴파일하고자 하는 TS 파일들이 있는 모든 디렉터리를 의미한다.

compilerOptions

• 해당 객체는 이름 그대로 컴파일 옵션이다.
• outDir
  • outDir는 JS파일이 생성될 디렉터리이다.
  • 위의 include 배열에 있는 TS 파일들을 컴파일했을 때 생성된 JS파일이 위치할 디렉터리를 지정한다.
• target
  • 생성할 JS파일의 버전을 설정할 수 있다.
• lib
  • 타겟 TS 파일에서 쓰일 기본 정의 파일을 지정한다.

---

TS에서 import를 사용할 때 생기는 문제가
크게 두 가지가 있다.

1. 외부 모듈을 사용하는데 정의 파일이 없을 때 (패키지 or 라이브러리가 JS로만 만들어졌을 때)
2. 다른 JS 파일을 사용해서, 타입 정의가 안 되어 있을 때

두 문제를 해결하는 방법이 각각 정의 파일 생성과 JSDocs이다.

 

정의 파일

• 정의 파일은 말 그대로 타입 정의를 해놓은 파일이다.
• 타입 정의는 TS에게 JS 코드의 타입, 반환 값을 설명해 주기 위해 사용하는 것이다.

보통의 npm 라이브러리의 정의 파일은 모두 만들어져있다.
이에 관해서는 후에 기록할 것이다. 이번 기록은 정의 파일이 어떤 식으로 작성되는지에 대한 기록이다.

//test.js
export const start = (config) => {
  return true;
};

export const err = (code) => {
  return code;
};

• 먼저 위의 파일을 모듈로 생각해보자.(설치한 모듈)
• 그리고 TS 파일에서 위의 모듈을 사용하려고 한다.

//index.ts
import {start,err} from 'test'

• 위와 같은 에러가 뜨는데 test에 대한 정의 파일이 없기 때문이다.
• 때문에 test.d.ts (정의 파일)을 만들어준다.

//test.d.ts
interface Config {
  ready: boolean;
}
declare module "test" {
  function start(config: Config): boolean;
  function err(code: number): number;
}

• 위와 같이 두 함수에 대한 call signature을 포함한 정의 파일을 만들어주면, 

• 에러가 사라지고, call signature가 자동으로 보이는 것을 확인할 수 있다.

모듈에 의한 문제는 위와 같이 정의 파일로 해결할 수 있다.

JSDocs

• JSDocs는 주석으로 함수의 인자와 반환 값의 타입을 알려주는 기능을 한다.
• 기존 JS 프로젝트에서 TS를 도입한다거나, TS의 보호를 받고 싶다고 하면 JSDocs를 사용하면 된다.

그대로 위의 test.js 파일을 사용하는데 이번엔 모듈이 아닌 파일로 import 해보자.

//index.ts
import {start,err} from './test.js'

• 위처럼 test.js 파일에서 함수들을 가져오면 TS에서 추론은 하지만, 확실한 보호를 받기 어렵다.
• JSDocs를 사용해 함수의 인자와 반환값의 타입을 지정해보자.
• 먼저 test.js 최상단에 아래 코드를 추가해준다.

//@ts-check
//->ts의 보호를 받겠다는 뜻
export const start = (config) => {
  return true;
};

export const err = (code) => {
  return code;
};

• 그리고 함수 위에 /** 주석을 추가해주면, vscode는 엔터를 눌렀을 때 자동으로 JSDocs 형식이 만들어진다.

/**
 * 
 * @param {*} config 
 * @returns 
 */

export const start = (config) => {
  return true;
};

• 위와 같이 만들어졌다.
• 첫 번째 주석은 함수에 대한 설명
• 두 번째는 인자의 타입, 이름
• 세 번째는 반환값의 타입이다.

/**
 * start project
 * @param {object} config
 * @param {boolean} config.ready 
 * @returns {boolean}
 */

export const start = (config) => {
  return true;
};

• 위처럼 작성해주면 된다.
• 인자가 object 타입일 경우 props의 타입도 지정해주면 된다.

• 이제 TS도 확실하게 알게 되었다.

참고

https://nomadcoders.co/typescript-for-beginners

타입스크립트로 블록체인 만들기 – 노마드 코더 Nomad Coders

https://www.typescriptlang.org/docs/handbook/

The starting point for learning TypeScript