JavaScriptJavaScript driver

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

Repository: fauna/faunadb-js

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

Via CDN:

<script src="//cdn.jsdelivr.net/npm/faunadb@latest/dist/faunadb.js"></script>

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

<script src="//cdn.jsdelivr.net/npm/faunadb@latest/dist/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 Fauna 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 Fauna response. See the JSDocs for faunadb.Client.

By default, the client object executes queries using HTTP Keep-Alive requests, which means that the connection is held open longer than required to receive a query response. This behavior can reduce the connection overhead when your code needs to issue many queries.

Should you ever need to disable keep-alive connections, you can do so in the client constructor’s options:

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

When keepAlive is set to false, each query that your code executes results in a separate HTTP connection to Fauna.

Pagination helpers

The driver contains helpers to provide a simpler API for consuming paged responses from Fauna. 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) {
  // Logs the page's contents,
  // for example: [ Ref(Collection("test"), "1234"), ... ]
  console.log(page);
});

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 documents.
  })

See the JSDocs for more information on the pagination helper.

Timeouts

The client can be configured to handle timeouts in two different ways:

  1. Specify an HTTP timeout by adding a timeout field to the options block when instantiating the client.

    When timeout is provided, the client waits the specified period before timing out, if it has yet to receive a response. When the period has elapsed, any subsequent response cannot be handled.

  2. Specify a server query timeout:

    1. by adding queryTimeout to the options block when instantiating the client, or

    2. by passing an object containing queryTimeout as the second parameter to the .query method.

    When a query timeout is provided, the server waits for the specified period before timing out, if it has yet to complete the current query. When the period has elapsed, the query fails and the server responds with an error.

Both timeouts are expressed in milliseconds.

For example:

// Specify an HTTP timeout
const client = new faunadb.Client({
  secret: 'YOUR_FAUNADB_SECRET',
  timeout: 1000,
})
// Specify a query timeout during client instantiation
const client = new faunadb.Client({
  queryTimeout: 2000,
  secret: 'YOUR_FAUNADB_SECRET',
})
// Specify a query timeout per query
client.query(
  q.Paginate(q.Collections()),
  { queryTimeout: 1 }
)

The queryTimeout passed to .query() take precedence over any queryTimeout specified during client instantiation.

Per-query options

Some options (currently only secret and queryTimeout) can be overridden on a per-query basis:

var createP = client.query(
  q.Create(
    q.Collection('test'),
    {
      data: { testField: 'testValue' }
    }
  ),
  { secret: 'YOUR_FAUNADB_SECRET' }
)
var helper = client.paginate(
  q.Match(q.Index('test_index'), 'example-term'),
  null,
  { secret: 'YOUR_FAUNADB_SECRET', }
)
var data = client.query(
  q.Paginate(q.Collections()),
  { queryTimeout: 100 }
)

Code

The JavaScript driver includes no polyfills. Support for Internet Explorer 11 requires a Promise polyfill.

Next steps

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!