Foxx – a lightweight Javascript application framework for ArangoDB

Foxx, Javascript Leave a comment

Edit: From version 1.4 the ArangoDB user manual available online also includes the documentation for FOXX.

For the last months we have been working on Foxx – a brand new Javascript framework on top of the upcoming version of the free and open source NoSQL database ArangoDB.
Foxx allows you to build APIs directly on top of the database and therefore skip the middleman (Rails, Django, Symfony or whatever your favorite web framework is). Foxx is designed with simplicity and the specific use case of modern client-side MVC frameworks in mind.
There are a couple of very interesting scenarios for Foxx:

  • You want to build a Single Page Web Application: most of the business logic is in the Javascript frontend. The backend’s most important task is to persist the data and send data to the client plus a bit of auth, modify, validate logic.  In this case ArangoDB plus a Foxx application is all you need as a backend.
  • Another use case is a mobile app either native or HTML5. Again you’ll have most of the logic already in the frontend (the app in this case). With Foxx you can create your API very easily. And as you don’t have a large full-size MVC stack included, your backend will be very, very fast.

You might want to consider Foxx even as lightweight, easy-to-learn alternative to Node.js.

How does it work?

Foxx apps are written in Javascript, the Javascript code is stored in production mode in the database. A Foxx app consists of a manifest file (a kind of central config file), the javascript application code, additional libraries like Backbone you might want to use, images and other assets.
As in similarly structured frameworks like Sinatra or Silex you define your own routes and assign functions to the routes. In these functions you have full access to the database.
Well, we all want to see code instead of reading long texts, so here is the not so awesome “Hello World” app in Foxx.

app = new FoxxApplication();
 
app.get("/hello/:name", function(req, res) {
 var name = req.params("name"),
  res.set("Content-Type", "text/plain");
  res.body("Hello " + name);
});
 
app.start(applicationContext);

Assuming we have a default ArangoDB installation and ArangoDB is running on port 8259 the browser can now access a url  http://localhost:8259/hello/{something} via REST. The database matches the url and returns “Hello {something}”. 

Is that all? Of course not. If you like to separate controller like logic from model related functionality, you can do this with Foxx as well. We don’t want to show this in detail in this very first announcement, but if you want to sneak a peek, have a look at Michael’s “todo app” implementation in Foxx.

What else is in Foxx?

  • Routes can have typed parameters (“foo” = string)
  • Routes can have annotations – the api documentation can be generated automatically from the annotations using Swagger
  • Foxx offers support for modules
  • Support for CoffeeScript
  • Support for the Underscore template engine is built in, other libs can be used as well.
  • The asset delivery system is easy to use and straight forward
  • “Format middleware”: React to certain request types (e.g. JSON) in a straight forward way
  • In development mode you edit your application files with your favorite editor/IDE. ArangoDB will read the files from the disk with each request. In production mode the code is stored inside of ArangoDB for faster response.
  • Using the setup/teardown feature in the manifest file.
  • You can run multiple Foxx apps at the same time – take a Foxx blog, a Foxx chat, a Foxx forum -> voilá, your community is ready
  • And: there will be a place to share Foxx apps

Is Foxx production ready?

This is a technical preview for the open minded – get the feature preview branch from Github (update: Foxx has been merged into the regular codebase a while ago), play around with it, give us some feedback and send us feature requests and muffins (we already have a real fox in the office, but if you have another one, come and bring it as a present as well). And yes, we are going to provide binaries very soon. And: not all features are done yet. On top of the list is the authentication feature, which will come next.

Installing the demo app

ArangoDB has now a “preview/Foxx” branch and a repository “ArangoDB-Apps” – The demo todo app called “aye_aye” is available there. First start arangosh.

arangosh> var aal = require("org/arangodb/aal");

Look for the “aye_aye” app in the repository:

arangosh> aal.printFishbowl("aye_aye");
Name: aye_aye
Author: Michael Hackstein
 
Description:
This a demo application implement a ToDo list based on TodoMVC.
 
1.0.7: aal.load("github", "mchacki/aye_aye", "v1.0.7");

There is one version listed above, so go ahead and load it:

arangosh> aal.load("github", "mchacki/aye_aye", "v1.0.7");
{
  "path" : "/tmp/Foxx/share/arangodb/js/apps/aye_aye-1.0.7",
  "error" : false,
  "code" : 200
}

Check that it is loaded now:

arangosh> aal.printAvailable()
 
AppID              Name                  Version    Path
=================  ====================  ========== ===================================
app:aardvark:1.0   aardvark              1.0        aardvark
app:aye_aye:1.0.7  aye_aye               1.0.7      aye_aye-1.0.7

Next we make it available using the “/todos” route:

arangosh> aal.installApp("aye_aye", "/todos");
{
  "appId" : "app:aye_aye:1.0.7",
  "mountId" : "21447079"
}
 
arangosh> aal.printInstalled()
 
MountID     AppID             Mount              Active  Devel
==========  =========         =================  ======  =====
21447079    app:aye_aye:1.0.7 /todos             yes     no

Open your browser at
http://localhost:8529/todos/

and enjoy!

To remove the app run:

arangosh> aal.uninstallApp("/todos");

About Lucas Dohmen

Lucas – as part of the core team – is the person behind the Ruby ArangoDB driver family, ArangoDB Foxx and parts of the graph functionality.