ArangoDB JavaScript Driver

The official ArangoDB JavaScript client for Node.js and the browser.

Links

• API Documentation

• Changelog

• Migration Guide

Install

With npm or yarn

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

For browsers

When using modern JavaScript tooling with a bundler and compiler (e.g. Babel), arangojs can be installed using npm or yarn like any other dependency.

You can also use jsDelivr CDN during development:

<script type="importmap">
  {
    "imports": {
      "arangojs": "https://cdn.jsdelivr.net/npm/arangojs@9.0.0/esm/index.js?+esm"
    }
  }
</script>
<script type="module">
  import { Database } from "arangojs";
  const db = new Database();
  // ...
</script>
Copy

Basic usage example

Modern JavaScript/TypeScript with async/await and ES Modules:

import { Database, aql } from "arangojs";

const db = new Database();
const Pokemons = db.collection("my-pokemons");

async function main() {
  try {
    const pokemons = await db.query(aql`
      FOR pokemon IN ${Pokemons}
      FILTER pokemon.type == "fire"
      RETURN pokemon
    `);
    console.log("My pokemans, let me show you them:");
    for await (const pokemon of pokemons) {
      console.log(pokemon.name);
    }
  } catch (err) {
    console.error(err.message);
  }
}

main();
Copy

Using a different database:

const db = new Database({
  url: "http://127.0.0.1:8529",
  databaseName: "pancakes",
  auth: { username: "root", password: "hunter2" },
});

// The credentials can be swapped at any time
db.useBasicAuth("admin", "maplesyrup");
Copy

Old-school JavaScript with promises and CommonJS:

var arangojs = require("arangojs");
var Database = arangojs.Database;

var db = new Database();
var pokemons = db.collection("pokemons");

db.query({
  query: "FOR p IN @@c FILTER p.type == 'fire' RETURN p",
  bindVars: { "@c": "pokemons" },
})
  .then(function (cursor) {
    console.log("My pokemons, let me show you them:");
    return cursor.forEach(function (pokemon) {
      console.log(pokemon.name);
    });
  })
  .catch(function (err) {
    console.error(err.message);
  });
Copy

Note: The examples throughout this documentation use async/await and other modern language features like multi-line strings and template tags. When developing for an environment without support for these language features, substitute promises for await syntax as in the above example.

Compatibility

The arangojs driver is compatible with the latest stable version of ArangoDB available at the time of the driver release and remains compatible with the two most recent Node.js LTS versions in accordance with the official Node.js long-term support schedule. Versions of ArangoDB that have reached their end of life by the time of a driver release are explicitly not supported.

For a list of changes between recent versions of the driver, see the CHANGELOG.

Note: arangojs is only intended to be used in Node.js or a browser to access ArangoDB from outside the database. If you are looking for the ArangoDB JavaScript API for Foxx or for accessing ArangoDB from within the arangosh interactive shell, please refer to the documentation of the @arangodb module and the db object instead.

Error responses

If the server returns an ArangoDB error response, arangojs will throw an ArangoError with an errorNum property indicating the ArangoDB error code and expose the response body as the response property of the error object.

For all other errors during the request/response cycle, arangojs will throw a NetworkError or a more specific subclass thereof and expose the originating request object as the request property of the error object.

If the server responded with a non-2xx status code, this NetworkError will be an HttpError with a code property indicating the HTTP status code of the response and a response property containing the response object itself.

If the error is caused by an exception, the originating exception will be available as the cause property of the error object thrown by arangojs. For network errors, this will often be a TypeError.

Node.js network errors

In Node.js, network errors caused by a TypeError will often have a cause property containing a more detailed exception.

Specifically, these are often either system errors (represented by regular Error objects with additional properties) or errors from the undici module Node.js uses internally for its native fetch implementation.

Node.js system error objects provide a code property containing the specific string error code, a syscall property identifying the underlying system call that triggered the error (e.g. connect), as well as other helpful properties.

For more details on Node.js system errors, see the Node.js documentation of the SystemError interface as well as the section on Node.js error codes.

For more details on the errors thrown by undici, see the undici errors documentation.

Common issues

Unexpected server errors

Please make sure you are using the latest version of this driver and that the version of the arangojs documentation you are reading matches that version.

Changes in the major version number of arangojs (e.g. 8.x.y -> 9.0.0) indicate backwards-incompatible changes in the arangojs API that may require changes in your code when upgrading your version of arangojs.

Additionally please ensure that your version of Node.js (or browser) and ArangoDB are supported by the version of arangojs you are trying to use. See the compatibility section for additional information.

You can install an older version of arangojs using npm or yarn:

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

No code intelligence when using require instead of import

