arangojs

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

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-preview.1/esm/index.js?+esm"
    }
  }
</script>
<script type="module">
  import { Database } from "arangojs";
  const db = new Database();
  // ...
</script>

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();

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");

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);
  });

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 arangojs encounters an API error, it will throw an ArangoError with an errorNum property indicating the ArangoDB error code and the code property indicating the HTTP status code from the response body.

For any other non-ArangoDB error responses (4xx/5xx status code), it will throw an HttpError error with the status code indicated by the code property.

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

In all of these cases the server response object will be exposed as the response property on the error object.

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

Common issues

Missing functions or 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. 7.x.y -> 8.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.

Note: As of June 2018 ArangoDB 2.8 has reached its End of Life and is no longer supported in arangojs 7 and later. If your code needs to work with ArangoDB 2.8 you can continue using arangojs 6 and enable ArangoDB 2.8 compatibility mode by setting the config option arangoVersion: 20800 to enable the ArangoDB 2.8 compatibility mode in arangojs 6.

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

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

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,
  });

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,
  });

Or using object destructuring:

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

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

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.

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

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

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.

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.

Node.js with self-signed HTTPS certificates

If you need to support self-signed HTTPS certificates in Node.js, you may have to override the global fetch agent. At the time of this writing, there is no official way to do this for the native fetch implementation in Node.js.

However as Node.js uses the undici module for its fetch implementation internally, you can override the global agent by adding undici as a dependency to your project and using its setGlobalDispatcher as follows:

import { Agent, setGlobalDispatcher } from "undici";

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

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

import { Agent, setGlobalDispatcher } from "undici";

setGlobalDispatcher(
  new Agent({
    rejectUnauthorized: false,
  })
);

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));

Please refer to the documentation of this 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.

Changelog

[9.0.0] - 2024-07-31

This is a major release and breaks backwards compatibility.

See the migration guide for detailed instructions for upgrading your code to arangojs v9.

Removed

• Removed Node.js 14 and Node.js 16 support

  With Node.js 14 and 16 having reached their end of life, arangojs will no longer support these versions of Node.js going forward.

  For more information, see the Node.js release schedule.

• Removed Params and Headers types

  These can mostly be replaced with the native URLSearchParams and Headers types but most public methods still accept the equivalent Record types for convenience.

• Removed deprecated FulltextIndex and related types

  Fulltext indexes have been deprecated in ArangoDB 3.10 and should be replaced with ArangoSearch.

• Removed browser build

  The browser build has been removed from the repository and will no longer be published to npm. The npm package can still be used in the browser by using common frontend tooling like webpack or rollup.

• Removed Collection methods for simple queries: list, all, any, byExample, firstExample, removeByExample, replaceByExample, updateByExample, lookupByKeys, removeByKeys, fulltext

  Simple queries were deprecated in ArangoDB 3.4 and can be replicated with AQL.

Changed

• Replaced request logic with native fetch API (#788, DE-578, DE-758)

  The node-specific request logic using the http and https modules has been replaced with all-new logic using the web standard fetch API, which should work in Node.js, browsers and other conformant environments.

• Unicode names are now no longer automatically NFC normalized (DE-65)

  This change affects all database, collection, graph, view and analyzer names using unicode characters. Starting with arangojs v7.7.0 these names were automatically NFC normalized. This behavior has now been reverted to match the behavior of other ArangoDB drivers and help detect normalization issues in user code.

• Changed return type of aql and the AQL join helper function to AqlQuery

  Previously the internal GeneratedAqlQuery type was exposed as the return type of these functions, leading to complexity when handling generic type arguments.

• Removed dependency on Node path module or its browserify equivalent

  This change should be backwards-compatible but may produce different results when using non-normalized paths and base-paths in custom routes. This should help support more environments and reduce the size of the browser bundle.

• Inlined x3-linkedlist dependency

  Inlining this dependency should help make arangojs more portable.

• Split the Collection type parameter into result and input types (#807)

  It is now possible to specify a separate type for the data passed when creating or modifying documents in addition to the type of the data returned when fetching documents. This allows excluding computed properties from the input type while still including them in the result type.

Added

• Added ESM support (DE-236)

  The driver now supports being imported as an ES module or CommonJS module and provides exports for both types of environments. This change should be backwards-compatible.

• Added support for withHidden option in collection.indexes

  This option was introduced in ArangoDB 3.10.13 and 3.11.7 and allows fetching the progress information of indexes that are in the building phase.

• Added support for withStats option in collection.indexes

  This method now takes an object with withStats and withHidden options instead of a boolean flag.

• Added readonly Job#id property

  This property was not previously exposed.

• Added skipFastLockRound option for streaming transactions

  This option was introduced in 3.12.1 and allows skipping the fast lock round.

• Added non-specific EnsureIndexOptions type and ensureIndex method signature (#778)

  This allows creating indexes without narrowing the index type.