From 686106d544ecc3b6ffd4db2b665d3bc879a58d8c Mon Sep 17 00:00:00 2001
From: Jules Laplace <jules@okfoc.us>
Date: Mon, 24 Sep 2012 16:22:07 -0400
Subject: ok

---
 node_modules/mongoose/docs/middleware.md | 61 ++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 node_modules/mongoose/docs/middleware.md

(limited to 'node_modules/mongoose/docs/middleware.md')

diff --git a/node_modules/mongoose/docs/middleware.md b/node_modules/mongoose/docs/middleware.md
new file mode 100644
index 0000000..947006d
--- /dev/null
+++ b/node_modules/mongoose/docs/middleware.md
@@ -0,0 +1,61 @@
+
+Middleware
+==========
+
+Middleware are defined at the Schema level and are applied when the methods
+`init` (when a document is initialized with data from MongoDB), `save`, and
+`remove` are called on a document instance.
+
+There are two types of middleware, serial and parallel.
+
+Serial middleware are defined like:
+
+    schema.pre('save', function (next) {
+      // ...
+    })
+
+They're executed one after the other, when each middleware calls `next`.
+
+Parallel middleware offer more fine-grained flow control, and are defined
+like
+
+    schema.pre('remove', true, function (next, done) {
+      // ...
+    })
+
+Parallel middleware can `next()` immediately, but the final argument will be
+called when all the parallel middleware have called `done()`.
+
+## Use cases
+
+Middleware are useful for:
+
+- Complex validation
+- Removing dependent documents when a certain document is removed (eg:
+removing a user removes all his blogposts)
+- Asynchronous defaults
+- Asynchronous tasks that a certain action triggers. For example:
+  - Triggering custom events
+  - Creating notifications
+  - Emails
+
+and many other things. They're specially useful for atomizing model logic
+and avoiding nested blocks of async code.
+
+## Error handling
+
+If any middleware calls `next` or `done` with an `Error` instance, the flow is
+interrupted, and the error is passed to the callback.
+
+For example:
+
+    schema.pre('save', function (next) {
+        // something goes wrong
+        next(new Error('something went wrong'));
+    });
+
+    // later...
+
+    myModel.save(function (err) {
+      // err can come from a middleware
+    });
-- 
cgit v1.2.3-70-g09d2