If you are using require to import the arangojs module in JavaScript, the default export might not be recognized as a function by the code intelligence of common editors like Visual Studio Code, breaking auto-complete and other useful features.

As a workaround, use the arangojs function exported by that module instead of calling the module itself:

  const arangojs = require("arangojs");

- const db = arangojs({
+ const db = arangojs.arangojs({
    url: ARANGODB_SERVER,
  });
Copy

Alternatively you can use the Database class directly:

  const arangojs = require("arangojs");
+ const Database = arangojs.Database;

- const db = arangojs({
+ const db = new Database({
    url: ARANGODB_SERVER,
  });
Copy

Or using object destructuring:

- const arangojs = require("arangojs");
+ const { Database } = require("arangojs");

- const db = arangojs({
+ const db = new Database({
    url: ARANGODB_SERVER,
  });
Copy

Error stack traces contain no useful information

Due to the async, queue-based behavior of arangojs, the stack traces generated when an error occur rarely provide enough information to determine the location in your own code where the request was initiated.

Using the precaptureStackTraces configuration option, arangojs will attempt to always generate stack traces proactively when a request is performed, allowing arangojs to provide more meaningful stack traces at the cost of an impact to performance even when no error occurs.

  import { Database } from "arangojs";

  const db = new Database({
    url: ARANGODB_SERVER,
+   precaptureStackTraces: true,
  });
Copy

Note that arangojs will attempt to use Error.captureStackTrace if available and fall back to generating a stack trace by throwing an error. In environments that do not support the stack property on error objects, this option will still impact performance but not result in any additional information becoming available.

Unix domain sockets

If you want to use Unix domain sockets, you need to install the undici module, which is an optional peer dependency of arangojs.

npm install --save undici
Copy

If the undici module is not installed and arangojs attempts to make a request over a Unix domain socket, the request will fail with a plain Error with a message indicating that the undici module is unavailable.

Node.js with self-signed HTTPS certificates

If you need to support self-signed HTTPS certificates in Node.js, you will need to install the undici module, which is an optional peer dependency of arangojs.

npm install --save undici
Copy

You can instruct arangojs to use the undici module by setting the config.agentOptions option:

  import { Database } from "arangojs";

  const db = new Database({
    url: ARANGODB_SERVER,
+   agentOptions: {
+     ca: [
+       fs.readFileSync(".ssl/sub.class1.server.ca.pem"),
+       fs.readFileSync(".ssl/ca.pem"),
+     ],
+   },
  });
Copy

To override the global fetch agent instead, you can use the undici module's setGlobalDispatcher method as follows:

import { Agent, setGlobalDispatcher } from "undici";

setGlobalDispatcher(
  new Agent({
    ca: [
      fs.readFileSync(".ssl/sub.class1.server.ca.pem"),
      fs.readFileSync(".ssl/ca.pem"),
    ],
  })
);
Copy

Although this is strongly discouraged, it's also possible to disable HTTPS certificate validation entirely this way, but note this has extremely dangerous security implications:

  import { Database } from "arangojs";

  const db = new Database({
    url: ARANGODB_SERVER,
+   agentOptions: {
+     rejectUnauthorized: false,
+   },
  });
Copy

The requirement to use the undici module to override these settings is a known limitation of Node.js at the time of this writing.

When using arangojs in the browser, self-signed HTTPS certificates need to be trusted by the browser or use a trusted root certificate.

Streaming transactions leak

When using the transaction.step method it is important to be aware of the limitations of what a callback passed to this method is allowed to do.

const collection = db.collection(collectionName);
const trx = db.transaction(transactionId);

// WARNING: This code will not work as intended!
await trx.step(async () => {
  await collection.save(doc1);
  await collection.save(doc2); // Not part of the transaction!
});

// INSTEAD: Always perform a single operation per step:
await trx.step(() => collection.save(doc1));
await trx.step(() => collection.save(doc2));
Copy

Please refer to the documentation of the transaction.step method for additional examples.

Streaming transactions timeout in cluster

Example messages: transaction not found, transaction already expired.

Transactions have different guarantees in a cluster.

When using arangojs in a cluster with load balancing, you may need to adjust the value of config.poolSize to accommodate the number of transactions you need to be able to run in parallel. The default value is likely to be too low for most cluster scenarios involving frequent streaming transactions.

Note: When using a high value for config.poolSize you may have to adjust the maximum number of threads in the ArangoDB configuration using the server.maximal-threads option to support larger numbers of concurrent transactions on the server side.

License

The Apache License, Version 2.0. For more information, see the accompanying LICENSE file.

Includes code from x3-linkedlist used under the MIT license.