🛡️ Validation & Middleware

Why Validate at the Model?

You could check every field in your route handlers — but you'd have to remember to do it in every handler that touches that data, forever. Put the rules in the schema instead and they run automatically on every save() and create(), no matter which part of your app is calling. The database becomes the single source of truth for what "valid" means.

Think of validation as a checkpoint at the door: the document must pass every rule before Mongoose will let it through to MongoDB. Middleware is the staff working the door — it can transform the document, log the visit, or turn it away entirely.

Built-in Validators

Mongoose ships with validators for the most common rules. You've seen some already; here they are together, each with a custom message via the [value, 'message'] array form:

import mongoose from 'mongoose';
const { Schema } = mongoose;

const productSchema = new Schema({
  name: {
    type: String,
    required: [true, 'Product name is required'],  // presence
    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']           // numeric range
  },
  sku: {
    type: String,
    match: [/^[A-Z]{2}-\d{4}$/, 'SKU must look like XX-0000']  // regex
  },
  category: {
    type: String,
    enum: {                                          // allowed set
      values: ['Electronics', 'Clothing', 'Books', 'Home'],
      message: '{VALUE} is not a supported category'  // {VALUE} interpolates
    }
  }
});

Custom & Async Validators

When the built-ins aren't enough, supply your own validate function. It returns true for valid and false for invalid. Use a regular function so this refers to the document (handy for cross-field checks).

const userSchema = new Schema({
  password: {
    type: String,
    required: true,
    validate: {
      validator(v) {
        // ≥8 chars, one lower, one upper, one digit
        return /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).{8,}$/.test(v);
      },
      message: 'Password needs 8+ chars with upper, lower, and a number'
    }
  },
  passwordConfirm: {
    type: String,
    required: true,
    validate: {
      // Cross-field: compare against another field via `this`
      validator(v) { return v === this.password; },
      message: 'Passwords do not match'
    }
  }
});

Asynchronous validators

If a rule needs to hit the database or an API, make the validator async (or return a promise). It passes when the promise resolves to true.

const signupSchema = new Schema({
  email: {
    type: String,
    required: true,
    validate: {
      async validator(email) {
        const existing = await mongoose.models.User.findOne({ email });
        return !existing;   // false → email already taken
      },
      message: 'That email is already registered'
    }
  }
});

Handling ValidationError

When validation fails, the promise rejects with an error whose name is 'ValidationError'. It carries an errors object keyed by field, each with a human-readable message. Catch it and turn it into a clean 400 response.

// Express route
app.post('/api/products', async (req, res) => {
  try {
    const product = await Product.create(req.body);
    res.status(201).json(product);
  } catch (err) {
    if (err.name === 'ValidationError') {
      // Flatten { field: { message } } → { field: message }
      const errors = Object.fromEntries(
        Object.entries(err.errors).map(([field, e]) => [field, e.message])
      );
      return res.status(400).json({ message: 'Validation failed', errors });
    }
    if (err.code === 11000) {  // duplicate key (from a unique index)
      return res.status(409).json({ message: 'That value is already taken' });
    }
    console.error(err);
    res.status(500).json({ message: 'Server error' });
  }
});

{
  "message": "Validation failed",
  "errors": {
    "price": "Price cannot be negative",
    "category": "Sports is not a supported category"
  }
}

Validation on Updates

Here's a trap that catches everyone: update operations skip validation by default. findByIdAndUpdate and friends talk almost directly to MongoDB and bypass your schema rules unless you opt in with runValidators: true.

// ❌ This can write price: -50 straight past your min:0 rule
await Product.findByIdAndUpdate(id, { price: -50 });

// ✅ Opt in to validation (and return the updated doc)
await Product.findByIdAndUpdate(
  id,
  { price: -50 },
  { new: true, runValidators: true }  // now the min:0 rule fires → ValidationError
);

Middleware (Hooks)

