Akka.Js

This project aim to bring Akka framework available for JS applications.

NOTE the current exposed API is minimal, I will be happy to receive Issues asking for further functionalities to be exposed, and more happy to have PR.

Quick start

Install the module:

npm install akkajs

A simple Ping Pong between two actors looks like:

const akkajs = require("akkajs")

const system = akkajs.ActorSystem.create()

class Pinger extends akkajs.Actor {
  constructor() {
    super()
    this.name = "pinger"
    this.receive = this.receive.bind(this)
  }
  receive(msg) {
    console.log("RECEIVED PING")
    this.sender().tell("pong")
  }
}

const pinger = system.spawn(new Pinger())

class Ponger extends akkajs.Actor {
  constructor() {
    super()
    this.name = "ponger"
    this.receive = this.receive.bind(this)
  }
  receive(msg) {
    console.log("RECEIVED PONG")
    this.sender().tell("ping")
  }
}

const ponger = system.spawn(new Ponger())

pinger.tell("ping", ponger)

An Actor based greeter on Node looks like follows:

const akkajs = require("akkajs")
const readline = require("readline")

const system = akkajs.ActorSystem.create("helloworld")

class Greeter extends akkajs.Actor {
  constructor() {
     super()
     // following guideline in:  https://facebook.github.io/react/docs/react-without-es6.html#autobinding
     this.receive = this.receive.bind(this)
   }
   receive(msg) {
    console.log("Hello " + msg)
   }
}

const greeter = system.spawn(new Greeter())

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
})

rl.question(
  "What is your name? ",
  (answer) => {
    greeter.tell(answer)
    rl.close()
  }
)

Akka.Js is pure Javascript and has not got known limitations in running in the major browsers or directly on any JS VM (e.g. Node, Phantom, ...)

Into the github repo there are few examples under the demo folder.

To run the examples simply clone this project go into the demo directory and run with:

https://github.com/akka-js/akka.js_bindings.git
cd akka.js_bindings/demo
run <example-name>

Full API

Configuration

Configuration class enable you to configure your ActorSystem.

Configuration is based on the HOCON standard ported to JS through ScalaJs thanks to SHOCON

The Configuration constructor accept an optional String as parameter that enable you to override parameters.

all defaults instantiation:

const config = new akkajs.Configuration()

custom instantiation:

const config = new akkajs.Configuration(`akka {
  loglevel = "DEBUG"
  stdout-loglevel = "DEBUG"
}`)

the full default configuration can be found here

Methods

Method	Description
config.add(moreconfig)	To add additional customizations to your configuration (e.g. config.add("akka.log-config-on-start = on"))
config.get()	To obtain the configuration object to construct an ActorSytem

ActorSystem

An ActorSystem is a container and the environment for your Actors.

The ActorSystem creator method accept an optional String as name and an optional configuration.

all defaults instantiation:

const system = akkajs.ActorSystem.create()

with custom name:

const system = akkajs.ActorSystem.create("myActorSystem")

with custom name and configuration:

const system = akkajs.ActorSystem.create("myActorSystem", config.get())

Methods

Method	Description
system.terminate()	Shutdown the ActorSystem
system.select(actorpath)	To obtain the reference to an Actor
system.spawn(actor)	Will spawn a new instance of the provided Actor and return the reference to it

Actor

An Actor is is an execution unit that runs concurrently with other actors.

You have to define a class that extends akkajs.Actor and use the spawn method on an instance of it to run your Actor and obtain the reference to it.

class Example extends akkajs.Actor {
  constructor() {
    super()
    this.receive = this.receive.bind(this)
  }
  receive(msg) {
    // do something when you receive a message
  }
}

const actor = system.spawn(new Example())

Actors talk each other only by message passing and you cannot call directly a method on them. Given a reference to an Actor you can invoke the followings:

Methods

Method	Description
actor.path()	Return a String representing a logical path associated to your actor, it can be used to identify an actor using the select method
actor.tell(msg)	Send to the Actor the specified msg
actor.tell(msg, anotheractor)	Send to the Actor the specified msg pretending the sender to be anotheractor
actor.kill()	Will kill the specified actor

When defining an Actor class you can override a few definitions

Methods

Method	Description
this.name	The name of the Actor will be used to construct the path
this.receive(msg)	This method gets triggered when dequeuing the mailbox of the actor
this.preStart()	Triggered once when the Actor is started (or re-started)
this.postStop()	Triggered once when the Actor is stopped

an example class that override all of these looks like:

class Example extends akkajs.Actor {
  constructor() {
    super()
    this.name = "newname"
    this.preStart = this.preStart.bind(this)
    this.receive = this.receive.bind(this)
    this.postStop = this.postStop.bind(this)
  }
  preStart() { console.log("starting " + this.name) }
  receive(msg) { console.log("received message: " + msg) }
  postStop() { console.log("stopping") }
}

// and you can trigger all of them by running:
const actor = system.spawn(new Example())
setTimeout(
  () => {
    actor.tell("hello world")
    actor.kill()
  }
)

From within the Actor itself you have access to a few more functions to call:

Methods

Method	Description
this.path()	Return the path of the Actor
this.parent()	Return the array of the children of this Actor
this.children()	Return the array of the children of this Actor
this.sender()	Called within the receive method return the reference to the Actor that sent the message - inferring the sender has some limitations consider using explicit sender in the tell method to have it working reliably
this.self()	Return the reference to itself
this.system()	Return the ActorSystem this Actor belong to
this.spawn(actor)	Let spawn an Actor as a child of this one, return it's reference
this.become(func)	Change the current receive function to the argument func

Compile and contribute

You need to install Sbt to compile this project from sources. Compile with

sbt compile

and you can test examples with your modifications by running first:

sbt deploy

and running desired examples into the demo directory.