Merge pull request #94 from digitalsadhu/add_deserialization_hooks

digitalsadhu · digitalsadhu · commit 58b8da6828e2 · 2016-01-10T22:15:47.000+01:00
Add deserialization hooks
diff --git a/README.md b/README.md
@@ -275,9 +275,38 @@ module.exports = function (MyModel) {
 
 ##### function parameters
 
-- `options` All config options set for the serialization process. See below.
+- `options` All config options set for the serialization process.
 - `callback` Callback to call with error or serialized records
 
+## Custom Deserialization
+For occasions where you need greater control over the deserialization process, you can implement a custom deserialization function for each model as needed. This function will be used instead of the regular deserialization process.
+
+#### example
+```js
+module.exports = function (MyModel) {
+  MyModel.jsonApiDeserialize = function (options, callback) {
+    // either return an error
+    var err = new Error('Unable to deserialize record');
+    err.status = 500;
+    cb(err)
+
+    //or
+    //options.data is the raw data
+    //options.result needs to be populated with deserialization result
+    options.result = options.data.data.attributes;
+
+    cb(null, options);
+  }
+}
+```
+
+##### function parameters
+
+- `options` All config options set for the deserialization process.
+- `callback` Callback to call with error or serialized records
+
+## The options object
+
 ###### `options.type`
 Resource type. Originally calculated from a models plural. Is used in the default
 serialization process to set the type property for each model in a jsonapi response.
@@ -367,10 +396,80 @@ This is the attributes settings as defined in the `attributes` configuration opt
 explained earlier. Use this in `beforeJsonApiSerialize` to make any model specific
 adjustments before serialization.
 
-## Serialization Hooks
-For occasions when you don't want to fully implement serialization for a model manually but
-you need to manipulate the serialization process, you can use the serialization
-hooks `beforeJsonApiSerialize` and `afterJsonApiSerialize`.
+###### `options.data`
+The raw body data prior to deserialization from creates and updates. This can be
+manipulated prior to deserialization using `beforeJsonApiDeserialize`
+
+###### `options.result`
+The deserialized raw body data. This is used when saving
+models as part of a create or update operation. You can manipulate this prior to
+the save occuring in `afterJsonApiDeserialize`
+
+## Serialization/Deserialization Hooks
+For occasions when you don't want to fully implement (de)serialization for a model manually but
+you need to manipulate the serialization/deserialization process, you can use the
+hooks `beforeJsonApiSerialize`, `afterJsonApiSerialize`, `beforeJsonApiDeserialize` and `afterJsonApiDeserialize`.
+
+### beforeJsonApiDeserialize
+In order to modify the deserialization process on a model by model basis, you can
+define a `Model.beforeJsonApiDeserialize` function as shown below. The function
+will be called with an options object and a callback which must be called with either
+an error as the first argument or the modified options object as the second
+parameter.
+
+**Examples of things you might want to use this feature for**
+- modifying `options.data.data.attributes` prior to their being deserialized into model properties that
+will be saved
+- modifying `options.data.data.relationships` prior to their being used to save relationship linkages
+
+#### code example
+```js
+module.exports = function (MyModel) {
+  MyModel.beforeJsonApiDeserialize = function (options, callback) {
+    // either return an error
+    var err = new Error('Unwilling to deserialize record');
+    err.status = 500;
+    callback(err)
+
+    // or return modified data
+    options.data.data.attributes.title = 'modified title';
+
+    // returned options.data will be deserialized by either the default deserialization process
+    // or by a custom deserialize function if one is present on the model.
+    callback(null, options);
+  }
+}
+```
+
+### afterJsonApiDeserialize
+This function will be called with an options object and a callback which must be called with either
+an error as the first argument or the modified options object as the second parameter.
+
+**Examples of things you might want to use this feature for**
+- modifying `options.result` after their having being deserialized from `options.data.data.attributes`
+- modifying `options.data.data.relationships` prior to their being used to save relationship linkages
+
+#### code example
+```js
+module.exports = function (MyModel) {
+  MyModel.afterJsonApiDeserialize = function (options, callback) {
+    // either return an error
+    var err = new Error('something went wrong!');
+    err.status = 500;
+    callback(err)
+
+    // or return modified data prior to model being saved with options.result
+    options.result.title = 'modified title';
+
+    callback(null, options);
+  }
+}
+```
+
+##### function parameters
+- `options` All config options set for the deserialization process. See the "the options object"
+section above for info on what options properties are available for modification.
+- `callback` Callback to call with error or options object.
 
 ### beforeJsonApiSerialize
 In order to modify the serialization process on a model by model basis, you can
diff --git a/lib/deserialize.js b/lib/deserialize.js
@@ -25,10 +25,37 @@ module.exports = function (app, options) {
       return regex.test(ctx.method.name);
     });
 
