@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

Resources

• mongoose

License

• MIT