JavaScriptJavascript driver

The section describes Fauna’s open source Javascript driver, which provides the resources required to interact with FaunaDB.

Supported runtimes

This driver supports and is tested on:

  • Node.js

    • LTS

    • Stable

  • Chrome

  • Firefox

  • Safari

  • Internet Explorer 11

Installation

Node.js

npm install --save faunadb

See faunadb on NPM for more information.

Browsers

The browser release can be found in the fauna/faunadb-js-release repository.

This release can be installed via Bower:

bower install faunadb

Or via CDN:

<script src="//cdn.jsdelivr.net/gh/fauna/faunadb-js-release@latest/faunadb.js"></script>

The minified version of the driver can also be used via CDN:

<script src="//cdn.jsdelivr.net/gh/fauna/faunadb-js-release@latest/faunadb-min.js"></script>

Usage

Requiring the driver

var faunadb = require('faunadb'),
  q = faunadb.query

This is the recommended require stanza. The faunadb.query module contains all of the functions to create FaunaDB Query expressions.

Instantiating a client and issuing queries

var client = new faunadb.Client({ secret: 'YOUR_FAUNADB_SECRET' })

Once the client has been instantiated, it can be used to issue queries. For example, to create an instance in an existing class named test with the data: { testField: 'testValue' }:

var createP = client.query(
  q.Create(
    q.Collection('test'),
    { data: { testField: 'testValue' } }
  )
)

All methods on faunadb.Client return ES6 Promises. So, if we wanted to handle the Promise to access the Ref of the newly created instance:

createP.then(function(response) {
  console.log(response.ref); // Logs the ref to the console.
})

response is a JSON object containing the FaunaDB response. See the JSDocs for faunadb.Client.

Pagination Helpers

The driver contains helpers to provide a simpler API for consuming paged responses from FaunaDB. See the Paginate reference for a description of paged responses.

Using the helper to page over sets lets the driver manage cursors and pagination state. For example, client.paginate:

var helper = client.paginate(
  q.Match(
    q.Index('test_index'),
    'example-term'
  )
)

The return value, helper, is an instance of PageHelper. The each method executes a callback function on each consumed page.

helper.each(function(page) {
  console.log(page); // Logs the page's contents, for example: [ Ref(Collection("test"), "1234"), ... ]
});

Note that each returns a Promise<void> that is fulfilled on the completion of pagination.

The pagination can be transformed server-side via the Fauna Query Language by using the map and filter functions.

For example, to retrieve the matched instances:

helper.map(function(ref) { return q.Get(ref); }).each(function(page) {
  console.log(page); // Logs the retrieved instances.
});

See the JSDocs for more information on the pagination helper.

Code

As the driver targets multiple JS runtimes, it is developed in vanilla ES5. We use the es6-promise polyfill in order to provide Promise support.

Next steps

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!