🦡 Mongoose ODM Fundamentals

What Is Mongoose?

Mongoose is an Object Document Mapper (ODM) for MongoDB and Node.js. It sits between your JavaScript code and the database, giving you a schema-based way to model data, plus built-in type casting, validation, query building, and lifecycle hooks (middleware).

💡 The translator analogy. Mongoose is a fluent translator between two worlds — your structured JavaScript objects and MongoDB's documents. Without it you'd handle every low-level detail by hand; with it, you describe your data once and Mongoose handles the casting, validation, and plumbing.

Connecting with Mongoose

Install with npm install mongoose. Modern Mongoose (v6+) no longer needs the old useNewUrlParser/useUnifiedTopology flags — they're the default and are ignored now.

// db.js
const mongoose = require('mongoose');

async function connectDB() {
  try {
    await mongoose.connect(process.env.MONGODB_URI || 'mongodb://localhost:27017/myapp');
    console.log('MongoDB connected');
  } catch (err) {
    console.error('MongoDB connection error:', err);
    process.exit(1);   // fail fast if the database is unreachable
  }
}

module.exports = connectDB;

Schemas and Models

A schema defines the shape, types, defaults, and rules for documents. Compiling it with mongoose.model() produces a model — the object you actually query with.

💡 The blueprint analogy. A schema is a house blueprint: it says which rooms exist, their sizes, and what materials are allowed. Deviate from the blueprint mid-build and you get structural problems — deviate from the schema and you get inconsistent data.

const mongoose = require('mongoose');
const { Schema } = mongoose;

const userSchema = new Schema({
  firstName: { type: String, required: true, trim: true },
  lastName:  { type: String, required: true, trim: true },
  email: {
    type: String,
    required: true,
    unique: true,      // creates a unique index (not a validator!)
    lowercase: true,
    match: [/^\S+@\S+\.\S+$/, 'Please provide a valid email']
  },
  age:      { type: Number, min: [0, 'Age cannot be negative'], max: 120 },
  isActive: { type: Boolean, default: true },
  address:  { city: String, state: String, zipCode: String },  // embedded object
  interests: [String],                                          // array of strings
  company:  { type: Schema.Types.ObjectId, ref: 'Company' }     // reference
}, { timestamps: true });   // auto createdAt / updatedAt

const User = mongoose.model('User', userSchema);
module.exports = User;

CRUD with Models

Models expose clean methods for every operation. Modern Mongoose returns real promises, so async/await is the idiomatic style.

Create

// Option A: construct, then save
const user = new User({ firstName: 'John', lastName: 'Doe', email: 'john@example.com', age: 30 });
await user.save();

// Option B: create in one step
const jane = await User.create({
  firstName: 'Jane', lastName: 'Smith', email: 'jane@example.com', age: 28,
  interests: ['design', 'travel']
});

Read

const all   = await User.find();                          // every user
const byId  = await User.findById('60d21b4667d0d8992e610c85');
const byMail = await User.findOne({ email: 'john@example.com' });

// Chainable query builder: filter, project, sort, paginate
const adults = await User.find({ age: { $gte: 18 } })
  .select('firstName lastName email -_id')  // fields to include (and exclude _id)
  .sort({ lastName: 1 })
  .limit(10)
  .lean();                                   // plain JS objects — faster, read-only

Update

// Update without returning the document
await User.updateOne({ email: 'john@example.com' }, { $set: { age: 31 } });

// Find and update, returning the NEW version and running validators
const updated = await User.findByIdAndUpdate(
  '60d21b4667d0d8992e610c85',
  { $push: { interests: 'cooking' } },
  { new: true, runValidators: true }
);

Delete

await User.deleteOne({ email: 'john@example.com' });
const removed = await User.findByIdAndDelete('60d21b4667d0d8992e610c85'); // returns the deleted doc
await User.deleteMany({ isActive: false });

Validation

Validation is Mongoose's headline feature. Built-in validators cover the common cases; custom validators handle anything else, including async checks.

const productSchema = new Schema({
  name: {
    type: String,
    required: [true, 'Product name is required'],
    trim: true,
    minlength: [2, 'Name must be at least 2 characters'],
    maxlength: [100, 'Name cannot exceed 100 characters']
  },
  price: {
    type: Number,
    required: true,
    min: [0, 'Price cannot be negative'],
    validate: {
      validator: v => Number.isFinite(v) && Math.round(v * 100) === v * 100,
      message: props => `${props.value} must have at most 2 decimal places`
    }
  },
  category: {
    type: String,
    enum: {
      values: ['Electronics', 'Clothing', 'Books', 'Home', 'Food'],
      message: '{VALUE} is not a supported category'
    }
  }
});

Handle the resulting error to show friendly messages:

