pmongo v1.0.0

pmongo

Promised wrapper for mongodb native driver

Install

Pmongo is available through npm:

npm install pmongo

Pmongo is based on native Promises.
That's why you must have nodejs 0.11 version or greater or iojs
Also pmongo depends on node-mongodb-native but it is not included in package.json you must specify it as a dependency in your root project

Usage

Use pmongo just like mongojs, except you can also use the returned promise instead of the callback. Note that a promise isn't returned if a callback is specified.

var pmongo = require('pmongo');
var db = pmongo(connectionString, [collections]);

The connection string should follow the format desribed in the mongo connection string docs. Some examples of this could be:

// simple usage for a local db
var db = pmongo('mydb', ['mycollection']);

// the db is on a remote server (the port default to mongo)
var db = pmongo('example.com/mydb', ['mycollection']);

// we can also provide some credentials
var db = pmongo('username:password@example.com/mydb', ['mycollection']);

// connect now, and worry about collections later
var db = pmongo('mydb');
var mycollection = db.collection('mycollection');

After we connected we can query or update the database just how we would using the mongo API with the exception that the functions return a promise for the result rather than the result itself. Cursor operations such as find() and sort() return a cursor; to get a promise for the result, you have to force evaluation using toArray(). Alternatively, you can just call then() on the cursor and it will call toArray() for you, returning a promise. The function findOne() returns a promise immediately, not a cursor.

// find everything
db.mycollection.find().toArray().then(function(docs){
	// docs is an array of all the documents in mycollection
});

// find everything, but sort by name
db.mycollection.find().sort({name:1}).toArray().then(function(docs) {
	// docs is now a sorted array
});

// find a document using a native ObjectId
db.mycollection.findOne({
	_id: pmongo.ObjectId('523209c4561c640000000001')
}).then(function(doc) {
	// doc._id.toString() === '523209c4561c640000000001'
});

// find all named 'mathias' and increment their level
db.mycollection.update({name:'mathias'}, {$inc:{level:1}}, {multi:true})
	.then(function(lastErrorObject) {
		// the update is complete
	});

// find one named 'mathias', tag him as a contributor and return the modified doc
db.mycollection.findAndModify({
	query: { name: 'mathias' },
	update: { $set: { tag:'maintainer' } },
	new: true
})
.then(function(doc) {
	// doc.tag === 'maintainer'
});

// use the save function to just save a document
db.mycollection.save({created:'just now'});

The forEach function is a special case. The library supports the mongojs style:

// iterate over all whose level is greater than 90.
db.mycollection.find({level:{$gt:90}}).forEach(function(err, doc) {
	if (doc) {
      //do things with doc
    } else {
      //the callback gets called at the end with a null doc
      console.log('Finished!');
    }
});

It also supports a promise version. If you pass a callback to the forEach function with only one argument, you get the promise version. The promise will resolve (with undefined) when the callback has been called for all documents.

// iterate over all whose level is greater than 90 (promise version)
db.mycollection.find({level:{$gt:90}}).forEach(function(doc) {
	//do things with doc
})
.then(function () {
  console.log('Finished!');
});

If you provide a callback to find or any cursor config operation mongojs will call toArray for you

db.mycollection.find({}, function(err, docs) { ... });

db.mycollection.find({}).limit(2).skip(1, function(err, docs) { ... });

is the same as

db.mycollection.find({}).toArray(function(err, docs) { ... });

db.mycollection.find({}).limit(2).skip(1).toArray(function(err, docs) { ... });

If you are using the promises API, you must call toArray() on cursors before a promise can be obtained. E.g.:

db.mycollection.find().limit(2).skip(1).toArray()
	.then(function (docs) {
		// ...
	});

For more detailed information about the different usages of update and querying see the mongo docs

Streaming cursors

All cursors are a readable stream of objects.

var JSONStream = require('JSONStream');

// pipe all documents in mycollection to stdout
db.mycollection.find({}).pipe(JSONStream.stringify()).pipe(process.stdout);

Notice that you should pipe the cursor through a stringifier (like JSONStream) if you want to pipe it to a serial stream like a http response.

Tailable cursors

If you are using a capped collection you can create a tailable cursor to that collection by adding tailable:true to the find options

var cursor = db.mycollection.find({}, {}, {tailable:true, timeout:false});

// since all cursors are streams we can just listen for data
cursor.on('data', function(doc) {
	console.log('new document', doc);
});

Note that you need to explicitly set the selection parameter in the find call.

Database commands

With pmongo you can run database commands just like with the mongo shell using db.runCommand()

db.runCommand({ping:1}).then(function(res) {
	if(!err && res.ok) console.log("we're up");
});

or db.collection.runCommand()

db.things.runCommand('count').then(function(res) {
	console.log(res);
});

Replication Sets

Pmongo can also connect to a mongo replication set by providing a connection string with multiple hosts

var db = pmongo('rs-1.com,rs-2.com,rs-3.com/mydb?slaveOk=true', ['mycollection']);

For more detailed information about replica sets see the mongo replication docs