Skip to content


Subversion checkout URL

You can clone with
Download ZIP
fauna client library for javascript
CoffeeScript Ruby
Tree: 95d2328abf

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 (

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 ( for HTTP inside node, and 'browser-request' ( inside a browser.

All API calls use the standard Q futures library (

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.


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 the instance id (as id), timestamp (as ts), and class name in the database (as className).

console.log "Song title is '#{song.title}' (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:

class Album extends fauna.Class
  @eventSet "tracks"

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.


Apache 2 license, included in 'LICENSE.txt'.


@robey - Robey Pointer

Something went wrong with that request. Please try again.