Implement include scopes

lib/include.js

@@ -3,6 +3,52 @@ var utils = require('./utils');
 var isPlainObject = utils.isPlainObject;
 var defineCachedRelations = utils.defineCachedRelations;
 
+/*!
+ * Normalize the include to be an array
+ * @param include
+ * @returns {*}
+ */
+function normalizeInclude(include) {
+  if (typeof include === 'string') {
+    return [include];
+  } else if (isPlainObject(include)) {
+    // Build an array of key/value pairs
+    var newInclude = [];
+    if (typeof include.relation === 'string' && isPlainObject(include.scope)) {
+      var obj = {};
+      obj[include.relation] = new IncludeScope(include.scope);
+      newInclude.push(obj);
+    } else {
+      for (var key in include) {
+        var obj = {};
+        obj[key] = include[key];
+        newInclude.push(obj);
+      }
+    }
+    return newInclude;
+  } else {
+    return include;
+  }
+}
+
+function IncludeScope(scope) {
+  this._scope = utils.deepMerge({}, scope || {});
+  if (this._scope.include) {
+    this._include = normalizeInclude(this._scope.include);
+    delete this._scope.include;
+  } else {
+    this._include = null;
+  }
+};
+
+IncludeScope.prototype.conditions = function() {
+  return utils.deepMerge({}, this._scope);
+};
+
+IncludeScope.prototype.include = function() {
+  return this._include;
+};
+
 /*!
  * Include mixin for ./model.js
  */
@@ -59,36 +105,19 @@ Inclusion.include = function (objects, include, cb) {
     cb && cb(err, objects);
   });
 
-
-  /*!
-   * Normalize the include to be an array
-   * @param include
-   * @returns {*}
-   */
-  function normalizeInclude(include) {
-    if (typeof include === 'string') {
-      return [include];
-    } else if (isPlainObject(include)) {
-      // Build an array of key/value pairs
-      var newInclude = [];
-      for (var key in include) {
-        var obj = {};
-        obj[key] = include[key];
-        newInclude.push(obj);
-      }
-      return newInclude;
-    } else {
-      return include;
-    }
-  }
-
   function processIncludeItem(objs, include, cb) {
     var relations = self.relations;
 
-    var relationName, subInclude;
+    var relationName;
+    var subInclude = null, scope = null;
     if (isPlainObject(include)) {
       relationName = Object.keys(include)[0];
+      if (include[relationName] instanceof IncludeScope) {
+        scope = include[relationName];
+        subInclude = scope.include();
+      } else {
         subInclude = include[relationName];
+      }
     } else {
       relationName = include;
       subInclude = null;
@@ -126,7 +155,31 @@ Inclusion.include = function (objects, include, cb) {
       
       var inst = (obj instanceof self) ? obj : new self(obj);
       // Calling the relation method on the instance
-      inst[relationName](function (err, result) {
+      
+      var related; // relation accessor function
+      
+      if (relation.multiple && scope) {
+        var includeScope = {};
+        var filter = scope.conditions();
+        
+        // make sure not to miss any fields for sub includes
+        if (filter.fields && Array.isArray(subInclude) && relation.modelTo.relations) {
+          includeScope.fields = [];
+          subInclude.forEach(function(name) {
+            var rel = relation.modelTo.relations[name];
+            if (rel && rel.type === 'belongsTo') {
+              includeScope.fields.push(rel.keyFrom);
+            }
+          });
+        }
+        
+        utils.mergeQuery(filter, includeScope, {fields: false});
+        related = inst[relationName].bind(inst, filter);
+      } else {
+        related = inst[relationName].bind(inst);
+      }
+      
+      related(function (err, result) {
         if (err) {
           return callback(err);
         } else {

lib/utils.js

@@ -3,7 +3,7 @@ exports.fieldsToArray = fieldsToArray;
 exports.selectFields = selectFields;
 exports.removeUndefined = removeUndefined;
 exports.parseSettings = parseSettings;
-exports.mergeSettings = mergeSettings;
+exports.mergeSettings = exports.deepMerge = mergeSettings;
 exports.isPlainObject = isPlainObject;
 exports.defineCachedRelations = defineCachedRelations;
 exports.sortObjectsByIds = sortObjectsByIds;
@@ -93,6 +93,8 @@ function mergeQuery(base, update, spec) {
   // Overwrite fields
   if (spec.fields !== false && update.fields !== undefined) {
     base.fields = update.fields;
+  } else if (update.fields !== undefined) {
+    base.fields = [].concat(base.fields).concat(update.fields);
   }
   
   // set order

test/include.test.js

@@ -97,6 +97,7 @@ describe('include', function () {
           user.id.should.equal(p.ownerId);
           user.__cachedRelations.should.have.property('posts');
           user.__cachedRelations.posts.forEach(function (pp) {
+            pp.should.have.property('id');
             pp.userId.should.equal(user.id);
             pp.should.have.property('author');
             pp.__cachedRelations.should.have.property('author');
@@ -109,6 +110,41 @@ describe('include', function () {
     });
   });
   
+  it('should fetch Passports with include scope on Posts', function (done) {
+    Passport.find({
+      include: {owner: {relation: 'posts', scope:{
+        fields: ['title'], include: ['author'],
+        order: 'title DESC'
+      }}}
+    }, function (err, passports) {
+      should.not.exist(err);
+      should.exist(passports);
+      passports.length.should.equal(3);
+      
+      var passport = passports[0];
+      passport.number.should.equal('1');
+      passport.owner().name.should.equal('User A');
+      var owner = passport.owner().toObject();
+      
+      var posts = passport.owner().posts();
+      posts.should.be.an.array;
+      posts.should.have.length(3);
+      
+      posts[0].title.should.equal('Post C');
+      posts[0].should.not.have.property('id'); // omitted
+      posts[0].author().should.be.instanceOf(User);
+      posts[0].author().name.should.equal('User A');
+      
+      posts[1].title.should.equal('Post B');
+      posts[1].author().name.should.equal('User A');
+      
+      posts[2].title.should.equal('Post A');
+      posts[2].author().name.should.equal('User A');
+      
+      done();
+    });
+  });
+
   it('should fetch User - Posts AND Passports', function (done) {
     User.find({include: ['posts', 'passports']}, function (err, users) {
       should.not.exist(err);