Как написать JS-библиотеку на ScalaJS

Scala.js открывает огромный мир фронтенд технологий для Scala разработчиков. Обычно проекты, использующие Scala.js, это веб- или nodejs-приложения, но бывают случаи, когда вам просто нужно создать JavaScript-библиотеку.

Есть некоторые тонкости в написании такой Scala.js библиотеки, но они покажутся знакомыми для JS разработчиков. В этой статей мы создадим простую Scala.js библиотеку (код) для работы с Github API и сосредоточимся на идиоматичности JS API.

Но сначала наверняка вы хотите спросить, зачем вообще может понадобиться делать такую библиотеку? Например, если у вас уже есть клиентское приложение написанное на JavaScript и оно общается с бэкендом на Scala.

Вряд ли у вас получится написать ее с чистого листа с помощью Scala.js, но можно написать библиотеку для взаимодействия между вами и фронтенд разработчиками, которая позволит:

• спрятать сложную или неочевидную клиентсайд логику в ней и предоставить удобное API;
• в библиотеке вы сможете работать с моделями из backend приложения;
• изоморфный код из коробки и можете забыть про проблемы синхронизации протоколов;
• у вас будет публичный API для разработчиков, как у Facebook’s Parse.

Также это отличный выбор для разработки Javascript API SDK, благодаря всем этим преимуществам.

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

Давайте начнем создание библиотеки

Требования: как Scala разработчики мы хотим писать в функциональном стиле и использовать все фишки Scala. В свою очередь API библиотеки должно быть легко понять для JS разработчиков.

Начнем со структуры каталогов, она не отличается от обычной структуры для Scala приложения:

+-- build.sbt
+-- project
¦   +-- build.properties
¦   L-- plugins.sbt
+-- src
¦   L-- main
¦       +-- resources
¦       ¦   +-- demo.js
¦       ¦   L-- index-fastopt.html
¦       L-- scala
L-- version.sbt

resources/index-fastopt.html — страница только загрузит нашу библиотеку и файл resources/demo.js, для проверки API

API

Цель — упростить взаимодействие с Github API. Для начала мы сделаем только одну фичу — загрузку юзеров и их репозиториев. Итак это публичный метод и парой моделей с результатами ответа. Начнем с модели.

Модель

Определим наши классы вот так:

case class User(name: String,
                avatarUrl: String,
                repos: List[Repo])

sealed trait Repo {
  def name: String
  def description: String
  def stargazersCount: Int
  def homepage: Option[String]
}

case class Fork(name: String,
                description: String,
                stargazersCount: Int,
                homepage: Option[String]) extends Repo

case class Origin(name: String,
                  description: String,
                  stargazersCount: Int,
                  homepage: Option[String],
                  forksCount: Int) extends Repo

Ничего сложного, User имеет несколько репозиториев, а репозиторий может быть оригиналом или форком, как же нам экспортировать это для JS разработчиков?

Для полного описания функционала смотрите Export Scala.js APIs to Javascript.

API для создания объектов.
Давайте посмотрим как оно работает, простое решение экспортировать конструктор.

@JSExport
case class Fork(name: String, /*...*/)]

Но оно не сработает, у вас нет экспортированного конструктора Option, поэтому не получится создать параметр homepage. Есть и другие ограничения для case классов, вы не сможете экспортировать конструкторы с наследованием, вот такой код даже не скомпилируется

@JSExport
case class A(a: Int)
@JSExport
case class B(b: Int) extends A(12)

@JSExport
object Github {
  @JSExport
  def createFork(name: String,
                 description: String,
                 stargazersCount: Int,
                 homepage: UndefOr[String]): Fork =
    Fork(name, description, stargazersCount, homepage.toOption)
}

Тут, с помощью js.UndefOr мы обрабатываем опциональный параметр в стиле JS: можно передать String или вообще обойтись без него:

// JS
var homelessFork = Github().createFork("bar-fork", "Bar", 1);
var fork =         Github().createFork("bar-fork", "Bar", 1, "http://foo.bar");

