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

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

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

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

Цитаты из упомянутой выше документации (выделено мной)

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

Если вы автор библиотеки и ваш пакет написан на TypeScript, включите автоматически сгенерированные файлы объявлений в свой пакет вместо публикации в Definitely Typed.

Из typescriptlang.org:

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

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

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

Если ваш пакет не написан на TypeScript, предпочтительным подходом является второй подход.

Оба как бы говорят:

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

typescript npm javascript typescript-typings definitelytyped
person bernie    schedule 01.07.2019    source источник
comment
Даже если пакет написан на чистом JavaScript, если авторы пакета сами поддерживают объявления, они должны распространяться как его часть. Это делают многие библиотеки, такие как moment, и это значительно упрощает управление версиями и зависимостями как для авторов, так и для их иждивенцев. Я думаю, вы читаете рекомендации, которые предполагают, что вы не контролируете тип пакета и применяете их слишком широко.   -  person Aluan Haddad    schedule 01.07.2019
comment
@AluanHaddad То, что вы говорите, полностью повторяет то, что я думал. Я не смотрел на moment.js, но я видел, что некоторые основные плагины Vue.js, написанные на JS, также публикуют свои собственные файлы объявлений, как вы описали. Возможно, я неправильно прочитал кавычки, но я понимаю, что они, по крайней мере, подразумевают, что DefinitelyTyped предпочтительнее. Хотя обоснование не приводится...   -  person bernie    schedule 01.07.2019
comment
Кстати, даже если это не отвечает на ваш вопрос, я просто говорю вам, что вы можете сгенерировать определение типа из документов, если они написаны хорошо. Так что, возможно, это требует меньших усилий, чем вы думаете   -  person Cristian Traìna    schedule 01.07.2019
comment
@bernie Принимаете ли вы участие в определениях? буду рада принять участие   -  person Avin Kavish    schedule 01.07.2019
comment
@AluanHaddad Если вы напишете это как ответ, я приму это   -  person bernie    schedule 04.07.2019
comment
@UniqIdentifierAssignedAtBirth Да, это было бы здорово! См. здесь: https://github.com/berniegp/mock-xmlhttprequest/issues/13#issuecomment-508450764 Извините за поздний ответ; Я должен был настроить некоторые вещи.   -  person bernie    schedule 04.07.2019

Ответы (1)


arrow_upward
3
arrow_downward

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

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

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.X.X -› нарушает несколько правил для объявлений типов

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

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

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

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

2.1.1. Плюсы

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

2.1.2. Минусы

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

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

2.2.1. Плюсы

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

  • Репозиторий DT поставляется с двумя дополнительными функциями:

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

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

2.2.2. Минусы

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

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

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

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

  • #P21# #P22#
    #P23# #P24# #P25# #P26#
    #P27# #P28# #P29#

  • Объем DT репо

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

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

person Tomasz Zabłocki    schedule 20.07.2019
comment
Отличная рецензия. Я бы сказал, что ошибки в объявлениях типов, предоставляемых модулем JS (например, для помощи в завершении кода), недостаточно, чтобы вызвать изменение основной версии в самом пакете. Я предполагаю, что это не соответствует строгому semver, но я думаю, что он обеспечивает схему нумерации выпусков, более соответствующую фактическому использованию библиотеки. - person bernie; 15.08.2019
comment
Хотя пример версии, очевидно, является крайним случаем, он не полностью гипотетичен и, как уже упоминалось, не соответствует требованиям. Кроме того, есть - person Tomasz Zabłocki; 28.08.2019
comment
Я думаю, что система съела последнюю часть вашего комментария! - person bernie; 29.08.2019
comment
@bernie, по-видимому, так оно и было. В последней части речь шла о том, что объявления типов имеют решающее значение для разработчиков машинописных текстов, поскольку речь идет о нарушенной компиляции, а не об отсутствии завершения кода. - person Tomasz Zabłocki; 29.08.2019