<commit_before># mongoist

A [node.js](http://nodejs.org) module for mongodb built with async/await in mind, that emulates [the official mongodb API](http://www.mongodb.org/display/DOCS/Home) as much as possible.

Mongoist driver is heavily inspired by mongojs.

[![Build Status](https://travis-ci.org/saintedlama/mongoist.svg?branch=master)](https://travis-ci.org/saintedlama/mongoist)
[![Coverage Status](https://coveralls.io/repos/github/saintedlama/mongoist/badge.svg?branch=master)](https://coveralls.io/github/saintedlama/mongoist?branch=master)
[![mongoist analyzed by Codellama.io](https://app.codellama.io/api/badges/5a0439591b4c363a0f9427e6/31ad4e758e5c06b9e1d9d7e0d74cb475)](https://app.codellama.io/repositories/5a0439591b4c363a0f9427e6)

## 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);
```

## 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_

### Connecting

```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](http://mongodb.github.io/node-mongodb-native/2.2/reference/connecting/).

#### 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);
```

### Accessing Collections

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

```javascript<commit_msg>Fixed a typo in code<commit_after># mongoist

A [node.js](http://nodejs.org) module for mongodb built with async/await in mind, that emulates [the official mongodb API](http://www.mongodb.org/display/DOCS/Home) as much as possible.

Mongoist driver is heavily inspired by mongojs.

[![Build Status](https://travis-ci.org/saintedlama/mongoist.svg?branch=master)](https://travis-ci.org/saintedlama/mongoist)
[![Coverage Status](https://coveralls.io/repos/github/saintedlama/mongoist/badge.svg?branch=master)](https://coveralls.io/github/saintedlama/mongoist?branch=master)
[![mongoist analyzed by Codellama.io](https://app.codellama.io/api/badges/5a0439591b4c363a0f9427e6/31ad4e758e5c06b9e1d9d7e0d74cb475)](https://app.codellama.io/repositories/5a0439591b4c363a0f9427e6)

## 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);
```

## 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_

### Connecting

```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](http://mongodb.github.io/node-mongodb-native/2.2/reference/connecting/).

#### 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);
```

### Accessing Collections

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

```javascript
{'fraction_non_alphanumeric': 0.10442051572683479, 'fraction_numerical': 0.018985548313969963, 'mean_word_length': 5.090595340811044, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 9, 'https://': 16, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3120254', 'n_tokens_mistral': 2203, 'n_tokens_neox': 2032, 'n_words': 707}