mongodb-next
A MongoDB API wrapper with:
- A fluent, chaining API without traditional MongoDB drivers and wrappers' function varity and long names
- Streams2 support with proper
.destroy()
calls - Promise support
- Supports
node-mongodb-native
v1
as well asv2
. - MongoDB 2.6+ support
- Aggregation framework support
- Bulk write support
Note: tests currently fail on Travis because Travis uses MongoDB 2.4
All methods return promises, so your code now looks like this:
var wrap = collectionvar collection = var batch = collection // ordered batched writesbatchbatchbatch
Or the new way:
var DB = ;var db = ; dbconnect
Or if you use something like co:
Context
Christian, the maintainer of node-mongodb-native, is interested in a version of the MongoDB driver that supports native promises as well as other ES6+ features. However, this won't remotely be a possibility until after v3.0 of the driver is out.
I expressed my interest in creating a well defined API, and this is what I consider ideal. As Christian is refactoring the driver, this may, in the future, be an alternative API. The goal is for this API to last past ES7, where code will look like:
{ var docs = await collection} run
Compatibility
This library uses promises extensively. Currently, it uses bluebird, but it will eventually switch to native promises.
This library also only supports MongoDB 2.6+, but most commands will still work with MongoDB 2.4 and any MongoDB driver that shims various 2.6 commands for 2.4.
This library supports node-mongodb-native@1
as well as @2
.
API
var DB = ;
var db = DB(uri, [options])
Create a new db instance from a URI w/ options.
A wrapper around MongoClient.connect()
db.connect.then( => )
Wait until the database is connected. Use this before doing any subsequent commands.
db.raw
The raw database connection provided by MongoDB.
wrap(collection)
The primary constructor wraps a MongoDB Collection.
This is the same as doing db.collection(name)
.
var wrap = collectionvar collection = // orvar db = ;dbconnect
Entry Points
Only a few methods are available on collection
itself:
.find()
- for searching or updating multiple documents.findOne()
- for searching or updating a single document.insert()
- for inserting documents.remove()
- remove documents, shortcut for.find().remove()
.aggregate()
- for aggregations.mapReduce()
- for mapReduce.batch()
- to create sequential bulk writes.parallel()
- to create parallel bulk writes
The API is somewhat subject to change so they won't be documented thoroughly. If what you "expect" to work does not work, please let us know so we can figure out how to improve the API. If you're in doubt, look at the code.
Options
Most options are available as chainable methods.
collection)
Update operators are also methods with the $
prefix as well as without
if there are no conflicts:
collection // there's no .push() because that's a streams2 API method namecollection
Promises
All methods have .then()
and .catch()
,
allowing them to be yield
or await
ed.
collection
Streams
The .find()
method, when not used with any .update()
or .remove()
commands,
returns a stream.
collection
Callbacks
Callbacks are only supported using the .exec()
or .end()
commands.
collection
Transforms
You may chain transforms, equivalent to [].map()
:
collection
Options
You may set options yourself using the .setOption()
or .setOptions()
methods:
collectioncollection
Examples
Insert with write concern:
collection
Find both of the above documents and pipe:
var stringify = stringify collection// create $or: [], though a `name: {$in: []}` would probably be better here
Equivalent of .findAndModify()
and returning the new object:
collection
Do a multi
update, which is by default unless .new()
or .remove()
are chained or .updateOne()
is used`:
collection
Do an aggregation:
collection
Do a mapReduce:
collection
By default, the out
is { inline: 1 }
, the methods below are available.
.out()
.sort()
.query()
.limit()
.scope()
collection
Paginate:
{ options = options || {} collection }