[JavaScript] TypeScript 처럼 사용하는 방법 - JSDoc

dhkim 11월 14, 2023

 



 이번 포스팅에서는 JavaScript를 TypeScript와 같이 변수 타입에 대한 정의와 규칙을 보다 세밀하게 정의하고, VS Code에서의 툴팁 참조를 더 쉽게 할 수 있는 JSDoc 활용 및 사용법을 예제와 함께 다룹니다.

해당 포스팅에서는 VS Code와 오류를 시각적으로 코드에 보여주는 "Error Lens" Extension을 사용합니다.


1. TypeScript 오류 발생 시키기.    

    @ts-check를 Javascript 파일의 최 상단에 선언합니다.
Javascript를 module로 사용하는 경우나, 'use strick' 으로 사용하는 경우와 같이 IDE에서 TypeScript의 오류 구문을 보여주게 됩니다.
(단, 오류가 발생해도 브라우저 콘솔에 오류로 출력 되지는 않습니다.)


1) 오류 예시 : number 타입 변수에 boolean 값을 넣은 경우


2) 오류 건너뛰기

    @ts-expect-error 혹은 @ts-ignore 문구를 사용하여, 일부 오류를 무시할 수 있습니다.




2. Enum

    JSDoc의 @enum 키워드를 사용하여 enum형식을 정의합니다. 괄호({})에는 enum의 반환형을 기입합니다.


1) 정의

1
2
3
4
5
6
/** @enum {string} */
const LOG_LEVEL = {
    DEBUG    : "DEBUG",
    ERROR    : "ERROR",  
    WARNING  : "WARNING"
}


2) 타입 정의

    앞서 다룬 "@ts-check"를 적용할 경우 아래 사진과 같이 오류를 출력해 줍니다.

더불어, @type을 사용하면 정의한 'LOG_LEVEL' 외에도 number, string, boolean 등의 타입을 명시할 수 있습니다.




3. Function

    Enum 파트에서 정의한 로그 레벨을 활용한 함수(function)에 대한 주석문서 예시입니다.

1) 인자, 반환값 명시

    @params, @returns


2) 화살표 함수에서의 명시

    @type을 사용하여 간단한 유틸성 함수의 경우에서 인자와 반환값을 명시합니다.



4. 자료형 정의

    선언된 변수의 주석 외에도 TypeScript의 Interface와 같이 자료형에 대한 정의를 JSDoc을 통해 문서화 할 수 있습니다. 더불어, @ts-check를 통해 오류 예방과 생산성 향상을 기대해볼 수 있습니다.


1) 정의

    @typedef 으로 명시할 자료형의 명칭을 작성합니다.

    @properyt 의 괄호({})에 타입을 명시하고 자료형을 구성할 요소를 작성합니다.


2) 예제

    저장할 행 단위의 자료와 행 단위 데이터(ISaveRowData)를 요소로 갖는 배열 자료형(ISaveData)을 명시하는 예제입니다.

sourceData를 정의하는 타입은 각각 18,19,20 라인이 모두 동일한 의미를 갖습니다.

  • 4 : ISaveData - 배열 단위 자료형
  • 9 : ISaveRowData - 행 단위 자료형
  • 18 : 데이터 셋 단위로 명시
  • 19 : 행 단위 데이터로 명시 (1)
  • 20 : 행 단위 데이터로 명시 (2)




[전체 예제코드]

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
// @ts-check

(() => {

    /** @type {number} */
    let number = 11;

    //@ts-expect-error
    number = '';

    //@ts-ignore
    number = true;


//#region  :: Enum

    /** @enum {string} */
    const LOG_LEVEL = {
        DEBUG    : "DEBUG",
        ERROR    : "ERROR",  
        WARNING  : "WARNING"
    }

    /** @type {LOG_LEVEL} */
    const temp = LOG_LEVEL.DEBUG;

    /**
     * 이력 남기기.
     * 
     * @param   {LOG_LEVEL}   logLevel 로그 수준
     * @param   {String}      text 내용
     * @returns {String}
     */
    function History(logLevel, text) {
        const fullText = `[${logLevel}] ${text}`;

        console.log(fullText);

        return fullText;
    }

    /** @type {(logLevel:LOG_LEVEL, text:String) => String} */
    const Arrow_History = (logLevel, text) => {
        const fullText = `[${logLevel}] ${text}`;

        console.log(fullText);

        return fullText;
    }


//#endregion


//#region   :: Data Format

    /**
     * @typedef ISaveData
     * @type {ISaveRowData[]}
     */

    /**
     * @typedef ISaveRowData
     * @property {String} seq
     * @property {String} product
     * @property {Number} price
     * @property {*} expireDt
     * @property {boolean} soldOut
     */

    /**
     * 저장하는 함수
     *
     * @param {ISaveData} inputData 저장하고자 하는 값
     * @returns {boolean}
     */
    function SaveData(inputData) {
        
        /** Save Logic */

        return true;
    }



    /** @type {ISaveData} */
    /** @type {ISaveRowData[]} */
    /** @type {Array<ISaveRowData>} */
    const sourceData = [
        { seq: '001', product: 'apple'   , price: 1000, expireDt: '2023-12-31', soldOut: false  },
        { seq: '002', product: 'banaa'   , price: 2000, expireDt: '2024-01-00', soldOut: false  },
        { seq: '003', product: 'melon123', price: 4000, expireDt: '2033-10-01', soldOut: true   },
        { seq: '004', product: 'grape'   , price: 1500, expireDt: '2023-11-15', soldOut: false  },
        { seq: '005', product: 'cherry'  , price: 4400, expireDt: '2023-11-15', soldOut: true   },
    ];

    SaveData();

//#endregion 

})()

0 댓글