dCap

A NodeJS implementation of dCap.

Download

You can install cDap by cloning this repository or by using npm

npm install dcap

Tests

There is a fairly comprehensive test suite.

cd /path/to/cloned/repo
mocha

// TODO notes for REST api tests

http://thewayofcode.wordpress.com/2013/04/21/how-to-build-and-test-rest-api-with-nodejs-express-mocha/

https://brianstoner.com/blog/testing-in-nodejs-with-mocha/

https://www.npmjs.org/package/supertest

To see code coverage run

cd /path/to/cloned/repo
./coverage/generate.sh

Open ./coverage/coverage.html in your browser to view the coverage report.

Note: make sure you install jscoverage first.

Usage

var dcap = require('dcap');

var store = dcap.createMemStore(opts);
//var store = dcap.createElasticSearchStore(opts);

var client = dcap.createClient(store, options);

var server = dcap.createServer(store, options);

server.listen(port, callback);

Store

Implementations of a dCap store.

There are a few Store implementations, the only difference in syntax being the options they take in instantiation.

MemStore - An in-memory implementation

var store = dcap.createMemStore({});

ElasticSearchStore - A store backed with ElasticSearch (coming soon) // TODO move out to dcap-elasticsearch?

var opts = {};
var store = dcap.createElasticSearchStore(opts);

store.get(repo, id, callback)

store.get('repo-id', 'commit-id', function(error, commit) {
  // error will either be Error or null
  // commit will be a JSON object
})

store.put(repo, id, commit, callback)

store.put('repo-id', 'commit-id', commitObj, function(error) {
  // error will either be Error or null
})

store.query(criteria, callback)

//TODO Change type of return to object with more info about matches?

For a full list of criteria see here.

var criteria = {
  repo: '1234',
  from: 1398441136000
}

store.query(criteria, function(error, commits) {
  // error will either be Error or null
  // commits will be an array of matching commits
})

Client

Implementation of a dCap client.

var options = {
  send: {
    "repo1": [
      "_local"
    ],
    "repo2": [
      "_local",
      "http://host.com:1234"
    ],
    "*": [
      "http://host.com:1234"
    ]
  },
  receive: {
    "repo1": "_local",
    "repo2": "http://host.com:1234"
    "*": "http://host.com:1234" // * is required
  }
}

var client = dcap.createClient(store, options);

Conventions

dcap client follows the standard Node callback conventions.

client.someFunction(param1, param2, callback);

function callback(error, optionalReturnValue) {
  // error will either be a standard Error or null

  // optionalReturnValue is the return value of the function.
  // Note: some functions have no return value, like graph.save(repo, commit, callback)
}

client.save(repo, commit, callback)

client.save('repo-id', commitObj, function(error) {
  // error will either be Error or null
})

client.get(repo, commit)

client.get('repo-id', 'commit-id', function(error, commit) {
  // error will either be Error or null
  // commit will be a JSON object
})

client.query(criteria, commit)

For a full list of criteria see here.

var criteria = {
  repo: '1234',
  from: 1398441136000
}

client.query(criteria, function(error, commits) {
  // error will either be Error or null
  // commits will be an array of matching commits
})

Server

Implementation of a dCap server.

var server = dcap.createServer(store, {});
server.listen(8081, callback);