Модули и зависимости

Deno использует ECMAScript-модули в качестве своей модульной системы по умолчанию, чтобы соответствовать современным стандартам JavaScript и способствовать более эффективному и согласованному опыту разработки. Это официальный стандарт для JavaScript-модулей, позволяющий улучшить процесс tree-shaking, повысить интеграцию с инструментами и обеспечить поддержку в разных средах.

Используя ECMAScript-модули, Deno гарантирует совместимость с постоянно развивающейся экосистемой JavaScript. Для разработчиков это означает оптимизированную и предсказуемую модульную систему, которая избегает сложностей, связанных с устаревшими форматами модулей, такими как CommonJS.

Импорт модулей

В этом примере функция add импортируется из локального модуля calc.ts.

export function add(a: number, b: number): number {
  return a + b;
}

// imports the `calc.ts` module next to this file
import { add } from "./calc.ts";

console.log(add(1, 2)); // 3

Вы можете запустить этот пример, вызвав deno run main.ts в каталоге, который содержит как main.ts, так и calc.ts.

В случае с ECMAScript-модулями, локальные указатели импорта должны всегда включать полное расширение файла. Его нельзя опускать.

// WRONG: missing file extension
import { add } from "./calc";

// CORRECT: includes file extension
import { add } from "./calc.ts";

Импорт сторонних модулей и библиотек

При работе со сторонними модулями в Deno используйте тот же синтаксис import, что и для локального кода. Сторонние модули обычно импортируются из удаленного реестра и начинаются с jsr:, npm: или https://.

import { camelCase } from "jsr:@luca/cases@1.0.0";
import { say } from "npm:cowsay@1.6.0";
import { pascalCase } from "https://deno.land/x/case/mod.ts";

Deno рекомендует использовать JSR, современный реестр JavaScript, для сторонних модулей. Там вы найдете множество хорошо документированных ES-модулей для ваших проектов, включая Стандартную библиотеку Deno.

Вы можете подробнее узнать о поддержке Deno для пакетов npm здесь.

Управление сторонними модулями и библиотеками

Ввод полного имени модуля с полным указателем версии может стать утомительным при импорте их в несколько файлов. Вы можете централизовать управление удаленными модулями с помощью поля imports в вашем файле deno.json. Мы называем это поле imports — карту импорта, которая основана на стандарте карт импорта.

{
  "imports": {
    "@luca/cases": "jsr:@luca/cases@^1.0.0",
    "cowsay": "npm:cowsay@^1.6.0",
    "cases": "https://deno.land/x/case/mod.ts"
  }
}

Благодаря переименованным указателям код выглядит более читаемо:

import { camelCase } from "@luca/cases";
import { say } from "cowsay";
import { pascalCase } from "cases";

Переименованное имя может быть любым допустимым указателем. Это очень мощная функция в Deno, которая может переименовывать всё. Узнайте больше о возможностях карты импорта здесь.

Добавление зависимостей с помощью deno add

Процесс установки упрощается с помощью подкоманды deno add. Он автоматически добавит последнюю версию запрошенного пакета в раздел imports файла deno.json.

# Add the latest version of the module to deno.json
$ deno add jsr:@luca/cases
Add @luca/cases - jsr:@luca/cases@1.0.0

{
  "imports": {
    "@luca/cases": "jsr:@luca/cases@^1.0.0"
  }
}

Также можно указать точную версию:

# Passing an exact version
$ deno add jsr:@luca/cases@1.0.0
Add @luca/cases - jsr:@luca/cases@1.0.0

Подробнее см. в deno add справке.

Вы также можете удалить зависимости с помощью deno remove:

$ deno remove @luca/cases
Remove @luca/cases

{
  "imports": {}
}

Подробнее см. в deno remove справке.

Версии пакетов

Можно указать диапазон версий для импортируемого пакета. Это делается с помощью символа @, за которым следует указатель диапазона версий, и следует схеме версионирования semver.

Например:

@scopename/mypackage           # highest version
@scopename/mypackage@16.1.0    # exact version
@scopename/mypackage@16        # highest 16.x version >= 16.0.0
@scopename/mypackage@^16.1.0   # highest 16.x version >= 16.1.0
@scopename/mypackage@~16.1.0   # highest 16.1.x version >= 16.1.0

Вот обзор всех способов указания версии или диапазона:

Импорты HTTPS

