Зачем публиковать файл объявления TypeScript в DefiniteTyped для библиотеки Javascript?

Question

Я опубликовал две библиотеки Javascript на npm, и пользователи попросили определения типов TypeScript для них обоих.Я сам не использую TypeScript, и у меня нет планов переписывать эти библиотеки в TypeScript, но я все же хотел бы добавить файлы определения типов, хотя бы для лучшего завершения кода IntelliSense.Я ищу несколько советов по этому вопросу.

Я начал с чтения документов DefinitiveTyped проекта и документации по публикации файла объявлений для пакета npm ,Оба источника утверждают, что «публикация в организации @types на npm» является предпочтительным подходом для проектов, не написанных на TypeScript.

Почему это предпочтительнее публикации определений типов вместе с самой библиотекой через поле types вpackage.json?Я действительно не вижу смысла вовлекать в это третье лицо.Похоже, что обновление определений типов и их управление версиями в этом случае просто более сложное.

Цитаты из документации, на которую есть ссылки выше (выделено мной)

Из Определенно Типа:

Если вы являетесь автором библиотеки и ваш пакет написан на TypeScript , bundle автоматически сгенерированные файлы объявлений в вашем пакете вместо публикацииОпределенно типизированный.

От typescriptlang.org:

Теперь, когда вы создали файл объявления, следуя инструкциям этого руководства, пришло время опубликовать его в npm,Существует два основных способа публикации файлов объявлений в npm:

• , связываемых с вашим пакетом npm, или
• публикация в организации @types на npm.

Если ваш пакет написан на TypeScript , тогда первый подход предпочтителен.Используйте флаг --declaration для создания файлов объявлений.Таким образом, ваши объявления и JavaScript всегда будут синхронизированы.

Если ваш пакет не написан на TypeScript , то second - этоПредпочтительный подход.

Кажется, оба говорят:

if (isAuthor && lang === "typescript")
  bundle();
else
  publishOnDefinitelyTyped();

Answer 1

Руководства по публикации объявлений типов кажутся немного устаревшими и редкими в нескольких областях.

Я попытаюсь детально сравнить оба сценария.

1.Типы в комплекте с пакетом npm

1.1.С точки зрения потребителя упаковки

1.1.1.Плюсы

Как правило, типы пакетов в комплекте более удобны благодаря упорядоченному управлению зависимостями.

• нет необходимости в дополнительной зависимости @types (добавление зависимости пакета)
• нетнеобходимо синхронизировать версии между пакетом и его типами (обновление зависимости пакета)

1.1.2.Минусы

• ограниченные способы отказаться от использования пакетов связанных типов

  Включает случаи, когда потребителю необходимо изменить или заменить объявления типов.

  Процесс может быть значительно проблематичным в проектах с продуманными настройками сборки из-за уже ограниченных параметров конфигурации.

1.2.С точки зрения автора пакета

1.2.1.Плюсы

• Владелец библиотеки может выпускать исправления и обновления объявлений типов по своему усмотрению, с любой периодичностью или по расписанию
• без ограничений на сторонние или внешние зависимости типа
• обеспечение одновременной поддержки нескольких версий осуществляется так же, как и для фактического кода

1.2.2.Минусы

Наличие типов в комплекте с пакетом означает, что фактически каждый раз публикуется версия двух контрактов API.

Пример:

Давайте предположим, что библиотека предназначена для того, чтобы соответствовать семи версиям.

• последний выпуск -> 1.0.0
• основная версия повреждена из-за критического изменения -> 2.0.0
• сообщается о критической ошибке в объявлениях типов, релиз не работает для группы пользователей с проектами машинописи
• исправление в типах является серьезным изменением

Варианты для следующей версии:

A. 2.XX -> нарушает правила semver для объявлений типов

B. 3.0.0 -> нарушает правила semver для фактического кода

Вероятно, существует множество вариантов такого сценария.

2.Публикация в определенном типе репозитория

2.1.С точки зрения потребителя упаковки

2.1.1.Плюсы

• простой отказ через удаление зависимости @types

2.1.2.Недостатки

• Потребитель пакета отвечает за синхронизацию версий пакета и связанных типов

2.2.С точки зрения автора пакета

2.2.1.Плюсы

• не влияют на цикл выпуска пакета

• В репозитории DT есть две дополнительные особенности:

  • библиотека dts-lint дляутверждения типа и тестирование типа
  • глубокий анализ производительности и следа компилятора, включая различия между последней версией пакета и пакетом после модификаций PR.

  Может быть включен первый инструментв другой пакет репо с небольшими усилиями.Я не уверен, можно ли повторить анализ в своем собственном репозитории, но он содержит много ценных данных.

2.2.2.Минусы

• нестандартный способ поддержки прошлых выпусков

• график выпуска типа, ограниченный циклами обзора и выпуска DT

  Предполагая, что создатель DefiniteTyped PRвладелец пакета @types, обычно требуется от одного до двух дней до слияния PR.Кроме того, существует небольшая задержка перед тем, как тип-издатель обновляет пакет @types npm, связанный с PR.

  Дополнительный процесс проверки применяется в случаях, когда PR является первым вкладом автора в данный пакет.

• с использованием внешних зависимостей

  В справочнике по TypeScript сказано:

  Если ваши определения типов зависят от другого пакета:

  Не объединяйте его с вашим, храните каждый в отдельном файле.

  Также не копируйте объявления в вашем пакете.

  Зависит от пакета объявлений типа npm, еслион не упаковывает свои файлы объявлений.

  Судя по количеству избыточных типов утилит, они вряд ли соблюдаются.

  Автору объявлений типов разрешено использовать смежный репозиторий DTтипы.В зависимости от пакетов из этого списка требуется, чтобы они были в белом списке типов-издателей.

  Новые пакеты могут быть добавлены в белый список путем отправки PR издателю типов.Потребовалось более двух недель, чтобы объединить мой пиар.Я не знаю, нормально ли это, так как я подал один пиар.

• Объем репозитория DT

  У меня нет сравнения или опыта кросс-IDE, но что касается сред JetBrains, объем памяти полностью проиндексированного проекта репо DT сделанIDE непригоден для использования.

  Отключение перекомпиляции при изменениях помогает в некоторой степени.Разочарование IDE можно обойти, удалив содержимое репозитория DT, не относящееся к интересующему пакету.