Merge pull request #75 from digitalsadhu/feature/request-includes

Feature/request includes

Author: digitalsadhu

README.md

@@ -12,9 +12,8 @@ JSONAPI support for loopback.
 [http://jsonapi.org/](http://jsonapi.org/)
 
 ## Status
-This project is a work in progress. Consider it beta software. For ember users, this should be
-basically working except for side loading which should be coming pretty soon.
-The functionality that is present is pretty well tested. 100 integration tests and counting!
+This project is a work in progress. Consider it beta software. For ember users, this should be basically.
+The functionality that is present is pretty well tested. 100+ integration tests and counting!
 
 Currently supported:
 - Find all records via GET
@@ -27,15 +26,16 @@ Currently supported:
 - Find relationships via GET eg. /posts/1/relationships/author (belongsTo, hasMany, hasOne)
 - Creating resource relationship linkages during a resource create
 - Updating/deleting resource relationship linkages during a resource update
+- [Side loading data](http://jsonapi.org/format/#fetching-includes) via `include` param 
 
 Not yet properly supported:
-- Side loading data is in the works but is not yet supported
 - manipulating relationships directly via:
   - POST /:resource/relationships/:relatedResource
   - PATCH /:resource/relationships/:relatedResource
   - DELETE /:resource/relationships/:relatedResource
 
 ## Requirements
+- JSON API v1.0
 - loopback ^v2.0.0
 - strong-remoting ^v2.22.0
 

lib/deserialize.js

@@ -1,6 +1,6 @@
-'use strict';
+/* global require,module */
 var deserializer = require('./deserializer');
-
+var RelUtils = require('./utilities/relationship-utils');
 var utils = require('./utils');
 
 module.exports = function (app) {
@@ -49,6 +49,31 @@ module.exports = function (app) {
       //TODO: Rewrite to normal search model by type and FK
     }
 
+    /**
+     * Handle include relationship requests (aka sideloading)
+     */
+    if (RelUtils.isRequestingIncludes(ctx)) {
+      ctx.res.set({'Content-Type': 'application/vnd.api+json'});
+
+      ctx.req.isSideloadingRelationships = true;
+
+      if (RelUtils.isLoopbackInclude(ctx)) {
+        return next();
+      }
+
+      if (!RelUtils.shouldIncludeRelationships(ctx.req.method)) {
+        return next(RelUtils.getInvalidIncludesError());
+      }
+
+      var include = RelUtils.getIncludesArray(ctx.req.query);
+      include = include.length === 1 ? include[0] : include;
+
+      ctx.args = ctx.args || {};
+      ctx.args.filter = ctx.args.filter || {};
+      ctx.args.filter.include = include;
+
+    }
+
     next();
   });
 };

lib/errors.js

@@ -60,8 +60,16 @@ function JSONAPIErrorHandler (err, req, res, next) {
       err.code = 'presence';
       err.name = 'ValidationError';
     }
-    errors.push(buildErrorResponse(statusCode, err.message, err.code, err.name));
 
