hanishi/akka.js

Akka, for Scala.js

This repository is the port of sources Akka to the JavaScript runtime, thanks to Scala.js

LIVE DEMO

Use it

To have a blazing fast kick off you can check out our examples.

Otherwise, if you want to start from scratch:

First of all you need to setup a new Scala.js project. Then add to your JS project configuration:

libraryDependencies += "org.akka-js" %%% "akkajsactor" % "2.2.6.14"

If you want to use Akka Stream:

libraryDependencies += "org.akka-js" %%% "akkajsactorstream" % "2.2.6.14"

To test your code you can use:

libraryDependencies += "org.akka-js" %%% "akkajstestkit" % "2.2.6.14" % "test"
libraryDependencies += "org.akka-js" %%% "akkajsstreamtestkit" % "2.2.6.14" % "test"

You can also use Akka Typed:

libraryDependencies += "org.akka-js" %%% "akkajsactortyped" % "2.2.6.14"
libraryDependencies += "org.akka-js" %%% "akkajstypedtestkit" % "2.2.6.14" % "test"

And Akka Stream Typed interface:

libraryDependencies += "org.akka-js" %%% "akkajsactorstreamtyped" % "2.2.6.14"

Please note that Akka.js 2.2.6.14 is shipped from the stable Akka 2.6.14. At this point you can use most of the Akka core Api as described in the official docs.

Check out the @andreaTP session at Scala Days 2016: slides video

Or @andreaTP session at BeeScala 2016: slides video

@andreaTP at ScalaUA 2017: slides video

@andreaTP at ScalaSwarm 2017: slides video

Caveats

There are small caveats to keep in mind to ensure that your code will run smoothly on both Jvm and Js.

Startup Time

On Js VM the control flow will execute first all operations in line, so to ensure your code will run AFTER the ActorSystem is started you need to run your code within a block like this:

import system.dispatcher
import scala.concurrent.duration._
system.scheduler.scheduleOnce(0 millis){
  ... your code here ...
}

Reflective Actor Instatiation

Since Scala.Js 0.6.15 reflective class instatiation is perfectly supported.

Testing

To handle blocking testing in test suites you cannot use modules that interact with external world. Is therefore strictly prohibited to use any different ExecutionContext (i.e. you cannot import scala.concurrent.ExecutionContext.Implicits.global).

Mailbox configuration

Due to the lack of runtime reflection in Scala.Js is not possible to configure mailbox of actors using requirements but is it possible to do so with direct configuration. i.e.

lazy val config: Config =
  ConfigFactory
    .parseString("""
      stash-custom-mailbox {
        mailbox-type = "akka.dispatch.UnboundedDequeBasedMailbox"
      }
      """
    ).withFallback(akkajs.Config.default)

val system: ActorSystem = ActorSystem("wsSystem", config)

val actorWithStash =
  system.actorOf(Props(new ActorWithStash()).withMailbox("stash-custom-mailbox"), "ActorWithStash")

Linking errors with scala-java-time

Akka.Js ships with scalajs-java-time that is strictly a minimal subset of scala-java-time("io.github.cquiroz" %%% "scala-java-time"). If a user has scala-java-time has dependency(even transitive) make sure to do the proper exclusion when importing Akka.Js.

e.g.:

libraryDependencies += "org.akka-js" %%% "akkajsactor" % "<version>" exclude("org.scala-js", "scalajs-java-time")

Add-ons

Since semantics difference to Akka on JVM we include a bunch of helpers to make life easier:

akkajs.Config.default // default configuration shipped with Akka.JS

akka.testkit.TestKitBase {
  await() // to help on waiting during tests
  await(duration: Long) // with configurable duration
}

To change default configuration logging level you can simply:

lazy val conf =
  ConfigFactory
    .parseString("""
    akka {
      loglevel = "DEBUG"
      stdout-loglevel = "DEBUG"
    }""")
    .withFallback(akkajs.Config.default)

lazy val system = ActorSystem("yourname", conf)

Design documentation

The BSc thesis detailing most of the work and the approach taken can be found here

The original codebase derives from Sébastien Doeraene's scala-js-actors, you can find his original report here.

Build it

To work with the very last version you can compile and publish local:

git clone https://github.com/unicredit/akka.js
cd akka.js
sbt akkaJsActorJS/publishLocal

To have also akka-stream:

sbt akkaJsActorStreamJS/publishLocal

For the bleeding edge akka-typed

sbt akkaJsActorTypedJS/publishLocal

Built with Akka.js

• akka-ui FRP with Akka.js

Akka version

Akka.Js can now compile against different versions of Akka, we check the codebase against MASTER, but for specific needs you can try to compile against a different Akka version by changing the akkaVersion while building.

Credits

Akka.js wouldn't have been possible without the enormous support of the R&D department of UniCredit lead by Riccardo Prodam. What started as a side-project for a master thesis grew into an important open source milestone. Check out other projects from the unicredit team here

License

Akka.js is distributed under the Scala License.