added population to queries

Author: vdemedes

Readme.md

@@ -104,6 +104,51 @@ posts = yield Post.where('position').gt(5).find();
 posts = yield Post.gt('position', 5).find();
 ```
 
+#### Find and populate
+
+Let's say you have such Post document:
+```json
+{
+    "_id": ObjectId("5234d25244e937489c000004"),
+    "title": "Great title",
+    "body": "Great body",
+    "comments": [
+        ObjectId("5234d25244e937489c000005"),
+        ObjectId("5234d25244e937489c000006"),
+        ObjectId("5234d25244e937489c000007")
+    ]
+}
+```
+
+And you need to fetch each Comment document from *comments* field:
+
+```javascript
+var post = yield Post.findOne();
+var comments = post.get('comments');
+
+var index = 0;
+var commentId;
+
+while (commentId = comments[index]) {
+    comments[index] = yield Comment.findById(commentId);
+    
+    index++;
+}
+```
+
+With populating, you don't need to write all that and instead do this:
+
+```javascript
+// .populate() tells query to populate comments field
+// with documents fetched using Comment model
+var post = yield Post.populate('comments', Comment).findOne();
+var comments = post.get('comments');
+
+// comments is an array of Comment models now
+```
+
+**Note**: When you will try to save a document with populated fields, they will be reverted back to _id's.
+
 #### Find one
 
 Finds only one document. Returns either Model instance (Post, in these examples) or undefined.

lib/mongorito.js

@@ -66,8 +66,9 @@ Function.prototype.around = function (action) {
 var Model;
 
 var InstanceMethods = {
-	initialize: function (attrs) {
+	initialize: function (attrs, options) {
 		this.attributes = attrs || {};
+		this.options = options || {};
 		this.collection = Mongorito.collection(this.collection);
 		this.configure();
 	},
@@ -146,18 +147,30 @@ var InstanceMethods = {
 		var id = this.get('_id');
 		var fn = id ? this.update : this.create;
 
-		yield this.runHooks('before', 'save');
+		// revert populated documents to _id's
+		var populate = this.options.populate;
+		for (var key in populate) {
+			var value = this.get(key);
+			
+			if (value instanceof Array) {
+				value = value.map(function (doc) {
+					return doc.get('_id');
+				});
+			} else {
+				value = value.get('_id');
+			}
+			
+			this.set(key, value);
+		}
 
+		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;
 
@@ -167,8 +180,9 @@ var InstanceMethods = {
 			updated_at: timestamp
 		});
 
-		var doc = yield collection.insert(attrs);
+		yield this.runHooks('before', 'create');
 
+		var doc = yield collection.insert(attrs);
 		this.set('_id', doc._id);
 
 		yield this.runHooks('after', 'create');
@@ -177,30 +191,26 @@ var InstanceMethods = {
 	},
 
 	update: function *() {
-		yield this.runHooks('before', 'update');
-		
 		var collection = this.collection;
 		var attrs = this.attributes;
 
 		var timestamp = Math.round(new Date().getTime() / 1000);
 		this.set('updated_at', timestamp);
 
+		yield this.runHooks('before', 'update');
 		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 this.runHooks('before', 'remove');
 		yield collection.remove({
 			_id: this.get('_id')
 		});
-		
 		yield this.runHooks('after', 'remove');
 
 		return this;
@@ -266,7 +276,11 @@ var StaticMethods = {
 	}
 };
 
-['where', 'limit', 'skip', 'sort', 'exists', 'lt', 'lte', 'gt', 'gte', 'in', 'nin', 'and', 'or', 'ne', 'nor'].forEach(function (method) {
+[
+ 'where', 'limit', 'skip', 'sort', 'exists', 
+ 'lt', 'lte', 'gt', 'gte', 'in', 'nin',
+ 'and', 'or', 'ne', 'nor', 'populate'
+].forEach(function (method) {
 	StaticMethods[method] = function () {
 		var collection = this.collection();
 		var model = this;
@@ -291,7 +305,7 @@ var Query = Class.extend({
 		this.collection = collection;
 		this.model = model;
 		this.query = {};
-		this.options = {};
+		this.options = { populate: {} };
 		this.lastKey = key;
 	},
 
@@ -301,7 +315,7 @@ var Query = Class.extend({
 			for (key in conditions) {
 				this.where(key, conditions[key]);
 			}
-		} else {
+		} else if (typeof arguments[0] == 'string') {
 			if (!value) {
 				this.lastKey = key;
 				return this;
@@ -358,6 +372,12 @@ var Query = Class.extend({
 		return this;
 	},
 
+	populate: function (key, model) {
+		this.options.populate[key] = model;
+		
+		return this;
+	},
+	
 	count: function *(query) {
 		this.where(query);
 
@@ -374,12 +394,49 @@ var Query = Class.extend({
 
 		var collection = this.collection;
 		var model = this.model;
+		var options = this.options;
 
-		var docs = yield collection.find(this.query, this.options);
+		var docs = yield collection.find(this.query, options);
 
-		return docs.map(function (doc) {
-			return new model(doc);
-		});
+		var index = 0;
+		var doc;
+		
+		while (doc = docs[index++]) {
+			// options.populate is a key-model pair object
+			for (var key in options.populate) {
+				// model to use when populating the field
+				var model = options.populate[key];
+				
+				var value = doc[key];
+				
+				// if value is an array of IDs, loop through it
+				if (value instanceof Array) {
+					var subdocs = value.map(function (id) {
+						return model.findById(id.toString());
+					});
+					
+					value = yield subdocs;
+				} else {
+					value = yield model.findById(value);
+				}
+				
+				// replace previous ID with actual documents
+				doc[key] = value;
+			}
+			
+			// index - 1, because index here is already an index of the next document
+			docs[index - 1] = new model(doc, {
+				populate: options.populate
+			});
+		}
+		
+		return docs;
+	},
+	
+	findOne: function *(query) {
+		var docs = yield this.find(query);
+		
+		return docs[0];
 	},
 
 	remove: function *(query) {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mongorito",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "ES6 generator-based MongoDB ODM. It rocks.",
   "author": "Vadim Demedes <vdemedes@gmail.com>",
   "dependencies": {

test/mongorito.test.js

@@ -36,7 +36,7 @@ Function.prototype.isGenerator = function () {
 });
 
 describe ('Mongorito', function () {
-	var Post;
+	var Post, Comment;
 
 	before (function () {
 		Mongorito.connect('localhost/mongorito_test');
@@ -46,10 +46,15 @@ describe ('Mongorito', function () {
 		Post = Model.extend({
 			collection: 'posts'
 		});
+		
+		Comment = Model.extend({
+			collection: 'comments'
+		});
 	});
 
 	beforeEach (function *() {
 		yield Post.remove();
+		yield Comment.remove();
 	});
 
 	describe ('Model', function () {
@@ -361,6 +366,39 @@ describe ('Mongorito', function () {
 				var posts = yield Post.where('index').in([4, 5]).find();
 				posts.length.should.equal(2);
 			});
+			
+			it ('should populate the response', function *() {
+				var n = 3;
+				var comments = [];
+				
+				while (n--) {
+					var data = commentFixture();
+					var comment = new Comment(data);
+					yield comment.save();
+					
+					comments.push(comment);
+				}
+				
+				var data = postFixture({
+					comments: comments.map(function (comment) { return comment.get('_id'); })
+				});
+				var post = new Post(data);
+				yield post.save();
+				
+				var createdPost = yield Post.populate('comments', Comment).findOne();
+				createdPost.get('comments').forEach(function (comment, index) {
+					comment.get('_id').toString().should.equal(comments[index].get('_id').toString());
+				});
+				
+				// now confirm that populated documents
+				// don't get saved to database
+				yield createdPost.save();
+				
+				createdPost = yield Post.findOne();
+				createdPost.get('comments').forEach(function (id, index) {
+					id.toString().should.equal(comments[index].get('_id').toString());
+				});
+			});
 		});
 
 		describe ('Hooks', function () {