mongoist

A node.js module for mongodb built with async/await in mind, that emulates the official mongodb API as much as possible.

Mongoist driver is heavily inspired by mongojs.


Motivation

The official MongoDB driver for Node.js (https://github.com/mongodb/node-mongodb-native) leaves connection management to the user - this means to connect
to a mongodb database this boilerplate code is needed

``javascript
const { MongoClient } = require("mongodb");

MongoClient.connect("mongodb://localhost:27017/myproject").then(
(connection) => {
connection.close();
}
);
`

Due to the asynchronous nature of connect, a connection that is used everywhere in an application is not that easy to export from a module.

`javascript
const { MongoClient } = require("mongodb");

MongoClient.connect("mongodb://localhost:27017/myproject").then(
(connection) => {
// THIS WILL NOT WORK AS EXPECTED!!!
module.exports = connection;
}
);
`

Mongoist solves this problem by managing the connection internally in a lazy fashion. With mongoist you can create a db.js module exporting a
not yet opened database connection:

`javascript
module.exports = mongoist(connectionString);
`

Along these same lines, connection information may not be available synchronously. The connection
information provided to mongoist can be contained in a Promise, affording for gathering the
connection information from arbitrary sources (e.g. mongo-memory-server):

`javascript
module.exports = mongoist(Promise.resolve());
`

Usage

_Please note: Any line in the examples that uses the await keyword should be called inside an async function. If you haven't used async/await yet, you'll want to do some research to help you understand how it works. Or take a look at https://ponyfoo.com/articles/understanding-javascript-async-await for a great read about async/await_

$3

`javascript
const mongoist = require("mongoist");
const db = mongoist(connectionString, connectionOptions);
`

The connectionString and connectionOptions are passed to the underlying official mongodb driver.
Find out more about connection strings and options.

#### Migrating from mongojs

While mongojs uses callbacks only, mongoist uses promises only. To allow migrating to mongoist without migrating the whole application,
mongoist supports wrapping the mongojs driver.

`javascript
const mongojsDb = mongojs(connectionString);
const db = mongoist(mongojsDb);

async function findDocuments() {
const docs = await db.a.find({});
// ...
}

// We need to call the async function this way since top level await keyword is not allowed in JavaScript
findDocuments().then(() => console.log("Done querying mongodb"));
`

#### Connection Management

Mongoist uses the connection pool provided by the official mongodb driver, so there is no need to manage connections on your own.
For most use cases it's best to create a db.js node module that exports a mongoist database connection.

`javascript
module.exports = mongoist(connectionString);
`

$3

Mongoist uses a proxy implementation under the hood to allow accessing a collection named foo as

`javascript
db.foo.find(...);
`

instead of

`javascript
db.collection('foo').find(...);
`

$3

`javascript
// find everything in mycollection returned as array
const documents = await db.mycollection.find();

// find everything in mycollection returned as a Cursor (no intermediate Promise)
const documentsCursor = db.mycollection.findAsCursor();

// take the first document from the cursor
const document = await documentsCursor.next();

// find everything in mycollection, but sort by name
const sortedDocuments = await db.mycollection
.findAsCursor()
.sort({ name: 1 })
.toArray();

// find a document using a native ObjectId
const documentById = await db.mycollection.findOne({
_id: mongoist.ObjectId("523209c4561c640000000001"),
});

// Update all documents named 'mathias' and increment their level
const resultUpdate = await db.mycollection.update(
{ name: "mathias" },
{ $inc: { level: 1 } },
{ multi: true }
);

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

// use the save function to just save a document
const doc = await db.mycollection.save({ created: "just now" });
`

$3

The mongodb operations find and aggregate return a cursor, that is resolved in the mongodb shell to an array. Mongoist
provides the operations findAsCursor and aggregateAsCursor to return a cursor, and shorthand functions find and
aggregate to return an array.

Bulk updates

`javascript
var 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 } });

await bulk.execute();
// done...
`

$3

`js
const db = mongoist("mongodb://localhost/mydb");

// Emitted if no db connection could be established
db.on("error", function (err) {
console.log("database error", err);
});

// Emitted if a db connection was established
db.on("connect", function () {
console.log("database connected");
});
`

$3

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

`js
const result = await db.runCommand({ ping: 1 });
console.log("we're up");
`

or db.collection.runCommand()

`js
const result = await db.things.runCommand("count");
console.log(result);
`

Similarly, you can use db.adminCommand() to run a command on the admin database of the
MongoDB cluster or instance you're connected to:

`js
const result = await db.adminCommand({ currentOp: 1 });
console.log(result);
`

$3

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

`js
const db = mongoist("rs-1.com,rs-2.com,rs-3.com/mydb?slaveOk=true");
`

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

API

This API documentation is a work in progress.

$3

Mongoist exposes the prototypes of Database, Collection, Cursor and Bulk
to provide basic support for mocking, stubbing data access in tests.

`js
const mongoist = require("mongoist");

