Simple, expressive and yieldable MongoDB for co/koa.
The official MongoDB driver now returns promises and supports yielding too. Therefore, this project is no longer being actively maintained. If you would like to keep using the query builder interface, you can do so by installing mquery as well.
var co = require('co');
var connect = require('yieldb').connect;
co(function*(){
var db = yield connect(url);
var User = db.col('users');
yield User.insert(doc) // promise/thunk
yield User.findOne(id) // mquery
yield User.remove(id) // mquery
yield User.update(id, { $set: .. }) // mquery
yield User.findAndModify(id, modifier) // mquery
yield User.remove(id) // mquery
})()
yieldb
makes working with mongodb and
co/koa a breeze.
Connecting to mongodb is easy.
var co = require('co');
var connect = require('yieldb').connect;
co(function*(){
var db = yield connect(mongodbUri [, options]);
})()
Replica-sets, sharding and all the features available through the mongodb driver are supported out of the box.
yieldb
Collections provide a simple, constistent interface to work with mongodb collections.
Call db.col(collectionName)
to get a collection.
var co = require('co');
var connect = require('yieldb').connect;
co(function*(){
var db = yield connect(mongodbUri [, options]);
// get a collection
var User = db.col('users');
// look up a user
var doc = yield User.findOne(id);
})()
Key features:
Each collection method returns a yieldable. For example:
var User = db.col('users');
yield User.insert({ name: 'yieldb' });
var doc = yield User.find({ name: 'yieldb' });
Note that these yieldables are also Promise
s for maximal compatibility
with other modules:
var User = db.col('users');
User.insert({ name: 'yieldb' }).then(function(function() {
User.find({ name: 'yieldb' }).then(function(doc) {
console.log(doc);
}, onFail);
}, onFail);
Any collection method which accepts selector arguments will benefit from
auto-casting _id
hexStrings to ObjectId
. For example:
var User = db.col('users');
var ObjectId = require('mongodb').ObjectID;
// the following are equivalent
var doc = yield User.findOne('541b432d84dd6253074aabe6');
var doc = yield User.findOne({ _id: '541b432d84dd6253074aabe6' });
var doc = yield User.findOne({ _id: new ObjectId('541b432d84dd6253074aabe6') });
Where it makes sense, collection methods return an instance of mquery. This means you can use all the query builder helper methods in mquery.
var User = db.col('users');
var docs = yield User.find({ role: 'developer' })
.limit(10)
.sort({ name: 'desc' })
.read('primaryPreferred');
The methods which do not return an mquery
are
insert()
drop()
index()
indexes()
.aggregate()
However, these methods do return Promise
s like every other collection method.
In the future, aggregate
will likely return an mquery
once support has been
added.
As mentioned above, all collection methods return Promises
. Since most
collection methods also return an mquery
instance, we get Promise
support
for free everywhere. Call the query builders then()
method anywhere in
the chain to receive a
bluebird Promise
.
db.col('stats').where({ count: { $gt: 100 }})
.then(JSON.stringify)
.then(respond)
.catch(handleError)
Returns a collection
instance
var users = db.col('users');
Returns a promise which closes the db
connection.
yield db.close();
Returns a promise which deletes the entire database.
yield db.drop();
Returns a promise which lists existing collections in the database.
yield db.listCollections();
Returns a promise which sends a ping to the database.
yield db.ping();
Returns a promise which responds with MongoDB status.
yield db.serverStatus();
Returns a yieldable mquery instance.
yield db.col('watches').find(selector, options);
Returns a yieldable mquery instance.
yield db.col('watches').findOne(selector, options);
Accepts either a single object or array of objects.
Objects which do not have an _id
will receive one assigned a new ObjectId
.
Returns a yieldable promise;
yield db.col('watches').insert(obj, options);
yield db.col('watches').insert([obj1, obj2, ..], options);
Returns a yieldable mquery instance.
yield db.col('watches').update(selector, update, options);
{ multi: true, fullResult: true }
Returns a yieldable mquery instance.
yield db.col('watches').remove(selector, options);
Returns a yieldable promise.
yield db.col('watches').drop();
Accepts an array of pipeline operations and returns a yieldable promise.
yield db.col('watches').aggregate(pipeline);
The promise also has it's own stream()
method if that's what you're after.
yield db.col('watches').aggregate(pipeline).stream();
Returns a yieldable mquery instance.
yield db.col('watches').findOneAndUpdate(selector, update, options)
Returns a yieldable mquery instance.
yield db.col('watches').findOneAndRemove(selector, options)
Returns a yieldable mquery instance.
yield db.col('watches').count(selector, options)
Returns a yieldable mquery instance.
yield db.col('watches').distinct(key [, query]);
Returns a yieldable mquery instance.
yield db.col('watches').where(selector).select('name email')
Creates an index. Returns a yieldable promise.
yield db.col('watches').index(indexDefinition, options);
Drops an index. Returns a yieldable promise.
yield db.col('watches').dropIndex(indexDefinition);
Retreives an array of all defined indexes for this collection. Returns a yieldable promise.
var indexes = yield db.col('watches').indexes();
Sets default collection options which apply to all methods of this collection.
var User = db.col('users');
User.setOptions({ maxTime: 500 });
yield User.find();
Options are passed to the mquery.setOptions method. All mquery options are supported.
npm install yieldb --save
make test
runs testsmake test-cov
runs tests + test coveragemake open-cov
opens test coverage results in your browseryieldb
supports the debug
module for help during development.
Enable verbose logging by setting your DEBUG
env variable like so:
DEBUG=yieldb* npm test
```
## Sponsored by
[Pebble Technology!](https://getpebble.com)
## License
[MIT](https://github.com/pebble/yieldb/blob/master/LICENSE)