Что, если я скажу вам, что существует некий компромисс между простым Javascript со всей его гибкостью и структурой TypeScript? В этой краткой статье мы познакомимся с решением, которое мне нравится использовать в личных и профессиональных проектах.

Условие:

  • Некоторые базовые знания JavaScript/Typescript
  • Код Visual Studio (рекомендуется)
  • NodeJs, Deno или другие

Но сначала позвольте мне представить несколько концепций, прежде чем углубляться в конкретные примеры.

Введение

JSDoc – это API документации, созданный для JavaScript. Идея состоит в том, чтобы поместить некоторые аннотации в комментарии, чтобы объяснить: что, почему, кто и т.д.; назначение: переменной, функции, условия и т. д. Подробнее о JSdoc см. здесь и здесь.

Файл jsconfig.json позволяет вам установить некоторую информацию о конфигурации для проекта JavaScript в среде IDE, которая использует технологию LSP (например, VS Code). Мы не собираемся объяснять здесь все возможности, но это очень интересный способ настроить ваш проект с дополнительной пользовательской конфигурацией. Узнать больше можно здесь.

Цель этого файла в этом руководстве — установить для параметра «checkJs» значение «true».

«Когда checkJs включен, в файлах JavaScript сообщается об ошибках. Это эквивалентно включению // @ts-check в начало всех файлов JavaScript […]». — typescriptlang.org

{
  "compilerOptions": {
    "checkJs": true
  }
}

Я думаю, вы начинаете понимать, к чему все идет: мы собираемся использовать проверку типов TypeScript в наших файлах JavaScript. И с учетом сказанного, JSDoc позволит нам быть более точными и сложными во всем, что мы хотим определить.

Таким образом, целью этой статьи будет добавление некоторых объяснений к решению, которое я действительно считаю немного недооцененным и мало обсуждаемым.

С учетом сказанного, мы собираемся проиллюстрировать на примерах настройку конкретных элементов, которые я часто использую в своих проектах. Конечно, вы не увидите 100% всех возможностей, но у вас будет некоторый ключ, чтобы начать использовать его в своих проектах.

Чтобы лучше понять их, я действительно предлагаю вам скопировать примеры в вашу IDE, чтобы увидеть, как работают автозаполнения и ошибки.

Типизированная переменная

Типизированная переменная — это самый первый способ представить JSDoc. С аннотацией «@type» вы можете применить любой тип к переменной. Таким образом, вы можете гарантировать, что разработчик сможет иметь правильное автозаполнение (более связное, чем если бы тип был «любой») и не захочет присваивать ему неправильное значение.

Вот несколько основных примеров, которые демонстрируют некоторые случаи, которые вы хотели бы использовать.

Типизированная функция

После типизированной переменной и понимания основ того, как применить тип к элементу, следующий уровень — типизированные параметры функции.

На мой взгляд, это может быть наиболее важной стратегией для использования с JSDoc, поскольку она позволяет вам быть действительно явным и, возможно, избежать проверки типов параметров внутри функции с некоторыми уродливыми условиями, которые отягощают ваши логические (даже если, конечно, JSDoc и CheckJs не блокируют компиляцию JS, поэтому вы все равно можете использовать неправильные типизированные аргументы, и это будет работать).

Для этого мы будем использовать несколько ключевых слов: «@param», «@returns» и «@template».

Типизированный интерфейс

«@typedef» — очень полезная аннотация для документирования пользовательских сложных типов, которые вы хотите использовать несколько раз в своем коде. Например: раньше объект с некоторыми свойствами определялся как простая переменная и как параметр функции.

Вы также можете использовать «@callback», что очень похоже на то, как работает «@typedef», но полезно для определения типов функций.

Типизированные элементы класса

И последнее, но не менее важное: вы также можете добавить аннотацию, чтобы сделать элементы вашего класса более понятными. Если вы знакомы с ООП, то легко поймете, для чего они нужны: «@private», «@public», «@protected». ", "@override", "@extends" и "@implements".

Примечание: также может быть хорошей идеей использовать атрибут закрытого класса, если ваша среда достаточно новая.

Заключение

Я действительно думаю, что JSDoc — интересная стратегия для добавления типизированных элементов в проект JavaScript вместо использования TypeScript. В JSDoc есть гораздо более интересные вещи («@example», «@deprecated», «@author» и т. д.), и если вы не знаете об этом намного больше, я действительно приглашаю вас быстро прочитать документацию, это поможет вам написать более описательный код, даже на TypeScript!

Конечно, у этого решения есть свои преимущества, но также и недостатки, и в этот момент вам может быть интересно:

«Почему я должен использовать их вместо перехода на TypeScript?»

На мой взгляд, реального ответа нет: вы вольны выбирать. И не заставляйте меня говорить то, чего я не говорил, мне нравится использовать TypeScript для некоторых проектов, но иногда я просто чувствую, что будет достаточно просто написать простой JavaScript и добавить минимум типизированных элементов с помощью JSDoc, чтобы улучшить мой код.

Другой способ увидеть это, если вы хотите добавить типизированный материал в уже существующий проект JavaScript. В этом случае вам не нужно преобразовывать его в TypeScript, а просто настройте «jsconfig.json» с помощью «checkJs». На этом этапе вы сможете исправить проблемы с типизированными ассоциациями (вызов функции, назначение переменных) и, поверьте мне (поскольку я уже это делал), особенно если вы новичок, как я, вы столкнетесь с такими проблемами.

В заключение я бы сказал, что JSDoc может облегчить эксплуатацию машиной, интерпретацию человеком и понимание во время обмена. Так что не забудьте добавить JSDoc в следующий раз, когда захотите поделиться с кем-то кодом 😉.

Вот и все! Большое спасибо за прочтение моей первой статьи. Также особая благодарность QUEMARD Maël за помощь в написании этой статьи и FERREIRA Marianne за исправление моего опасного английского.

Дайте мне знать ваши мысли в комментариях!