feat: serialization/deserialization hooks (#105)

closes #105
closes #104
closes #37
closes #66

Author: javiertury

README.md

@@ -54,12 +54,14 @@ Serializer.register(type, options);
     * **deserialize** (optional): Describes the function which should be used to deserialize a related property which is not included in the JSON:API document. It should be:
       * A _function_ with one argument `function(data) { ... }`which defines the format to which a relation should be deserialized. By default, the ID of the related object is returned, which would be equal to `function(data) {return data.id}`. See [issue #65](https://github.com/danivek/json-api-serializer/issues/65).
 * **convertCase** (optional): Case conversion for serializing data. Value can be : `kebab-case`, `snake_case`, `camelCase`
+* **beforeSerialize** (optional): A _function_ with one argument `beforeSerialize(data) => newData` to transform data before serialization. 
 
 **Deserialization options:**
 
 * **unconvertCase** (optional): Case conversion for deserializing data. Value can be : `kebab-case`, `snake_case`, `camelCase`
 * **blacklistOnDeserialize** (optional): An array of blacklisted attributes. Default = [].
 * **whitelistOnDeserialize** (optional): An array of whitelisted attributes. Default = [].
+* **afterDeserialize** (optional): A _function_ with one argument `afterDeserialize(data) => newData` to transform data after deserialization.
 
 **Global options:**
 
@@ -525,6 +527,44 @@ const deserialized = Serializer.deserializeAsync(typeConfig, data).then(result =
 });
 ```
 
+## Custom serialization and deserialization
+
+If your data requires some specific transformations, those can be applied using `beforeSerialize` and `afterDeserialize`
+
+Example for composite primary keys:
+
+```javascript
+Serializer.register('translation', {
+    beforeSerialize: (data) => {
+      // Exclude pk1 and pk2 from data
+      const { pk1, pk2, ...attributes } = data;
+
+      // Compute external id
+      const id = `${pk1}-${pk2}`;
+
+      // Return data with id
+      return {
+        ...attributes,
+        id
+      };
+    },
+    afterDeserialize: (data) => {
+      // Exclude id from data
+      const { id, ...attributes } = data;
+
+      // Recover PKs
+      const [pk1, pk2] = id.split('-');
+
+      // Return data with PKs
+      return {
+        ...attributes,
+        pk1,
+        pk2,
+      };
+    },
+});
+```
+
 ## Benchmark
 
 ```bash

lib/JSONAPISerializer.js

@@ -571,6 +571,10 @@ module.exports = class JSONAPISerializer {
       deserializedData.meta = data.meta;
     }
 
+    if (options.afterDeserialize) {
+      return options.afterDeserialize(deserializedData);
+    }
+
     return deserializedData;
   }
 
@@ -612,6 +616,10 @@ module.exports = class JSONAPISerializer {
       );
     }
 
