Best practices for Mongoose

Mongoose Best Practices

Mongoose is one of the most popular MongoDB ODM (Object Document Mapping) libraries in Node.js, widely used especially in Koa2 projects. It provides powerful data modeling, validation, and querying capabilities, helping developers interact with MongoDB more efficiently. Below are some Mongoose best practices covering various aspects from model definition to query optimization.

Model Definition and Schema Design

When defining models, Schema design is crucial. A well-designed Schema not only improves query efficiency but also reduces data redundancy. Here’s an example of a user model:

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

const userSchema = new Schema({
  username: {
    type: String,
    required: true,
    unique: true,
    trim: true,
    minlength: 3,
    maxlength: 30
  },
  email: {
    type: String,
    required: true,
    unique: true,
    match: /^\S+@\S+\.\S+$/
  },
  password: {
    type: String,
    required: true,
    minlength: 6
  },
  role: {
    type: String,
    enum: ['user', 'admin'],
    default: 'user'
  },
  createdAt: {
    type: Date,
    default: Date.now
  },
  updatedAt: {
    type: Date,
    default: Date.now
  }
});

// Middleware to update the timestamp
userSchema.pre('save', function(next) {
  this.updatedAt = Date.now();
  next();
});

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

In this example, we’ve added uniqueness constraints for username and email and used a regular expression to validate the email format. The role field is restricted to predefined values using an enum, ensuring only valid roles can be assigned. The createdAt and updatedAt fields are used to track document creation and update times.

Using Middleware

Mongoose middleware (also known as hooks) allows inserting custom logic before or after certain operations. Common middleware includes pre and post hooks. Here’s an example of a password encryption middleware:

const bcrypt = require('bcryptjs');

userSchema.pre('save', async function(next) {
  if (!this.isModified('password')) return next();
  
  try {
    const salt = await bcrypt.genSalt(10);
    this.password = await bcrypt.hash(this.password, salt);
    next();
  } catch (err) {
    next(err);
  }
});

This middleware checks if the password has been modified before saving the user document. If modified, it encrypts the password using bcrypt, ensuring the password is always stored securely.

Query Optimization

Mongoose offers various query optimization techniques. Here are some common ones:

1. Use select to limit returned fields: Avoid returning unnecessary fields to reduce network traffic and memory usage.

   User.findById(userId).select('username email role');
   

2. Use lean for better performance: lean returns plain JavaScript objects instead of Mongoose documents, reducing memory usage and improving performance.

   User.find().lean();
   

3. Use indexes wisely: Adding indexes to frequently queried fields can significantly improve query speed.

   userSchema.index({ username: 1, email: 1 });
   

4. Batch operations: Using insertMany, updateMany, or bulkWrite is more efficient than single operations.

   User.insertMany([user1, user2, user3]);
   

Error Handling

Error handling in Mongoose is a critical part of development. Here’s a common error handling pattern:

app.use(async (ctx, next) => {
  try {
    await next();
  } catch (err) {
    if (err.name === 'ValidationError') {
      ctx.status = 400;
      ctx.body = { error: err.message };
    } else if (err.code === 11000) {
      ctx.status = 409;
      ctx.body = { error: 'Duplicate key error' };
    } else {
      ctx.status = 500;
      ctx.body = { error: 'Internal server error' };
    }
  }
});

In this example, we catch Mongoose validation errors and unique key conflicts, returning appropriate HTTP status codes and error messages. Other errors are handled with a generic 500 status code.

Transaction Support

MongoDB 4.0 and later support transactions, and Mongoose provides corresponding APIs. Here’s an example of a transaction:

const session = await mongoose.startSession();
session.startTransaction();

try {
  const user = await User.create([{ username: 'john', email: 'john@example.com' }], { session });
  await Profile.create([{ userId: user[0]._id, bio: 'Hello world' }], { session });
  await session.commitTransaction();
} catch (err) {
  await session.abortTransaction();
  throw err;
} finally {
  session.endSession();
}

Transactions ensure that multiple operations either all succeed or all fail, which is useful for maintaining data consistency.

Virtual Fields and Instance Methods

Virtual fields and instance methods can extend model functionality. Here’s an example:

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

userSchema.methods.comparePassword = async function(candidatePassword) {
  return await bcrypt.compare(candidatePassword, this.password);
};

The virtual field fullName is not stored in the database but can be accessed via user.fullName. The instance method comparePassword compares a user-input password with the encrypted password stored in the database.

Aggregation Pipeline

Mongoose supports MongoDB’s aggregation pipeline for complex data analysis and transformation. Here’s an example:

const result = await User.aggregate([
  { $match: { role: 'user' } },
  { $group: { _id: '$role', count: { $sum: 1 } } }
]);

This aggregation pipeline counts all documents where the role is user. The aggregation pipeline is highly flexible and can be used for complex data processing.

Performance Monitoring and Debugging

Mongoose provides debugging and performance monitoring features. Debug logs can be enabled as follows:

mongoose.set('debug', true);

Additionally, you can customize debug output using mongoose.set('debug', (collectionName, method, query, doc) => { ... }). This is helpful for performance tuning and troubleshooting.

Connection Management and Configuration

Proper connection management improves application stability and performance. Here’s a recommended connection configuration:

const options = {
  useNewUrlParser: true,
  useUnifiedTopology: true,
  poolSize: 10,
  connectTimeoutMS: 5000,
  socketTimeoutMS: 45000
};

mongoose.connect(process.env.MONGODB_URI, options)
  .then(() => console.log('MongoDB connected'))
  .catch(err => console.error('MongoDB connection error:', err));

In this configuration, we set parameters like connection pool size, connection timeout, and socket timeout. These can be adjusted based on actual needs.

Plugin System

Mongoose’s plugin system allows reusing common functionality. Here’s an example of a plugin that auto-generates a slug:

function slugPlugin(schema, options) {
  schema.add({ slug: String });
  
  schema.pre('save', function(next) {
    if (this.isModified('title')) {
      this.slug = this.title.toLowerCase().replace(/\s+/g, '-');
    }
    next();
  });
}

const articleSchema = new Schema({ title: String });
articleSchema.plugin(slugPlugin);

This plugin automatically generates a slug field based on the title field. Plugins can significantly reduce repetitive code and improve development efficiency.