0Pricing
MongoDB Academy · Lesson

Mongoose Middleware: Pre and Post Hooks

Learners will write document and query middleware hooks for tasks like hashing passwords before save or logging after find.

Mongoose Middleware: Pre and Post Hooks is a free MongoDB Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MongoDB Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What Is Mongoose Middleware?

Mongoose middleware (also called hooks) are functions that run before or after specific operations like save, find, updateOne, deleteOne, and more. They enable you to inject custom logic into the lifecycle of document and query operations without cluttering your route handlers. Common uses include hashing passwords before save, logging query times, enforcing soft deletes, and populating related data after find.

Two Types: Document and Query Middleware

Mongoose has two distinct categories of middleware: Document middleware hooks into operations on a specific Document instance (save, validate, remove, init). Query middleware hooks into query operations invoked on the Model (find, findOne, updateOne, deleteOne, etc.). The key difference is what this refers to—in document middleware, this is the document; in query middleware, this is the query object.

// Document middleware: 'this' = the document
userSchema.pre('save', function () {
  console.log('Saving document:', this.email);
});

// Query middleware: 'this' = the Query object
userSchema.pre('find', function () {
  console.log('Running query:', this.getQuery());
});

Pre-save: Hashing Passwords

The pre-save hook is the most common document middleware. It runs before a document is saved to MongoDB. The canonical use case is hashing passwords: when a user document is saved with a new or modified password, hash it with bcrypt before storing. The this.isModified('password') check prevents re-hashing an already-hashed password on unrelated saves.

const bcrypt = require('bcrypt');

userSchema.pre('save', async function () {
  // 'this' is the User document being saved
  if (!this.isModified('password')) {
    return; // skip if password hasn't changed
  }
  const saltRounds = 12;
  this.password = await bcrypt.hash(this.password, saltRounds);
  // The hashed value replaces the plain password before MongoDB stores it
});

isNew and isModified Helpers

Document middleware has access to tracking helpers: this.isNew is true when the document is being inserted for the first time (not updated). this.isModified(path) returns true if the specified field has been changed since the document was last saved or fetched. These helpers let you run hooks conditionally—only on creation, or only when a specific field changes.

userSchema.pre('save', async function () {
  if (this.isNew) {
    // Only runs when creating a new user, not on updates
    this.verificationToken = crypto.randomBytes(32).toString('hex');
    this.verificationExpires = new Date(Date.now() + 24 * 60 * 60 * 1000);
  }

  if (this.isModified('email')) {
    // Only runs when the email field specifically changed
    this.emailVerified = false; // reset verification on email change
  }
});

Post-save: Side Effects After Saving

Post-save hooks run after a document is successfully persisted. They receive the saved document as the first argument and (in older Mongoose) a next callback. Post hooks are ideal for side effects that should happen after a successful save: sending a welcome email, updating a search index, publishing an event to a message queue, or clearing a cache. Errors in post hooks do not roll back the save.

userSchema.post('save', async function (doc) {
  // 'doc' is the saved document
  if (doc.isNew) {
    // Note: 'isNew' is false here (doc was just saved, so it's no longer new)
    // Track this with a flag set in pre-save:
  }
});

// Pattern: set a flag in pre-save, read it in post-save
userSchema.pre('save', function () {
  this._wasNew = this.isNew; // save state before it changes
});

userSchema.post('save', async function (doc) {
  if (doc._wasNew) {
    await sendWelcomeEmail(doc.email, doc.name);
    await analyticsTracker.track('user_created', { userId: doc._id });
  }
});

Query Middleware: Pre-find for Soft Deletes

A classic query middleware pattern is implementing soft deletes. Instead of removing documents, set a deletedAt field. Then add a pre('find') hook that automatically adds { deletedAt: null } to every find query, ensuring deleted documents are never returned by default. This provides an audit trail while making the soft-delete logic transparent to the rest of the application.

const postSchema = new mongoose.Schema({
  title: String,
  content: String,
  deletedAt: { type: Date, default: null }
});

// Automatically exclude soft-deleted documents from all find queries
postSchema.pre(/^find/, function () {
  // 'this' is the Query object
  this.where({ deletedAt: null });
  // /^find/ matches find, findOne, findOneAndUpdate, etc.
});

// Now Post.find({}) never returns deleted posts
// To explicitly query deleted posts, you'd call Post.find({}).bypassMiddleware() or use .lean() with the native driver

Query Middleware: Pre-find Automatic Population

You can use query middleware to automatically populate a reference field on every find. This ensures that a referenced document is always resolved without requiring callers to add .populate() to every query. While convenient, be careful—automatic population adds a second query for every find and can degrade performance if the reference is large or not always needed.

const reviewSchema = new mongoose.Schema({
  productId: { type: mongoose.Schema.Types.ObjectId, ref: 'Product' },
  userId: { type: mongoose.Schema.Types.ObjectId, ref: 'User' },
  rating: Number,
  comment: String
});