try {
  await Product.create({ name: 'X', price: -5, category: 'Toys' });
} catch (err) {
  if (err.name === 'ValidationError') {
    for (const field in err.errors) {
      console.log(err.errors[field].message);
      // "X must be at least 2 characters", "Price cannot be negative", "Toys is not a supported category"
    }
  }
}

Middleware (Hooks)

Middleware (also called hooks) runs code automatically before (pre) or after (post) an operation. It's the right home for cross-cutting concerns like hashing passwords or logging.

const bcrypt = require('bcrypt');

// Hash the password before every save — but only if it changed
userSchema.pre('save', async function (next) {
  if (!this.isModified('password')) return next();
  this.password = await bcrypt.hash(this.password, 10);
  next();
});

// Post-save hook: fire a side effect after the document is written
userSchema.post('save', function (doc) {
  console.log(`User saved: ${doc.email}`);
});

// Query middleware: 'this' is the query, not a document
userSchema.pre('find', function () {
  this.where({ isActive: true });   // hide soft-deleted users automatically
});

Virtuals & Methods

Virtuals are computed properties that are never stored in MongoDB. Instance methods add behavior to individual documents; static methods add behavior to the model itself.

💡 The spreadsheet analogy. A virtual is like a calculated column: fullName is derived from firstName and lastName the same way a "Total" column is Price × Quantity — it updates automatically and stores nothing.

// Virtual getter (computed, read-only)
userSchema.virtual('fullName').get(function () {
  return `${this.firstName} ${this.lastName}`;
});

// Virtual setter (split one value into two fields)
userSchema.virtual('fullName').set(function (name) {
  const [first, ...rest] = name.split(' ');
  this.firstName = first;
  this.lastName = rest.join(' ');
});

// Instance method — available on a document
userSchema.methods.getInitials = function () {
  return this.firstName[0] + this.lastName[0];
};

// Static method — available on the model
userSchema.statics.findByEmail = function (email) {
  return this.findOne({ email });
};

// Usage
const u = new User({ firstName: 'John', lastName: 'Doe' });
console.log(u.fullName);        // "John Doe"
console.log(u.getInitials());   // "JD"
const found = await User.findByEmail('john@example.com');

Indexes & Population

Indexes

Indexes make reads fast at the cost of slightly slower writes and extra storage. Index the fields you filter and sort on most.

userSchema.index({ lastName: 1, firstName: 1 });   // compound index
userSchema.index({ email: 1 }, { unique: true });   // unique index
userSchema.index({ firstName: 'text', lastName: 'text' }); // text search

Population: join-like reference resolution

When a field is a reference (ref), populate() replaces the stored ObjectId with the actual referenced document — Mongoose's answer to a SQL JOIN.

const orderSchema = new Schema({
  user:  { type: Schema.Types.ObjectId, ref: 'User', required: true },
  items: [{
    product:  { type: Schema.Types.ObjectId, ref: 'Product' },
    quantity: { type: Number, min: 1 }
  }],
  status: { type: String, enum: ['pending', 'shipped', 'delivered'], default: 'pending' }
}, { timestamps: true });

const Order = mongoose.model('Order', orderSchema);

// Resolve references, selecting only the fields you need
const orders = await Order.find({ user: userId })
  .populate('user', 'firstName lastName email')
  .populate('items.product', 'name price')
  .sort('-createdAt');

Hands-on Exercise

const mongoose = require('mongoose');
const { Schema } = mongoose;

const userSchema = new Schema({
  firstName: { type: String, required: true, trim: true },
  lastName:  { type: String, required: true, trim: true },
  email:     { type: String, required: true, unique: true, lowercase: true },
  age:       { type: Number, min: [0, 'Age cannot be negative'], max: [120, 'Age too large'] }
}, { timestamps: true, toJSON: { virtuals: true } });

userSchema.virtual('fullName').get(function () {
  return `${this.firstName} ${this.lastName}`;
});

userSchema.pre('save', function (next) {
  console.log(`Saving user: ${this.email}`);
  next();
});

const User = mongoose.model('User', userSchema);

async function demo() {
  const ok = await User.create({ firstName: 'Ray', lastName: 'Dev', email: 'RAY@EXAMPLE.COM', age: 30 });
  console.log(ok.fullName, ok.email);   // "Ray Dev  ray@example.com" (lowercased)

  try {
    await User.create({ firstName: 'Bad', lastName: 'Age', email: 'bad@example.com', age: -1 });
  } catch (err) {
    console.log(err.errors.age.message); // "Age cannot be negative"
  }
}

Best Practices

Summary & Quiz

📚 Further Reading

• Mongoose — Schemas Guide
• Mongoose — Validation
• Mongoose — Middleware
• Mongoose — Population

🚀 What's Next?

You now have the full MongoDB toolkit: documents, CRUD, and Mongoose. Next you'll put it all together in the Weekend Project: Databases, building a real data layer end to end.