Middleware
Middleware (also called pre and post hooks) are functions which are passed control during execution of asynchronous functions. Middleware is specified on the schema level and is useful for writing plugins. Mongoose 4.0 has 2 types of middleware: document middleware and query middleware. Document middleware is supported for the following document functions.
Query middleware is supported for the following Model and Query functions.
Both document middleware and query middleware support pre and post hooks. How pre and post hooks work is described in more detail below.
Pre
There are two types of pre
hooks, serial and parallel.
Serial
Serial middleware are executed one after another, when each middleware calls next
.
var schema = new Schema(..);
schema.pre('save', function (next) {
// do stuff
next();
});
Parallel
Parallel middleware offer more fine-grained flow control.
var schema = new Schema(..);
schema.pre('save', true, function (next, done) {
// calling next kicks off the next middleware in parallel
next();
doAsync(done);
});
The hooked method, in this case save
, will not be executed until done
is called by each middleware.
Use Cases
Middleware are useful for atomizing model logic and avoiding nested blocks of async code. Here are some other ideas:
- complex validation
- removing dependent documents
- (removing a user removes all his blogposts)
- asynchronous defaults
- asynchronous tasks that a certain action triggers
- triggering custom events
- notifications
Error handling
If any middleware calls next
or done
with an error, the flow
is interrupted, and the error is passed to the callback.
schema.pre('save', function (next) {
var err = new Error('something went wrong');
next(err);
});
// later...
myDoc.save(function (err) {
console.log(err.message) // something went wrong
});
Post middleware
post middleware are executed after
the hooked method and all of its pre
middleware have completed.
post
middleware do not directly receive flow control, e.g. no next
or
done
callbacks are passed to it. post
hooks are a way to register
traditional event listeners for these methods.
schema.post('init', function (doc) {
console.log('%s has been initialized from the db', doc._id);
})
schema.post('validate', function (doc) {
console.log('%s has been validated (but not saved yet)', doc._id);
})
schema.post('save', function (doc) {
console.log('%s has been saved', doc._id);
})
schema.post('remove', function (doc) {
console.log('%s has been removed', doc._id);
})
Notes on findAndUpdate() and Query Middleware
Pre and post save()
hooks are not executed on update()
,
findOneAndUpdate()
, etc. You can see a more detailed discussion why in
this GitHub issue.
Mongoose 4.0 has distinct hooks for these functions.
schema.pre('update', function() {
this.start = Date.now();
});
schema.post('update', function() {
console.log('update() took ' + (Date.now() - this.start) + ' millis');
});
Next Up
Now that we've covered middleware, let's take a look at Mongoose's approach to faking JOINs with its query population helper.