+    if (options.beforeSerialize) {
+      data = options.beforeSerialize(data);
+    }
+
     return {
       type,
       id: data[options.id] ? data[options.id].toString() : undefined,
@@ -848,19 +856,20 @@ module.exports = class JSONAPISerializer {
     if (!isObjectLike(rData)) {
       serializedRelationship.id = rData.toString();
     } else {
-      serializedRelationship.id = rData[rOptions.id].toString();
-      // Not include relationship object which only contains an id
-      if (!(Object.keys(rData).length === 1 && rData[rOptions.id])) {
-        const identifier = `${type}-${serializedRelationship.id}`;
-        const serializedIncluded = this.serializeResource(
-          type,
-          rData,
-          rOptions,
-          included,
-          extraData,
-          overrideSchemaOptions
-        );
+      const serializedIncluded = this.serializeResource(
+        type,
+        rData,
+        rOptions,
+        included,
+        extraData,
+        overrideSchemaOptions
+      );
+
+      serializedRelationship.id = serializedIncluded.id;
+      const identifier = `${type}-${serializedRelationship.id}`;
 
+      // Not include relationship object which only contains an id
+      if (serializedIncluded.attributes && Object.keys(serializedIncluded.attributes).length) {
         // Merge relationships data if already included
         if (included.has(identifier)) {
           const alreadyIncluded = included.get(identifier);

lib/validator.js

@@ -60,6 +60,12 @@ function validateOptions(options) {
       "option 'unconvertCase' must be one of 'kebab-case', 'snake_case', 'camelCase'"
     );
 
+  if (options.beforeSerialize && typeof options.beforeSerialize !== 'function')
+    throw new Error("option 'beforeSerialize' must be function");
+
+  if (options.afterDeserialize && typeof options.afterDeserialize !== 'function')
+    throw new Error("option 'afterDeserialize' must be function");
+
   const { relationships } = options;
   Object.keys(relationships).forEach((key) => {
     relationships[key] = {

test/fixture/articles.data.js

@@ -36,6 +36,29 @@ module.exports = [
         created: '2015-09-15T18:42:12.475Z',
       },
     ],
+    translations: [
+      {
+        id: '1',
+        lang: 'es',
+        title: '¡JSON API pinta la caseta de la bici!',
+        body: 'El artículo más corto jamás escrito',
+        created: '2015-06-07T18:01:02.123Z',
+      },
+      {
+        id: '1',
+        lang: 'pt',
+        title: 'API JSON pinta a garagem da bicicleta!',
+        body: 'O artículo más corto jamás escrito',
+        created: '2015-06-07T20:01:02.123Z',
+      },
+      {
+        id: '1',
+        lang: 'de',
+        title: 'JSON API malt meinen Fahrradschuppen!',
+        body: 'Der kürzeste Artikel, der jemals geschrieben wurde',
+        created: '2015-06-07T22:01:02.123Z',
+      },
+    ],
   },
   {
     id: '2',
@@ -83,5 +106,28 @@ module.exports = [
         created: '2015-09-15T18:42:12.475Z',
       },
     ],
+    translations: [
+      {
+        id: '2',
+        lang: 'es',
+        title: 'JSON API 1.0',
+        body: 'Especificaciones de JSON API',
+        created: '2015-06-07T18:01:02.123Z',
+      },
+      {
+        id: '2',
+        lang: 'pt',
+        title: 'JSON API 1.0',
+        body: 'Especificações de JSON API',
+        created: '2015-06-07T20:01:02.123Z',
+      },
+      {
+        id: '2',
+        lang: 'de',
+        title: 'JSON API 1.0',
+        body: 'JSON API Spezifikationen',
+        created: '2015-06-07T22:01:02.123Z',
+      },
+    ],
   },
 ];

test/integration/examples.js

@@ -43,7 +43,10 @@ describe('Examples', function() {
       comments: {
         type: 'comment',
         schema: 'only-body'
-      }
+      },
+      translations: {
+        type: 'translation'
+      },
     },
     topLevelMeta: function(extraOptions) {
       return {
@@ -72,6 +75,25 @@ describe('Examples', function() {
     id: '_id',
     whitelist: ['body']
   });
+  Serializer.register('translation', {
+    beforeSerialize: (data) => {
+      const { id: articleId, lang, ...attributes } = data;
+      const id = `${articleId}-${lang}`;
+      return {
+        ...attributes,
+        id
+      }
+    },
+    afterDeserialize: (data) => {
+      const { id, ...attributes } = data;
+      const [articleId, lang] = id.split('-');
+      return {
+        ...attributes,
+        id: articleId,
+        lang,
+      };
+    },
+  });
 
   it('should serialize articles data', function(done) {
     var serializedData = Serializer.serialize('article', articlesData, {
@@ -116,7 +138,7 @@ describe('Examples', function() {
     expect(serializedData.data[0].links).to.have.property('self').to.eql('/articles/1');
     expect(serializedData.data[0].meta).to.have.property('meta').to.eql('metadata');
     expect(serializedData).to.have.property('included');
-    expect(serializedData.included).to.be.instanceof(Array).to.have.lengthOf(10);
+    expect(serializedData.included).to.be.instanceof(Array).to.have.lengthOf(16);
     var includedAuhor1 = _.find(serializedData.included, {
       'type': 'people',
       'id': '1'
@@ -136,6 +158,16 @@ describe('Examples', function() {
     expect(includedComment1).to.have.property('attributes');
     expect(includedComment1.attributes).to.have.property('body');
     expect(includedComment1.attributes).to.not.have.property('created');
+    var includedPublishing1 = _.find(serializedData.included, {
+      'type': 'translation',
+      'id': '1-es'
+    });
+    expect(includedPublishing1).to.have.property('attributes');
+    expect(includedPublishing1.attributes).to.have.property('title');
+    expect(includedPublishing1.attributes).to.have.property('body');
+    expect(includedPublishing1.attributes).to.have.property('created');
+    expect(includedPublishing1.attributes).to.not.have.property('id');
+    expect(includedPublishing1.attributes).to.not.have.property('lang');
     done();
   });
 

test/unit/JSONAPISerializer.test.js

@@ -134,7 +134,7 @@ describe('JSONAPISerializer', function() {
       const singleData = {
         _id: '1',
       };
-      const serializedData = Serializer.serializeResource('articles', singleData, _.merge(defaultOptions, {
+      const serializedData = Serializer.serializeResource('articles', singleData, _.merge({}, defaultOptions, {
         id: '_id',
       }));
       expect(serializedData).to.have.property('type').to.eql('articles');
@@ -146,13 +146,35 @@ describe('JSONAPISerializer', function() {
       done();
     });
 
+    it('should return serialized data with option beforeSerialize', function(done) {
+      const singleData = {
+        pk1: '1',
+        pk2: '4',
+      };
+      const serializedData = Serializer.serializeResource('articles', singleData, _.merge({}, defaultOptions, {
+        beforeSerialize: (data) => {
+          const { pk1, pk2, ...attributes } = data;
+          const id = `${pk1}-${pk2}`;
+          return {
+            ...attributes,
+            id
+          };
+        }
+      }));
+      expect(serializedData).to.have.property('type').to.eql('articles');
+      expect(serializedData).to.have.property('id').to.eql('1-4');
+      expect(serializedData.relationships).to.be.undefined;
+      expect(serializedData.links).to.be.undefined;
+      expect(serializedData.meta).to.be.undefined;
+
+      done();
+    });
+
     it('should return type of string for a non string id in input', function(done) {
       const singleData = {
         id: 1,
       };
-      const serializedData = Serializer.serializeResource('articles', singleData, _.merge(defaultOptions, {
-        id: 'id',
-      }));
+      const serializedData = Serializer.serializeResource('articles', singleData, defaultOptions);
       expect(serializedData).to.have.property('type').to.eql('articles');
       expect(serializedData).to.have.property('id').to.be.a('string').to.eql('1');
       done();
@@ -1631,6 +1653,39 @@ describe('JSONAPISerializer', function() {
       done();
     });
 
+    it('should return deserialized data with option afterDeserialize', function(done) {
+      const Serializer = new JSONAPISerializer();
+      Serializer.register('articles', {
+        afterDeserialize: (data) => {
+          const { id, ...attributes } = data;
+          const [pk1, pk2] = id.split('-');
+          return {
+            ...attributes,
+            pk1,
+            pk2,
+          };
+        },
+      });
+
+      const data = {
+        data: {
+          type: 'article',
+          id: '1-2',
+          attributes: {
+            title: 'JSON API paints my bikeshed!',
+            body: 'The shortest article. Ever.',
+            created: '2015-05-22T14:56:29.000Z'
+          }
+        }
+      };
+
+      const deserializedData = Serializer.deserialize('articles', data);
+      expect(deserializedData).to.have.property('pk1').to.eql('1');
+      expect(deserializedData).to.have.property('pk2').to.eql('2');
+      expect(deserializedData).to.not.have.property('id');
+      done();
+    });
+
     it('should deserialize with \'alternativeKey\' option and no included', function(done) {
       const Serializer = new JSONAPISerializer();
       Serializer.register('article', {
@@ -2057,9 +2112,7 @@ describe('JSONAPISerializer', function() {
 
     it('should deserialize with \'links\' and \'meta\' properties', function(done) {
       const Serializer = new JSONAPISerializer();
-      Serializer.register('articles', {
-        id: '_id'
-      });
+      Serializer.register('articles');
 
       const data = {
         data: {

test/unit/validator.test.js

@@ -171,6 +171,26 @@ describe('validator', function () {
       done();
     });
 
+    it('incorrect beforeSerialize', (done) => {
+      expect(function () {
+        validator.validateOptions({
+          beforeSerialize: 'test',
+        });
+      }).to.throw(Error, "option 'beforeSerialize' must be function");
+
+      done();
+    });
+
+    it('incorrect afterDeserialize', (done) => {
+      expect(function () {
+        validator.validateOptions({
+          afterDeserialize: 'test',
+        });
+      }).to.throw(Error, "option 'afterDeserialize' must be function");
+
+      done();
+    });
+
     it('no type provided on relationship', (done) => {
       expect(function () {
         validator.validateOptions({