@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
• Environment Variables
• Connecting to MongoDB
• Creating a Collection Schema
• Creating a Collection Model
  • Properties of MongoModel Instance
  • Methods of MongoModel Instance
• Resources
• License

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

Resources

• mongoose

License

• MIT