@am92/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 ^6.8.2 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 Model Instance
  • Methods of Model Instance
• Resources
• License

Installation

npm install --save @am92/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 'Model' methods can executed. The connection can be established as shown below:

import { mongoConnect } from '@am92/mongo-odm'
await mongoConnect()

Creating a Collection Schema

import { buildSchema } from '@am92/mongo-odm'

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

const schemaOptions = {}  // Schema Options as defined by mongoose Schema Class

const CollectionSchema = buildSchema(CollectionSchemaObject, schemaOptions)

export default CollectionSchema

buildSchema() returns an instance of mongoose Schema Class.

Note: The 'options' object properties to be used is as defined by mongoose Schema Class. By default, buildSchema 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 '@am92/mongo-odm'

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

export default SubDocumentSchema

Using mongoose from @am92/mongo-odm

import mongoose, { Schema, Types, ObjectId } from '@am92/mongo-odm'

Creating a Collection Model

import { Model } from '@am92/mongo-odm'
import CollectionSchema from './CollectionSchema.mjs'

const CollectionODM = new Model('Collection', CollectionSchema)

export default CollectionODM

Properties of Model Instance

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

Methods of Model 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.aggregate	Runs mongoose aggregate function

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

CollectionODM.aggregate(pipeline)

Arguments

• pipeline (Array): mongoose pipeline array as per 'aggregate' method

Returns

• result (Any): Result as per mongoose 'aggregate' method

Example

const result = await CollectionODM.aggregate(pipeline)

Contributors

Ankit Gandhi

Mehul Agarwal

Resources

• mongoose

License

• MIT