Mongodb Data Layer
===

This is a simple yet (hopefully) useful set of tools to aid working with mongodb.

- Mongodb Data Layer
- Usage
- Mongodb connection factory
- IMongoParams
- createConnection(config: IMongoParams): Promise
- createClient(config: IMongoParams): Promise
- MongodbRepository
- Instantiation
- Protected methods
- findOneBy(query: Record): Promise
- [unpaginatedSearch(query: Record): Promise](#unpaginatedsearchquery-recordstring-any-promisetentity)
- existsBy(query: Record): Promise
- runPaginatedQuery(query: Record, page?: number, size?: number): Promise>
- deleteBy(query: any): Promise
- Public methods
- deleteById(id: ObjectId | string): Promise
- findById(id: ObjectId | string): Promise
- existsById(id: ObjectId | string): Promise
- save(entity: TEntity): Promise
- Contributing

Usage

Currently there are two main functionallities:

Mongodb connection factory

Utility functions that receive a fiven configuration and return a promise resolving to either a mongodb Db, or the MongoClient instance itself. These functions are detailed below.

Both functions accept a IMongoParams interface, which is as follows:

$3

``typescript
interface IMongoParams {
uri: string; // Mongodb full URI including schema
dbName: string; // Name of the desired database
options?: MongoClientOptions; // Passthrough options for MongoClient's connect method
maximumConnectionAttempts?: number; // Number of connection attempts to make before throwing a ConnectionError
}
`

$3

This receives the connection params and resolves to an instance of mongodb's Db.

Example:
`typescript
import mongodb, { IMongoParams } from '@irontitan/mongodb-data-layer'

const mongodbParams: IMongoParams = {
uri: 'mongodb://localhost:27017',
dbName: 'my-database'
}

mongodb.createConnection(mongodbParams)
.then(db => {
const collection = db.collection('users')

collection.findOne({ username: 'rjmunhoz' })
.then(user => {
if (!user) throw new Error('User not found!')

console.log('Found user rjmunhoz')
})
})
`

$3

Same as createConnection, but resolves to a MongoClient instead

Example:
`typescript
import mongodb, { IMongoParams } from '@irontitan/mongodb-data-layer'

const mongodbParams: IMongoParams = {
uri: 'mongodb://localhost:27017',
dbName: 'my-database'
}

mongodb.createClient(mongodbParams)
.then(mongoClient => {
const db = mongoClient.db('my-database')
const collection = db.collection('users')

collection.findOne({ username: 'rjmunhoz' })
.then(user => {
if (!user) throw new Error('User not found!')

console.log('Found user rjmunhoz')
db.close() // this is why we actually implemented createClient
})
})
`

MongodbRepository

This is a class which implements common and, usually, repetitive functionallity.

$3

MongodbRepository is an abstract class and, as so, you cannot instantiate it directly; it mus be extended.
This is because you have to provide your own entity type like so:

`typescript
import { Db } from 'mongodb'
import { Profile } from '../../domain/profile/Profile'
import { MongodbRepository } from '@irontitan/mongodb-data-layer'

export class ProfileRepository extends MongodbRepository {
constructor (connection: Db) {
super(connection.collection('profiles'))
}
}
`

$3

These methods are available for your repository to use, but are generally too generic to be used outside the data layer (aka they require queries and database-only stuff)

#### findOneBy(query: Record): Promise

Receives a query object, runs it and resolves to its result

#### unpaginatedSearch(query: Record): Promise

Runs the given query and resolves to its results without applying pagination

#### existsBy(query: Record): Promise

Runs the given query resolving to true if a result was found and to false otherwise.

> This simply counts the amount of documents found by the query, without fetching any of them.

#### runPaginatedQuery(query: Record, page?: number, size?: number): Promise>

Runs the given query and resolves to its results paginated.

The PaginatedQueryResult is as follows

`typescript
interface PaginatedQueryResult {
count: number; // amount of results returned by this call
total: number; /// total amount of documents found by query
range: {
from: number; // number of the first result
to: number; // number of the last result
};
results: TEntity[]; // array of results
}
`

#### deleteBy(query: any): Promise

Deletes any documents matched by the given query and resolves to a boolean indicating success

$3

These methods are simple enough to be database agnostic and, thus, can be used directly by other layers.

#### deleteById(id: ObjectId | string): Promise

Deletes a document given its ID and resolves to a boolean indicating success

#### findById(id: ObjectId | string): Promise

Finds a document by its ID and resolved to an instance of TEntity, if one was found, or to null` otherwise

#### existsById(id: ObjectId | string): Promise

Resolved to a boolean indicating wether a given document exists or not, based on its ID

> This uses existsBy under the hood

#### save(entity: TEntity): Promise

Upserts an entity to the database and resolves to the same input entity

Contributing

See CONTRIBUTING.md