congo

Congo is a thin wrapper for node-mongodb-native that makes connections and collections a little easier.

congo

congo is a wrapper for node-mongodb-native that makes connections and collections a little easier. Thanks to Thom Seddon's work on co-mongo, congo can also be used with ES6 generators.

npm install congo
npm install https://github.com/martinrue/congo/tarball/master

The first thing you must do is call configure to tell congo where the database is and various other options about how the database connection should be made.

var database = require('congo');
 
database.configure({
  host: 'localhost',
  name: 'test',
  port: 27017,
  pool: 5,
  generators: false,
  reconnect: false,
  collections: []
});
KeyDefaultMeaning
hostlocalhosthostname of database
nametestname of database
port27017database port
pool5number of pooled connections
generatorsfalseallows congo to be used with generators if true (see below)
reconnectfalsewhether to use mongodb-native's reconnect/replay behaviour
collections[]list of known collections to map onto the db object

After the call to configure, call get to retrieve a database object.

database.get(function(errdb) {
  // db is a connected database object 
});

All non-system collections are attached directly onto the database object, so querying a collection is as simple as:

database.get(function(errdb) {
  db.users.findOne({}, function(erruser) {
 
  });
});

For convenience, congo also attaches a new findAll function to each collection. This allows you skip dealing with the cursor if you simply want to retrieve all results from a multi-result query:

database.get(function(errdb) {
  db.users.findAll({}, function(errusers) {
    // users is an array of all users from the database 
  });
});

Because congo queries all existing collections and attaches them to the database object, new collections you intend to create won't have a corresponding db.[collection]. In this situation, you can supply an array of collection names in the config that are always mapped onto the database object:

var database = require('congo');
 
database.configure({
  host: 'localhost',
  name: 'mydb',
  collections: ['users', 'products', 'orders']
});
 
database.get(function(errdb) {
  // db.users, db.products and db.orders will all be available, 
  // regardless of whether they existed before or not 
});

One pooled database connection is created internally and congo reuses it. This means you can call database.get anywhere and not worry about creating unnecessary additional connections.

If { reconnect: true } is set on the configuration object, the mongo driver will reconnect automatically. This also queues commands and replays them once connections are re-established.

If { reconnect: false } is set (the default), congo itself reconnects closed connections on each database.get call and does not queue any failed commands.

If { generators: true } is set, all applicable driver functions are thunked via co-mongo to enable you to yield calls instead of using callbacks.

var database = require('congo');
var co = require('co');
 
database.configure({
  name: 'database',
  generators: true
});
 
co(function*() {
  var db = yield database.get();
 
  var user = yield db.users.findOne({ name: 'bob' });
  var users = yield db.users.findAll();
  var total = yield db.users.count();
 
  yield db.close();
})();

Database events such as 'close' and 'error' are propogated. If you're interested in them, pass a handler to database.on:

database.on('close', function() {
  // database connection was closed 
});
 
database.on('error', function() {
  // error occurred on the database 
});

The ObjectID et al. functions that you would normally be able to access from require('mongo').[func] have been extended onto congo and can be used in exactly the same way:

var database = require('congo');
 
database.get(function(errdb) {
  db.users.findOne({ _id: database.ObjectID('...') }, function(erruser) {
 
  });
});

There are two sets of end-to-end tests to cover the primary driver functions in both callback and generator configurations. The test setup and teardown functions require the mongo executable to be on the path.

To run the regular callback tests, npm test is all you need.

To run the generator tests, run npm run test-generators.