Mongoose Patterns

Mongoose Patterns - MongoDB ODM Best Practices

Purpose

Expert guidance for Mongoose/MongoDB:

• Schema Design - Proper typing and validation
• Queries - Efficient query patterns
• Indexes - Performance optimization
• Aggregations - Complex data operations
• Relationships - References vs embedding

Project Structure

server/
├── db/
│   ├── connection.ts      # MongoDB connection
│   └── index.ts           # Export db utilities
├── models/
│   ├── user.model.ts
│   ├── post.model.ts
│   └── index.ts           # Export all models
types/
└── models/
    ├── user.types.ts      # User interfaces
    └── post.types.ts      # Post interfaces

Schema Design

Basic Schema with TypeScript

// types/models/user.types.ts
import { Types, Document } from 'mongoose';

export interface IUser {
	email: string;
	name: string;
	passwordHash: string;
	role: 'admin' | 'user' | 'guest';
	profile?: {
		bio?: string;
		avatar?: string;
	};
	createdAt: Date;
	updatedAt: Date;
}

export interface IUserDocument extends IUser, Document {
	_id: Types.ObjectId;
	comparePassword(password: string): Promise<boolean>;
	toPublic(): Omit<IUser, 'passwordHash'>;
}

// server/models/user.model.ts
import mongoose, { Schema, Model } from 'mongoose';
import { IUser, IUserDocument } from '$types/models/user.types';

const userSchema = new Schema<IUserDocument>(
	{
		email: {
			type: String,
			required: [true, 'Email is required'],
			unique: true,
			lowercase: true,
			trim: true,
			validate: {
				validator: (v: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v),
				message: 'Invalid email format',
			},
		},
		name: {
			type: String,
			required: [true, 'Name is required'],
			minlength: [2, 'Name must be at least 2 characters'],
			maxlength: [100, 'Name cannot exceed 100 characters'],
			trim: true,
		},
		passwordHash: {
			type: String,
			required: true,
			select: false, // Never include by default
		},
		role: {
			type: String,
			enum: ['admin', 'user', 'guest'],
			default: 'user',
		},
		profile: {
			bio: { type: String, maxlength: 500 },
			avatar: { type: String },
		},
	},
	{
		timestamps: true,
		toJSON: { virtuals: true },
		toObject: { virtuals: true },
	}
);

// Indexes
userSchema.index({ email: 1 }, { unique: true });
userSchema.index({ role: 1 });
userSchema.index({ createdAt: -1 });

// Instance methods
userSchema.methods.comparePassword = async function (password: string): Promise<boolean> {
	return Bun.password.verify(password, this.passwordHash);
};

userSchema.methods.toPublic = function () {
	const obj = this.toObject();
	delete obj.passwordHash;
	return obj;
};

// Static methods
userSchema.statics.findByEmail = function (email: string) {
	return this.findOne({ email: email.toLowerCase() });
};

export const UserModel: Model<IUserDocument> = mongoose.model('User', userSchema);

Connection Management

// server/db/connection.ts
import mongoose from 'mongoose';
import { logger } from '@common';

const MONGODB_URI = process.env['MONGODB_URI']!;

if (!MONGODB_URI) {
	throw new Error('MONGODB_URI environment variable not set');
}

let isConnected = false;

export async function connectDB(): Promise<void> {
	if (isConnected) {
		logger.info('Using existing MongoDB connection');
		return;
	}

	try {
		await mongoose.connect(MONGODB_URI, {
			maxPoolSize: 10,
			serverSelectionTimeoutMS: 5000,
			socketTimeoutMS: 45000,
		});

		isConnected = true;
		logger.info('Connected to MongoDB');
	} catch (error) {
		logger.error('MongoDB connection error:', error);
		throw error;
	}
}

export async function disconnectDB(): Promise<void> {
	if (!isConnected) return;

	await mongoose.disconnect();
	isConnected = false;
	logger.info('Disconnected from MongoDB');
}

// Graceful shutdown
process.on('SIGINT', async () => {
	await disconnectDB();
	process.exit(0);
});

Query Patterns

Find with Typing

// Find one
const user = await UserModel.findById(id);
const userByEmail = await UserModel.findOne({ email });

// Find with projection
const users = await UserModel.find({ role: 'user' }).select('name email role').lean(); // Returns plain objects (faster)

// Find with pagination
const page = 1;
const limit = 20;
const users = await UserModel.find()
	.sort({ createdAt: -1 })
	.skip((page - 1) * limit)
	.limit(limit)
	.lean();

// Count
const total = await UserModel.countDocuments({ role: 'user' });

Update Patterns

// Update one (returns updated doc)
const updated = await UserModel.findByIdAndUpdate(
	id,
	{ $set: { name: 'New Name' } },
	{ new: true, runValidators: true }
);

// Update many
const result = await UserModel.updateMany({ role: 'guest' }, { $set: { role: 'user' } });
console.log(`Updated ${result.modifiedCount} documents`);

