# chpr-mongodb

[![CircleCI](https://circleci.com/gh/transcovo/chpr-mongodb.svg?style=shield&circle-token=8da2c27e11852beee45a48836681cb9cfb423412)](https://circleci.com/gh/transcovo/chpr-mongodb) [![codecov](https://codecov.io/gh/transcovo/chpr-mongodb/branch/master/graph/badge.svg?token=TTjxBMcFBQ)](https://codecov.io/gh/transcovo/chpr-mongodb)

> MongoDB connector

[MIGRATIONS GUIDELINES](./docs/migrations.md)

---

<!-- TOC depthFrom:2 -->

- [Requirements](#requirements)
- [Configuration](#configuration)
  - [Overall configuration](#overall-configuration)
  - [Database connection configuration](#database-connection-configuration)
- [Instanciation](#instanciation)
  - [Simple connection](#simple-connection)
  - [Models definitions](#models-definitions)
  - [Migrations definitions](#migrations-definitions)
- [Migrate to version chpr-mongodb 2](./docs/migrate-to-version-2.md)
- [Installation](#installation)
- [Tests](#tests)
- [/!\ Deprecation warnings](#\-deprecation-warnings)
  - [`migrate('update', 'init')`](#migrateupdate-init)
  - [`migrate('update')` with no second parameter](#migrateupdate-with-no-second-parameter)

<!-- /TOC -->

This library is a wrapper on [`node-mongodb-native`](https://github.com/mongodb/node-mongodb-native/tree/2.2).
The original documentation is available [here](http://mongodb.github.io/node-mongodb-native/2.2/). The purpose is to help
having robust connection on MongoDb databases potentially on multiple
databases, with models definitions and migration patterns.

## Requirements

- `async` / `await` is required (Node.js 7+)
- `MongoDB 3.2+` is required to use the `document validation` feature

## Configuration

### Overall configuration

The connector configuration object must look like this:

```js
{
  databases: [
    // Database configuration
  ]
}
```

By default, all indexes are created in background. You can change this
behavior by setting the property `ensureIndexInBackground` to `false`.

### Database connection configuration

If you want to connect a specific database, please use the following object
format:

```js
{
  name: 'riders', // Database name
  url: 'mongodb://localhost:27017/riders', // Database connection string
  options: {
    // MongoDb connection options
  }
}
```

The `options` properties are documented in the [official documentation](http://mongodb.github.io/node-mongodb-native/2.2/api/MongoClient.html#.connect).

## Instanciation

### Simple connection

```js
const { MongoDbConnector } = require('chpr-mongodb');

async function start() {
  const client = new MongoDbConnector({
    databases: [{
      name: 'test',
      url: 'mongodb://localhost:27017/test'
    }]
  });

  await client.connect();
}

async function stop() {
  await client.disconnect();
}
```

### Models definitions

> Please have a look to the [example](docs/models.md).

```js
const { MongoDbConnector } = require('chpr-mongodb');

async function start() {
  const client = new MongoDbConnector({
    databases: [{
      name: 'test',
      url: 'mongodb://localhost:27017/test'
    }]
  }, {
    users: {
      DATABASE: 'test',
      COLLECTION: 'users'
    }
  });

  await client.connect();

  // Example of models initialization (tests only):
  await client.migrate('update', 'from-models');
}

async function stop() {
  await client.disconnect();
}
```

### Migrations definitions

> Please have a look to the [migrations documentation](docs/migrations.md).

```js
// migrations/index.js
const addUniqueIndexExample20171129 = require('./1.add-unique-index-example.js');

module.exports = new Map([
  ['1', addUniqueIndexExample20171129]
]);

```

```js
// migrate.js
const { MongoDbConnector } = require('chpr-mongodb');

const migrations = require('./migrations');

async function start() {
  const client = new MongoDbConnector({
    databases: [{
      name: 'test',
      url: 'mongodb://localhost:27017/test'
    }]
  }, {
    users: {
      DATABASE: 'test',
      COLLECTION: 'users'
    }
  }, migrations);

  await client.connect();

  // Example of unique migration call (tests only):
  await client.migrate('update', '1');
}

async function stop() {
  await client.disconnect();
}

```

## Installation

```bash
nvm i

npm install
```

## Tests

```bash
# Run the mocha tests only
npm run mocha

# Run the eslint only
npm run eslint

# Run the coverage withuut eslint
npm run mocha

# Run all the tests
npm test
```

## /!\ Deprecation warnings

### `migrate('update', 'init')`

> After 2018-03-01, no guarantee about its support is given

The keyword `init` has been deprecated in favor of `from-models`. It was
unclear that this migration was special and was applying for a test purpose
only migration of models from the models definitions themselves. The
replacement will be:

```
migrate('update', 'from-models')
```

Or even more explicit:

```
applyModels('update')
```

### `migrate('update')` with no second parameter

> After 2018-03-01, no guarantee about its support is given

The absence of second parameter to the `migrate` method was unclear that
it will apply all migrations from the very first one to the last one. The
keyword `all` is prefered until now. The following syntax will apply the
same result:

```
migrate('update', 'all')
```

Or even more explicit:

```
applyAllMigrations('update')
```