Что такое файл с расширением .d.ts?

.d.ts файлы: TypeScript Declaration Files

Что это

.d.ts файлы (Declaration Files) это файлы которые содержат только типы TypeScript, без реализации. Используются для описания типов JavaScript библиотек или для распространения типов отдельно от кода.

Структура

// index.d.ts — только типы, ноCode
export interface User {
  id: number;
  name: string;
  email: string;
}

export function getUser(id: number): Promise<User>;
export function createUser(name: string, email: string): Promise<User>;

export class UserService {
  constructor(apiUrl: string);
  fetchUser(id: number): Promise<User>;
}

Зачем нужны

1. Типы для JavaScript библиотек

// jquery.d.ts
declare function $(selector: string): JQuery;
declare namespace $ {
  function ajax(settings: AjaxSettings): void;
}

1. Распространение типов отдельно

# npm install lodash
# npm install --save-dev @types/lodash

1. Документирование API

// api.d.ts
export function calculatePrice(
  quantity: number,
  unitPrice: number,
  discountPercent?: number
): number;

Создание собственных типов

// math.ts
export function add(a: number, b: number): number {
  return a + b;
}

// При компиляции TypeScript создаёт:
// math.js (JavaScript код)
// math.d.ts (TypeScript типы)

// math.d.ts
export declare function add(a: number, b: number): number;

tsconfig.json для генерации .d.ts

{
  "compilerOptions": {
    "declaration": true,
    "declarationDir": "./dist",
    "emitDeclarationOnly": false,
    "outDir": "./dist"
  }
}

DefinitelyTyped

@types это пакеты на npm с типами для популярных библиотек

npm install --save-dev @types/node
npm install --save-dev @types/express
npm install --save-dev @types/react

Типичный package.json

{
  "name": "my-library",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ]
}

Namespace Declaration

// globals.d.ts
declare namespace MyApp {
  interface Config {
    apiUrl: string;
    debug: boolean;
  }
  
  const config: Config;
  function init(cfg: Config): void;
}

// Использование
MyApp.config.apiUrl = 'https://api.example.com';
MyApp.init(MyApp.config);

Triple-slash Directives

// /// <reference path="./other.d.ts" />
declare interface Window {
  myGlobal: string;
}

Плюсы

✅ IDE автодополнение ✅ Type checking ✅ Документирование ✅ Распространение типов

Минусы

❌ Дополнительный файл ❌ Может устаревать ❌ Сложность для маленьких проектов

Когда создавать

✅ Библиотеки на npm ✅ Публичные API ✅ Большие проекты

❌ Маленькие скрипты ❌ Внутренние инструменты