Middleware (also called hooks) are functions Mongoose runs automatically around lifecycle events. pre hooks run before the operation; post hooks run after. The single most important distinction is what this refers to:

Document middleware — hashing a password

The canonical use: transform a document before it's saved. In document middleware, this is the document, and isModified() lets you skip work when nothing relevant changed.

import bcrypt from 'bcrypt';

userSchema.pre('save', async function (next) {
  // 'this' is the document about to be saved
  if (!this.isModified('password')) return next();  // only re-hash on change
  this.password = await bcrypt.hash(this.password, 12);
  next();
});

// Pair it with an instance method to check a login attempt:
userSchema.methods.comparePassword = function (candidate) {
  return bcrypt.compare(candidate, this.password);
};

Query middleware — filtering every find

Query middleware fires around find, findOne, updates, and so on. Here this is the query, so you refine the query itself.

// Regex /^find/ matches find, findOne, findById, findOneAndUpdate...
userSchema.pre(/^find/, function (next) {
  // 'this' is the query — exclude soft-deleted users everywhere
  this.where({ active: { $ne: false } });
  next();
});

Post hooks — reacting after the fact

userSchema.post('save', function (doc, next) {
  console.log(`Saved user ${doc.email}`);  // send welcome email, audit log, etc.
  next();
});

// A post-save error hook can prettify the E11000 duplicate-key error:
userSchema.post('save', function (err, doc, next) {
  if (err.code === 11000) return next(new Error('Email already in use'));
  next(err);
});

Real-World Patterns

Auto-generating a URL slug

Run a pre('validate') hook so the generated slug is itself validated before saving.

import slugify from 'slugify';

postSchema.pre('validate', function (next) {
  if (this.isModified('title')) {
    this.slug = slugify(this.title, { lower: true, strict: true });
  }
  next();
});

Schema-wide validation with invalidate

When a rule spans several fields, a pre('validate') hook can flag any field with this.invalidate():

projectSchema.pre('validate', function (next) {
  if (this.endDate && this.startDate && this.endDate < this.startDate) {
    this.invalidate('endDate', 'End date must be after start date');
  }
  next();
});

Cascading cleanup on delete

// Remove a user's posts when the user is deleted
userSchema.pre('deleteOne', { document: true, query: false }, async function (next) {
  await mongoose.model('Post').deleteMany({ author: this._id });
  next();
});

Practice & Quiz

const accountSchema = new Schema({
  username: {
    type: String,
    required: [true, 'Username is required'],
    match: [/^[a-zA-Z0-9_]+$/, 'Letters, numbers, and underscores only']
  },
  email: {
    type: String,
    required: [true, 'Email is required'],
    lowercase: true, trim: true
  },
  age: { type: Number, min: [13, 'Must be at least 13'] },
  plan: {
    type: String,
    enum: { values: ['free', 'pro', 'team'], message: '{VALUE} is not a valid plan' },
    default: 'free'
  }
});

postSchema.pre('save', function (next) {
  if (this.isModified('published') && this.published && !this.publishedAt) {
    this.publishedAt = new Date();
  }
  next();
});

Best Practices & Pitfalls

✅ Do

• Put validation rules in the schema so they run on every write, everywhere
• Give every rule a clear, user-facing message
• Pass runValidators: true whenever you use findByIdAndUpdate
• Guard pre('save') work with this.isModified(field)
• Catch both ValidationError and E11000 in your route handlers

❌ Don't

• Rely on async validators as your only duplicate defence — use a unique index too
• Forget next() (or an async/promise return) in a hook
• Use arrow functions for validators or hooks — they break this
• Put heavy, slow work inside frequently-run middleware

Summary

📚 Additional Resources

• Mongoose — Validation
• Mongoose — Middleware
• Mongoose — Error & ValidationError API
• Mongoose — Plugins

🚀 What's Next?

Your documents are now clean and safe. But most data is connected — a post has an author, an order has a customer. Next: Population & References, where you'll link documents across collections and pull related data together with populate().