+    debug('Handling invalid relationship specified in url');
+    if (/Relation (.*) is not defined for (.*) model/.test(err.message)) {
+      statusCode = 400;
+      err.message = 'Bad Request';
+      err.code = 'INVALID_INCLUDE_TARGET';
+      err.name = 'BadRequest';
+    }
+
+    errors.push(buildErrorResponse(statusCode, err.message, err.code, err.name));
   } else {
     debug('Unable to determin error type. Treating error as a general 500 server error.');
     //catch all server 500 error if we were unable to understand the error.

lib/serialize.js

@@ -1,5 +1,4 @@
-'use strict';
-
+/* global module,require */
 var serializer = require('./serializer');
 var utils = require('./utils');
 var _ = require('lodash');
@@ -24,7 +23,8 @@ module.exports = function (app, defaults) {
       relatedModelPlural,
       relations,
       res,
-      model;
+      model,
+      requestedIncludes;
 
     var matches = regexs.filter(function (regex) {
       return ctx.methodString.match(regex);
@@ -77,8 +77,13 @@ module.exports = function (app, defaults) {
       }
     }
 
+    // If we're sideloading, we need to add the includes
+    if (ctx.req.isSideloadingRelationships) {
+      requestedIncludes = ctx.req.remotingContext.args.filter.include;
+    }
     options = {
       primaryKeyField: primaryKeyField,
+      requestedIncludes: requestedIncludes,
       host: utils.hostFromContext(ctx),
       topLevelLinks: {
         self: utils.urlFromContext(ctx)
@@ -104,7 +109,11 @@ module.exports = function (app, defaults) {
     relations = utils.getRelationsFromContext(ctx, app);
 
     // Serialize our request
-    res = serializer(type, data, relations, options);
+    try {
+      res = serializer(type, data, relations, options);
+    } catch (e) {
+      next(e);
+    }
 
     ctx.result = res;
 

lib/serializer.js

@@ -1,4 +1,5 @@
 var _ = require('lodash');
+var RelUtils = require('./utilities/relationship-utils');
 var utils = require('./utils');
 
 module.exports = function serializer (type, data, relations, options) {
@@ -25,6 +26,13 @@ module.exports = function serializer (type, data, relations, options) {
     resultData.links = makeLinks(options.topLevelLinks);
   }
 
+  /**
+   * If we're requesting to sideload relationships...
+   */
+  if (options.requestedIncludes) {
+    handleIncludes(resultData, options.requestedIncludes, relations);
+  }
+
   return resultData;
 };
 
@@ -231,3 +239,101 @@ function makeLinks (links, item) {
 
   return retLinks;
 }
+
+/**
+ * Handles serializing the requested includes to a seperate included property
+ * per JSON API spec.
+ * @private
+ * @memberOf {Serializer}
+ * @param {Object} resp
+ * @param {Array<String>|String}
+ * @throws {Error}
+ * @return {undefined}
+ */
+function handleIncludes (resp, includes, relations) {
+  var resources = _.isArray(resp.data) ? resp.data : [resp.data];
+
+  if (typeof includes === 'string') {
+    includes = [ includes ];
+  }
+
+  if (!_.isArray(includes)) {
+    throw RelUtils.getInvalidIncludesError('JSON API unable to detect valid includes');
+  }
+
+  var embedded = resources.map(function subsituteEmbeddedForIds (resource) {
+    return includes.map(function (include) {
+      var relation = relations[include];
+      var propertyKey = relation.keyFrom;
+      var plural = utils.pluralForModel(relation.modelTo);
+      var embeds = [];
+
+      // If relation is belongsTo then pk and fk are the other way around
+      if (relation.type === 'belongsTo' || relation.type === 'referencesMany') {
+        propertyKey = relation.keyTo;
+      }
+
+      if (!relation) {
+        throw RelUtils.getInvalidIncludesError('Can\'t locate relationship "' + include + '" to include');
+      }
+
+      resource.relationships[include] = resource.relationships[include] || {};
+
+      if (resource.relationships[include] && resource.attributes[include]) {
+        if (_.isArray(resource.attributes[include])) {
+          embeds = resource.attributes[include].map(function (rel) {
+            rel = utils.clone(rel);
+            return createCompoundIncludes(rel, propertyKey, relation.keyTo, plural);
+          });
+          embeds = _.compact(embeds);
+
+          resource.relationships[include].data = resource.attributes[include].map(function (relData) {
+            return {
+              id: String(relData[propertyKey]),
+              type: plural
+            };
+          });
+        } else {
+          var rel = utils.clone(resource.attributes[include]);
+          var compoundIncludes = createCompoundIncludes(rel, propertyKey, relation.keyFrom, plural);
+
+          resource.relationships[include].data = {
+            id: String(resource.attributes[include][propertyKey]),
+            type: plural
+          };
+          embeds.push(compoundIncludes);
+        }
+        delete resource.attributes[relation.keyFrom];
+        delete resource.attributes[relation.keyTo];
+        delete resource.attributes[include];
+      }
+      return embeds;
+    });
+  });
+
+  if (embedded.length) {
+    resp.included = _.flattenDeep(embedded);
+  }
+}
+
+/**
+ * Creates a compound include object.
+ * @private
+ * @memberOf {Serializer}
+ * @param {Object} relationship
+ * @param {String} key
+ * @param {String} type
+ * @return {Object}
+ */
+function createCompoundIncludes (relationship, key, fk, type) {
+  var compoundInclude = makeRelation(type, String(relationship[key]));
+
+  // remove the id key since its part of the base compound document, not part of attributes
+  delete relationship[key];
+  delete relationship[fk];
+
+  // The rest of the data goes in the attributes
+  compoundInclude.attributes = relationship;
+
+  return compoundInclude;
+}

lib/utilities/relationship-utils.js

@@ -0,0 +1,70 @@
+var _ = require('lodash');
+
+/* global module */
+module.exports = {
+  getIncludesArray: getIncludesArray,
+  getInvalidIncludesError: getInvalidIncludesError,
+  isRequestingIncludes: isRequestingIncludes,
+  shouldIncludeRelationships: shouldIncludeRelationships,
+  isLoopbackInclude: isLoopbackInclude
+};
+
+/**
+ * Get the invalid includes error.
+ * @public
+ * @memberOf {RelationshipUtils}
+ * @param {String} message
+ * @return {Error}
+ */
+function getInvalidIncludesError (message) {
+  var error = new Error(message || 'JSON API resource does not support `include`');
+  error.statusCode = 400;
+  error.code = 400;
+  error.status = 400;
+
+  return error;
+}
+
+function isLoopbackInclude (ctx) {
+  return ctx.args && ctx.args.filter;
+}
+
+function isJSONAPIInclude (req) {
+  return _.isPlainObject(req.query) && req.query.hasOwnProperty('include') && req.query.include.length > 0;
+}
+
+/**
+ * Is the user requesting to sideload relationships?>
+ * @public
+ * @MemberOf {RelationshipUtils}
+ * @return {Boolean}
+ */
+function isRequestingIncludes (ctx) {
+  return isLoopbackInclude(ctx) || isJSONAPIInclude(ctx.req);
+}
+
+/**
+ * Returns an array of relationships to include. Per JSON specification, they will
+ * be in a comma-separated pattern.
+ * @public
+ * @memberOf {RelationshipUtils}
+ * @param {Object} query
+ * @return {Array}
+ */
+function getIncludesArray (query) {
+  var relationships = query.include.split(',');
+
+  return relationships.map(function (val) {
+    return val.trim();
+  });
+}
+
+/**
+ * We should only include relationships if they are using GET
+ * @public
+ * @memberOf {RelationshipUtils}
+ * @return {Boolean}
+ */
+function shouldIncludeRelationships (method) {
+  return method.toLowerCase() === 'get';
+}

package.json

@@ -4,7 +4,8 @@
   "description": "JSONAPI support for loopback",
   "main": "lib/index.js",
   "scripts": {
-    "test": "npm run lint && mocha --reporter=spec ./test/**/*.test.js",
+    "inspect": "jsinspect .",
+    "test": "npm run lint && mocha --reporter=spec ./test/**/*.test.js && npm run inspect",
     "tester": "mocha --reporter=spec ./test/**/*.test.js",
     "lint": "eslint .",
     "version:major": "xyz -i major",
@@ -39,6 +40,7 @@
     "babel-eslint": "^4.1.3",
     "chai": "^3.3.0",
     "eslint": "^1.6.0",
+    "jsinspect": "^0.7.2",
     "loopback": "^2.22.2",
     "loopback-datasource-juggler": "^2.40.1",
     "mocha": "^2.3.3",