mongoose-connection-promise

Convenience library to connect Mongoose to a MongoDB instance using promises.

Note: With the introduction of mongoose > 5.x this library becomes obsolete as the handling of connections has been greatly improved in mongoose > 5.x. Read here for a good summary of the changes/improvements introduced.

Therefore this library will not be updated for mongoose > 5.x.

Table of Contents

• Install
• Motivation
• Usage
• API
• Test
• Author
• License

(TOC generated by verb using markdown-toc)

Install

Install with npm

$ npm install mongoose-connection-promise

Install with yarn

$ yarn add mongoose-connection-promise

Motivation

Although mongoose does not force you to wait until a mongoose connection has been created, the author of this module prefers to not start with any application before we know that a connection has been established successfully.

mongoose-connection-promise helps connecting and disonnecting to MongoDB in mongoose reliably.

Usage

Use mongoose-connection-promise in express.js

Connect mongoose to a MongoDB instance using the default settings:

const express = require('express');
const MongooseConnection = require('mongoose-connection-promise');

const app = express();

// Initialize using the default settings, which is assuming MongoDB to run
// at mongodb://localhost:27017
const mongooseConnection = new MongooseConnection();

console.log(mongooseConnection.config.host); // Returns localhost
console.log(mongooseConnection.config.port): // Returns 27017

mongooseConnection.connect()
  .then(connection => {
    app.db = connection;
    const port = 3003;
    app.listen(port, err => {
      if (err) {
        console.log('Could not start express server');
      } else {
        console.log(`Express server started at port ${port}`);
      }
    });
  })
  .catch(err => {
    console.log('Error creating a mongoose connection', err);
  });

Pass in options:

const MongooseConnection = require('mongoose-connection-promise');

const opts = {
  username: 'foo',
  password: 'bar',
  host: 'mongo.local',
  port: 27018,
  debug: true
};

const mongooseConnection = new MongooseConnection(opts);

mongooseConnection.connect()
  .then(connection => {
    // successfully connected
  })
  .catch(err => {
    // an error occurred
  });

API

Configuration

Define a configuration object to pass to the constructor.

If no options are defined, the default options will be used: See index.js => defaultOpts for more information about the current default options.

Params

• opts {Object}: Options to pass in.
• opts.debug {Boolean}: Whether MongoDB runs in debug mode or not.
• opts.host {String}: The MongoDBhost, defaults to localhost. See the mongodb connection string spec for more details.
• opts.port {Number}: The MongoDB port, defaults to 27017. See the mongodb connection string spec for more details.
• opts.database {String}: The MongoDB database, defaults to admin. See the mongodb connection string spec for more details.
• opts.connectOptions {Object}: The MongoDB connection properties, being passed through to the native MongoDB driver. See mongoose' documentation, resp. MongoDB's native driver for node.js' documentation for more details.

Example

// Default Options:
const defaultOpts = {
   debug: false,
   host: 'localhost',
   port: 27017,
   database: '',
   connectOptions: {
     db: {},
     server: {
       auto_reconnect: true
     },
     replset: {},
     user: {},
     pass: {},
     auth: {},
     mongos: {}
   }
};

.constructor()

Initialize a new MongooseConnection.

Params

• {Configuration}: opts - Options to initialize MongooseConnection.

.DEFAULT_CONFIG

Returns the default options of mongoose-connection-promise

.connect()

Connect mongoose to the given instance of MongoDB.

• returns {Promise}

.get()

Get an existing connection or create a new one.

In contrary to .connect() this method will not create a new connection if MongooseConnection is already connected, but the existing connection will be re-used and returned.

• returns {Promise<NavtiveConnection,Error>}: Returns the connection to MongoDB.

.disconnect()

Disconnects all mongoose connections.

• returns {Promise<void,Error>}

.isConnected()

Indicates whether there is a current and ready-to-use mongoose connection.

• returns {boolean}

.defaultOptions()

Return the default options (DEPRECATED).

• returns: object

Test

Start the MongoDB docker container:

$ npm run dc-dev-up

Then run the tests:

$ npm run test

Author

Stefan Walther

• github/stefanwalther
• twitter/waltherstefan

License

MIT

This file was generated by verb-generate-readme, v0.6.0, on February 22, 2018.