+    /**
+     * 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;
+    }
+
     if (utils.shouldApplyJsonApi(ctx, options) || matches.length > 0) {
       // set the JSON API Content-Type response header
       ctx.res.set({'Content-Type': 'application/vnd.api+json'});
 
+      options.model = utils.getModelFromContext(ctx, app);
+      options.method = ctx.method.name;
+
       /**
        * Check the incoming payload data to ensure it is valid according to the
        * JSON API spec.
@@ -44,40 +71,24 @@ module.exports = function (app, options) {
         return next(new Error(errors));
       }
 
-      serverRelations = utils.getRelationsFromContext(ctx, app);
-
-      // transform the payload
-      ctx.args.data = deserializer(data, serverRelations);
-
-      //TODO: Rewrite to normal search model by type and FK
-    }
+      options.data = data;
 
-    /**
-     * 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();
-      }
+      serverRelations = utils.getRelationsFromContext(ctx, app);
 
-      if (!RelUtils.shouldIncludeRelationships(ctx.req.method)) {
-        return next(RelUtils.getInvalidIncludesError());
-      }
+      options.relationships = serverRelations;
 
-      var include = RelUtils.getIncludesArray(ctx.req.query);
-      include = include.length === 1 ? include[0] : include;
+      // transform the payload
+      deserializer(options, function (err, deserializerOptions) {
+        if (err) return next(err);
 
-      ctx.args = ctx.args || {};
-      ctx.args.filter = ctx.args.filter || {};
-      ctx.args.filter.include = include;
+        options.data = deserializerOptions.data;
+        ctx.args.data = deserializerOptions.result;
 
+        next();
+      });
+    } else {
+      next();
     }
-
-    next();
   });
 };
 
diff --git a/lib/deserializer.js b/lib/deserializer.js
@@ -1,5 +1,17 @@
 var _ = require('lodash');
-var inflection = require('inflection');
+
+function defaultBeforeDeserialize (options, cb) {
+  cb(null, options);
+}
+
+function defaultDeserialize (options, cb) {
+  options.result = options.data.data.attributes || {};
+  cb(null, options);
+}
+
+function defaultAfterDeserialize (options, cb) {
+  cb(null, options);
+}
 
 /**
  * Deserializes the requests data.
@@ -9,70 +21,28 @@ var inflection = require('inflection');
  * @param {Object} serverRelations
  * @return {Object}
  */
