Mongoose with MongoDB

This chapter follows Schema design in MongoDB. Use Mongoose when you want declarative validation, hooks, and populate in exchange for another abstraction layer. Use the native driver when you want minimal overhead, aggregation-heavy pipelines, or tight control over BSON types.

1
pnpm add mongoose

This chapter assumes Mongoose 9.11.x with the mongodb driver 7.x it bundles.

Schemas and TypeScript inference

A schema defines paths, defaults, and validators. Infer document types from the schema:

1
import { Schema, model, InferSchemaType, HydratedDocument } from 'mongoose';
2

3
const kittenSchema = new Schema(
4
  {
5
    name: { type: String, required: true, trim: true },
6
    age: { type: Number, min: 0 },
7
  },
8
  { timestamps: true },
9
);
10

11
kittenSchema.methods.speak = function speak(this: HydratedDocument<KittenDoc>) {
12
  return this.name ? `Meow, I am ${this.name}` : 'I have no name';
13
};
14

15
type KittenDoc = InferSchemaType<typeof kittenSchema>;
16
export const Kitten = model('Kitten', kittenSchema);

timestamps: true adds createdAt and updatedAt automatically.

Models and documents

The model is the constructor and query entry point; a document is one persisted instance with .save() and instance methods.

1
const doc = new Kitten({ name: 'Milo', age: 2 });
2
await doc.save();
3
console.log(doc.speak());
4

5
const found = await Kitten.findOne({ name: 'Milo' }).exec();

Validation

Validators run on save() and on most update helpers when { runValidators: true }:

1
kittenSchema.path('age').validate((v: number) => v >= 0, 'Age must be non-negative');

Driver-level $jsonSchema (previous chapter) still applies if you enable it on the collection; Mongoose adds application-side checks before BSON hits the wire.

Middleware

Pre and post hooks run around lifecycle events:

1
kittenSchema.pre('save', function () {
2
  if (this.isModified('name')) {
3
    this.set('name', this.name.trim());
4
  }
5
});

Query middleware runs when you await a Query—for example findOneAndUpdate.

Virtuals

Virtuals are computed properties not stored in MongoDB:

1
kittenSchema.virtual('info').get(function () {
2
  return `${this.name} is ${this.age ?? '?'} years old`;
3
});

Enable virtuals in JSON output when needed: schema.set('toJSON', { virtuals: true }).

Populate

Replace stored ObjectId refs with documents from another collection:

1
const storySchema = new Schema({
2
  title: String,
3
  author: { type: Schema.Types.ObjectId, ref: 'Person' },
4
});
5
export const Story = model('Story', storySchema);
6

7
const story = await Story.findOne({ title: 'Casino Royale' }).populate('author').exec();

Populate is convenient but issues extra queries—sometimes $lookup in aggregation or embedding (see schema design) is faster.

lean()

.lean() returns plain objects instead of Mongoose documents—less overhead for read-only API responses:

1
const rows = await Kitten.find({ age: { $gte: 1 } }).lean().exec();

Aggregations always return POJOs; they are never hydrated documents.

Connect with Mongoose

1
import mongoose from 'mongoose';
2

3
export async function connectMongoose(uri = process.env.MONGODB_URI) {
4
  if (!uri) throw new Error('MONGODB_URI is not set');
5
  await mongoose.connect(uri);
6
}

One Mongoose connection wraps the driver pool; do not open a second native client to the same cluster without reason.

Next: Indexes and query performance in MongoDB.