Как типизировать стороннюю JavaScript-библиотеку, если нет доступа к её исходному коду?

Что такое файлы деклараций

Когда вы используете стороннюю JavaScript-библиотеку в TypeScript, компилятор не знает о её типах. Чтобы исправить это, создаются файлы деклараций с расширением .d.ts. Они содержат только описания типов, без реализации. Это позволяет TypeScript проверять корректность использования библиотеки и предоставлять автодополнение в редакторе.

Способы типизации

Первый способ — установить готовые типы из репозитория DefinitelyTyped. Для этого выполняется команда npm install @types/имя_библиотеки. Например, для библиотеки lodash: npm install @types/lodash. Это самый простой путь, если типы уже существуют.

Второй способ — создать собственный файл деклараций. Если готовых типов нет, вы можете описать библиотеку вручную. Для этого создаётся файл, например, my-library.d.ts, и в нём объявляется модуль:

declare module 'my-library' {
  export function doSomething(value: string): number;
  export const version: string;
}

Затем этот файл подключается в tsconfig.json через поле include или files.

Практический пример

Предположим, у вас есть библиотека old-utils, которая не имеет типов. Вы создаёте файл old-utils.d.ts:

declare module 'old-utils' {
  export function formatDate(date: Date): string;
  export function parseJSON(text: string): any;
}

Теперь в коде можно импортировать функции с проверкой типов:

import { formatDate } from 'old-utils';
const dateStr = formatDate(new Date()); // OK

Когда применять

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

Вывод: типизация сторонних библиотек — важная часть работы с TypeScript. Используйте готовые типы, когда они есть, и создавайте собственные декларации для редких или внутренних библиотек. Это обеспечивает безопасность типов и улучшает разработку.