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.

Installation

npm

npm install congo

GitHub

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

Configuration

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: []
});

| Key | Default | Meaning | |-------------|-----------|--------------------------------------------------------------| | host | localhost | hostname of database | | name | test | name of database | | port | 27017 | database port | | pool | 5 | number of pooled connections | | generators | false | allows congo to be used with generators if true (see below) | | reconnect | false | whether to use mongodb-native's reconnect/replay behaviour | | collections | [] | list of known collections to map onto the db object |

Querying

Get Database

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

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

Collections

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

database.get(function(err, db) {
  db.users.findOne({}, function(err, user) {

  });
});

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(err, db) {
  db.users.findAll({}, function(err, users) {
    // users is an array of all users from the database
  });
});

New Collections

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(err, db) {
  // db.users, db.products and db.orders will all be available,
  // regardless of whether they existed before or not
});

Connections

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.

Generators

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

Example

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

Events

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

ObjectID, DBRef, BSON, etc. Functions

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(err, db) {
  db.users.findOne({ _id: database.ObjectID('...') }, function(err, user) {

  });
});

Tests

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.