NodeJS (current & LTS)
This is a complete Scala.js facade for Node.js and npm packages; which means you can develop full-blown Node.js applications using popular JavaScript software stacks including the MEAN Stack (MongoDB, Express, Angular, Node), Cassandra, MySQL and many other popular npm packages.
Table of Contents
Introduction
The goal of this project is to provide a complete Scala.js binding for the entire MEAN Stack. Why? Because I love NodeJS, but I have a love/hate relationship with JavaScript. And many others feel the same way about JavaScript, which is why there are so many languages that are designed to improve the experience (CoffeeScript, TypeScript, Scala.js and others). Simply put, ScalaJs.io let's me have my cake and eat it too! And as such, I've gone to great lengths to bring all the things you love about developing applications on the MEAN Stack to Scala.
ScalaJs.io is a componentized platform; allowing developers to use only the features they want. If all your application requires is a binding for AngularJS, you can use just that. Alternatively, you could use only the Node bindings, or the entire MEAN stack (or any of the bundled npm library bindings).
Currently, there are at least four development use cases for ScalaJs.io:
- Building full MEAN stack applications using the bundled MongoDB, Express, Angular and Node bindings.
- Building rich thin-client web front-ends using AngularJS bindings only (with any backend).
- Building REST services using Node (and optionally Express) bindings only.
- Building CLI applications using Node bindings only.
Development
Build Requirements
- [SBT 0.13.16] (http://www.scala-sbt.org/download.html)
Build/publish the SDK
$ sbt clean publish-local
Resolvers
To add the ScalaJs.io bindings/library to your project, add the following to your build.sbt:
resolvers += Resolver.sonatypeRepo("releases")
Developed using ScalaJs.io
The following applications were developed using ScalaJs.io:
Application | Frontend | Backend | Scalajs.io version | Description |
---|---|---|---|---|
Phaser-Invaders | Scala.js + DOM | Scala + NodeJS | 0.3.x | Port of Phaser Invaders. |
Socialize | Scala.js + AngularJS | Scala.js + NodeJS | 0.4.0 | A Facebook-inspired Social networking web application. |
Todo MVC | Scala.js + AngularJS | Scala.js + NodeJS | 0.2.x | A simple Todo example application. |
Trifecta | Scala.js + AngularJS | Scala + Play 2.4.x | 0.4.0 | Trifecta is a web-based and CLI tool that simplifies inspecting Kafka messages and Zookeeper data. |
The MEAN Stack — AngularJS, MongoDB, Mongoose, Express and more
Module / Package | Version | Description |
---|---|---|
angular | 1.6.3 | AngularJS/core binding for Scala.js |
angular-anchor-scroll | 1.6.3 | AngularJS/anchorScroll binding for Scala.js |
angular-animate | 1.6.3 | AngularJS/animate binding for Scala.js |
angular-cookies | 1.6.3 | AngularJS/cookies binding for Scala.js |
angular-facebook | 1.6.3 | AngularJS/facebook binding for Scala.js |
angular-md5 | 1.6.3 | AngularJS/md5 binding for Scala.js |
angular-file-upload | 1.6.3 | AngularJS/fileupload binding for Scala.js |
angular-nvd3 | 1.6.3 | AngularJS/nvd3 binding for Scala.js |
angular-sanitize | 1.6.3 | AngularJS/sanitize binding for Scala.js |
angular-ui-bootstrap | 1.6.3 | AngularJS/ui-bootstrap binding for Scala.js |
angular-ui-router | 1.6.3 | AngularJS/ui-router binding for Scala.js |
angularjs-toaster | 1.6.3 | AngularJS/toaster binding for Scala.js |
express | 4.13.4 | Fast, unopinionated, minimalist web framework for Node.js |
mongodb | 2.2.22 | The official MongoDB driver for Node.js. |
mongoose | 4.8.1 | Mongoose is a MongoDB object modeling tool designed to work in an asynchronous environment. |
mpromise | 0.5.5 | A promises/A+ conformant implementation, written for mongoose. |
Looking for a complete list of available bindings? Go here
Discussions
There's a discussion about ScalaJs.io on Reddit.
Advantages over JavaScript
Scala.js offers many advantages over native JavaScript:
- Scala.js is strongly-typed
- Excellent IDE support
- No JavaScript Warts
- More concise
- Go beyond JavaScript ES6, today
Consider the following example in JavaScript. Here we have a nested collection of callbacks (read: pyramid of doom) in order to gather the information that we display at the end.
JavaScript and Node.js
var output1 = null;
var output2 = null;
var output3 = null;
fs.mkdirp("/a/test/dir", function (err1) {
Assert.ifError(err1);
fs.writeFile("/a/test/dir/file.txt", "Hello World", function (err2) {
Assert.ifError(err2);
fs.readFile("/a/test/dir/file.txt", function (err3, data) {
Assert.ifError(err3);
output1 = data; // ~> Buffer("Hello World")
fs.unlink("/a/test/dir/file.txt", function (err4) {
Assert.ifError(err4);
fs.readdir("/a/test", function (err5, dir) {
Assert.ifError(err5);
output2 = dir; // ~> ["dir"]
fs.stat("/a/test/dir", function (err6, stats) {
Assert.ifError(err6);
output3 = stats.isDirectory(); // ~> true
fs.rmdir("/a/test/dir", function (err7) {
Assert.ifError(err7);
fs.mkdirp("C:\\use\\windows\\style\\paths", function (err8) {
Assert.ifError(err8);
console.log("output1 =", output1.toString(), output1);
console.log("output2 =", output2);
console.log("output3 =", output3)
})
})
})
})
})
})
})
});
Now consider the equivalent logic in Scala.js using its much more elegant for
comprehension:
Scala.js and Node.js
import io.scalajs.nodejs.console
import io.scalajs.nodejs.Fs._
for {
_ <- Fs.mkdirpFuture("/a/test/dir")
_ <- Fs.writeFileFuture("/a/test/dir/file.txt", "Hello World")
output1 <- Fs.readFileFuture("/a/test/dir/file.txt") // ~> Buffer("Hello World")
_ <- Fs.unlinkFuture("/a/test/dir/file.txt")
output2 <- Fs.readdirFuture("/a/test") // ~> ["dir"]
output3 <- Fs.statFuture("/a/test/dir").map(_.isDirectory()) // ~> true
_ <- Fs.rmdirFuture("/a/test/dir")
_ <- Fs.mkdirpFuture("C:\\use\\windows\\style\\paths")
} {
console.log("output1 =", output1.toString(), output1)
console.log("output2 =", output2)
console.log("output3 =", output3)
}
Node.js
The Node.js integration is nearly complete (feature for feature), and should be more than sufficient for most web-based and CLI applications. Additionally, there are a growing number of third-party (mostly OSS) modules that have been implemented as well, including bcrypt, cassandra-driver, kafka-node, mysql, xml2js and many others.
#### ModulesThe following core Node.js modules (v8.7.0) have been implemented:
Node Module | Description |
---|---|
assert | Provides a simple set of assertion tests that can be used to test invariants. |
buffer | The Buffer class was introduced as part of the Node.js API to make it possible to interact with octet streams in the context of things like TCP streams and file system operations. |
child_process | The child_process module provides the ability to spawn child processes. |
cluster | The cluster module allows you to easily create child processes that all share server ports. |
crypto | The crypto module provides cryptographic functionality that includes a set of wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign and verify functions. |
dns | Support for DNS queries. |
events | Node.js Events Interface |
fs | File I/O is provided by simple wrappers around standard POSIX functions. |
http | Node.js HTTP Interface |
https | Node.js HTTPS Interface |
net | The net module provides you with an asynchronous network wrapper. |
os | Provides a few basic operating-system related utility functions. |
path | This module contains utilities for handling and transforming file paths. |
querystring | The querystring module provides utilities for parsing and formatting URL query strings. |
readline | Readline allows reading of a stream on a line-by-line basis. |
repl | The REPL provides a way to interactively run JavaScript and see the results. |
stream | A stream is an abstract interface implemented by various objects in Node.js. |
string-decoder | The string_decoder module provides an API for decoding Buffer objects into strings in a manner that preserves encoded multi-byte UTF-8 and UTF-16 characters. |
timers | The timer module exposes a global API for scheduling functions to be called at some future period of time. |
tty | The tty module provides the tty.ReadStream and tty.WriteStream classes. |
url | The url module provides utilities for URL resolution and parsing. |
util | The util module is primarily designed to support the needs of Node.js's internal APIs. |
vm | The vm module provides APIs for compiling and running code within V8 Virtual Machine contexts. |
zlib | This provides bindings to Gzip/Gunzip, Deflate/Inflate, and DeflateRaw/InflateRaw classes. |
NOTE: The SBT artifacts for Node.js platform are (choose one):
- NodeJS v8.7.0: "io.scalajs" %%% "nodejs" % "0.5.0"
- NodeJS LTS v6.11.4: "io.scalajs" %%% "nodejs-lts" % "0.5.0"
The following Third Party/OSS Node.js (npm) modules have been implemented:
Module / Package | Version | Description |
---|---|---|
async | 2.0.0 | Higher-order functions and common patterns for asynchronous code. |
bcrypt | 0.0.3 | A native JS bcrypt library for NodeJS. |
bignum | 0.12.5 | Arbitrary-precision integer arithmetic using OpenSSL. |
body-parser | 1.15.1 | Body parsing middleware. |
brake | 1.0.1 | Throttle a stream with backpressure. |
buffermaker | 1.2.0 | buffermaker is a convenient way of creating binary strings. |
cassandra-driver | 3.0.2 | DataStax Node.js Driver for Apache Cassandra |
cheerio | 0.22.0 | Tiny, fast, and elegant implementation of core jQuery designed specifically for the server |
chalk | 1.1.3 | Terminal string styling done right. Much color. |
cookie | 0.3.1 | HTTP server cookie parsing and serialization |
cookie-parser | 1.4.3 | Cookie parsing with signatures |
colors | 1.1.2 | Get colors in your node.js console. |
csv-parse | 1.1.2 | CSV parsing implementing the Node.js 'stream.Transform' API. |
csvtojson | 1.1.4 | A tool concentrating on converting csv data to JSON with customised parser supporting. |
drama | 0.1.3 | drama is an Actor model implementation for JavaScript and Node.js |
escape-html | 1.0.3 | Escape string for use in HTML |
express | 4.13.4 | Fast, unopinionated, minimalist web framework for Node.js |
express-csv | 0.6.0 | express-csv provides response csv easily to express. |
express-fileupload | 0.0.5 | Simple express file upload middleware that wraps around connect-busboy |
express-ws | 2.0.0 | WebSocket endpoints for Express applications |
feedparser-promised | 1.1.1 | Wrapper around feedparser with promises. |
filed | 0.1.0 | Simplified file library. |
github-api-node | 0.11.2 | A higher-level wrapper around the Github API. |
glob | 7.1.1 | A little globber. |
html-to-json | 0.6.0 | Parses HTML strings into objects using flexible, composable filters. |
htmlparser2 | 3.9.1 | A forgiving HTML/XML/RSS parser. The parser can handle streams and provides a callback interface. |
jsdom | 9.9.1 | A JavaScript implementation of the WHATWG DOM and HTML standards, for use with Node.js |
jwt-simple | 0.5.0 | JWT(JSON Web Token) encode and decode module |
kafka-node | 0.0.11 | A node binding for librdkafka |
kafka-rest | 0.0.4 | REST Proxy wrapper library for Kafka |
md5 | 2.1.0 | A JavaScript function for hashing messages with MD5. |
memory-fs | 0.3.0 | A simple in-memory filesystem. Holds data in a javascript object. |
mkdirp | 0.5.1 | Recursively mkdir, like mkdir -p. |
moment | 2.17.1 | Parse, validate, manipulate, and display dates in JavaScript. |
moment-timezone | 0.5.11 | Parse and display dates in any timezone. |
mongodb | 2.2.22 | The official MongoDB driver for Node.js. |
mongoose | 4.8.1 | Mongoose is a MongoDB object modeling tool designed to work in an asynchronous environment. |
mpromise | 0.5.5 | A promises/A+ conformant implementation, written for mongoose. |
multer | 1.1.0 | Multer is a node.js middleware for handling multipart/form-data. |
mysql | 2.10.2 | A node.js driver for mysql. |
node-zookeeper-client | 0.2.2 | A higher-level ZooKeeper client based on node-zookeeper with support for locking and master election. |
numeral | 2.0.4 | A javascript library for formatting and manipulating numbers. |
oppressor | 0.0.1 | Streaming http compression response negotiator. |
readable-stream | 2.2.2 | Streams3, a user-land copy of the stream library from Node.js. |
request | 2.72.1 | Simplified HTTP request client. |
rxjs | 4.1.0 | The Reactive Extensions for JavaScript. |
socket.io | 1.7.2 | Realtime application framework (Node.JS server). |
socket.io-client | 1.7.2 | Socket.io client. |
splitargs | 0.0.7 | Splits strings into tokens by given separator except treating quoted part as a single token. |
tingodb | 0.5.1 | Embedded Node.js database upward compatible with MongoDB. |
tough-cookie | 2.3.2 | RFC6265 Cookies and Cookie Jar for node.js. |
transducers-js | 0.4.174 | A high performance Transducers implementation for JavaScript. |
type-is | 1.6.14 | Infer the content-type of a request. |
watch | 0.18.0 | Utilities for watching file trees. |
winston | 2.3.1 | A multi-transport async logging library for Node.js. |
winston-daily-rotate-file | 1.4.4 | A multi-transport async logging library for Node.js. |
xml2js | 0.4.16 | Simple XML to JavaScript object converter. |
NOTE: The full SBT artifact expression is: "io.scalajs.npm" %%% "xxxx" % version (e.g. "io.scalajs.npm" %%% "express" % "0.5.0")
I've provided an example to demonstrate how similar the Scala.js code is to the JavaScript that it replaces.
The following is a simple Hello World app in Node using JavaScript:
var http = require("http");
http.createServer(function(request, response) {
response.writeHead(200, {"Content-Type": "text/plain"});
response.write("Hello World");
response.end();
}).listen(8888);
Here's the same example using Scala.js:
import io.scalajs.nodejs.http._
import scalajs.js
Http.createServer((request: ClientRequest, response: ServerResponse) => {
response.writeHead(200, js.Dictionary("Content-Type" -> "text/plain"))
response.write("Hello World")
response.end()
}).listen(8888)
Express.js
The following is a simple Hello World app in Node and Express using JavaScript:
var express = require('express');
var app = express();
app.get('/', function (req, res) {
res.send('Hello World');
})
var server = app.listen(8081, function () {
var host = server.address().address
var port = server.address().port
console.log("Example app listening at http://%s:%s", host, port)
})
Here's the same example using Scala.js:
import io.scalajs.nodejs.console
import io.scalajs.npm.express._
val app = Express()
app.get("/", (req: Request, res: Response) => res.send("Hello World"))
val server = app.listen(8081, connect)
private def connect: js.Function = () => {
val host = server.address().address
val port = server.address().port
console.log("Example app listening at http://%s:%s", host, port)
}
The following is a more elaborate example:
import io.scalajs.npm.express._
import io.scalajs.util.ScalaJsHelpers._
import scalajs.js
val todos: js.Array[Todo] = emptyArray
val app = Express()
app.use(BodyParser.json())
app.use(BodyParser.urlencoded(new UrlEncodedBodyOptions(extended = true)))
app.get("/api/todo/:id", (request: Request, response: Response) => getTodo(request, response))
app.get("/api/todos", (request: Request, response: Response) => getTodos(request, response))
app.post("/api/todo", (request: Request, response: Response) => createTodo(request, response))
def createTodo(request: Request, response: Response) = {
request.bodyAs[Todo] match {
case todo if todo.hasTitle =>
todo.id = UUID.randomUUID().toString
todos.push(todo)
response.send(todos)
case todo =>
response.badRequest(todo)
}
}
def getTodo(request: Request, response: Response) = {
val todoId = request.params("id")
todos.indexWhereOpt(_.id == todoId) match {
case Some(index) => response.send(todos(index))
case None => response.notFound(todoId)
}
}
def getTodos(request: Request, response: Response) = response.send(todos)
@js.native
trait Todo extends js.Object {
var id: String = js.native
var title: String = js.native
var completed: Boolean = js.native
}
implicit class TodoExtensions(val todo: Todo) extends AnyVal {
@inline
def hasId: Boolean = Option(todo).flatMap(t => Option(t.id)).exists(_.trim.nonEmpty)
@inline
def hasTitle: Boolean = Option(todo).flatMap(t => Option(t.title)).exists(_.trim.nonEmpty)
@inline
def isComplete: Boolean = hasId && hasTitle
}
MongoDB
The following example demonstrates establishing a connection to MongoDB using Scala.js:
import io.scalajs.nodejs.console
import io.scalajs.npm.mongodb._
import io.scalajs.util.ScalaJsHelper._
// Connection URL. This is where your mongodb server is running.
val url = "mongodb://localhost:27017/test"
// Use connect method to connect to the Server
MongoClient.connect(url, (err, db) => {
if (isDefined(err)) {
console.log("Unable to connect to the mongoDB server. Error:", err)
} else {
// HURRAY!! We are connected. :)
console.log("Connection established to: %s", url)
// TODO do some work here with the database.
// close connection
db.close()
}
})
Or, if you'd like to be more Scala idiomatic, the connection fragment could be written as follows:
import io.scalajs.nodejs.console
import io.scalajs.npm.mongodb._
import scala.util.{Success, Failure}
MongoClient.connectFuture(url) onComplete {
case Success(db) =>
// HURRAY!! We are connected. :)
console.log("Connection established to: %s", url)
// TODO do some work here with the database.
// close connection
db.close()
case Failure(e) =>
console.log("Unable to connect to the mongoDB server. Error:", e.getMessage)
}
Alternatively, you could choose to use "foreach" to directly manage only the success case:
import io.scalajs.npm.mongodb._
import io.scalajs.util.PromiseHelper._
MongoClient.connectFuture(url) foreach { db =>
// HURRAY!! We are connected. :)
console.log("Connection established to: %s", url)
// TODO do some work here with the database.
// close connection
db.close()
}
ScalaJs.io exposes Future-based alternatives to most of the asynchronous functions found in MongoDB, Express, Angular and Node. This means that you can use Scala's amazing for comprehensions to replace the dreaded pyramid of doom callbacks normally associated with JavaScript asynchronous code.
Consider the following:
for {
// List all the virtual machine images you can use.
vmImages <- computeManagementClient.virtualMachineVMImages.listFuture
// Create a cloud service.
computeManagementClient <- computeManagementClient.hostedServices.createFuture(
HostedServicesOptions(serviceName = serviceName, label = "cloud service 01", location = "West US"))
// Create a virtual machine in the cloud service
deployment <- computeManagementClient.virtualMachines.createDeploymentFuture(serviceName, deploymentOptions)
} {
console.info(deployment)
}