ArangoDB client

A client for the ArangoDB nosql database for nodejs and browsers.

NOTE: The official ArangoDB JavaScript driver now lives @ https://github.com/arangodb/arangojs.

Latest changes

The Query API returns result from Aql cursors unfiltered. Before you only got the result Array missing some 'extra' information.

db.query
  .for('u').in('_users').return('u')
  .exec()
  .then(function(ret){
    console.log("ret.result", ret.result); // array with results
    console.log("ret.extra", ret.extra); // extra information
  });

A callback method has been added that can be used instead of a callback passed as argument.

x = db.database.create("newdb")
  .callback(function(err,ret){
    ... same as above ...  
  });

// x => Promise

You may however still pass a callback to the API methods in which case promises are bypassed so you achieve a little less overhead in your db.api calls.

var x = db.collection.list(function(err,ret){
  console.log("err(%s):",err,ret);
});

// x => undefined

Introduction

You can use arango-client either as node.js server module or from a web client. Since arango-client is written as a commonJS module you can just require it in your nodejs project or using the generated build file which you can include into your client side app.

Install

From source: `git clone git://github.com/triAGENS/ArangoDB-JavaScript`
web component: `component install triAGENS/ArangoDB-JavaScript`
nodejs module: `npm install arangojs`

Building

make build

Creates a single build.js component in the ./build directory. A standalone is built separately and named arango.js.

Documentation

make docs

Generates the documentation in the documentation folder. An installation of yuidocjs is required (npm i -g yuidocjs). You can visit the latest documentation on http://www.arangodb.org/manuals-javascript/master/.

Test

make test

Runs the test suite sequentially under nodejs and karma (supporting Firefox and Chrome). Feel free to chip in by writing tests if you want a more stable package.

Quick start

To use the client you require it at a commonJS module.

var arango = require('arango');

Then you initialize a connection which returns a db handle.

var db = arango.Connection("http://myarangodb.server.com:8529");

db.collection.list().done(function(res){
  console.log("collections: %j", res);
});

In a browser

For usage in a web browser you can either use the standalone version arango.js or the build.js component. A minimal html page using the arangodb client from a web app can look like this.

<!doctype html>
<html>
<head>
    <title>ArangoDB in your browser</title>
    <meta charset="utf-8"/>
</head>
<body>
    <div id="test"></div>
    <script src="../build/build.js"></script>
    <script>
        var arango = require('arango'),
            elem = document.getElementById('test'),
            db = new arango.Connection;

        db.collection.list().then(function(res){
            elem.innerHTML = JSON.stringify(res,null,2);
        }, function(error){
            elem.innerHTML = JSON.stringify(error,null,2);
        })        
    </script>
</body>
</html>

The standalone version yields a global arango object.

<!doctype html>
<html>
<head>
    <title>ArangoDB in your browser</title>
    <meta charset="utf-8"/>
</head>
<body>
    <div id="test"></div>
    <!-- Note: Exports global arango -->
    <script src="../build/arango.js"></script>
    <script>
        var elem = document.getElementById('test'),
            db = new arango.Connection;

        db.collection.list().then(function(res){
            elem.innerHTML = JSON.stringify(res,null,2);
        }, function(error){
            elem.innerHTML = JSON.stringify(error,null,2);
        })        
    </script>
</body>
</html>

API

The following API:s are (more or less) supported, check out the ArangoDB documentation.

The API methods return a promise. If you like nodejs callbacks you can use the callback utility provided by the micropromise framework.

Example using a promise:

db.document.get(docid).then(function(res){ 
  console.log("res: %j", res) 
},function(err){ 
  console.log("err: %j", err) 
});

Example when using a callback:

db.document.get(docid)
  .callback(function(err,res){
    if(err) console.log("err: %j", res);
    else console.log("res: %j", res);
  });

Usage

Connect()

Factory for arango connection. Sets up a connection to localhost http://127.0.0.1:8529 by default.

  db = arango.Connection()

Connection string

  db = arango.Connection("http://127.0.0.1/mydb:collection");

Connection with http auth

  db = arango.Connection("http://user:pass@your.host.com/database");

Connection object

  db = arango.Connection({_name:"database",_collection:"collection",_server:{hostname:"test.host"}});

Connecting to a unix socket (nodejs only)

  db = arango.Connection({_server:{socketPath:"/var/tmp/arango.sock"}});

String and object

  db = arango.Connection("http://test.host.com:80/default",{_server:{username:"user",password:"pass"}});

String and api plugin

  db = arango.Connection("http://test.host.com:80/foxx",{api:{'foxx':require('foxx')}});

use()

With use() you can switch connection settings

  var test = db.use("http://test.host:8520")

Use another database

  var test_mydb = test.use("/mydb");

Change to another database & collection

  var test_mydb2_mail = test_mydb.use("/mydb2:mail");

Change collection

  var test_mydb2__users = test_mydb2_mail.use(":_users");

Creating collections & documents

Initialize a Connection

var db = arango.Connection('http://127.0.0.1:8529');

Create a new database

db.database.create('mydb').then(function(res){
  console.log("Database created: %j", res);
},function(err){
  console.log("Failed to create database: %j", err);
})

Use mydb database

var mydb = db.use('/mydb');

Create a 'test' collection

mydb.collection.create('test').then(function(res){
  console.log("result: %j",res);
},function(err){
  console.log("error: %j",err);
});

List all collections in mydb, note the use of done()

mydb.collection.list().done(function(res){
  console.log("collections: %j", res);
});

Create a collection with options

mydb.collection.create('mycoll',{
  journalSize: 10000000,
  waitForSync:true,
  keyOptions: { 
    type: "autoincrement", 
    increment: 5, 
    allowUserKeys: true 
  }
}).then(function(res){
  console.log("result: %j",res);
},function(err){
  console.log("error: %j",err);
});

Delete collection (using callback)

mydb.collection.delete('mycoll').callback(function(err,ret){
  console.log("error(%s): %j", err, ret);
});

Create a 'test2' collection (using callback)

mydb.collection.create('test2').callback(function(err,ret){
  console.log("error(%s): %j", err, ret);
});

Create a new document in 'test' collection

mydb.document.create('test',{a:'test',b:123,c:Date()})
  .then(function(res){ 
    console.log("res: %j", res); 
  },function(err){ 
    console.log("err: %j", err); 
  });

Get a list of all documents in 'test' collection

mydb.document.list('test')
  .then(function(res){ 
    console.log("res: %j", res); 
  },function(err){ 
    console.log("err: %j", err); 
  });

Create a new document and create a new collection by passing in options

mydb.document.create("newcollection",{a:"test"},{createCollection:true})
  .then(function(res){ console.log("res", JSON.stringify(res) },
    function(err){ console.log("err", err) } );
});

Create document and wait for disk sync

mydb.document.create("newcollection",{a:"test"},{waitForSync:true})
  .then(function(res){ console.log("res", JSON.stringify(res) },
    function(err){ console.log("err", err) } );
});

Create another document in the collection

db.document.create("newcollection",{b:"test"})
  .then(function(res){ console.log("res", JSON.stringify(res) },
    function(err){ console.log("err", err) } );
});

Joining

  db.admin.version()
    .join(db.admin.time())
    .spread(function(v,t){ 
    console.log(v.server,v.version,t.time);
  });

Calling API methods directly

You may also request a

Arango

Install / Use

README