ArangoDB JavaScript Driver

The official ArangoDB low-level JavaScript client.

Note: if you are looking for the ArangoDB JavaScript API in Foxx (or the arangosh interactive shell) please refer to the documentation about the @arangodb module instead; specifically the db object exported by the @arangodb module. The JavaScript driver is only meant to be used when accessing ArangoDB from outside the database.

• Changelog
• Reference

Compatibility

ArangoJS is compatible with the latest stable version of ArangoDB available at the time of the driver release.

The arangoVersion option can be used to tell arangojs to target a specific ArangoDB version. Depending on the version this will enable or disable certain methods and change behavior to maintain compatibility with the given version. The oldest version of ArangoDB supported by arangojs when using this option is 2.8.0 (using arangoVersion: 20800).

The latest yarn/npm distribution of ArangoJS is compatible with the current Node.js version and the active LTS versions, following the official Node.js long-term support schedule.

The included browser build is compatible with recent versions of all modern browsers (Edge, Chrome, Firefox and Safari).

Versions outside this range may be compatible but are not actively supported.

Note: Starting with arangojs 6.0.0, all asynchronous functions return promises. If you are using a version of Node.js older than Node.js 6.x LTS (“Boron”) make sure you replace the native Promise implementation with a substitute like bluebird to avoid a known memory leak in older versions of the V8 JavaScript engine.

Versions

The version number of this driver does not indicate supported ArangoDB versions!

This driver uses semantic versioning:

• A change in the bugfix version (e.g. X.Y.0 -> X.Y.1) indicates internal changes and should always be safe to upgrade.
• A change in the minor version (e.g. X.1.Z -> X.2.0) indicates additions and backwards-compatible changes that should not affect your code.
• A change in the major version (e.g. 1.Y.Z -> 2.0.0) indicates breaking changes that require changes in your code to upgrade.

If you are getting weird errors or functions seem to be missing, make sure you are using the latest version of the driver and following documentation written for a compatible version. If you are following a tutorial written for an older version of arangojs, you can install that version using the <name>@<version> syntax:

# for version 6.x.x
yarn add arangojs@6
# - or -
npm install --save arangojs@6

You can find the documentation for each version by clicking on the corresponding date on the left in the list of version tags.

Install

With Yarn or NPM

yarn add arangojs
# - or -
npm install --save arangojs

With Bower

Starting with arangojs 6.0.0 Bower is no longer supported and the browser build is now included in the NPM release (see below).

From source

git clone https://github.com/arangodb/arangojs.git
cd arangojs
npm install
npm run dist

For browsers

For production use arangojs can be installed with Yarn or NPM like any other dependency. Just use arangojs like you would in your server code:

import { Database } from "arangojs";
// -- or --
var arangojs = require("arangojs");

Additionally the NPM release comes with a precompiled browser build:

var arangojs = require("arangojs/lib/web");

You can also use unpkg during development:

< !-- note the path includes the version number (e.g. 6.0.0) -- >
<script src="https://unpkg.com/arangojs@6.0.0/lib/web.js"></script>
<script>
var db = new arangojs.Database();
db.listCollections().then(function (collections) {
  alert("Your collections: " + collections.map(function (collection) {
    return collection.name;
  }).join(", "));
});
</script>

If you are targeting browsers older than Internet Explorer 11 you may want to use babel with a polyfill to provide the missing functionality needed to use arangojs.

When loading the browser build with a <script> tag make sure to load the polyfill first:

<script src="https://cdnjs.cloudflare.com/ajax/libs/babel-polyfill/6.26.0/polyfill.js"></script>
<script src="https://unpkg.com/arangojs@6.0.0/lib/web.js"></script>

Basic usage example

// Modern JavaScript
import { Database, aql } from "arangojs";
const db = new Database();
(async function() {
  const now = Date.now();
  try {
    const cursor = await db.query(aql`
      RETURN ${now}
    `);
    const result = await cursor.next();
    // ...
  } catch (err) {
    // ...
  }
})();

// or plain old Node-style
var arangojs = require("arangojs");
var db = new arangojs.Database();
var now = Date.now();
db.query({
  query: "RETURN @value",
  bindVars: { value: now }
})
  .then(function(cursor) {
    return cursor.next().then(function(result) {
      // ...
    });
  })
  .catch(function(err) {
    // ...
  });

// Using different databases
const db = new Database({
  url: "http://localhost:8529"
});
db.useDatabase("pancakes");
db.useBasicAuth("root", "");
// The database can be swapped at any time
db.useDatabase("waffles");
db.useBasicAuth("admin", "maplesyrup");

// Using ArangoDB behind a reverse proxy
const db = new Database({
  url: "http://myproxy.local:8000",
  isAbsolute: true // don't automatically append database path to URL
});

// Trigger ArangoDB 2.8 compatibility mode
const db = new Database({
  arangoVersion: 20800
});

For AQL please check out the aql template tag for writing parametrized AQL queries without making your code vulnerable to injection attacks.

Error responses

If arangojs encounters an API error, it will throw an ArangoError with an errorNum error code as well as a code and statusCode property indicating the intended and actual HTTP status code of the response.

For any other error responses (4xx/5xx status code), it will throw an HttpError error with the status code indicated by the code and statusCode properties.

If the server response did not indicate an error but the response body could not be parsed, a SyntaxError may be thrown instead.

In all of these cases the error object will additionally have a response property containing the server response object.

If the request failed at a network level or the connection was closed without receiving a response, the underlying error will be thrown instead.

Examples

// Using async/await
try {
  const info = await db.createDatabase("mydb");
  // database created
} catch (err) {
  console.error(err.stack);
}

// Using promises with arrow functions
db.createDatabase("mydb").then(
  info => {
    // database created
  },
  err => console.error(err.stack)
);