Как расширить типы внешней библиотеки, не создавая новый тип?

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

Расширение интерфейсов

Если библиотека экспортирует интерфейс, можно объявить интерфейс с тем же именем в том же модуле или глобальном пространстве. TypeScript автоматически объединит поля.

// types/library-augmentation.d.ts
import 'some-library';

declare module 'some-library' {
  interface User {
    age: number;
    role: 'admin' | 'user';
  }
}

Расширение модулей (module augmentation)

Для расширения экспортируемых типов модуля используется конструкция declare module 'имя-пакета'. Внутри можно добавлять новые поля к существующим интерфейсам или объявлять новые экспорты.

// global.d.ts
import 'express';

declare module 'express' {
  interface Request {
    user?: { id: string; name: string };
  }
}

Расширение глобальных типов

Если библиотека добавляет что-то в глобальную область (например, Window), можно использовать declare global внутри модуля.

export {};

declare global {
  interface Window {
    myLib: { init: () => void };
  }
}

Где это применяется

• Добавление кастомных полей в Request Express после middleware аутентификации.
• Расширение типов сторонних UI-библиотек (например, добавление пропсов к компонентам).
• Дополнение типов для плагинов, которые не имеют собственных деклараций.

Важно, чтобы файл с расширением был подключён в компиляцию (через include в tsconfig или импорт). Иначе TypeScript не увидит объединение.

Итог: declaration merging и module augmentation позволяют гибко адаптировать типы внешних библиотек под нужды проекта без создания новых типов и без форка пакета. Это особенно ценно при работе с legacy-кодом или плохо типизированными зависимостями.