JS 프로젝트에 Typescript 행 추가

만약 당신이 JS 세계에서 한동안 머물렀다면, 타자 스크립트가 매우 유행하는 것을 알아차렸을 것이다.하지만 그것부터 시작하지 않으면 타자 스크립트를 추가하는 것은 고통스러울 수도 있다.
꼭 그렇지는 않아요. 다섯 줄에서 케이크를 먹을 수도 있고 케이크를 먹을 수도 있어요!

일단 타자를 왜 쳐요?

논쟁의 초점은 당신의 자바스크립트 코드에 Typescript가 피할 수 있는 오류가 반드시 발생하기 시작할 것이다. 특히 프로젝트가 점점 커질 때이다.
켄트 도드(Kent C.Dodds)는 아직 유형 시스템이 없다면 유형 시스템을 추가하는 것도 테스트에 들어가는 첫걸음이라고 말했다.
How to add testing to an existing project
모든 사람들이 뚜렷한 오류를 잡고 싶어 한다. 예를 들어 하나string를 통해 하나number가 나타날 것으로 예상되고 달콤한 IDE가 자동으로 완성되며 변경할 때 더욱 자신감을 가지게 된다.
믿으셨을지도 모르지만, 순수한 JS 프로젝트에 깊이 빠졌습니다. Typescript를 추가하는 것은 큰 골칫거리인 것 같습니다.좋은 해결 방안이 하나 있는데 하나의 선이 필요하다.

/** @param {number} value */
function onlyGiveMeNumbers (value) {
    return Math.round(value)
}

번영!특별한 JSDoc 댓글에 감사드립니다. 충분히 타자를 칠 수 있습니다.너는 단지 2*를 사용하여 여러 줄의 주석을 시작할 수 있도록 확보하기만 하면 된다.
지금 사용할 수 없는 경우에는 다음 세 가지 옵션이 있습니다.

각 파일의 상단에 // @ts-check 추가

VS 코드를 사용하는 경우 checkJs 옵션 1개

프로젝트 루트 디렉터리에 tsconfig.json 또는 jsconfig.json

// jsconfig.json
// if you make a tsconfig.json make sure to add "checkJs": true

{
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
  "compilerOptions": {
    "module": "es2020",
    "moduleResolution": "node",
    "target": "es2020",
    "lib": ["dom", "es2019"],
    "checkJs": true,
    "noEmit": true,
    "strict": false,
    "baseUrl": ".",
  }
}

코드가 자바스크립트라도 TS 언어 서버를 사용하여 코드를 검사하는 IDE가 많기 때문이다.checkJstrue로 설정하면 기존 내용을 이용할 수 있지만 JSDoc는 어느 곳에서든 형식을 any로 설정하지 않고 편집기에 필요한 정보를 제공할 수 있습니다.
TS에 비해 다음과 같은 이점이 있습니다.

컴파일 절차 없음

초간단 설정

최종 묶음 크기에 영향을 미치지 않음

자기 기록

TS

의 전체 버전과 거의 동일
마지막으로 JSDoc 가입을 다시 고려할 수도 있습니다.표준 JSDoc는 Typescript의 기능과 일치하지 않습니다.
만약 당신이 정부측JSDoc documentation(JSDoc, 당신이 원한다면)을 따른다면, 어떤 일들은 당신이 할 수 없거나, 설치하기가 매우 번거롭거나(TS와 비교하면) 심지어는 당신에게 영향을 주지 않을 수도 있습니다.
봐라, 나는 두 가지 타자 세계가 있다고 생각한다.

응용 논리

도서관 부지

응용 프로그램 논리에서 입력은 일반적으로 매우 직접적이고 (2와 비교) 일치성과 철저성을 확보해야 한다.
예를 들어 관리 임무를 처리하는 프로그램이 있다고 가정하면 핵심 영역의 유형을 정의한 다음에 이 영역이 필요한 함수와 방법이 모두 이런 유형인지 확인해야 한다.

모든 도메인을 정의합니다.

/**
 * @typedef Quest
 * @prop {string} target What you should hunt
 * @prop {boolean} completed Whether the quest is completed or not
 */

/**
 * @typedef QuestBoard
 * @prop {string} name The board's name
 * @prop {Quest[]} quests All the quests on this board
 */

