В TypeScript декларации типов (.d.ts файлы) играют ключевую роль для работы с внешними библиотеками и для обеспечения типизации в проектах, где часть кода написана на чистом JavaScript. Эти файлы не содержат реализаций функций или классов, они лишь описывают сигнатуры, интерфейсы и структуры данных, которые помогают компилятору проверять корректность кода.

Что представляют собой .d.ts файлы

.d.ts — это файлы деклараций, которые содержат описание типов без реализации. В них можно встретить объявления интерфейсов, типов, классов, функций, пространств имен и модулей. Компилятор использует их исключительно для анализа типов, но в итоговый JavaScript они не попадают. Это означает, что .d.ts — это своего рода “контракт” между кодом и компилятором.

Использование с внешними библиотеками

Очень часто .d.ts файлы применяются для подключения типов к библиотекам, написанным на JavaScript. Например, при установке пакета через npm можно отдельно добавить его типы через @types/имя_пакета. Эти декларации позволяют использовать сторонние библиотеки в TypeScript так, словно они изначально были написаны с поддержкой строгой типизации.

Пример:

import express from "express";
const app = express();
app.get("/", (req, res) => {
res.send("Hello World");
});

Благодаря наличию @types/express разработчик получает автодополнение, подсказки по типам Request и Response, а также проверку корректности использования API.

Собственные декларации типов

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

declare module "legacy-lib" {
export function doSomething(param: string): void;
}

После этого TypeScript позволит использовать библиотеку в коде, обеспечивая проверки типов.

Глобальные объявления

Помимо модульных деклараций, в .d.ts можно описывать глобальные объекты и переменные, доступные во всем проекте. Например, если у проекта есть глобальная переменная, можно объявить её следующим образом:

declare const VERSION: string;

Теперь в коде при использовании VERSION компилятор будет знать, что это строка, и сможет отследить ошибки.

Генерация деклараций из TypeScript кода

TypeScript также умеет автоматически генерировать .d.ts файлы из существующего TS-кода, если в tsconfig.json включен параметр declaration: true. Это особенно полезно при разработке библиотек: пользователи библиотеки получают готовые типы и могут интегрировать её в свои проекты без дополнительных усилий.

Совместное использование с JavaScript проектами

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