Mongoose MongoDB ODM

Mongoose follows a major version lifecycle. Choosing the right version depends on whether you need new features, security patches, or are maintaining legacy systems:

• Mongoose 9 (Current): The latest major version. Use this for the best experience, including all new features and improvements.
• Mongoose 8 (Prior): Receives new features, improvements, and bug fixes until at least February 1, 2026.
• Mongoose 7 (Legacy): Receives important fixes only; not the primary development focus.
• Mongoose 6 (Limited Maintenance): Receives only security patches and requested bug fixes. End of Life is February 1, 2027, after which no updates (including security) will be provided.
• Mongoose 5 (End of Life): No longer maintained or updated as of March 1, 2024.

A Mongoose document is an instance of a Model class that is backed by MongoDB data. The class hierarchy is Document < Model < User (your specific model). Documents provide built-in support for change tracking, casting, validation, middleware, and persistence via the save() method.

const User = mongoose.model('User', new Schema({ name: String }));

// `doc` is a document instance
const doc = new User({ name: 'John Smith' });

doc instanceof User; // true
doc instanceof mongoose.Model; // true
doc instanceof mongoose.Document; // true

A SchemaType is a configuration object for an individual property within a Mongoose schema. It defines the data type for a path, validation rules, getters/setters, and default values.

Important Distinction: A SchemaType is a configuration object, not the data itself. For example, mongoose.Schema.Types.ObjectId is a configuration for a schema path, whereas mongoose.Types.ObjectId is the actual constructor used to create a MongoDB ObjectId instance.

const schema = new Schema({ name: String });
schema.path('name') instanceof mongoose.SchemaType; // true
schema.path('name') instanceof mongoose.Schema.Types.String; // true

In Mongoose 7, the minimize option (which strips empty objects) only applied when saving a new document. In Mongoose 8, minimize is also applied when save() is called on an existing document.

const schema = new Schema({
  nested: {
    field1: Number
  }
});
const Test = mongoose.model('Test', schema);

// Both Mongoose 7 and Mongoose 8 strip out empty objects when saving
// a new document in MongoDB by default
const { _id } = await Test.create({ nested: {} });
let rawDoc = await Test.findById(_id).lean();
rawDoc.nested; // undefined

// Mongoose 8 will also strip out empty objects when saving
// an existing document in MongoDB
const doc = await Test.findById(_id);
doc.nested = {};
doc.markModified('nested');
await doc.save();

let rawDoc = await Test.findById(_id).lean();
rawDoc.nested; // undefined in Mongoose 8, {} in Mongoose 7

While one-to-many relationships are typically handled by a parent pointer on the 'many' side, you can maintain an array of child pointers on the 'one' side. To make these available for population, you must explicitly push() the child document into the parent's array and save() the parent.

Alternatively, instead of maintaining two sets of pointers (which can get out of sync), you can simply query the child collection directly using the parent's ID.

// Option 1: Pushing refs to children to allow .populate('stories')
author.stories.push(story1);
await author.save();

// Option 2: Direct query (often safer to avoid sync issues)
const stories = await Story.find({ author: author._id }).exec();

Mongoose automatically adds an _id property of type ObjectId to every schema.

Customizing _id:

• Overwriting: You can define your own _id path (e.g., _id: Number). If you do this, you are responsible for setting the _id before saving, otherwise Mongoose will throw an error: "document must have an _id before saving".
• Disabling for Subdocuments: You can disable the automatic _id on subdocuments by passing { _id: false } in the subdocument's schema options or by setting _id: false within the subdocument's schema definition.

// Overwriting default _id
const schema = new Schema({
  _id: Number
});
const Model = mongoose.model('Test', schema);
const doc = new Model();
doc._id = 1;
await doc.save(); // works

// Disabling _id on a subdocument
const nestedSchema = new Schema(
  { name: String },
  { _id: false }
);

Mongoose population behaves like a SQL left join.

• If a single reference path (e.g., author) finds no matching document, the field will be null.
• If an array reference path (e.g., fans) finds no matching documents, the field will be an empty array [].

// Single ref: returns null if not found
const story = await Story.findOne({ title: 'Casino Royale' }).populate('author');
story.author; // null

// Array ref: returns [] if nothing matches
const storyWithAuthors = await Story.findOne({ title: 'Casino Royale' }).populate('authors');
storyWithAuthors.authors; // []

When using .lean(), Mongoose returns Plain Old JavaScript Objects (POJOs) instead of full Mongoose documents. Because virtuals are properties of Mongoose documents, they are not available on lean documents.

If you need virtuals while using lean() for performance, use the mongoose-lean-virtuals plugin.

const fullDoc = await User.findOne();
fullDoc.domain; // 'gmail.com' (Full Mongoose document)

const leanDoc = await User.findOne().lean();
leanDoc.domain; // undefined (POJO)