Как типизировать данные из сторонних NPM пакетов?

Типизация данных из сторонних NPM-пакетов

При работе с JavaScript-экосистемой типизация данных из сторонних пакетов — это критически важная задача для поддержания надежности кодовой базы. Вот основные подходы и лучшие практики.

1. Использование встроенных типов (@types-пакеты)

Для пакетов, написанных на JavaScript, сообщество TypeScript активно создает декларации типов в репозитории DefinitelyTyped. Они устанавливаются через npm с префиксом @types/.

npm install --save-dev @types/lodash

После установки TypeScript автоматически подхватит типы. Это наименее затратный способ, но он зависит от сообщества — типы могут быть устаревшими или неполными.

2. Проверка наличия встроенных типов в самом пакете

Многие современные пакеты поставляют типы "из коробки". В их package.json указано поле types или typings:

{
  "name": "modern-package",
  "version": "2.0.0",
  "types": "./dist/index.d.ts"
}

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

3. Создание собственных деклараций (.d.ts файлы)

Когда типы отсутствуют, необходимо создавать файлы деклараций. Поместите их в директорию src/types/ или @types/ в корне проекта.

Пример для модуля без типов:

// src/types/legacy-module.d.ts
declare module 'legacy-module' {
  export function calculate(data: unknown): number;
  export const defaultCoefficient: number;
}

Для глобальных расширений используйте объявление в глобальной области:

// src/types/global.d.ts
declare global {
  interface Window {
    customMethod: () => void;
  }
}

4. Постепенная типизация через утилитарные типы

Используйте встроенные утилиты TypeScript для безопасной работы с частично типизированными данными:

import { SomeUnknownData } from 'untyped-package';

// Использование утверждений типа с проверкой
if (isValidData(data)) {
  const typedData = data as MyInterface;
}

// Частичная типизация через Partial и условные проверки
type PartialTypes = Partial<Record<string, unknown>>;
const safelyTyped: PartialTypes = unsafeData;

// Использование unknown с сужением типа
function processInput(input: unknown): string {
  if (typeof input === 'string') {
    return input.toUpperCase();
  }
  throw new Error('Invalid type');
}

5. Генерация типов через JSDoc (для постепенной миграции)

Если пакет имеет хорошую JSDoc-документацию, можно использовать tsc для генерации предварительных типов:

npx typescript --allowJs --checkJs --declaration --emitDeclarationOnly --outDir types src/

6. Использование утилит для анализа рантайма

Для сложных случаев, когда типы динамические, применяют guard-функции:

// type-guards.ts
import { SomeExternalData } from 'untyped-package';

export function isApiResponse(data: unknown): data is ApiResponse {
  return (
    data != null &&
    typeof data === 'object' &&
    'status' in data &&
    'body' in data
  );
}

// Использование
if (isApiResponse(externalData)) {
  // Теперь externalData полностью типизирован как ApiResponse
  console.log(externalData.body);
}

7. Настройка tsconfig.json для работы с типами

Оптимизируйте конфигурацию TypeScript для гибкой работы со сторонними типами:

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/types"],
    "types": ["node", "jest"],
    "skipLibCheck": false,
    "allowSyntheticDefaultImports": true
  },
  "include": ["src/**/*", "src/types/**/*.d.ts"]
}

Рекомендуемый рабочий процесс

1. Проверьте наличие @types/ пакета
2. Изучите package.json исходного пакета на наличие встроенных типов
3. Создайте минимальные декларации для критически важных частей
4. Используйте unknown и type guards для максимальной безопасности
5. Рассмотрите возможность создания PR с типами в DefinitelyTyped для помощи сообществу

Ключевые принципы: всегда начинайте с самых строгих типов (unknown), постепенно расширяя типизацию по мере изучения API пакета. Используйте модульное тестирование для ваших type guards, чтобы гарантировать корректность типов в рантайме. Помните, что качественная типизация сторонних пакетов значительно снижает количество runtime-ошибок и улучшает опыт разработки.