Использование зависимостей из npm

В проектах Kotlin/JS всеми зависимостями можно управлять с помощью плагина Gradle. Сюда входят библиотеки Kotlin/Multiplatform, такие как kotlinx.coroutines, kotlinx.serialization или ktor-client.

Чтобы добавить зависимости от пакетов JavaScript из npm, DSL Gradle предоставляет функцию npm, которая позволяет указать пакеты, импортируемые из npm. Рассмотрим импорт пакета NPM под названием is-sorted.

Соответствующая часть файла сборки Gradle выглядит так:

dependencies {
    // ...
    implementation(npm("is-sorted", "1.0.5"))
}

Поскольку модули JavaScript обычно имеют динамическую типизацию, а Kotlin — язык со статической типизацией, необходимо предоставить своего рода адаптер. В Kotlin такие адаптеры называются внешними объявлениями. Для пакета is-sorted, в котором есть только одна функция, такое объявление написать несложно. В папке исходного кода создайте файл с именем is-sorted.kt и добавьте в него следующее содержимое:

@JsModule("is-sorted")
@JsNonModule
external fun <T> sorted(a: Array<T>): Boolean

Обратите внимание: если в качестве целевой платформы используется CommonJS, аннотации @JsModule и @JsNonModule необходимо соответствующим образом изменить.

Теперь эту функцию JavaScript можно использовать так же, как обычную функцию Kotlin. Поскольку в заголовочном файле мы указали информацию о типах (вместо того чтобы просто задать тип параметра и возвращаемого значения как dynamic), также доступны полноценная поддержка компилятора и проверка типов.

console.log("Hello, Kotlin/JS!")
console.log(sorted(arrayOf(1,2,3)))
console.log(sorted(arrayOf(3,1,2)))

При выполнении этих трёх строк в браузере или Node.js результат показывает, что вызов sorted был корректно сопоставлен с функцией, экспортируемой пакетом is-sorted:

Hello, Kotlin/JS!
true
false

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

Подробнее о написании объявлений см. в разделе Вызов JavaScript из Kotlin.