TypeScript @ts-check и JSDoc в VanillaJS

TypeScript может помочь тебе в проверке простых файлов JavaScript, с помощью комментария // @ts-check. Также можно улучшить работу, добавив надлежащие JSDocs для описания функций, которые будут указывать информацию о типе в TypeScript.

Если мы создадим обычный файл JavaScript index.js и напишем в нём какую-то функцию - то заставить TypeScript проверить этот файл сможем, добавив // @ts-check.

// @ts-check

function greet() {
  return 1;
}

greet('Hello');

В данном случае мы получим ошибку: Expected 0 arguments, but got 1.

Также, с помощью JSDoc, мы можем добавить документацию для описания типа функции. Это можно сделать через /** */. VS Code автоматически сгенерирует звёздочку в каждой строке, при нажатии клавиши enter. Мы укажем что функция возвращает строку @return {string}.

// @ts-check
/**
 * @return {string}
*/

function greet(greeting) {
  return 2;
}
greet('Hello');

Получаем ошибку: Type '2' is not assignable to type 'string'. Для того что бы её исправить, мы вернем вместо цифры параметр greeting. Тип у greeting строка, но при наведении на неё мы получаем greeting: any.

Для исправления, добавляем в JSDoc @param, и говорим, что параметр функции строка - greeting, и указываем имя параметра.

// @ts-check
/**
 * @param {string} greeting
 * @return {string}
*/

function greet(greeting) {
  return greeting;
}
greet('Hello');

Если мы попытаемся передать число в качестве аргумента функции greet(1) - получим ошибку Argument of type '1' is not assignable to parameter of type 'string'. Также, при наведении курсора на функцию - получаем более детальную информацию о том, какой тип принимает функция и что она возвращает, не смотря на то что типы объявлены в JSDoc, а не встроены в функцию.

В JSDoc есть намного больше вариантов. Чем больше мы документируем свой JavaScript с помощью JSDoc, тем ближе мы можем приблизить его к почти стандартному взаимодействию с TypeScript.