@m92/mongo-odm NPM

@m92/mongo-odm

This is an ODM (Object Document Mapping) which provides CRUD functionalities to interact with MongoDB Collections. This package uses mongoose package using its v6.x.x version.

This package provides the following functionalities:

MongoDB Connection Helper
Mongoose Schema Wrapper
Collection Modeling Class

Table of Content

Installation

$ npm install --save @m92/mongo-odm

Environment Variables

The following environment variables need to be set to work with this package:

##### Mongo Config
export MONGO_HOSTS=
export MONGO_DBNAME=
export MONGO_USER_AUTH=false
export MONGO_USERNAME=
export MONGO_PASSWORD=
export MONGO_REPLICASET=
export MONGO_REPLICASET_COUNT=0
export MONGO_READ_PREFERENCE=
export MONGO_SSL_ENABLED=false
export MONGO_SSL_VALIDATE=false
export MONGO_PEM_PATH=
export MONGO_POOL_SIZE=5

Note: Do not export variable 'MONGO_READ_PREFERENCE' if no value is to be set.

Connecting to MongoDB

MongoDB needs to be connected before the 'MongoModel' methods can executed. The connection can be established as shown below:

import mongoConnect from '@m92/mongo-odm/mongoConnect'
await mongoConnect()

Creating a Collection Schema

import mongoSchemaWrapper from '@m92/mongo-odm/mongoSchemaWrapper'

const CollectionSchemaObject = {
    // Schema Properties as defined by mongoose Schema Class
}
const options = {}

const CollectionSchema = mongoSchemaWrapper(CollectionSchemaObject, options)
export default CollectionSchema

mongoSchemaWrapper() returns an instance of mongoose Schema Class.

Note: The 'options' object properties to be used is as defined by mongoose Schema Class. By default, mongoSchemaWrapper adds 'timestamps: true' option which can be overriden if needed. You may avoid passing the 'options' object if no extra options are required for a given Schema.

Using mongoose Schema Class

import { Schema } from '@m92/mongo-odm/mongoose'

const SubDocumentSchema = new Schema({
  // Schema Properties as defined by mongoose Schema Class
})

export default SubDocumentSchema

Creating a Collection Model

import MongoModel from '@m92/mongo-odm/MongoModel'
import CollectionSchema from './CollectionSchema.mjs'

const CollectionODM = new MongoModel('Collection', CollectionSchema)
export default CollectionODM

Properties of MongoModel Instance

Properties	Description
CollectionODM.ModelName	Name of the Model
CollectionODM.Schema	mongoose Collection Schema
CollectionODM.MongooseModel	mongoose Model instance

Methods of MongoModel Instance

Method	Description
CollectionODM.getCount	Returns the count of Documents
CollectionODM.createOne	Creates a new Document
CollectionODM.createMany	Creates multiple new Documents
CollectionODM.replaceAll	Replaces all Documents with new Documents
CollectionODM.findOne	Finds and returns a single Document
CollectionODM.findMany	Finds and returns mulitple Documents
CollectionODM.findById	Finds using MongoDB ObjectId and returns a single Document
CollectionODM.findOneBy	Finds using key-value pair and returns a single Document
CollectionODM.findManyBy	Finds using key-value pair and returns mulitple Documents
CollectionODM.updateOne	Updates a single Document and returns the Updated Document
CollectionODM.updateMany	Updates multiple Documents and returns the Updated Documents
CollectionODM.updateById	Updates a single Document with spcified MongoDB ObjectId and returns the Updated Document
CollectionODM.updateOneBy	Updates a single Document using key-value pair and returns the Updated Document
CollectionODM.updateManyBy	Updates multiple Documents using key-value pair and returns the Updated Documents
CollectionODM.remove	Removes multiple documents and returns the delete response
CollectionODM.removeById	Deletes a single Document with spicifed MongoDB ObjectId and returns the Deleted Document
CollectionODM.list	Returns all the Documents from a given Collection
CollectionODM.search	Searches and returns Documents from a given Collection

CollectionODM.getCount(query)

Arguments

query (Object): mongoose query object

Returns

count (Number): Number of documents found

Example

const count = await CollectionODM.getCount({ ...queryProps })

CollectionODM.createOne(attrs)

Arguments

attrs (Object): Object as per CollectionSchema

Returns

document (Object): Created Lean Document

Example

const doc = await CollectionODM.createOne({ ...SchemaProps })

CollectionODM.createMany(attrs)

Arguments

attrs (Array): Array of Object as per CollectionSchema

Returns

documents (Array): Created Lean Documents Array

Example

const docs = await CollectionODM.createMany([{ ...SchemaProps }])

CollectionODM.replaceAll(attrs)

Arguments

attrs (Array): Array of Object as per CollectionSchema

Returns

documents (Array): Created Lean Documents Array

Example

const docs = await CollectionODM.replaceAll([{ ...SchemaProps }])