// Upsert
const user = await UserModel.findOneAndUpdate(
	{ email },
	{ $setOnInsert: { createdAt: new Date() }, $set: { lastLogin: new Date() } },
	{ upsert: true, new: true }
);

Delete Patterns

// Delete one
await UserModel.findByIdAndDelete(id);

// Delete many
const result = await UserModel.deleteMany({ role: 'guest' });
console.log(`Deleted ${result.deletedCount} documents`);

// Soft delete pattern
const softDeleteSchema = new Schema({
	deletedAt: { type: Date, default: null },
});

// Query middleware to exclude soft-deleted
userSchema.pre('find', function () {
	this.where({ deletedAt: null });
});

Aggregation Pipeline

// Complex aggregation
const stats = await UserModel.aggregate([
	// Match stage
	{ $match: { createdAt: { $gte: startDate } } },

	// Group stage
	{
		$group: {
			_id: '$role',
			count: { $sum: 1 },
			avgAge: { $avg: '$age' },
		},
	},

	// Sort stage
	{ $sort: { count: -1 } },

	// Project stage
	{
		$project: {
			role: '$_id',
			count: 1,
			avgAge: { $round: ['$avgAge', 1] },
			_id: 0,
		},
	},
]);

// Lookup (join)
const postsWithAuthors = await PostModel.aggregate([
	{
		$lookup: {
			from: 'users',
			localField: 'authorId',
			foreignField: '_id',
			as: 'author',
		},
	},
	{ $unwind: '$author' },
	{
		$project: {
			title: 1,
			content: 1,
			'author.name': 1,
			'author.email': 1,
		},
	},
]);

Indexes

Index Types

// Single field
userSchema.index({ email: 1 }); // Ascending
userSchema.index({ createdAt: -1 }); // Descending

// Compound index
userSchema.index({ role: 1, createdAt: -1 });

// Unique index
userSchema.index({ email: 1 }, { unique: true });

// Sparse index (only index docs with field)
userSchema.index({ nickname: 1 }, { sparse: true });

// TTL index (auto-delete after time)
sessionSchema.index({ expiresAt: 1 }, { expireAfterSeconds: 0 });

// Text index (full-text search)
postSchema.index({ title: 'text', content: 'text' });

// Partial index
userSchema.index(
	{ email: 1 },
	{
		partialFilterExpression: { isActive: true },
	}
);

Check Indexes

# List indexes
db.users.getIndexes()

# Explain query
db.users.find({ email: "test@test.com" }).explain("executionStats")

Relationships

Reference (Normalized)

// Post references User
const postSchema = new Schema({
	title: String,
	authorId: {
		type: Schema.Types.ObjectId,
		ref: 'User',
		required: true,
		index: true,
	},
});

// Populate
const post = await PostModel.findById(id).populate('authorId', 'name email');

// Virtual populate
userSchema.virtual('posts', {
	ref: 'Post',
	localField: '_id',
	foreignField: 'authorId',
});

const user = await UserModel.findById(id).populate('posts');

Embedded (Denormalized)

// Comments embedded in Post
const postSchema = new Schema({
	title: String,
	comments: [
		{
			author: String,
			content: String,
			createdAt: { type: Date, default: Date.now },
		},
	],
});

// Add comment
await PostModel.findByIdAndUpdate(id, {
	$push: { comments: { author: 'John', content: 'Great post!' } },
});

Middleware (Hooks)

// Pre-save hook
userSchema.pre('save', async function (next) {
	if (this.isModified('passwordHash')) {
		this.passwordHash = await Bun.password.hash(this.passwordHash);
	}
	next();
});

// Post-save hook
userSchema.post('save', function (doc) {
	logger.info(`User saved: ${doc.email}`);
});

// Pre-find hook
userSchema.pre('find', function () {
	// Always exclude deleted documents
	this.where({ deletedAt: null });
});

// Error handling hook
userSchema.post('save', function (error: Error, doc: IUserDocument, next: () => void) {
	if (error.name === 'MongoServerError' && (error as any).code === 11000) {
		next(new Error('Email already exists'));
	} else {
		next();
	}
});

Transactions

import mongoose from 'mongoose';

async function transferCredits(fromId: string, toId: string, amount: number) {
	const session = await mongoose.startSession();

	try {
		session.startTransaction();

		await UserModel.findByIdAndUpdate(fromId, { $inc: { credits: -amount } }, { session });

		await UserModel.findByIdAndUpdate(toId, { $inc: { credits: amount } }, { session });

		await session.commitTransaction();
	} catch (error) {
		await session.abortTransaction();
		throw error;
	} finally {
		session.endSession();
	}
}

Agent Integration

This skill is used by:

• mongoose-schema-designer agent
• mongoose-index-optimizer agent
• mongoose-aggregation agent
• mongodb-query-optimizer agent
• database-seeder agent

FORBIDDEN

1. User ID from input - Always use session/context
2. No indexes on query fields - Always index filtered fields
3. Returning passwordHash - Use select: false
4. N+1 queries - Use .populate() or aggregation
5. Unbounded queries - Always use .limit()

Version

• v1.0.0 - Initial implementation based on Mongoose 8.x patterns