Add async deserialization (#51)

closes #46

Author: danivek

Diff for: README.md

@@ -334,7 +334,14 @@ var data = {
   }
 };
 
+// Synchronously (blocking)
 Serializer.deserialize('article', data);
+
+// Asynchronously (non-blocking)
+Serializer.deserializeAsync('article', data)
+  .then((result) => {
+    ...
+  });
 ```
 
 ```JSON

Diff for: lib/JSONAPISerializer.js

@@ -166,7 +166,7 @@ module.exports = class JSONAPISerializer {
   }
 
   /**
-   * Asynchronously serialze input data to a JSON API compliant response.
+   * Asynchronously serialize input data to a JSON API compliant response.
    * Input data can be a simple object or an array of objects.
    *
    * @see {@link http://jsonapi.org/format/#document-top-level}
@@ -218,8 +218,8 @@ module.exports = class JSONAPISerializer {
         try {
           // Serialize a single item of the data-array.
           const serializedItem = isDynamicType
-          ? this.serializeMixedData(type, item, included, extraData)
-          : this.serializeData(type, item, options, included, extraData);
+            ? this.serializeMixedData(type, item, included, extraData)
+            : this.serializeData(type, item, options, included, extraData);
 
           // If the serialized item is null, we won't push it to the stream,
           // as pushing a null-value causes streams to end.
@@ -293,6 +293,49 @@ module.exports = class JSONAPISerializer {
     return deserializedData;
   }
 
+  /**
+   * Asynchronously Deserialize JSON API document data.
+   * Input data can be a simple object or an array of objects.
+   *
+   * @method JSONAPISerializer#deserializeAsync
+   * @param {string|Object} type resource's type as string or an object with a dynamic type resolved from data.
+   * @param {Object} data JSON API input data.
+   * @param {string} [schema=default] resource's schema name.
+   * @return {Promise} resolves with serialized data.
+   */
+  deserializeAsync(type, data, schema) {
+    schema = schema || 'default';
+
+    if (!_.isPlainObject(type)) {
+      if (!this.schemas[type]) {
+        throw new Error(`No type registered for ${type}`);
+      }
+
+      if (schema && !this.schemas[type][schema]) {
+        throw new Error(`No schema ${schema} registered for ${type}`);
+      }
+    } else {
+      type = this.validateDynamicTypeOptions(type);
+    }
+
+    return new Promise((resolve, reject) => { // eslint-disable-line consistent-return
+      if (Array.isArray(data.data)) {
+        const deserializedData = [];
+
+        const stream = intoStream.obj(data.data);
+        stream.on('data', (item) => {
+          deserializedData.push(this.deserializeResource(type, item, schema, data.included));
+        });
+
+        stream.on('end', () => resolve(deserializedData));
+
+        stream.on('error', reject);
+      } else {
+        return resolve(this.deserializeResource(type, data.data, schema, data.included));
+      }
+    });
+  }
+
   /**
    * Deserialize a single JSON API resource.
    * Input data must be a simple object.
@@ -301,6 +344,7 @@ module.exports = class JSONAPISerializer {
    * @param {string|Object} type resource's type as string or an object with a dynamic type resolved from data.
    * @param {Object} data JSON API resource data.
    * @param {string} [schema=default] resource's schema name.
+   * @param {Object[]} included.
    * @return {Object} deserialized data.
    */
   deserializeResource(type, data, schema, included) {
@@ -639,7 +683,7 @@ module.exports = class JSONAPISerializer {
       // Support for unpopulated relationships (with mongoDB BSON ObjectId)
       serializedRelationship.id = rData.toString();
     } else {
-        // Relationship has been populated
+      // Relationship has been populated
       serializedRelationship.id = rData[rOptions.id].toString();
       included.push(this.serializeData(rType, rData, rOptions, included, extraData));
     }

Diff for: test/unit/JSONAPISerializer.test.js

@@ -1601,6 +1601,131 @@ describe('JSONAPISerializer', function() {
     });
   });
 
+  describe('deserializeAsync', function() {
+    const Serializer = new JSONAPISerializer();
+    Serializer.register('articles', {});
+    const dataArray = {
+      data: [
+        {
+          type: 'articles',
+          id: '1',
+          attributes: {
+            title: 'Article 1',
+          },
+        },
+        { type: 'articles',
+          id: '2',
+          attributes: {
+            title: 'Article 2',
+          },
+        },
+        { type: 'articles',
+          id: '3',
+          attributes: {
+            title: 'Article 3',
+          },
+        },
+      ],
+    };
+
+    it('should return a Promise', () => {
+      const promise = Serializer.deserializeAsync('articles', { data: {} });
+      expect(promise).to.be.instanceOf(Promise);
+    });
+
+    it('should deserialize simple data', () => {
+      const data = {
+        data: {
+          type: 'article',
+          id: '1',
+          attributes: {
+            title: 'JSON API paints my bikeshed!',
+            body: 'The shortest article. Ever.',
+            created: '2015-05-22T14:56:29.000Z'
+          },
+          relationships: {
+            author: {
+              data: {
+                type: 'people',
+                id: '1'
+              }
+            },
+            comments: {
+              data: [{
+                type: 'comment',
+                id: '1'
+              }, {
+                type: 'comment',
+                id: '2'
+              }]
+            }
+          }
+        }
+      };
+
+      return Serializer.deserializeAsync('articles', data)
+      .then((deserializedData) => {
+        expect(deserializedData).to.have.property('id');
+        expect(deserializedData).to.have.property('title');
+        expect(deserializedData).to.have.property('body');
+        expect(deserializedData).to.have.property('created');
+        expect(deserializedData).to.have.property('author', '1');
+        expect(deserializedData).to.have.property('comments').to.be.instanceof(Array).to.eql(['1', '2']);
+      });
+    });
+
+    it('should deserialize an array of data', () =>
+    Serializer.deserializeAsync('articles', dataArray)
+      .then((deserializedData) => {
+        expect(deserializedData.length).to.eql(3);
+      })
+    );
+
+    it('should deserialize each array item on next tick', () => {
+      const tickCounter = new TickCounter(5);
+      return Serializer.deserializeAsync('articles', dataArray)
+        .then(() => {
+          expect(tickCounter.ticks).to.eql(4);
+        })
+    });
+
+    it('should throw an error if type has not been registered', function(done) {
+      expect(function() {
+        Serializer.deserializeAsync('authors', {});
+      }).to.throw(Error, 'No type registered for authors');
+      done();
+    });
+
+    it('should throw an error if custom schema has not been registered', function(done) {
+      expect(function() {
+        Serializer.deserializeAsync('articles', {}, 'custom');
+      }).to.throw(Error, 'No schema custom registered for articles');
+      done();
+    });
+
+    it('should deserialize mixed data with a dynamic type option as the first argument', () => {
+      const data = {
+        data: {
+          type: 'articles',
+          id: '1',
+          attributes: {
+            type: 'articles',
+            title: 'JSON API paints my bikeshed!',
+            body: 'The shortest article. Ever.'
+          }
+        }
+      };
+
+      return Serializer.deserializeAsync({type: 'type'}, data)
+        .then((deserializedData) => {
+          expect(deserializedData).to.have.property('type', 'articles');
+          expect(deserializedData).to.have.property('id', '1');
+          expect(deserializedData).to.have.property('title');
+          expect(deserializedData).to.have.property('body');
+        });
+    });
+  });
+
   describe('deserializeMixedData', function() {
     const Serializer = new JSONAPISerializer();
     Serializer.register('article');