CollectionODM.findOne(query, projection, options)

Arguments

query (Object): mongoose query object
projection (Object): mongoose projection object
options (Object): mongoose options object as per 'findOne' method

Returns

document (Object): Lean Document

Example

const doc = await CollectionODM.findOne(query, projection, options)

CollectionODM.findMany(query, projection, options)

Arguments

query (Object): mongoose query object
projection (Object): mongoose projection object
options (Object): mongoose options object as per 'find' method

Returns

documents (Array): Lean Documents Array

Example

const docs = await CollectionODM.findMany(query, projection, options)

CollectionODM.findById(id, projection, options)

Arguments

id (String): mongoose Document '_id' Value
projection (Object): mongoose projection object
options (Object): mongoose options object as per 'findById' method

Returns

document (Object): Found Lean Document

Example

const doc = await CollectionODM.findById(id, projection, options)

CollectionODM.findOneBy(key, value, projection, options)

Arguments

key (String): mongoose Document Property Name
value (any): mongoose Document Property Query Value
projection (Object): mongoose projection object
options (Object): mongoose options object as per 'findOne' method

Returns

document (Object): Found Lean Document

Example

const doc = await CollectionODM.findOneBy(key, value, projection, options)

CollectionODM.findManyBy(key, value, projection, options)

Arguments

key (String): mongoose Document Property Name
value (any): mongoose Document Property Query Value
projection (Object): mongoose projection object
options (Object): mongoose options object as per 'findOne' method

Returns

documents (Array): Found Lean Documents Array

Example

const doc = await CollectionODM.findManyBy(key, value, projection, options)

CollectionODM.updateOne(query, updateObj, options)

Arguments

query (Object): mongoose query object
updateObj (Object): mongoose update object
options (Object): mongoose options object as per 'findOneAndUpdate' method

Returns

document (Object): Updated Lean Document

Example

const updatedDoc = await CollectionODM.updateOne(query, updateObj, options)

CollectionODM.updateMany(query, updateObj, options)

Arguments

query (Object): mongoose query object
updateObj (Object): mongoose update object
options (Object): mongoose options object as per 'updateMany' method

Returns

documents (Array): Updated Lean Documents Array

Example

const updatedDocs = await CollectionODM.updateMany(query, updateObj, options)

CollectionODM.updateById(id, updateObj, options)

Arguments

id (String): mongoose Document '_id' Value
updateObj (Object): mongoose update object
options (Object): mongoose options object as per 'findByIdAndUpdate' method

Returns

document (Object): Updated Lean Document

Example

const updatedDoc = await CollectionODM.updateById(id, updateObj, options)

CollectionODM.updateOneBy(key, value, updateObj, options)

Arguments

key (String): mongoose Document Property Name
value (any): mongoose Document Property Query Value
updateObj (Object): mongoose update object
options (Object): mongoose options object as per 'findOneAndUpdate' method

Returns

document (Object): Updated Lean Document

Example

const updatedDoc = await CollectionODM.updateOneBy(key, value, updateObj, options)

CollectionODM.updateManyBy(key, value, updateObj, options)

Arguments

key (String): mongoose Document Property Name
value (any): mongoose Document Property Query Value
updateObj (Object): mongoose update object
options (Object): mongoose options object as per 'updateMany' method

Returns

documents (Array): Updated Lean Documents Array

Example

const updatedDocs = await CollectionODM.updateManyBy(key, value, updateObj, options)

CollectionODM.remove(query, options)

Arguments

query (Object): mongoose query object
options (Object): mongoose options object as per 'deleteMany' method

Returns

removeResponse (Object): // TODO

Example

const removeResponse = await CollectionODM.remove(query, options)

CollectionODM.removeById(id, options)

Arguments

id (String): mongoose Document '_id' Value
options (Object): mongoose options object as per 'findByIdAndRemove' method

Returns

document (Object): Deleted Lean Document

Example

const doc = await CollectionODM.removeById(id, options)

CollectionODM.list(projection, options)

Arguments

projection (Object): mongoose projection object
options (Object): mongoose options object as per 'find' method

Returns

documents (Array): Found Lean Documents Array

Example

const docs = await CollectionODM.list(projection, options)

CollectionODM.search(query, projection, options)

Arguments

query (Object): mongoose query object
projection (Object): mongoose projection object
options (Object): mongoose options object as per 'find' method

Returns

responseData (Object): Found Lean Documents Array with Counts

{
  "_meta": {
    "totalDocuments": 0,   // Total number of documents found against the 'query'
    "documentsCount": 0    // Number of documents found for given pagination options
  },
  "documents": []          // Lean Documents Array
}

Example

const responseData = await CollectionODM.search(query, projection, options)
const queryDocsCount = responseData._meta.totalDocuments
const pageDocsCount = responseData._meta.documentsCount
const docs = responseData.documents