{"id":43092,"library":"mongo-models","title":"mongo-models","description":"Lightweight MongoDB ODM using JavaScript classes and Joi schema validation, targeting Node.js >=8 with MongoDB 3.x. v3.0.4 is current stable, with infrequent releases. Differentiates from Mongoose by being minimal and class-based, and from the native MongoDB driver by providing model abstractions, schema enforcement via Joi, and automatic document instantiation.","status":"active","version":"3.0.4","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/jedireza/mongo-models","tags":["javascript","mongo","mongodb","model","models","odm"],"install":[{"cmd":"npm install mongo-models","lang":"bash","label":"npm"},{"cmd":"yarn add mongo-models","lang":"bash","label":"yarn"},{"cmd":"pnpm add mongo-models","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for MongoDB driver version 3.x.","package":"mongodb","optional":false},{"reason":"Used for schema validation of model documents.","package":"joi","optional":true}],"imports":[{"note":"Package does not ship ES modules; default CommonJS export only.","symbol":"MongoModels","correct":"const MongoModels = require('mongo-models')"},{"note":"No ESM support; destructure from CommonJS require.","wrong":"import { connect } from 'mongo-models'","symbol":"connect","correct":"const { connect } = require('mongo-models')"},{"note":"Use require() directly; ESM import will cause a runtime error.","wrong":"import MongoModels from 'mongo-models'; class Customer extends MongoModels { ... }","symbol":"Model class","correct":"class Customer extends require('mongo-models') { ... }"}],"quickstart":{"code":"const MongoModels = require('mongo-models');\nconst Joi = require('joi');\n\nconst schema = Joi.object({\n  _id: Joi.object(),\n  name: Joi.string().required(),\n  email: Joi.string().email(),\n  phone: Joi.string()\n});\n\nclass User extends MongoModels {\n  static create(name, email, phone) {\n    const document = new User({ name, email, phone });\n    return this.insertOne(document);\n  }\n}\nUser.collectionName = 'users';\nUser.schema = schema;\n\n(async () => {\n  await MongoModels.connect({ uri: process.env.MONGODB_URI ?? '', db: process.env.MONGODB_NAME ?? '' }, {});\n  const users = await User.create('Alice', 'alice@example.com', '555-1234');\n  console.log(users[0]);\n  await MongoModels.disconnect();\n})();","lang":"javascript","description":"Demonstrates creating a model class with Joi schema, inserting a document, and connecting/disconnecting to MongoDB."},"warnings":[{"fix":"Use mongodb@3.6.x with Node.js >=8, or stay on v2.x if upgrading mongodb.","message":"v3.x peer dependency mongodb@3.x.x only, not compatible with mongodb 4.x or 5.x.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always define Customer.collectionName = 'customers' and Customer.schema = joiSchema after the class definition.","message":"Static collectionName and schema properties must be set on the model class before any operations; forgetting them leads to undefined behavior.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pass the connection object as first argument and options as second: MongoModels.connect({ uri, db }, {}).","message":"connect() with object parameter changed from v2 to v3: v2 used { uri, db } but v3 expects { uri: string, db: string } as first argument.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Use const [doc] = await Model.insertOne(data); or destructure result array.","message":"insertOne() now returns an array of inserted documents (v3) instead of a single document (v2).","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"To get instances, iterate results and manually construct: results.map(doc => new Model(doc)).","message":"Model.find() returns plain objects, not model instances, unless you override the static method.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Manually validate before updates using Joi.validate or set up hooks.","message":"Schema validation via Joi is only triggered on insertOne/insertMany, not on find/findOne/update operations.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'3':19 '8':16 'abstract':47 'automat':53 'base':37 'class':9,36 'class-bas':35 'current':23 'differenti':28 'document':54 'driver':43 'enforc':49 'infrequ':26 'instanti':55 'javascript':8,56 'joi':11,51 'lightweight':4 'minim':33 'model':3,46,59,60 'mongo':2,57 'mongo-model':1 'mongodb':5,18,42,58 'mongoos':30 'nativ':41 'node.js':15 'odm':6,61 'provid':45 'releas':27 'schema':12,48 'stabl':24 'target':14 'use':7 'v3.0.4':21 'valid':13 'via':50 'x':20","created_at":"2026-06-05T16:58:08.309796+00:00","updated_at":"2026-06-05T16:58:08.309796+00:00","problems":[{"fix":"Use const MongoModels = require('mongo-models');","cause":"Importing ESM style (import) when package is CommonJS-only.","error":"TypeError: MongoModels.connect is not a function"},{"fix":"Ensure you have const MongoModels = require('mongo-models'); before class definition.","cause":"Forgot to require the package before extending.","error":"Error: MongoModels is not a constructor"},{"fix":"Add Model.collectionName = 'your_collection_name'; after class definition.","cause":"Collection name not set on model class.","error":"MongoError: cannot determine collection name"},{"fix":"Downgrade mongodb to 3.6.x or upgrade mongo-models to a version supporting 4.x.","cause":"Using mongodb@4.x which changes BSON types; mongo-models v3 requires mongodb@3.x.","error":"TypeError: Cannot read property '_bsontype' of undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/jedireza/mongo-models","github":"ssh://git@github.com/jedireza/mongo-models","docs":null,"changelog":null,"pypi":null,"npm":"mongo-models","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-05","next_check":"2026-09-03","install_tag":null}}