Дополнение модулей TypeScript и обработка вложенных JavaScript-файлов

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

Типы для пакетов JavaScript#

Для обеспечения обратной совместимости и гибкости TypeScript позволяет авторам пакетов предоставлять определения типов для своих JavaScript-пакетов. Такие определения типов обычно хранятся в репозитории "DefinitelyTyped". Вы можете использовать область @types для установки этих определений типов, например, @types/react — это определение типов для пакета React.

После установки этих определений типов вы можете использовать пакет с уверенность в типобезопасности. Вот пример определения компонента React с поддержкой типобезопасности:

Дополнение модулей#

Хотя для большинства популярных JavaScript-пакетов доступны готовые определения типов в области @types, некоторые пакеты могут не иметь определений типов или иметь устаревшие. В таких случаях TypeScript предоставляет мощную функцию, называемую "дополнение модулей", для добавления определений типов для этих пакетов. Давайте рассмотрим пример:

Теперь вы можете использовать это дополненное определение типов в вашем коде:

Дополнение модулей позволяет не только добавлять определения типов для пакетов, но и расширять существующие определения типов. Например, вы можете добавить новое свойство к объекту window:

И использовать его в вашем коде:

В предыдущем посте мы говорили о проблеме с типами в библиотеке React Router, и нам пришлось преодолеть последствия, расширяя и дополняя существующий тип через файл пользовательской декларации.

Помните, что при использовании дополнения модулей критически важно обеспечить точность ваших определений типов путем тщательной проверки исходного кода JavaScript. Неправильные определения типов могут привести к ошибкам времени выполнения. В приведенном выше примере свойство window.foo должно быть строкой, которая существует в объекте window.

Глобальное дополнение#

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

Вы можете добавить определения типов для этой глобальной переменной следующим образом:

Теперь вы можете использовать ее в вашем коде TypeScript:

Совмещая дополнение модулей и глобальное дополнение, вы можете также расширять определения типов для прототипов JavaScript. Однако это обычно не рекомендуется, так как это может загрязнить глобальную область видимости.

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

Вложенные JavaScript-файлы#

В приведенных ранее примерах мы предполагали, что импорты могут быть разрешены через входной файл пакета. Однако некоторые пакеты экспортируют вложенные JavaScript-файлы без соответствующих определений типов. Рассмотрим пакет под названием foo со следующей структурой:

Пакет foo экспортирует файл index.js в качестве входной точки и также экспортирует директорию bar.

Чтобы дополнить определения типов для пакета foo, вы можете создать файл foo.d.ts:

Однако, если вы попытаетесь импортировать файл baz.js в TypeScript, вы столкнетесь с ошибкой:

Чтобы дополнить определения типов для файла baz.js, вам нужно создать отдельный файл baz.d.ts:

Это гарантирует, что TypeScript сможет найти модуль и его соответствующие определения типов:

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

Этот подход позволяет поддерживать структуру вашего кода TypeScript и его типобезопасность, даже при работе с вложенными JavaScript-файлами.