Замечание касательно кеширования Scala-объектов:

Делать вызов Github() каждый раз не лучшее идея, если вам не нужна ленивость вы можете закешировать их при запуске:

<!--index-fastopt.html-->
<script>
  var Github = Github()

Если сейчас мы попробуем получить имя форка, получим undefined. Все правильно, оно не экспортировалось, давайте экспортируем свойства модели.

C нативными типами, такими как String, Boolean или Int проблем нет, их можно экспортировать так:

sealed trait Repo {
  @JSExport
  def name: String
  // ...
}

Поле case класса может быть экспортировано с помощью аннотации @(JSExport@field). Пример для свойства forks:

case class Origin(name: String,
                  description: String,
                  stargazersCount: Int,
                  homepage: Option[String],
                  @(JSExport@field) forks: Int) extends Repo

Option

Но как вы уже догадались есть проблема с homepage: Option[String]. Мы можем экспортировать ее тоже, но это бесполезно, чтобы получить значение из Option, js разработчик должен будет вызвать какой нибудь метод, но для Option ничего не экспортировано.

С другой стороны, мы хотели бы сохранить Option, чтобы наш Scala-код оставался простой и понятный. Простое решение — экспортировать специальный js геттер:

import scala.scalajs.js.JSConverters._

sealed trait Repo {
  //...

  //не экспортируем поле, с которым неудобно работать в JS
  def homepage: Option[String]

  @JSExport("homepage")
  def homepageJS: js.UndefOr[String] = homepage.orUndefined
}

Давайте попробуем:

console.log("fork.name: " + fork.name);
console.log("fork.homepage: " + fork.homepage);

Мы оставили наш любимый Option и сделали чистое красивое API для JS. Ура!

List

User.repos это List и есть трудности с его экспортированием. Решение такое же, просто экспортируем его как JS массив:

@JSExport("repos")
def reposJS: js.Array[Repo] = repos.toJSArray

// JS
user.repos.map(function (repo) {
  return repo.name;
});

Подтипы

Есть все еще одна проблема с трейтом Repo. Так как мы не экспортируем конструкторы, JS разработчик не сможет понять, с каким подтипом Repo он имеет дело.

в Javascript нет сопоставления с образцом (pattern matching) и использование наследования не так популярно (а иногда и спорно), поэтому у нас есть несколько вариантов:

• Создать методы isFork: Boolean или hasForks: Boolean. Это нормально, но не достаточно обобщенно.
• Добавить свойство type: String для всех подтипов.

Я выбираю 2 путь, его легко абстрагировать и использовать во всем проекте, давайте обьявим mixin который экспортирует свойство type:

trait Typed { self =>
  @JSExport("type")
  def typ: String = self.getClass.getSimpleName
}
</code>

Нам нужно другое имя, потому что <code>type</code> это зарезервированное слово в Scala.
<source lang="scala">
sealed trait Repo extends Typed {
  // ...
}

… и используем его:

// JS
fork.type // "Fork"

Сделать немного безопасней можно, если хранить константы (тут нам поможет компилятор):

class TypeNameConstant[T: ClassTag] {
  @JSExport("type")
  def typ: String = classTag[T].runtimeClass.getSimpleName
}

С помощью этого хелпера мы можем объявить нужные константы в объекте GitHub:

@JSExportAll
object Github {
  //...

  val Fork = new TypeNameConstant[model.Fork]
  val Origin = new TypeNameConstant[model.Origin]
}

Это позволит нам избежать строк в Javascript, пример

// JS
function isFork(repo) {
  return repo.type == Github.Fork.type
}

Вот так мы работаем с подтипами.

Что, если я не могу поменять обьект, который хочу экспортировать?

В этом случае, возможно, вы экспортируете классы своей кросс — компилируемой модели или объекты из импортированных библиотек. Способы одинаковы и для Option и для List, с одним различием — вам нужно самим реализовать приемлемые, с точки зрения JS, классы-обертки и конвертацию.