이 항목들이 필요한 모든 곳을 입력하십시오.

/**
 * @param {string} task
 * @return {Quest}
 */
function createQuest (target) {
    return { target, completed: false }
}

/**
 * Given a name and list of quests, create a new Quest Board.
 *
 * @param {string} name Name for the quest board.
 * @param {Quest[]=} quests optional list of quests.
 * @return {QuestBoard}
 */
function createQuestBoard (name, quests=[]) {
    return { name, quests }
}

만약 대부분의 입력이 응용 프로그램 영역에 있다면, JSDoc는 귀하께 존경할 만한 서비스를 제공할 것입니다.그러나 도서관 분야에 들어갈 때 일이 좀 모호해질 수 있다. 주로 범형 때문이다.

As a quick explanation, Generics, are a placeholder type. You tell your code that it will receive a "something", but whatever it is, here is how you should handle it. Without Generics you might have to duplicate functions for each kind of type you expect it to receive.

다른 사람이 사용할 수 있는 라이브러리를 만들 때 사람들이 무엇을 보낼지 예측할 수 없기 때문에 준비를 해야 한다. 나는 타자 전문가가 아니지만 무서운 라이브러리 타자를 본 적이 있다. JSDoc가 처리할 수 없을 수도 있다(또는 가능?).


탄나 린슬리⚛️

⚔️⚔️⚔️
2021년 2월 22일 오후 23:20
만약 당신이 이런 요구를 하지 않는다면, JSDoc는 여전히 자신을 잘 처리할 수 있을 것이다.

/**
 * @template SomeGenericType
 *
 * @typedef WrappedData
 * @prop {SomeGenericType} data
 * @prop {Object} meta
 * @prop {number} meta.createdAt
 */

/** @template DataType */
class DataWrapper {
    /** @param {DataType} data */
    constructor (data) {
        this.wrapped = this.wrap(data)
    }

    get data () {
        return this.unwrap()
    }

    /**
     * @private
     * @param {DataType} data
     * @return {WrappedData<DataType>}
     */
    wrap (data) {
        return {
            data,
            meta: {
                createdAt: +(new Date()),
            },
        }
    }

    /** @private */
    unwrap () {
        return this.wrapped.data
    }
}

// A generic wrapper that will work with any random thing
const messageWrapper = new DataWrapper('Hello, World!')

/** @extends {DataWrapper<Quest>} */
class QuestWrapper extends DataWrapper {}

const quest = createQuest('Capture a Shogun Ceanator!')
// This wrapper will only accept Quest type things
const questWrapper = new QuestWrapper(quest)

대부분의 범용 처리 예시와 마찬가지로 이것은 약간 가식적이고 유용하지 않지만 그래도 JSDoc는 통과할 방법을 강구했다.
하지만 JSDoc가 기록할 수 없는 일에 대해 당신은 무엇을 할 수 있습니까?
Typescript로 거의 모든 기능을 대등하게 수행할 수 있는 두 가지 팁이 있습니다.

당신이 편집한 비밀

이전 *.d.ts 파일

네가 편집한 작은 비밀

내가 전에 말했듯이, 당신의 편집기 (VS 코드일 수도 있음) 는 Typescript 언어 서버를 사용하여 당신의 코드를 해석하고 이해합니다.Vim에서도 같은 언어 서버를 사용하여 코드를 확인합니다(Neovim ftw).
이게 비밀이야!
내가 무슨 뜻이야?이것은 JSDoc 언어 서버가 아니라 Typescript 언어 서버입니다.
편집기가 코드를 이해하려고 할 때, 이것은 Typescript 매뉴얼을 통해 이해된다. 이것은 모든 JSDoc 내용을 이해하지만, 모든 Typescript 내용을 이해한다는 것을 의미한다.다음 예는 다음과 같습니다.

import { Quest } from 'quest'

class QuestMap {
    /** @param {ReturnType<QuestMap.toPersistence>} raw */
    static toDomain = (raw) => Quest.create(raw)

    /** @param {Quest} quest */
    static toPersistence = (quest) => ({ target: quest.target, completed: quest.completed })
}

