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

$3

``
npm install congo
`

$3

`
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.

`javascript
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

$3

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

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

$3

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

`javascript
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:

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

$3

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:

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

$3

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.

$3

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

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

$3

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

`javascript
database.on('close', function() {
// database connection was closed
});

database.on('error', function() {
// error occurred on the database
});
`

$3

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:

`javascript
var database = require('congo');

database.get(function(err, db) {
db.users.findOne({ _id: database.ObjectID('...') }, function(err, user) {

});
});
`

$3

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`.