Здесь важно использовать js замены только для экспорта (Scala => JS) и для создания экземпляров (JS => Scala) Все бизнес логика должна быть реализована только чистыми Scala классами.

Допустим у нас есть класс Commit, который мы изменить не можем.

case class Commit(hash: String)

Вот как его можно экспортировать:

object CommitJS {
  def fromCommit(c: Commit): CommitJS = CommitJS(c.hash)
}
case class CommitJS(@(JSExport@field) hash: String) {
  def toCommit: Commit = Commit(hash)
}

Затем, например, класс Branch из управляемого нами кода будет выглядеть вот так:

case class Branch(initial: Commit) {
  @JSExport("initial")
  def initialJS: CommitJS = CommitJS.fromCommit(initial)
}

Так как в JS среде commits представлены как CommitJS обьекты, фабричный метод для Branch будет:

@JSExport
def createBranch(initial: CommitJS) = Branch(initial.toCommit)

Конечно, это не супер способ, но зато он проверяется компилятором. Вот почему я предпочитаю смотреть на такую библиотеку не только как на прокси для value-классов, а как на фасад, который скрывает ненужные детали и упрощает API.

AJAX

Реализация

Для простоты мы будем использовать Ajax расширение библиотеки scalajs-dom для сетевых запросов. Давайте отвлечемся от экспорта и просто реализуем API.

Чтобы не усложнять, мы положим все связанное с AJAX в обьект API, у него будет два метода: для загрузки пользователя и загрузки репозитория.

Так же мы сделаем слой DTO, чтобы отделить API от модели. Результатом метода будет Future[String \/ DTO], где DTO это тип запрошенных данных, а String будет представлять ошибку Вот непосредственно код:

object API {

  case class UserDTO(name: String, avatar_url: String)
  case class RepoDTO(name: String,
                     description: String,
                     stargazers_count: Int,
                     homepage: Option[String],
                     forks: Int,
                     fork: Boolean)

  def user(login: String)
          (implicit ec: ExecutionContext): Future[String \/ UserDTO] =
    load(login, s"$BASE_URL/users/$login", jsonToUserDTO)

  def repos(login: String)
           (implicit ec: ExecutionContext): Future[String \/ List[RepoDTO]] =
    load(login, s"$BASE_URL/users/$login/repos", arrayToRepos)

  private def load[T](login: String,
                      url: String,
                      parser: js.Any => Option[T])
                     (implicit ec: ExecutionContext): Future[String \/ T] =
    if (login.isEmpty)
      Future.successful("Error: login can't be empty".left)
    else
      Ajax.get(url).map(xhr =>
        if (xhr.status == 200) {
          parser(js.JSON.parse(xhr.responseText))
            .map(_.right)
            .getOrElse("Request failed: can't deserialize result".left)
        } else {
          s"Request failed with response code ${xhr.status}".left
        }
      )

  private val BASE_URL: String = "https://api.github.com"

  private def jsonToUserDTO(json: js.Any): Option[UserDTO] = //...
  private def arrayToRepos(json: js.Any): Option[List[RepoDTO]] = //...
}

Десериализация кода скрыта, нам она не интересна, метод load возвращает строку ошибки, если код не 200, иначе он конвертирует ответ в JSON, а потом в DTO

Теперь мы может конвертировать ответ API в модель.

import scala.scalajs.concurrent.JSExecutionContext.Implicits.queue

object Github {

  // ...

  def loadUser(login: String): Future[String \/ User] = {
    for {
      userDTO <- EitherT(API.user(login))
      repoDTO <- EitherT(API.repos(login))
    } yield userFromDTO(userDTO, repoDTO)
  }.run

  private def userFromDTO(dto: API.UserDTO,
                          repos: List[API.RepoDTO]): User = //..
}

Здесь мы используем monad transformer для работы с Future[\/[..]], а потом конвертируем DTO в модель.

Отлично, это выглядит как функциональный код Scala, приятно смотреть. Теперь перейдем к экспорту метода loadUser для пользователей нашей библиотеки.