Deno также поддерживает операторы импорта, которые ссылаются на URL-адреса HTTP/HTTPS, либо напрямую:

import { Application } from "https://deno.land/x/oak/mod.ts";

либо в вашей карте импорта deno.json.

{
  "imports": {
    "oak": "https://deno.land/x/oak/mod.ts"
  }
}

Поддержка HTTPS-импортов позволяет поддерживать следующие JavaScript CDN, так как они предоставляют доступ к URL-адресам JavaScript-модулей:

• deno.land/x
• esm.sh
• unpkg.com

HTTPS-импорты полезны, если у вас небольшой, часто единственный файл, проект Deno, который не требует никакой другой конфигурации. С HTTPS-импортами вы можете избежать наличия файла deno.json вообще. Однако использование этого стиля импорта в более крупных приложениях не рекомендуется, так как вы можете столкнуться с конфликтами версий (когда разные файлы используют разные указатели версий).

Переопределение HTTPS-импортов

Другая ситуация, когда карты импорта могут быть очень полезны, — это переопределение HTTPS-импортов в определённых модулях.

Предположим, вы хотите переопределить указатель https://deno.land/x/my-library@1.0.0/mod.ts, который используется внутри файлов, полученных из https://deno.land/x/example/, на локальную отлаженную версию. Вы можете сделать это, используя область в карте импорта, которая выглядит примерно так:

{
  "imports": {
    "example/": "https://deno.land/x/example/"
  },
  "scopes": {
    "https://deno.land/x/example/": {
      "https://deno.land/x/my-library@1.0.0/mod.ts": "./patched/mod.ts"
    }
  }
}

Публикация модулей

Любая программа Deno, которая определяет экспорт, может быть опубликована как модуль. Это позволяет другим разработчикам импортировать и использовать ваш код в своих проектах. Модули могут быть опубликованы в:

• JSR — рекомендуемый вариант, поддерживает TypeScript напрямую и автоматически генерирует документацию для вас
• npm — используйте dnt для создания npm-пакета
• deno.land/x — для HTTPS-импортов, используйте JSR, если это возможно

Перезагрузка модулей

По умолчанию Deno использует глобальный кеш-каталог (DENO_DIR) для загруженных зависимостей. Этот кеш используется во всех проектах.

Вы можете принудительно переизвлекать и перекомпилировать модули в кеш, используя флаг --reload.

# Reload everything
deno run --reload my_module.ts

# Reload a specific module
deno run --reload=jsr:@std/fs my_module.ts

Использование только кэшированных модулей

Чтобы принудительно заставить Deno использовать только модули, которые были кэшированы ранее, используйте флаг --cached-only:

deno run --cached-only mod.ts

Это приведет к ошибке, если в дереве зависимостей для mod.ts есть какие-либо зависимости, которые ещё не кэшированы.

Локальное хранение удалённых модулей

Если ваш проект имеет внешние зависимости, вы можете сохранить их локально, чтобы избежать их загрузки из интернета каждый раз при построении проекта. Это особенно полезно при построении проекта на сервере CI или в контейнере Docker, или при исправлении или ином изменении удалённых зависимостей.

Deno предоставляет эту функциональность через настройку в вашем файле deno.json:

{
  "vendor": true
}

Добавьте этот фрагмент в ваш файл deno.json, и Deno будет кэшировать все зависимости локально в каталоге vendor при запуске проекта, или вы можете дополнительно запустить команду deno install --entrypoint, чтобы кэшировать зависимости сразу:

deno install --entrypoint main.ts

Затем вы можете запустить приложение как обычно с помощью deno run:

deno run main.ts

После локального хранения вы можете запустить main.ts без доступа к интернету, используя флаг --cached-only , который заставляет Deno использовать только локально доступные модули.

Проверка целостности и файлы блокировки

Представьте, что ваш модуль зависит от удаленного модуля по адресу https://some.url/a.ts. При первой компиляции вашего модуля a.ts загружается, компилируется и кэшируется. Эта кэшированная версия будет использоваться до тех пор, пока вы не запустите свой модуль на другом компьютере (например, в рабочей среде) или не перезагрузите кэш вручную (используя команду, например, deno install --reload).

Но что, если содержимое по адресу https://some.url/a.ts изменится? Это может привести к тому, что ваш производственный модуль будет работать с другим кодом зависимостей, чем ваш локальный модуль. Для обнаружения этого Deno использует проверку целостности и файлы блокировки.

