mongojs
A node.js module for mongodb, that emulates the official mongodb API as much as possible.
It wraps mongodb-native and is available through npm
npm install mongojs
Usage
mongojs is easy to use:
const mongojs = require('mongojs')
const db = mongojs(connectionString, [collections])
The connection string should follow the format described in the mongo connection string docs.
Some examples of this could be:
const db = mongojs('mydb', ['mycollection'])
const db = mongojs('example.com/mydb', ['mycollection'])
const db = mongojs('username:password@example.com/mydb', ['mycollection'])
const db = mongojs('username:password@example.com/mydb?authMechanism=SCRAM-SHA-1', ['mycollection'])
const db = mongojs('username:password@example.com/mydb?authSource=authdb', ['mycollection'])
const db = mongojs('username:password@example.com/mydb', ['mycollection'], { ssl: true })
const db = mongojs('mydb')
const mycollection = db.collection('mycollection')
More connection string examples
After we connected we can query or update the database just how we would using the mongo API with the exception that we use a callback.
The format for callbacks is always callback(error, value)
where error is null if no exception has occured. The update methods save
, remove
, update
and findAndModify
also pass the lastErrorObject
as the last argument to the callback function.
db.mycollection.find(function (err, docs) {
})
db.mycollection.find().sort({name: 1}, function (err, docs) {
})
db.mycollection.find({level: {$gt: 90}}).forEach(function (err, doc) {
if (!doc) {
return
}
})
db.mycollection.findOne({
_id: mongojs.ObjectId('523209c4561c640000000001')
}, function(err, doc) {
})
db.mycollection.update({name: 'mathias'}, {$inc: {level: 1}}, {multi: true}, function () {
})
db.mycollection.findAndModify({
query: { name: 'mathias' },
update: { $set: { tag: 'maintainer' } },
new: true
}, function (err, doc, lastErrorObject) {
})
db.mycollection.save({created: 'just now'})
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) { ... })
For more detailed information about the different usages of update and querying see the mongo docs
Events
const db = mongojs('mydb', ['mycollection'])
db.on('error', function (err) {
console.log('database error', err)
})
db.on('connect', function () {
console.log('database connected')
})
Streaming cursors
As of 0.7.0
all cursors are a readable stream of objects.
const JSONStream = require('JSONStream')
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
const cursor = db.mycollection.find({}, {}, {tailable: true, timeout: false})
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 mongojs you can run database commands just like with the mongo shell using db.runCommand()
db.runCommand({ping: 1}, function (err, res) {
if(!err && res.ok) console.log('we\'re up')
})
or db.collection.runCommand()
db.things.runCommand('count', function (err, res) {
console.log(res)
})
Bulk updates
As of 0.15 mongojs supports the Bulk updates introduced in mongodb 2.6. Here's an example of the usage
const bulk = db.a.initializeOrderedBulkOp()
bulk.find({type: 'water'}).update({$set: {level: 1}})
bulk.find({type: 'water'}).update({$inc: {level: 2}})
bulk.insert({name: 'Spearow', type: 'flying'})
bulk.insert({name: 'Pidgeotto', type: 'flying'})
bulk.insert({name: 'Charmeleon', type: 'fire'})
bulk.find({type: 'flying'}).removeOne()
bulk.find({type: 'fire'}).remove()
bulk.find({type: 'water'}).updateOne({$set: {hp: 100}})
bulk.execute(function (err, res) {
console.log('Done!')
})
Replication Sets
Mongojs can also connect to a mongo replication set by providing a connection string with multiple hosts
const db = mongojs('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
Using harmony features
If you run node.js with the --harmony
option, then you can ommit the collection names array, and you can do stuff like.
const mongojs = require('mongojs')
const db = require('mydb')
db.hackers.insert({name: 'Ed'})
In the above example the hackers
collection is enabled automagically (similar to the shell) using the Proxy
feature in harmony
Passing a DB to the constructor
If you have an instance of mongojs, you can pass this to the constructor and mongojs will use the
existing connection of that instance instead of creating a new one.
const mongodb = require('mongodb')
const mongojs = require('mongojs')
mongodb.Db.connect('mongodb://localhost/test', function (err, theDb) {
const db = mongojs(theDb, ['myCollection'])
})
Features not supported for MongoDB 2.4 or older (on mongojs version 1.0+).
- Index creation and deletion
- Aggregation cursors.
This features are relatively easy to add, but would make the code unnecessarily more complex.
If you are using mongodb 2.4 or older and would like to use mongojs 1.0 with the above mentioned
feautres, feel free to make a pull request or open and issue..
Upgrading from 0.x.x to 1.2.x
Version > 1.0.x is a major rewrite of mongojs. So expect some things not to work the same as in mongojs 0.x.x versions. Breaking changes include:
- Removed
mongojs.connect
use mongojs()
directly instead
API
This API documentation is a work in progress.
Collection
db.collection.aggregate([pipeline], [options], [callback])
https://docs.mongodb.org/manual/reference/method/db.collection.aggregate/
db.collection.aggregate([pipelineStep], [pipelineStep], [pipelineStep], ..., [callback])
db.collection.count([query], callback)
db.collection.createIndex(keys, options, [callback])
db.collection.distinct(field, query, callback)
db.collection.drop([callback])
db.collection.dropIndex(index, [callback])
db.collection.dropIndexes([callback])
db.collection.ensureIndex(keys, options, [callback])
db.collection.find([criteria], [projection], [callback])
This function applies a query to a collection. You can get the return value, which is a cursor, or pass a callback
as the last parameter. Said callback receives (err, documents)
db.collection.findOne([criteria], [projection], callback)
Apply a query and get one single document passed as a callback. The callback receives (err, document)
db.collection.findAndModify(document, callback)
db.collection.getIndexes(callback)
db.collection.group(document, callback)
db.collection.insert(docOrDocs, [callback])
db.collection.isCapped(callback)
db.collection.mapReduce(map, reduce, options, [callback])
db.collection.reIndex([callback])
db.collection.remove(query, [justOne], [callback])
db.collection.remove(query, [options], [callback])
db.collection.runCommand(command, [callback])
db.collection.save(doc, [options], [callback])
db.collection.stats(callback)
db.collection.update(query, update, [options], [callback])
db.collection.toString()
Get the name of the collection.
Cursor
cursor.batchSize(size, [callback])
cursor.count(callback)
cursor.explain(callback)
cursor.forEach(function)
cursor.limit(n, [callback])
cursor.map(function, [callback])
cursor.next(callback)
cursor.skip(n, [callback])
cursor.sort(sortOptions, [callback])
cursor.toArray(callback)
cursor.rewind()
cursor.destroy()
Database
db.addUser(document)
db.createCollection(name, options, [callback])
db.dropDatabase([callback])
db.eval(code, [params], [options], [callback])
db.getCollectionNames(callback)
db.getLastError(callback)
db.getLastErrorObj(callback)
db.removeUser(username, [callback])
db.runCommand(command, [callback])
db.stats([callback])
db.close()
Bulk
bulk.execute()
bulk.find(query)
bulk.find.remove()
bulk.find.removeOne()
bulk.find.replaceOne(document)
bulk.find.update(updaterParam)
bulk.find.updateOne(updaterParam)
bulk.find.upsert(upsertParam)
bulk.insert(document)
bulk.toString()
bulk.tojson()