fauna client library for javascript
CoffeeScript Ruby
Switch branches/tags
Nothing to show
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



This is a client library for using the fauna service (https://fauna.org).

It's written in coffeescript and node, but it compiles to javascript, and is explicitly written to work in (modern) browsers. It does this primarily by using the 'request' library (https://npmjs.org/package/request) for HTTP inside node, and 'browser-request' (https://npmjs.org/package/browser-request) inside a browser.

All API calls use the standard Q futures library (https://npmjs.org/package/q).

The packaging assumes you use browserify, or something very similar.


This library is currently incomplete, and only implements the features I need for the redpanda project. I intend to end up with a complete implementation of the fauna v1 API, so please file an issue or contact me (Twitter & email below) if you have suggestions, bug reports, or patches.

Basic usage is to create a new Fauna object, register your model classes with it, authenticate, and then do whatever you want.

var fauna = require('fauna-js');

var client = new fauna.Fauna();
client.addClasses(Song, Album);

Registering the model classes allows the library to encode and decode objects (see below).


Fauna works with "classes" and "instances" which should map to models and objects in your app.

A model is a prototype that extends fauna.Class. For example, here's a model for a song in coffeescript:

fauna = require 'fauna-js'

class Song extends fauna.Class
  @field "title", "rating"
  @reference "artist"

The static call @field registers "title" and "rating" as fields in your javascript object that should be submerged into the 'data' JSON blob when storing an object in fauna.

Similarly, @reference registers "artist" as a field that refers to another object stored in fauna. It will be stored by instance ID in the 'references' JSON blob. Fauna will usually follow references when fetching objects (at least one or two levels deep), so when reading a Song object, the "artist" field may contain another full object.

The @field and @reference calls can be used as many times as you want within a single class, or you may list all the relevant fields on a single line (like above), Check out the fauna documentation for more details about the 'data' and 'references' fields on stored instances.

The javascript equivalent of declaring a model class looks like this:

var fauna = require('fauna-js');

var extends = function(child, parent) {
  child.prototype = new parent;
  for (var key in parent) { child[key] = parent[key]; }

function Song() {
  fauna.Class.apply(this, arguments);
extends(Song, fauna.Class);

Song.field("title", "rating");

The definition of "extends" is shown only for convenience -- you should use the subclass mechanism your framework uses.

The fauna tracking info for an object will be stored in a field named '_fauna'. The tracking info contains:

  • id: the fauna resource reference ID
  • className: fauna class name
  • ts: javascript timestamp (milliseconds) of the last update
  • deleted: true/false if this refers to a deleted object
console.log "Song title is '#{song.title}' (fauna id #{song._fauna.id})"

The fauna class name can be inferred (the lowercase name of the model class, plus an 's') or declared explicitly with @faunaClass:

class Song extends fauna.Class
  @faunaClass "all_songs"

Event sets

Custom event sets can be declared on a model class with @eventSet, with optional config data attached:

class Album extends fauna.Class
  @eventSet "tracks", { ordered: true }

This will create a special field 'tracks' on any Album object, which refers to an object with methods for manipulating the set. The methods are:

  • add(object)

    Add an object to an event set. The object must already exist in fauna and be the result of some previous fauna-js call or passed to `createInstance'. It may be a fauna instance ID instead of an object, for convenience.

  • remove(object)

    Remove an object from an event set. The same restrictions apply as add.

  • page(params)

    Fetch the objects that were added to an event set within a time range. The default time range is infinite, or listing every object currently in the set. Paramaters are count (maximum number of objects to fetch), before, and after (tags returned by a previous result). The result is an object with the items in items, and the before/after tags in before and after.


Install dependencies using node:

$ npm install

Run tests using cake (or npm):

$ cake test

Build the library by compiling the coffeescript into javascript:

$ cake build

Pull requests and bug reports are tracked on github: https://github.com/robey/fauna-js


Apache 2 (open-source) license, included in 'LICENSE.txt'.


@robey - Robey Pointer robeypointer@gmail.com