Deno использует файл deno.lock для проверки целостности внешних модулей. Чтобы включить файл блокировки, необходимо выполнить следующие действия:

1. Создайте файл deno.json в текущей или родительской директории. Это автоматически создаст файл блокировки deno.lock.

   Обратите внимание, что это можно отключить, указав следующее в вашем файле deno.json:

   deno.json

   {
     "lock": false
   }
   

2. Используйте флаг --lock для включения и указания проверки файла блокировки.

Замороженный файл блокировки

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

Это может быть нежелательно в определенных сценариях (например, в CI-трубопроводах или производственной среде), где вам нужно, чтобы Deno выдавал ошибку, когда он сталкивается с зависимостью, которую он никогда раньше не видел. Для включения этого вы можете указать флаг --frozen или установить следующее в файле deno.json:

{
  "lock": {
    "frozen": true
  }
}

При запуске команды deno с замороженным файлом блокировки любая попытка обновить файл блокировки новыми данными приведет к завершению команды с ошибкой, отображающей изменения, которые должны были быть внесены.

Если вы хотите обновить файл блокировки, укажите --frozen=false в командной строке, чтобы временно отключить замороженный файл блокировки.

Изменение пути к файлу блокировки

Путь к файлу блокировки можно настроить, указав --lock=deps.lock или следующее в файле конфигурации Deno:

{
  "lock": {
    "path": "deps.lock"
  }
}

Частные репозитории

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

Deno поддерживает отправку токенов bearer при запросе удаленного модуля. Токены bearer — это преобладающий тип токенов доступа, используемых с OAuth 2.0, и они широко поддерживаются службами хостинга (например, GitHub, GitLab, Bitbucket, Cloudsmith и т. д.).

DENO_AUTH_TOKENS

CLI Deno будет искать переменную среды с именем DENO_AUTH_TOKENS для определения токенов аутентификации, которые следует использовать при запросе удаленных модулей. Значение переменной среды имеет формат n токенов, разделенных точкой с запятой (;) , где каждый токен является:

• токеном bearer в формате {token}@{hostname[:port]}, или
• данными аутентификации basic в формате {username}:{password}@{hostname[:port]}

Например, один токен для deno.land будет выглядеть примерно так:

DENO_AUTH_TOKENS=a1b2c3d4e5f6@deno.land

или:

DENO_AUTH_TOKENS=username:password@deno.land

А несколько токенов будут выглядеть так:

DENO_AUTH_TOKENS=a1b2c3d4e5f6@deno.land;f1e2d3c4b5a6@example.com:8080;username:password@deno.land

Когда Deno загружает удаленный модуль, где имя хоста соответствует имени хоста удаленного модуля, Deno установит заголовок Authorization запроса в значение Bearer {token} или Basic {base64EncodedData}. Это позволяет удаленному серверу распознать, что запрос является авторизованным запросом, связанным с конкретным аутентифицированным пользователем, и предоставить доступ к соответствующим ресурсам и модулям на сервере.

GitHub

Для доступа к частным репозиториям на GitHub вам необходимо выпустить личный токен доступа. Для этого войдите в GitHub и перейдите в раздел Настройки -> Настройки разработчика -> Личные токены доступа:

Затем выберите Создать новый токен, присвойте вашему токену описание и предоставьте ему соответствующий доступ к области repo. Область repo позволит читать содержимое файлов (подробнее о скопах в документации GitHub):

После создания GitHub отобразит новый токен один раз, значение которого вы хотите использовать в переменной среды:

Для доступа к модулям, содержащимся в частном репозитории на GitHub, вы должны использовать сгенерированный токен в переменной среды DENO_AUTH_TOKENS со скоупом raw.githubusercontent.com хоста. Например:

DENO_AUTH_TOKENS=a1b2c3d4e5f6@raw.githubusercontent.com

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

Если токен неверен или пользователь не имеет доступа к модулю, GitHub выдаст статус 404 Not Found, а не статус «неавторизован». Поэтому, если вы получаете ошибки, что модули, к которым вы пытаетесь получить доступ, не найдены в командной строке, проверьте настройки переменных среды и личные токены доступа.

Кроме того, deno run -L debug должен вывести сообщение отладки о количестве токенов, распарсенных из переменной среды. Он выведет сообщение об ошибке, если посчитает, что какой-либо из токенов имеет неправильный формат. Для обеспечения безопасности он не будет выводить никакие подробности о токенах.