Публикация

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

1. создание пакета npm с объявлениями
2. публикация в организации @types в npm.

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

В противном случае, мы рекомендуем отправить типы в DefinitelyTyped, которые опубликуют их в организации @types в npm.

Включение объявлений в ваш пакет npm

Если ваш пакет имеет основной файл .js, вам нужно указать основной файл объявления в вашем файле package.json также. Установите свойство types для указания пути к вашему скомпилированному файлу объявления. Например:

{
  "name": "awesome",
  "author": "Vandelay Industries",
  "version": "1.0.0",
  "main": "./lib/main.js",
  "types": "./lib/main.d.ts"
}

Обратите внимание, что поле "typings" синонимично с types, и может использоваться также.

Также обратите внимание, что если ваш основной файл объявления называется index.d.ts и находится в корне пакета (рядом с index.js), вам не нужно отмечать свойство types, хотя это рекомендуется.

Зависимости

Все зависимости управляются npm. Убедитесь, что все пакеты объявлений, от которых вы зависите, корректно указаны в секции "dependencies" в вашем package.json. Например, представим, что мы создали пакет, который использовал Browserify и TypeScript.

{
  "name": "browserify-typescript-extension",
  "author": "Vandelay Industries",
  "version": "1.0.0",
  "main": "./lib/main.js",
  "types": "./lib/main.d.ts",
  "dependencies": {
    "browserify": "latest",
    "@types/browserify": "latest",
    "typescript": "next"
  }
}

Здесь наш пакет зависит от пакетов browserify и typescript. browserify не включает свои файлы объявлений в пакеты npm, поэтому нам нужно было зависеть от @types/browserify для его объявлений. typescript, с другой стороны, включает файлы объявлений в свои пакеты, поэтому дополнительных зависимостей не потребовалось.

Наш пакет экспортирует объявления каждого из них, поэтому любой пользователь нашего пакета browserify-typescript-extension должен иметь эти зависимости. По этой причине мы использовали "dependencies", а не "devDependencies", иначе нашим потребителям пришлось бы вручную устанавливать эти пакеты. Если бы мы создали только приложение командной строки и не ожидали, что наш пакет будет использоваться как библиотека, мы могли бы использовать devDependencies.

Красные флажки

/// <reference path="..." />

Не используйте /// <reference path="..." /> в файлах объявлений.

/// <reference path="../typescript/lib/typescriptServices.d.ts" />
....

Используйте /// <reference types="..." /> вместо этого.

/// <reference types="typescript" />
....

Убедитесь, что вы пересмотрели раздел Использование зависимостей для получения дополнительной информации.

Упаковка зависимых объявлений

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

• Не объединяйте их с вашими, сохраняйте каждый в своем файле.
• Не копируйте объявления в свой пакет.
• Зависите от пакета объявлений npm, если он не упаковывает свои файлы объявлений.

Выбор версии с typesVersions

Когда TypeScript открывает файл package.json, чтобы выяснить, какие файлы ему нужно прочитать, он сначала обращается к полю, называемому typesVersions.

Перенаправление папок (использование *)

Файл package.json с полем typesVersions может выглядеть так:

{
  "name": "package-name",
  "version": "1.0.0",
  "types": "./index.d.ts",
  "typesVersions": {
    ">=3.1": { "*": ["ts3.1/*"] }
  }
}

Этот package.json сообщает TypeScript сначала проверить текущую версию TypeScript. Если это 3.1 или более поздняя версия, TypeScript определяет путь, который вы импортировали относительно пакета, и читает из папки ts3.1 пакета.

Вот что означает { "*": ["ts3.1/*"] } — если вы знакомы с сопоставлением путей, он работает точно так же.

В приведенном выше примере, если мы импортируем из "package-name", TypeScript будет пытаться разрешить импорт из [...]/node_modules/package-name/ts3.1/index.d.ts (и других соответствующих путей) при выполнении в TypeScript 3.1. Если мы импортируем из package-name/foo, мы будем пытаться найти [...]/node_modules/package-name/ts3.1/foo.d.ts и [...]/node_modules/package-name/ts3.1/foo/index.d.ts.

Что если мы не работаем в TypeScript 3.1 в этом примере? Ну, если ни одно из полей в typesVersions не совпадает, TypeScript возвращается к полю types, поэтому здесь TypeScript 3.0 и более ранние версии будут перенаправлены на [...]/node_modules/package-name/index.d.ts.

Перенаправление файлов

Когда вы хотите изменить разрешение только для одного файла за раз, вы можете указать TypeScript, как разрешить разные файлы, передав точные имена файлов:

{
  "name": "package-name",
  "version": "1.0.0",
  "types": "./index.d.ts",
  "typesVersions": {
    "<4.0": { "index.d.ts": ["index.v3.d.ts"] }
  }
}

В TypeScript 4.0 и выше импорт "package-name" будет разрешаться в ./index.d.ts, а в 3.9 и ниже — в "./index.v3.d.ts.

Поведение сопоставления

Способ, которым TypeScript определяет, соответствует ли версия компилятора и языка, использует semver ranges Node.

Несколько полей

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

{
  "name": "package-name",
  "version": "1.0",
  "types": "./index.d.ts",
  "typesVersions": {
    ">=3.2": { "*": ["ts3.2/*"] },
    ">=3.1": { "*": ["ts3.1/*"] }
  }
}

Поскольку диапазоны могут перекрываться, определение того, какое перенаправление применяется, зависит от порядка. Это означает, что в приведенном выше примере, даже если оба согласователя >=3.2 и >=3.1 поддерживают TypeScript 3.2 и выше, изменение порядка может привести к разному поведению, поэтому приведенный выше пример не будет эквивалентен следующему.

{
  "name": "package-name",
  "version": "1.0",
  "types": "./index.d.ts",
  "typesVersions": {
    // NOTE: this doesn't work!
    ">=3.1": { "*": ["ts3.1/*"] },
    ">=3.2": { "*": ["ts3.2/*"] }
  }
}

Опубликовать в

Пакеты в организации @types публикуются автоматически из DefinitelyTyped с помощью инструмента types-publisher. Чтобы ваши объявления были опубликованы как пакет @types, отправьте запрос на вытягивание в DefinitelyTyped. Более подробную информацию можно найти на странице руководства по участию.