Managing Data Consistency with Mongoose Middleware

The Problem: Leaky Business Logic

When building an application with Mongoose, it is common to start by placing data transformation logic—like hashing passwords or normalizing email addresses—directly inside your controller functions. This approach quickly leads to "leaky logic," where the same normalization code is duplicated across every route that creates or updates a user. If you forget to call the normalization function in a new API endpoint, you end up with inconsistent data in your MongoDB collection.

The solution is to move this logic into Mongoose Middleware (also known as hooks). By defining pre and post hooks on your schema, you ensure that specific logic executes automatically every time a document is saved or validated, regardless of which controller triggered the action.

Pre-Save Hooks for Data Integrity

Pre-save middleware runs before Mongoose calls save() on the document. This is the ideal place for data mutations that must happen before the record hits the database. Common use cases include password hashing, slug generation, or trimming whitespace from strings.

In Mongoose (v6+), middleware functions can be async. When using async functions, you do not need to call next(); the middleware will proceed once the promise resolves. However, if you use standard functions, calling next() is mandatory to prevent the operation from hanging indefinitely.

Post-Save Hooks for Side Effects

Post-save middleware executes after the document has been successfully persisted to MongoDB. Unlike pre-save hooks, post-save hooks are not intended to modify the document (as it is already saved), but rather to trigger side effects. Examples include sending a welcome email, logging an audit trail, or updating a cache.

Worked Example: User Normalization and Hashing

The following example demonstrates a User schema that automatically lowercases emails and hashes passwords before saving. This assumes you have bcryptjs installed for hashing.

const mongoose = require('mongoose');
const bcrypt = require('bcryptjs');

const userSchema = new mongoose.Schema({
  email: { type: String, required: true, unique: true },
  password: { type: String, required: true },
  createdAt: { type: Date, default: Date.now }
});

// Pre-save hook: Normalization and Hashing
userSchema.pre('save', async function(next) {
  // Only hash the password if it has been modified (or is new)
  if (!this.isModified('password')) return next();

  try {
    // Normalize email to lowercase
    if (this.email) {
      this.email = this.email.toLowerCase();
    }

    // Hash password
    const salt = await bcrypt.genSalt(10);
    this.password = await bcrypt.hash(this.password, salt);
    next();
  } catch (err) {
    next(err); // Pass errors to the next middleware or controller
  }
});

// Post-save hook: Logging
userSchema.post('save', function(doc, next) {
  console.log(`User created with ID: ${doc._id}`);
  next();
});

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

Verification Steps

1. Run a Create Operation: Use new User({ email: 'TEST@Example.com', password: '123' }).save(). Check the database to confirm the email is test@example.com and the password is a hashed string.
2. Check Logs: Verify that the post('save') console log appears only after the database write is confirmed.

The Critical Limitation: Update Bypassing

A common engineering pitfall is assuming pre('save') runs on every update. It does not. Mongoose middleware for save is document-based. Methods that target the database directly—such as findByIdAndUpdate(), updateOne(), or updateMany()—bypass document middleware entirely.

Method	Triggers pre('save')?	Alternative
doc.save()	Yes	N/A
findByIdAndUpdate()	No	Use pre('findOneAndUpdate') query middleware
updateOne()	No	Use pre('updateOne') query middleware

To ensure validation and hooks run during updates, you must either:

• Fetch the document, modify it, and call .save().
• Implement specific query middleware using schema.pre('findOneAndUpdate', ...).

Closing Decision

Use Mongoose middleware when you have "invariant" rules—logic that must be true for every single document regardless of how it was created. However, avoid placing complex business logic (like payment processing or external API calls) in hooks, as this creates "hidden" side effects that make debugging difficult. Keep hooks focused on data integrity and simple notifications.