만약 당신이 이 줄을 본다면:/** @param {ReturnType<QuestMap.toPersistence>} raw */편집기가 타자 스크립트 렌즈를 통해 물건을 검사하고 있기 때문에 타자 스크립트만 있는 기능 ReturnType 이 여전히 유효하다는 것을 볼 수 있을 것이다.
나는 아직 그것으로 광범위한 테스트를 한 적이 없지만, 그것은 보통 JSDoc 문법으로 작성할 수 있는 Typescript 특성에 적용된다.
그것은 확실히 한계가 있다. 예를 들어 나는 그것을 일하게 할 수 없다.

// some function that returns an arbitrary number of Promise<boolean>
const getBools = () => [Promise.resolve(false), Promise.resolve(true)]
const getString = async => 'Hello'

async function tryToTypeThis () {
    await Promise.all([
        ...getBools(),
        getString(),
    ])
}

async function jsDocPlease () {
    const promises = [...getBools(), getString()]

    // ???
    await /** @type {PromiseConstructor['all']<boolean | string>} */ (Promise.all(promises))
}

const getBools: () => Promise<boolean>[] = () => [Promise.resolve(false), Promise.resolve(true)]
const getString: () => Promise<string> = async => 'Hello'

async function canTypeThis () {
    await Promise.all<boolean | string>([
        ...getBools(),
        getString(),
    ])
}

이것은 다른 정성스럽게 설계된 예이다. 나는 당신이 이런 코드를 작성해서는 안 된다고 생각하지만, 그 목적은 JSDoc가 한계에 도달했다는 것을 보여주는 것이다.
하지만 해결책이 하나 더 있다.

무골호인.d, ts 파일

이전 설정에서 checkJs 을true로 설정해야 합니다. 편집기 형식의 기본 검사 .ts 파일이고, 정의된 파일은 이 파일에 속하기 때문입니다.
정의 파일을 작성하는 의미가 무엇인지 생각할 수도 있고, 완전한 타자 스크립트를 사용해도 괜찮다.
이 점에 대해 말하자면 Typescript에서도 최종적으로 정의 파일을 작성하여 JSDoc만 사용하는 모든 장점을 제공할 수 있습니다.
정의 파일을 사용하면 Typescript의 전체 기능 집합을 얻을 수 있지만, 다시 한 번 설명하자면, 절차를 컴파일할 필요가 없습니다. 구축 과정에서 항목이 JS 프로젝트이기 때문에 무시됩니다. (이것은 100% 확정된 것이 아닙니다. 만약 제가 틀렸다면 바로잡아 주십시오.)

/** @typedef {import('./types.d.ts').ComplexType} ComplexType */

/** @type {ComplexType} */
const complexVariable = {}

그럼 JSDoc를 사용해야 하나요?

만약 당신의 프로젝트가 거의 JS라면 TS를 전환하고 싶지만 비용이 너무 높아서 고려할 수 있는 옵션일 수도 있습니다.
TS로 전환하면 일이 입력되고 기록된다는 장점도 있다.
물론 JSDoc는 완벽하지 않다. 동등한 TS보다 훨씬 상세하고 때로는 몇 가지 문제의 답을 찾기 어렵다.
마지막으로 당신의 선택을 평가하고 당신에게 가장 적합한 선택을 하세요.

일부 유용한 자원

JSDoc를 작성할 때 실제로는 두 가지 문법을 사용할 수 있다. 하나는 JSDoc 공식 사이트에서 기술한 문법이고, 다른 하나는 패키지 컴파일러 문법이다.
CCS에는 클로즈업 컴파일러만 이해할 수 있는 추가 기능이 있습니다. 그러나 JSDoc에서 일부 기능을 사용했기 때문에 거리가 다를 수 있습니다.

Closure Compiler Syntax

Google은 TS 언어 서버에 의존하여 Google JSDoc 주석을 검사하기 때문에 Typescript 자체의 JSDoc 참고를 보고 지원하는 내용을 이해하는 것이 도움이 됩니다.

Typescript's JSDoc reference

Official JSDoc site

기타 링크

A basic Cheatsheet

Joshua's JSDoc Cheatsheet (a lot more complete)

만약 당신이 이 글을 좋아한다면, 당신은 나에게 더 많은 관심을 가질 수 있습니다: D