// Override collection find behavior to always return { foo: 'bar' }
mongoist.Collection.prototype.find = function () {
return [{ foo: "bar" }];
};

const db = mongoist("test");
console.log(db.a.find({}));

// Will print out [{ foo: 'bar' }]
`

$3

All operations return promises. If a return type is given, this is the type of the resolved promise.

#### db.collection.aggregate(pipelineArray, [options])

See https://docs.mongodb.org/manual/reference/method/db.collection.aggregate/

#### db.collection.aggregateAsCursor(pipelineArray, [options])

Returns a cursor instead of an array as db.collection.aggregate does.

See https://docs.mongodb.org/manual/reference/method/db.collection.aggregate/

#### db.collection.count([query], [options])

Supported options:

| Field | Type | Description |
| --------- | ------------------ | --------------------------------------------------------------- |
| limit | integer | Optional. The maximum number of documents to count. |
| skip | integer | Optional. The number of documents to skip before counting. |
| hint | string or document | Optional. An index name hint or specification for the query. |
| maxTimeMS | integer | Optional. The maximum amount of time to allow the query to run. |
| collation | document | Optional. |

See https://docs.mongodb.org/manual/reference/method/db.collection.count/

#### db.collection.createIndex(keys, options)

See https://docs.mongodb.org/manual/reference/method/db.collection.createIndex/

#### db.collection.distinct(field, query)

See https://docs.mongodb.org/manual/reference/method/db.collection.distinct/

#### db.collection.drop()

See https://docs.mongodb.org/manual/reference/method/db.collection.drop/

#### db.collection.dropIndex(index)

See https://docs.mongodb.org/manual/reference/method/db.collection.dropIndex/

#### db.collection.dropIndexes()

See https://docs.mongodb.org/manual/reference/method/db.collection.dropIndexes/

#### db.collection.ensureIndex(keys, options)

See https://docs.mongodb.org/manual/reference/method/db.collection.ensureIndex/

Deprecation Notice: Deprecated since version 3.0.0: db.collection.ensureIndex() is now an alias for db.collection.createIndex().

#### db.collection.find([query], [projection])

Returns an array of documents.

See https://docs.mongodb.org/manual/reference/method/db.collection.find/

#### db.collection.findAsCursor([query], [projection])

Returns a cursor instead of an array as db.collection.find does.

See https://docs.mongodb.org/manual/reference/method/db.collection.find/

#### db.collection.findOne([query], [projection])

Apply a query and returns one single document.

See https://docs.mongodb.org/manual/reference/method/db.collection.findOne/

#### db.collection.findAndModify(document)

See https://docs.mongodb.org/manual/reference/method/db.collection.findAndModify/

#### db.collection.getIndexes()

See https://docs.mongodb.org/manual/reference/method/db.collection.getIndexes/

#### db.collection.group(document)

See https://docs.mongodb.org/manual/reference/method/db.collection.group/

Deprecation Notice: Deprecated since version 3.4: Mongodb 3.4 deprecates the db.collection.group() method. Use db.collection.aggregate() with the $group stage instead.

#### db.collection.insert(docOrDocs, options)

See https://docs.mongodb.com/manual/reference/method/db.collection.insert/

#### db.collection.isCapped()

See https://docs.mongodb.com/manual/reference/method/db.collection.isCapped/

#### db.collection.reIndex()

See https://docs.mongodb.com/manual/reference/method/db.collection.reIndex/

#### db.collection.remove(query, [justOne])

Deprecation Notice: Deprecated since version 3.1: Mongodb 3.1 deprecates the db.collection.remove() method. Use db.collection.deleteMany(filter, options).

Equivalent to db.collection.remove(query, { justOne: true/false })

See https://docs.mongodb.com/manual/reference/method/db.collection.remove/

#### db.collection.deleteMany(filter, [options])

See https://docs.mongodb.com/manual/reference/method/db.collection.deleteMany/

#### db.collection.deleteOne(filter, [options])

See https://docs.mongodb.com/manual/reference/method/db.collection.deleteOne/

#### db.collection.remove(query, [options])

Deprecation Notice: Deprecated since version 3.1: Mongodb 3.1 deprecates the db.collection.remove() method. Use db.collection.deleteMany(filter, options).

See https://docs.mongodb.com/manual/reference/method/db.collection.remove/

#### db.collection.replaceOne(filter, replacement, [options])

See https://docs.mongodb.com/manual/reference/method/db.collection.replaceOne/

#### db.collection.runCommand(command)

See https://docs.mongodb.com/manual/reference/method/db.collection.runCommand/

#### db.collection.save(doc, [options])

See https://docs.mongodb.com/manual/reference/method/db.collection.save/

#### db.collection.stats()

See https://docs.mongodb.com/manual/reference/method/db.collection.stats/

#### db.collection.update(query, update, [options])

See https://docs.mongodb.com/manual/reference/method/db.collection.update/

#### db.collection.initializeOrderedBulkOp([options])

Creates a new ordered bulk. This operation is sync so no await is needed. See the Bulk section for more details.

#### db.collection.initializeUnorderedBulkOp([options])

Creates a new unordered bulk. This operation is sync so no await is needed. See the Bulk section for more details.

#### db.collection.toString()

Get the name of the collection.

$3

Cursor implements a readable stream. For example, you can pipe a cursor to a writeable stream.

`javascript
db.someCollection
.findAsCursor()
.pipe(writeableStream)
.on("finish", () => {
console.log("all documents piped to writeableStream");
});
`

#### cursor.addCursorFlag(flag, value)

See https://mongodb.github.io/node-mongodb-native/3.1/api/Cursor.html#addCursorFlag

#### cursor.batchSize(size)

See https://docs.mongodb.com/manual/reference/method/cursor.batchSize/

#### cursor.collation(collationDocument)

See https://docs.mongodb.com/manual/reference/method/cursor.collation/

Only supported with MongoDB 3.4 or higher.

#### cursor.count()

See https://docs.mongodb.com/manual/reference/method/cursor.count/

#### cursor.explain()

See https://docs.mongodb.com/manual/reference/method/cursor.explain/

#### cursor.limit(n)

See https://docs.mongodb.com/manual/reference/method/cursor.limit/

#### cursor.next()

See https://docs.mongodb.com/manual/reference/method/cursor.next/

#### cursor.hasNext()

See https://docs.mongodb.com/manual/reference/method/cursor.hasNext/

#### cursor.forEach(fn)

See https://docs.mongodb.com/manual/reference/method/cursor.foreach/

#### cursor.map(fn)

See https://docs.mongodb.com/manual/reference/method/cursor.map/

#### cursor.rewind()

Rewinds a cursor.

#### cursor.skip(n)

See https://docs.mongodb.com/manual/reference/method/cursor.skip/

#### cursor.sort(sortOptions)

See https://docs.mongodb.com/manual/reference/method/cursor.sort/

#### cursor.toArray()

See https://docs.mongodb.com/manual/reference/method/cursor.toArray/

#### cursor.close() (alias cursor.destroy())

https://docs.mongodb.com/manual/reference/method/cursor.close/

$3

#### db.createUser(document)

See https://docs.mongodb.com/manual/reference/method/db.createUser/

#### db.dropUser(username)

See https://docs.mongodb.com/manual/reference/method/db.dropUser/

#### db.dropAllUsers()

See https://docs.mongodb.com/manual/reference/method/db.dropAllUsers/

#### db.createCollection(name, options)

See https://docs.mongodb.com/manual/reference/method/db.createCollection/

#### db.getCollectionNames()

See https://docs.mongodb.com/manual/reference/method/db.getCollectionNames/

#### db.getCollectionInfos() (alias db.listCollections())

See https://docs.mongodb.com/manual/reference/method/db.getCollectionInfos/

#### db.getLastError()

See https://docs.mongodb.com/manual/reference/method/db.getLastError/

#### db.getLastErrorObj()

See https://docs.mongodb.com/manual/reference/method/db.getLastErrorObj/

#### db.runCommand(command)

See https://docs.mongodb.com/manual/reference/method/db.runCommand/

#### db.adminCommand(command)

See https://mongodb.github.io/node-mongodb-native/3.3/api/Db.html#executeDbAdminCommand

#### db.stats()

See https://docs.mongodb.com/manual/reference/method/db.stats/

#### db.close()

See https://docs.mongodb.com/manual/reference/method/db.close/

#### db.dropDatabase()

See https://docs.mongodb.com/manual/reference/method/db.dropDatabase/

$3

#### bulk.execute()

Executes a bulk.

See https://docs.mongodb.com/manual/reference/method/Bulk.execute/

#### bulk.find(query)

See https://docs.mongodb.com/manual/reference/method/Bulk.find/

#### bulk.find.remove()

See https://docs.mongodb.com/manual/reference/method/Bulk.find.remove/

#### bulk.find.removeOne()

See https://docs.mongodb.com/manual/reference/method/Bulk.find.removeOne/

#### bulk.find.replaceOne(document)

See https://docs.mongodb.com/manual/reference/method/Bulk.find.replaceOne/

#### bulk.find.update(updaterParam)

See https://docs.mongodb.com/manual/reference/method/Bulk.find.update/

#### bulk.find.updateOne(updaterParam)

See https://docs.mongodb.com/manual/reference/method/Bulk.find.updateOne/

#### bulk.find.upsert(upsertParam)

See https://docs.mongodb.com/manual/reference/method/Bulk.find.upsert/

#### bulk.insert(document)

See https://docs.mongodb.com/manual/reference/method/Bulk.insert/

#### bulk.toString()

See https://docs.mongodb.com/manual/reference/method/Bulk.toString/

#### bulk.tojson()`

See https://docs.mongodb.com/manual/reference/method/Bulk.tojson/