magnolia–A beautiful MongoDB driver w/ Q

Magnolia implements a coherent, lazy, & chainable interface... with promises! Don't nest callbacks anymore than you have to!

Init

If you don't mind state, you can init the module's state with default options.

var mongo = require('magnolia'),
    ObjectID = mongo.ObjectID;

mongo
    .server('localhost', 27117)
    .db('hello')
    .options({w: 1})
    .init(); // makes all the previous calls stored as defaults

Or you can start a chain with the defaults you would like.

var mongo = require('magnolia')
    .server({host: 'localhost', port: 27117)
    .db('hello')
    .options({w: 1});

Connection

magnolia(collection, [db])
.collection(collection)
.db(db)
.server(server)
.options(...)
- m:1
- journal:true
- fsync:true
- slaveOk:true

Find

magnolia('user')
    .filter({_id: ObjectID('4e4e1638c85e808431000003')}) // filter!
    .one() // just find one!
    .then(function (user) { // evaluate as a promise
        console.log('hello', user.name);
    });

magnolia('user')
    .filter({hello: 'world'})
    .toArray(function (err, docs) { /* ... */ });

.toArray([cb]) Query the collection, otherwise it will be lazily queried when you evaluate the chain as a promise
.filter(criteria) Filter the collection
.one() Find one! And return the document, instead of a list.
.limit(n).skip(m) to control paging.
.sort(fields) Order by the given fields. There are several equivalent syntaxes:
- .sort({'field1': -1, 'field2': 1})
- .sort({'field1': 1})
TODO Allow array sorting syntax as well

Find and modifiy

magnolia('user')
    .filter(query)
    .sort(sort)
    .options(options)
    .findAndModify(objNew, [options], [callback]);

Useful options (including the previous options):

.filter(...)
.sort(...)
.options(...)
- remove:true set to a true to remove the object before returning
- new:true set to true if you want to return the modified object rather than the original. Ignored for remove.
- upsert:true Atomically inserts the document if no documents matched.

Remove

magnolia('user')
    .filter(query)
    .remove(extra_query)
    .then(function (remove_count) { /* ... */ });

Insert

magnolia('user')
    .insert({name: 'ryan', company: 'Submersible'}, {safe: true})
    .then(function (doc) { /* ... */ });

magnolia('user')
    .safe()
    .insert([{foo: 'bar'}, {hello: 'world'}], function (err, docs) {
        /* ... */
    });

.safe() or .unsafe() Make sure document is in the database before returning
.options(...)
- safe:true

Update; update and insert (upsert)

Signature:

magnolia('user')
    .filter(criteria)
    .update(update, [options], [callback]);

magnolia('user')
    .filter(criteria)
    .upsert(objNew, [options], [callback]);

Useful options:

.filter(...)
.one() or .multi()
.safe() or .unsafe()
.options(...)
- safe:true Should always set if you have a callback.
- multi:true If set, all matching documents are updated, not just the first.
- upsert:true Atomically inserts the document if no documents matched.

Save

Performs an update if there's an _id, and an insert if not!

magnolia('user').save({_id: ObjectID('50c03c9c766c8598e0000002'), foo: 'bar'}); // update
magnolia('user').save({hello: 'world'}); // insert

Count

magnolia('user').count([filter], [cb]);

Map/reduce

Data types

magnolia.Long(numberString)
magnolia.ObjectID(hexString)
magnolia.Timestamp()
magnolia.DBRef(collectionName, id, dbName)
magnolia.Binary(buffer)
magnolia.Code(code, [context])
magnolia.Symbol(string)
magnolia.MinKey()
magnolia.MaxKey()
magnolia.Double(number)

Submersible/node-magnolia