// Always populate author info on find
reviewSchema.pre(/^find/, function () {
  this.populate({
    path: 'userId',
    select: 'name avatar'
  });
});

// Now Review.find() always includes user name and avatar

Pre-deleteOne: Cascade Deletes

Mongoose does not enforce cascade deletes (deleting related documents when a parent is deleted) automatically. You can implement cascade behavior using document middleware. A pre-deleteOne hook on a User model can delete all posts, comments, and sessions belonging to that user before the user document itself is removed. This keeps referential integrity without foreign key constraints.

userSchema.pre('deleteOne', { document: true, query: false }, async function () {
  // 'this' is the User document being deleted
  const userId = this._id;

  // Cascade delete related documents
  await Promise.all([
    Post.deleteMany({ authorId: userId }),
    Comment.deleteMany({ userId: userId }),
    Session.deleteMany({ userId: userId }),
    Notification.deleteMany({ userId: userId })
  ]);

  console.log('Cascade deleted data for user:', userId);
});

// Trigger:
// const user = await User.findById(id);
// await user.deleteOne(); // triggers pre-deleteOne above

Middleware Error Handling

If a pre-hook function throws an error or rejects a Promise, the operation it precedes is aborted. This lets you perform validation or authorization checks in middleware and abort saves or queries by throwing. For example, a pre-save hook that validates business logic (not just schema validation) can throw an error that bubbles up to the .save() call's catch block in the application code.

orderSchema.pre('save', async function () {
  if (this.total <= 0) {
    throw new Error('Order total must be positive');
  }

  // Check inventory synchronously before saving the order
  const product = await Product.findById(this.productId).lean();
  if (!product || product.stock < this.quantity) {
    throw new Error('Insufficient inventory for this order');
  }
});

// In route handler:
try {
  const order = new Order({ productId, quantity, total });
  await order.save(); // throws if pre-save hook rejects
} catch (err) {
  res.status(400).json({ error: err.message });
}

Aggregate Middleware

Mongoose also supports middleware for aggregation pipelines. A pre-aggregate hook gives you access to the pipeline array before it is sent to MongoDB, allowing you to prepend stages (like filtering soft-deleted documents) or append stages (like injecting a default limit). Access the pipeline via this.pipeline() inside the hook function.

postSchema.pre('aggregate', function () {
  // 'this' is the Aggregate object
  // Add a $match stage at the beginning to exclude soft-deleted documents
  this.pipeline().unshift({
    $match: { deletedAt: null }
  });
});

// Now Post.aggregate([...]) automatically excludes deleted posts
// at the start of every aggregation pipeline

Middleware Pitfalls: Query Methods That Bypass Hooks

Not all write operations trigger document middleware. updateMany(), findOneAndUpdate(), replaceOne() called on the Model (not an instance) bypass document save hooks—they are query middleware and need separate hooks if you want to intercept them. For example, a pre-save password hashing hook does NOT run when you call User.updateOne({}, { $set: { password: plain } }). Always hash in the application code for query-based updates.

// WRONG: password NOT hashed — bypasses pre-save hook
await User.updateOne({ _id: userId }, { $set: { password: plainPassword } });

// RIGHT for query-level updates: hash before calling updateOne
const hashed = await bcrypt.hash(plainPassword, 12);
await User.updateOne({ _id: userId }, { $set: { password: hashed } });

// Or: fetch, modify, save — triggers pre-save hook
const user = await User.findById(userId);
user.password = plainPassword; // hook will hash it
await user.save();

Quick Check

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

Lesson Recap

In this lesson you learned: pre hooks run before an operation and can abort it by throwing an error; post hooks run after and receive the result as an argument, document middleware (pre-save, pre-deleteOne) uses 'this' as the document, while query middleware uses 'this' as the Query object, and query-level write methods (updateOne, updateMany, findOneAndUpdate) bypass document middleware — always be aware of which hooks fire for each operation type. This completes the MongoDB & NoSQL Databases course track!

Frequently asked questions

Is the “Mongoose Middleware: Pre and Post Hooks” lesson free?

Yes — the full text of “Mongoose Middleware: Pre and Post Hooks” is free to read here on the web, and the MongoDB Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MongoDB Academy course, upgrade to CoddyKit PRO.

What will I learn in “Mongoose Middleware: Pre and Post Hooks”?

Learners will write document and query middleware hooks for tasks like hashing passwords before save or logging after find. You practise MongoDB Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start MongoDB Academy?

No prior experience is required. MongoDB Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Mongoose Middleware: Pre and Post Hooks” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this MongoDB Academy lesson?

Yes. Every MongoDB Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Connecting With the Official Node.js Driver
  2. Mongoose Schemas, Models, and Virtuals
  3. Mongoose Queries, Chaining, and Lean Documents
  4. Mongoose Middleware: Pre and Post Hooks
← Back to MongoDB Academy