JSDoc ( .js에서 타입 적용하기 )

해당 포스트는 VSCode에서 JSDoc을 이용하는 방법에 대해서 정리한 포스터입니다.

😮 JSDoc

JavaScript의 일반적인 주석과 형태가 조금 다르게 사용됩니다.
JSDoc을 변수나 함수에 이용하면 마우스 hover 시 나오는 설명을 추가할 수 있습니다.
또한 JSDoc을 이용하면 .js에서도 TypeScript를 사용하는 것처럼 타입을 체크할 수 있습니다.

/* 일반적인 주석 */

/** JSDoc */

1. 소스 코드 전체에 타입 적용하기

.js의 최상단에 // @ts-check를 기재하면 됩니다.
부분적으로 타입을 적용할 거라면 작성하지 않아도 됩니다.

// @ts-check

// 여기서 위의 "@ts-check"를 작성하지 않으면 변수 "str"을 "string"으로 인지하지만 "str = 10;"에서 에러를 발생하지는 않습니다.

// 즉시 실행 함수
(() => {
  /** @type { string } */
  let str = "apple";

  str = 10; // error: 'number' 형식은 'string' 형식에 할당할 수 없습니다.
})();

2. 기본 타입들

// @ts-check

/** @type { string } */
/** @type { number } */
/** @type { boolean } */
/** @type { * } */
/** @type { ? } */
/** @type { { name: string; age: number } } */
/** @type { (x:number, y:number) => number } */

// optional, 배열 등 TypeScript의 문법을 사용하는 것처럼 사용이 가능합니다.
// 더 자세한건 다른 블로그들에서 설명을 잘해줘서 필요하면 찾아서 사용하면 됩니다.

3. 타입 정의 및 사용

// @ts-check

/**
 * 타입 정의 방법 1)
 * 
 * @typedef { { name: string; age: number } } Person
 */
/**
 * 타입 정의 방법 2)
 * 
 * @typedef { Object } Person
 * @property { string } name
 * @property { number } age
 */

// 즉시 실행 함수
(() => {
  /** 
   * 아래처럼 정의된 타입을 적용할 수 있고, typescript의 utility도 사용이 가능합니다.
   * 
   * @type { Pick<Person, "name"> } */
  let person = {
    name: "john",
  };

  person = 10; // 'number' 형식은 'Pick<Person, "name">' 형식에 할당할 수 없습니다.
})();

4. 타입 불러오기

@typedef { import("경로").타입명 } 사용할이름

/**
 * 전역적으로 불러오기
 * 
 * @typedef { import("../@types/user").User } User
 */

/** @type { User } */
const user = {
  id: 1,
  name: "john",
  age: 26,
  gender: true,
};

/** 
 * 해당 타입에서만 사용하도록 불러오기
 * 
 * @type { import("../@types/user").User } */
const user = {
  id: 1,
  name: "john",
  age: 26,
  gender: true,
};

5. DOM에서 사용하기

DOM에서 사용하는 타입들( HTMLElement 등 )은 VSCode의 extensions에 들어가 있는데 아마도 VSCode를 설치하면 자동으로 같이 다운로드 되는 것 같습니다. ( 확실하지 않음 )

(() => {
  // 아래 코드는 이제 "Element | null"이라는 타입이 됩니다.
  const $submit = document.querySelector(".submit");

  // 따라서 아래와 같이 사용해야 합니다.
  // (1)
  $submit?.classList.add("active");

  // (2)
  if(!($submit instanceof HTMLButtonElement)) return;
  // 여기서부터는 "$submit"이 "HTMLButtonElement"가 됩니다.
  $submit.classList.add("active");
})();

😶 마무리

여태까지 함수를 정의할 때는 항상 JSDoc을 사용했었습니다.
하지만 그게 어떤 이름의 문법인지 몰랐고 이런 많은 기능들을 지원해주는지 전혀 몰랐습니다.
평소에는 TypeScript를 사용하는데 이번에 코드 스테이츠의 과제를 하면서 JavaScript를 사용했어야 했고, 타입이 없어서 불편함을 느끼던 중에 구글링을 통해서 JSDoc이라는 기능에 대해 알게 되었습니다.
앞으로 JavaScript를 사용하는 일이 생기면 특별한 이유가 없다면 무조건 JSDoc을 이용할 것 같습니다.

📮 레퍼런스

1. poiemaweb - JSDoc
2. typescript.github.io - JSDoc