Share the Future

Теперь у нас возникает вопрос, какой общепринятый способ для работы с асинхронными вызовами в Javascript? Я уже слышу смех js разработчиков, потому что его не существует. Callbacks, event emitters, promises, fibers, generators, async/await это все используется, что нам выбрать? Я считаю промисы это ближайшая реализация к Scala Future. Промисы очень популярны и уже поддерживаются из коробки многими соверменными бразуерами, мы возьмем их. Для начала надо сообщить нашему коду о промисах. это называется “Typed Facade”. мы легко можем это сделать сами, но в scalajs-dom уже есть реализация. Вот пример для тех, кто хочет сделать реализацию сам:

trait Promise[+A] extends js.Object {

  @JSName("catch")
  def recover[B >: A](
          onRejected: js.Function1[Any, B]): Promise[Any] = js.native

  @JSName("then")
  def andThen[B](
          onFulfilled: js.Function1[A, B]): Promise[Any] = js.native

  @JSName("then")
  def andThen[B](
          onFulfilled: js.Function1[A, B],
          onRejected: js.Function1[Any, B]): Promise[Any] = js.native
}

Ну и companion object с методами вроде Promise.all. Теперь нам надо только расширить этот trait:

@JSName("Promise")
class Promise[+R](
    executor: js.Function2[js.Function1[R, Any], js.Function1[Any, Any], Any]
)
  extends org.scalajs.dom.raw.Promise[R]

Итак, теперь нам надо лишь сконвертировать Future в Promise. Сделаем это с помощью implicit class:

object promise {

  implicit class JSFutureOps[R: ClassTag, E: ClassTag](f: Future[\/[E, R]]) {

    def toPromise(recovery: Throwable => js.Any)
                 (implicit ectx: ExecutionContext): Promise[R] =
      new Promise[R]((resolve: js.Function1[R, Unit],
                      reject: js.Function1[js.Any, Unit]) => {
        f.onSuccess({
          case \/-(f: R) => resolve(f)
          case -\/(e: E) => reject(e.asInstanceOf[js.Any])
        })
        f.onFailure {
          case e: Throwable => reject(recovery(e))
        }
      })
  }
}

Функция recovery превращает «упавший» Future в «упавший» Promise. Левая сторона дизъюнкции так же «роняет» promise.

Итак, теперь давайте поделимся нашим промисом с друзьями фронтендерами, как обычно мы добавим его в обьект Github рядом с оригинальным методом:

def loadUser(login: String): Future[String \/ User] = //...

@JSExport("loadUser")
def loadUserJS(login: String): Promise[User] =
  loadUser(login).toPromise(_.getMessage)

Здесь в случае ошибки мы роняем promise с ошибкой из исключения. Все, теперь можем протестировать API.

// JS
Github.loadUser("vpavkin")
  .then(function (result) {
    console.log("Name: ", result.name);
  }, function (error) {
    console.log("Error occured:", error)
  });

// Name: Vladimir Pavkin

Отлично, теперь мы можем использовать Future и все, к чему привыкли — и все же экспортировать его как идиоматичный JS API.

Заключение Вот несколько советов по написанию Javascript библиотеки с помощью Scala.js

• Кешируйте экспортируемые объекты при запуске;
• Экспортируйте seamless типы как есть;
• Не экспортируйте Option, List и другие Scala штуки. Используте геттер который конвертирует в js.UndefOr and js.Array;
• Не экспортируйте конструкторы. Используйте JS-friendly фабрики;
• JS-friendly означает принятие js.* типов и преобразовывайте их в стандартные типы Scala;
• Подмешивайте строковое поле type в типы-суммы;
• Экспортируйте Future как JS Promise;
• В первую очередь пишите на Scala. Не ограничивайте себя в самовыражении как Scala-разработчик, используйте возможности языка на полную.

Теперь вы знаете, что все это можно экспортировать.

Код примеров можно найти на GitHub: https://github.com/vpavkin/scalajs-library-tips


Владимир Павкин
Scala–разработчик