hooks

Author: vdemedes

Readme.md

@@ -2,6 +2,14 @@
 
 ES6 generator-based MongoDB ODM for Node.js v0.11.x.
 
+## Features
+
+- Based on ES6 generators, which means **no callbacks**
+- Common, established API you've already used to
+- Hooks (before:save, around:create, after:remove, etc)
+- Very simple and easy-to-understand implementation
+- Fully covered by tests
+
 ## Installation
 
 ```
@@ -39,6 +47,8 @@ Mongorito.close(); // alias for disconnect
 
 #### Define a model
 
+That's right. No schema.
+
 ```javascript
 var Post = Model.extend({
     collection: 'posts'
@@ -112,6 +122,53 @@ Or you can remove multiple documents using:
 yield Post.remove({ title: 'Some title' }); // query
 ```
 
+### Hooks
+
+Mongorito models support *before*, *create* and *around* (*before* + *create*) hooks for these events:
+
+- save (executes on both create and update)
+- create
+- update
+- remove
+
+To setup a hook for some event:
+
+```javascript
+var Post = Model.extend({
+   collection: 'posts',
+   
+   customHandling: function *(next) {
+       // processing, validating, etc
+       
+       yield next; // MUST be present
+   }.before('save')
+});
+```
+
+Same goes for other hooks:
+
+```javascript
+myAfterCreateHook: function *(next) {
+    // executes after document was created
+    
+    yield next;
+}.after('create'),
+
+myAroundRemoveHook: function *(next) {
+    // executes before and after document was removed
+    
+    yield next;
+}.around('remove')
+```
+
+If you want to break the chain and prevent executing of the next hooks, just throw an **Error**:
+
+```javascript
+myHook: function *(next) {
+    throw new Error('Next hooks will not be executed');
+}.before('update')
+```
+
 ## Tests
 
 To execute tests run:

lib/mongorito.js

@@ -1,4 +1,5 @@
 var Class = require('backbone-class');
+var compose = require('koa-compose');
 var monk = require('monk');
 var wrap = require('co-monk');
 
@@ -31,12 +32,40 @@ var Mongorito = {
  * Model
  */
 
+Function.prototype.before = function (action) {
+	this.hook = {
+		when: 'before',
+		action: action
+	};
+	
+	return this;
+};
+
+Function.prototype.after = function (action) {
+	this.hook = {
+		when: 'after',
+		action: action
+	};
+	
+	return this;
+};
+
+Function.prototype.around = function (action) {
+	this.hook = {
+		when: 'around',
+		action: action
+	};
+	
+	return this;
+};
+
 var Model;
 
 var InstanceMethods = {
 	initialize: function (attrs) {
 		this.attributes = attrs || {};
 		this.collection = Mongorito.collection(this.collection);
+		this.configure();
 	},
 
 	get: function (key) {
@@ -61,40 +90,102 @@ var InstanceMethods = {
 		return this.attributes[key] = value;
 	},
 
+	configure: function () {
+		this.hooks = {
+			before: {
+				create: [],
+				update: [],
+				remove: [],
+				save: []
+			},
+			after: {
+				create: [],
+				update: [],
+				remove: [],
+				save: []
+			}
+		};
+		
+		for (var name in this) {
+			var fn = this[name];
+			
+			if (fn.hook) {
+				var action = fn.hook.action;
+				var when = fn.hook.when;
+				
+				delete fn.hook;
+				
+				switch (when) {
+					case 'before':
+					case 'after':
+						this.hooks[when][action].push(fn);
+						break;
+					
+					case 'around':
+						this.hooks['before'][action].push(fn);
+						this.hooks['after'][action].unshift(fn);
+						break;
+				}
+			}
+		}
+	},
+	
+	runHooks: function *(when, action) {
+		yield compose(this.hooks[when][action]).call(this);
+	},
+	
 	save: function *() {
 		var id = this.get('_id');
 		var fn = id ? this.update : this.create;
 
-		return yield fn.call(this);
+		yield this.runHooks('before', 'save');
+		
+		var result = yield fn.call(this);
+		
+		yield this.runHooks('after', 'save');
+		
+		return result;
 	},
 
 	create: function *() {
+		yield this.runHooks('before', 'create');
+		
 		var collection = this.collection;
 		var attrs = this.attributes;
 
 		var doc = yield collection.insert(attrs);
 
 		this.set('_id', doc._id);
 
+		yield this.runHooks('after', 'create');
+		
 		return this;
 	},
 
 	update: function *() {
+		yield this.runHooks('before', 'update');
+		
 		var collection = this.collection;
 		var attrs = this.attributes;
 
 		yield collection.updateById(attrs._id, attrs);
 
+		yield this.runHooks('after', 'update');
+		
 		return this;
 	},
 
 	remove: function *() {
+		yield this.runHooks('before', 'remove');
+		
 		var collection = this.collection;
 
 		yield collection.remove({
 			_id: this.get('_id')
 		});
 
+		yield this.runHooks('after', 'remove');
+		
 		return this;
 	}
 };

package.json

@@ -1,12 +1,13 @@
 {
   "name": "mongorito",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "ES6 generator-based MongoDB ODM. It rocks.",
   "author": "Vadim Demedes <vdemedes@gmail.com>",
   "dependencies": {
     "backbone-class": "0.0.1",
     "co": "^3.1.0",
     "co-monk": "^1.0.0",
+    "koa-compose": "^2.3.0",
     "monk": "^0.9.0"
   },
   "devDependencies": {
@@ -16,23 +17,23 @@
   },
   "main": "./index.js",
   "scripts": {
-	"test": "./node_modules/.bin/mocha --harmony"
+    "test": "./node_modules/.bin/mocha --harmony"
   },
   "repository": {
-	"type": "git",
-	"url": "https://github.com/vdemedes/mongorito"
+    "type": "git",
+    "url": "https://github.com/vdemedes/mongorito"
   },
   "bugs": {
     "url": "https://github.com/vdemedes/mongorito/issues"
   },
   "keywords": [
-	"mongo",
-	"mongodb",
-	"co-mongo",
-	"co-mongodb",
-	"orm",
-	"odm",
-	"es6"
+    "mongo",
+    "mongodb",
+    "co-mongo",
+    "co-mongodb",
+    "orm",
+    "odm",
+    "es6"
   ],
   "license": "MIT"
 }