arangojs

ArangoDB JavaScript Driver

The official ArangoDB low-level JavaScript client.

Install

With Yarn or NPM

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

From source

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

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) {
    // ...
  });

Common issues

TypeScript error TS2304: Cannot find name 'Blob'.

Even if your project doesn't contain any browser code, you need to add "dom" to the "lib" array in your tsconfig.json to make arangojs work. This is a known limitation because the library supports both browser and Node environments and there is no common binary format that works in both environments:

// tsconfig.json
- "lib": ["es6"],
+ "lib": ["es6", "dom"],

Node.js ReferenceError: window is not defined

If you compile your Node project using a build tool like Webpack, you may need to tell it to target the correct environment:

// webpack.config.js
+ "target": "node",

To support use in both browser and Node environments arangojs uses the package.json browser field, to substitute browser-specific implementations for certain modules. Build tools like Webpack will respect this field when targetting a browser environment and may need to be explicitly told you are targetting Node instead.

Documentation

Latest Documentation

Testing

Run the tests using the yarn test or npm test commands:

yarn test
# - or -
npm test

By default the tests will be run against a server listening on http://localhost:8529 (using username root with no password). To override this, you can set the environment variable TEST_ARANGODB_URL to something different:

TEST_ARANGODB_URL=http://myserver.local:8530 yarn test
# - or -
TEST_ARANGODB_URL=http://myserver.local:8530 npm test

For development arangojs tracks the development build of ArangoDB. This means tests may reflect behavior that does not match any existing public release of ArangoDB.

To run tests for a specific release of ArangoDB other than the latest development build, use the environment variable ARANGO_VERSION, e.g. for 3.3:

ARANGO_VERSION=30300 yarn test
# - or -
ARANGO_VERSION=30300 npm test

The value follows the same format as the arangoVersion config option, i.e. XYYZZ where X is the major version, YY is the two digit minor version and ZZ is the two digit patch version (both zero filled to two digits).

Any incompatible tests will appear as skipped (not failed) in the test result.

To run the resilience/failover tests you need to set the environment variables RESILIENCE_ARANGO_BASEPATH (to use a local build of ArangoDB) or RESILIENCE_DOCKER_IMAGE (to use a docker image by name):

RESILIENCE_ARANGO_BASEPATH=../arangodb yarn test
# - or -
RESILIENCE_ARANGO_BASEPATH=../arangodb npm test

This runs only the resilience/failover tests, without running any other tests.

Note that these tests are generally a lot slower than the regular test suite because they involve shutting down and restarting individual ArangoDB server instances.

License

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

Changelog

[6.11.0] - 2019-08-16

Changed

• Renamed db.transaction to db.executeTransaction

  The method for executing server-side transactions is now called executeTransaction and the params argument now must be passed via the options object.

  For backwards-compatibility the new db.transaction method will continue to behave like before when passed an action string as the second argument. Note that this behavior is deprecated and will be removed in arangojs 7.

Added

• Added support for ArangoDB 3.5 streaming transactions

  New streaming transactions can be created using db.beginTransaction and existing streaming transactions can be accessed by passing the transaction ID to db.transaction.

  See the documentation of the transaction.run method for examples of using streaming transactions with arangojs.

• Added support for ArangoDB 3.5 Analyzers API

  See the documentation of the database.analyzer method and the Analyzer instances for information on using this API.

• Added collection.getResponsibleShard method

• Added support for new ArangoDB 3.5 collection properties

• Added support for new ArangoDB 3.5 View properties

Fixed

• Fixed a problem causing empty nested AQL expressions to be converted to bind variables

  Nesting an empty AQL expression like the result of calling aql.join with an empty array would previously result in the AQL expression not being recognized and being converted to an object bind variable instead.