node-modli/modli-mongo

View on GitHub
README.md

Summary

Maintainability
Test Coverage
[![wercker status](https://app.wercker.com/status/965720bdeb6427fcccf0323da755240b/s/master "wercker status")](https://app.wercker.com/project/bykey/965720bdeb6427fcccf0323da755240b)
[![Code Climate](https://codeclimate.com/github/node-modli/modli-mongo/badges/gpa.svg)](https://codeclimate.com/github/node-modli/modli-mongo)
[![Test Coverage](https://codeclimate.com/github/node-modli/modli-mongo/badges/coverage.svg)](https://codeclimate.com/github/node-modli/modli-mongo/coverage)

# Modli - Mongo Adapter

This module provides adapter for the [Mongo](https://www.mongodb.com)
datasource for integration with [Modli](https://github.com/node-modli).

## Installation

```
npm install modli-mongo --save
```

## Config and Usage

When defining a property which will utilize the adapter it is required that a
`collection` be supplied:

```javascript
import { model, adapter, Joi, use } from 'modli';
import mongo from 'modli-mongo';

model.add({
  name: 'foo',
  version: 1,
  collection: 'fooCollection'
  schema: {
    id: Joi.number().integer(),
    fname: Joi.string().min(3).max(30),
    lname: Joi.string().min(3).max(30),
    email: Joi.string().email().min(3).max(254).required()
  }
});
```

Then add the adapter as per usual with the following config object structure:

```javascript
adapter.add({
  name: 'mongoFoo',
  source: mongo
  config: {
    host: {HOST_IP},
    port: {HOST_PORT},
    username: {USERNAME},
    password: {PASSWORD},
    database: {DATABASE}
  }
});
```

You can then use the adapter with a model via:

```javascript
// Use(MODEL, ADAPTER)
const mongoTest = use('foo', 'mongoFoo');
```

## Methods

The following methods exist natively on the Mongo adapter:

### `execute`

Allows for executing methods directly on the collection:

```javascript
mongoTest.execute('insert', { /*...record...*/ })
  .then(/*...*/)
  .catch(/*...*/);
```

### `checkConn`

Ensures (or waits for) established connection:

```javascript
mongoTest.checkConn()
  .then(/*...*/);
```

*Note: the `checkConn` method is already utilized by all other methods
and only needs to be added in a case where you're extending
on or using a method of the `db` object directly.*

### `createCollection`

Creates the collection based on the model's `collection` name:

```javascript
mongoTest.createCollection()
  .then(/*...*/)
  .catch(/*...*/);
```

### `create`

Creates a new record based on object passed:

```javascript
mongoTest.create({
    fname: 'John',
    lname: 'Smith',
    email: 'jsmith@gmail.com'
  })
  .then(/*...*/)
  .catch(/*...*/);
```

### `read`

Returns records matching a query object (or all if no query specified):

```javascript
mongoTest.read({ fname: 'John' })
  .then(/*...*/)
  .catch(/*...*/);
```

### `update`

Updates record(s) based on query and body:

```javascript
mongoTest.update({ fname: 'John' }, {
    fname: 'Bob',
    email: 'bsmith@gmail.com'
  })
  .then(/*...*/)
  .catch(/*...*/);
```

### `delete`

Deletes record(s) based on query:

```javascript
mongoTest.delete({ fname: 'John' })
  .then(/*...*/)
  .catch(/*...*/);
```

### `extend`

Extends the adapter to allow for custom methods:

```javascript
mongoTest.extend('myMethod', () => {
  /*...*/
});
```

## Development

The Mongo adapter requires the following environment variables to be set for
running the tests. These should be associated with the Mongo instance running
locally.

```
MODLI_MONGO_HOST,
MODLI_MONGO_PORT,
MODLI_MONGO_USERNAME,
MODLI_MONGO_PASSWORD,
MODLI_MONGO_DATABASE
```

This repository includes a base container config for running locally which is
located in the [/docker](/docker) directory.

## Makefile and Scripts

A `Makefile` is included for managing build and install tasks. The commands are
then referenced in the `package.json` `scripts` if that is the preferred
task method:

* `all` (default) will run all build tasks
* `start` will run the main script
* `clean` will remove the `/node_modules` directories
* `build` will transpile ES2015 code in `/src` to `/build`
* `test` will run all spec files in `/test/src`
* `test-cover` will run code coverage on all tests
* `lint` will lint all files in `/src`

## Testing

Running `make test` will run the full test suite. Since adapters require a data
source if one is not configured the tests will fail. To counter this tests are
able to be broken up.

**Test Inidividual File**

An individual spec can be run by specifying the `FILE`. This is convenient when
working on an individual adapter.

```
make test FILE=some.spec.js
```

The `FILE` is relative to the `test/src/` directory.

**Deploys**

For deploying releases, the `deploy TAG={VERSION}` can be used where `VERSION` can be:

```
<newversion> | major | minor | patch | premajor
```

Both `make {COMMAND}` and `npm run {COMMAND}` work for any of the above commands.

## License

Modli-Mongo is licensed under the MIT license. Please see `LICENSE.txt` for full details.

## Credits

Modli-Mongo was designed and created at [TechnologyAdvice](http://www.technologyadvice.com).