-module.exports = function deserializer (data, serverRelations) {
-  var clientRelations = data.data.relationships;
-  var result = data.data.attributes || {};
+module.exports = function deserializer (options, cb) {
+  var model = options.model;
 
-  if (_.isPlainObject(clientRelations)) {
-    _.each(clientRelations, function (relation, name) {
-      handleClientRelations(data, result, serverRelations[name], relation);
-    });
-  }
+  var beforeDeserialize = (typeof model.beforeJsonApiDeserialize === 'function') ?
+    model.beforeJsonApiDeserialize : defaultBeforeDeserialize;
 
-  return result;
+  var deserialize = (typeof model.jsonApiDeserialize === 'function') ?
+    model.jsonApiDeserialize : defaultDeserialize;
 
-};
+  var afterDeserialize = (typeof model.afterJsonApiDeserialize === 'function') ?
+    model.afterJsonApiDeserialize : defaultAfterDeserialize;
 
-/**
- * Modifies the result for each client relation.
- * @private
- * @memberOf {Deserializer}
- * @param {Object} data
- * @param {Object} result The result object to modify.
- * @param {Object} serverRelation
- * @param {Object} clientRelationf
- * @return {undefined}
- */
-function handleClientRelations (data, result, serverRelation, clientRelation) {
-  var relationType = null;
-  var relationValue = null;
-  var foreignKeySuffix = 'Id';
-  var foreignKey = serverRelation.foreignKey;
-
-  if (_.isPlainObject(serverRelation)) {
-    if (_.isArray(clientRelation.data)) {
-      if (_.isEmpty(clientRelation.data)) {
-        relationValue = [];
-      } else {
-        relationType = _.result(_.find(clientRelation.data, 'type'), 'type');
-        relationValue = _.map(clientRelation.data, function (val) {
-          return val.id;
-        });
-      }
-
-      // pluralize
-      foreignKeySuffix += 's';
-    } else {
-      if (clientRelation.data) {
-        relationType = clientRelation.data.type;
-        relationValue = clientRelation.data.id;
-      }
-    }
-
-    if (!relationType) {
-      relationType = serverRelation.model;
-    } else {
-      relationType = inflection.singularize(relationType);
-      if (relationType !== serverRelation.model) {
-        return;
-      }
-    }
+  var deserializeOptions = _.cloneDeep(options);
 
-    if (!foreignKey) {
-      relationType = inflection.camelize(relationType, true);
-      foreignKey = relationType + foreignKeySuffix;
-    }
-
-    result[foreignKey] = relationValue;
-  }
-}
+  beforeDeserialize(deserializeOptions, function (err, deserializeOptions) {
+    if (err) return cb(err);
+    deserialize(deserializeOptions, function (err, deserializeOptions) {
+      if (err) return cb(err);
+      afterDeserialize(deserializeOptions, function (err, deserializeOptions) {
+        if (err) return cb(err);
+        return cb(null, deserializeOptions);
+      });
+    });
+  });
+};
diff --git a/lib/index.js b/lib/index.js
@@ -28,11 +28,11 @@ module.exports = function (app, options) {
   debug('Started');
   options.debug = debug;
   headers(app, options);
-  relationships(app, options);
   removeRemoteMethods(app, options);
   patch(app, options);
   serialize(app, options);
   deserialize(app, options);
+  relationships(app, options);
   create(app, options);
   update(app, options);
   errors(app, options);
diff --git a/lib/relationships.js b/lib/relationships.js
@@ -11,13 +11,11 @@ module.exports = function (app, options) {
   var id, data, model;
 
   remotes.before('**', function (ctx, next) {
-
     if (utils.shouldNotApplyJsonApi(ctx, options)) {
       return next();
     };
-
     id = ctx.req.params.id;
-    data = ctx.args.data;
+    data = options.data;
     model = utils.getModelFromContext(ctx, app);
     relationships(id, data, model);
 
@@ -26,14 +24,15 @@ module.exports = function (app, options) {
 
   // for create
   remotes.after('**', function (ctx, next) {
-
     if (utils.shouldNotApplyJsonApi(ctx, options)) {
       return next();
     };
 
-    if (ctx.result) {
-      id = ctx.result.id;
-      data = ctx.req.body;
+    if (ctx.method.name !== 'create') return next();
+
+    if (ctx.result && ctx.result.data) {
+      id = ctx.result.data.id;
+      data = options.data;
       model = utils.getModelFromContext(ctx, app);
       relationships(id, data, model);
     };
@@ -52,6 +51,7 @@ function relationships (id, data, model) {
   _.each(data.data.relationships, function (relationship, name) {
 
     var serverRelation = model.relations[name];
+    if (!serverRelation) return;
     var type = serverRelation.type;
     var modelTo = serverRelation.modelTo;
 
diff --git a/test/override-deserializer.test.js b/test/override-deserializer.test.js
diff --git a/test/relationships.test.js b/test/relationships.test.js
