Added comments to json-2-csv; Updated tests

Author: mrodrig

lib/json-2-csv.js

@@ -3,73 +3,88 @@
 var _ = require('underscore'),
     async = require('async');
 
-var options = {};
+var options = {}; // Initialize the options - this will be populated when the csv2json function is called.
 
 // Takes the parent heading and this doc's data and creates the subdocument headings (string)
 var retrieveSubHeading = function (heading, data) {
-    var subKeys = _.keys(data),
-        newKey;
+    var subKeys = _.keys(data), // retrieve the keys from the current document
+        newKey; // temporary variable to aid in determining the heading - used to generate the 'nested' headings
     _.each(subKeys, function (subKey, indx) {
-        newKey = heading === '' ? subKey : heading + '.' + subKey;
-        if (typeof data[subKey] === 'object' && data[subKey] !== null) { // Another nested document
-            subKeys[indx] = retrieveSubHeading(newKey, data[subKey]);
+        // If the given heading is empty, then we set the heading to be the subKey, otherwise set it as a nested heading w/ a dot
+        newKey = heading === '' ? subKey : heading + '.' + subKey; 
+        if (typeof data[subKey] === 'object' && data[subKey] !== null) { // If we have another nested document
+            subKeys[indx] = retrieveSubHeading(newKey, data[subKey]); // Recur on the subdocument to retrieve the full key name
         } else {
-            subKeys[indx] = newKey;
+            subKeys[indx] = newKey; // Set the key name since we don't have a sub document
         }
     });
-    return subKeys.join(options.DELIMITER);
+    return subKeys.join(options.DELIMITER); // Return the headings joined by our delimiter
 };
 
+// Retrieve the headings for all documents and return it.  This checks that all documents have the same schema.
 var retrieveHeading = function (data) {
-    return function (cb) {
-        var keys = _.keys(data);
-        _.each(keys, function (key, indx) {
-            if (typeof data[key] === 'object') {
+    return function (cb) { // Returns a function that takes a callback - the function is passed to async.parallel
+        var keys = _.keys(data); // Retrieve the current data keys
+        _.each(keys, function (key, indx) { // for each key
+            if (typeof data[key] === 'object') { 
+                // if the data at the key is a document, then we retrieve the subHeading starting with an empty string heading and the doc
                 keys[indx] = retrieveSubHeading('', data[key]);
             }
         });
+        // Retrieve the unique array of headings (keys)
         keys = _.uniq(keys);
+        // If we have more than 1 unique list, then not all docs have the same schema - report an error
         if (keys.length > 1) { throw new Error('Not all documents have the same schema.', keys); }
-        cb(null, _.flatten(keys).join(options.DELIMITER));
+        cb(null, _.flatten(keys).join(options.DELIMITER)); // Return headings back
     };
 };
 
+// Convert the given data with the given keys
 var convertData = function (data, keys) {
-    var output = [];
-    _.each(keys, function (key, indx) {
-        var value = data[key];
-        if (keys.indexOf(key) > -1) {
-            if (typeof value === 'object') {
-                output.push(convertData(value, _.keys(value)));
+    var output = [], // Array of CSV representing converted docs
+        value; // Temporary variable to store the current data
+    _.each(keys, function (key, indx) { // For each key
+        value = data[key]; // Set the current data that we are looking at
+        if (keys.indexOf(key) > -1) { // If the keys contain the current key, then process the data
+            if (typeof value === 'object') { // If we have an object
+                output.push(convertData(value, _.keys(value))); // Push the recursively generated CSV
             } else {
-                output.push(value);
+                output.push(value); // Otherwise push the current value
             }
         }
     });
-    return output.join(options.DELIMITER);
+    return output.join(options.DELIMITER); // Return the data joined by our field delimiter
 };
 
+// Generate the CSV representing the given data.
 var generateCsv = function (data) {
-    return function (cb) {
+    return function (cb) { // Returns a function that takes a callback - the function is passed to async.parallel
+        // Reduce each JSON document in data to a CSV string and append it to the CSV accumulator
         return cb(null, _.reduce(data, function (csv, doc) { return csv += convertData(doc, _.keys(doc)) + options.EOL; }, ''));
     };
 };
 
 module.exports = {
 
+    // Function to export internally
+    // Takes options as a document, data as a JSON document array, and a callback that will be used to report the results
     json2csv: function (opts, data, callback) {
-        if (!callback) { throw new Error('A callback is required!'); }
+        if (!callback) { throw new Error('A callback is required!'); } // If a callback wasn't provided, throw an error
         if (!opts) { callback(new Error('Options were not passed and are required.')); return null; } // Shouldn't happen, but just in case
-        else { options = opts; }
-        if (!data) { callback(new Error('Cannot call json2csv on ' + data)); return null; }
-        if (typeof data === 'object' && !data.length) { // Single document, not an array
+        else { options = opts; } // Options were passed, set the global options value
+        if (!data) { callback(new Error('Cannot call json2csv on ' + data + '.')); return null; } // If we don't receive data, report an error
+        if (typeof data !== 'object') { // If the data was not a single document or an array of documents
+            cb(new Error('Data provided was not an array of documents.'));  // Report the error back to the caller
+        } else if (typeof data === 'object' && !data.length) { // Single document, not an array
             data = [data]; // Convert to an array of the given document
         }
+        // Retrieve the heading and the CSV asynchronously in parallel
         async.parallel([retrieveHeading(data), generateCsv(data)], function (err, res) {
             if (!err) {
-                callback(null, res.join(options.EOL));
+                // Data received with no errors, join the two responses with an end of line delimiter to setup heading and CSV body
+                callback(null, res.join(options.EOL)); 
             } else {
-                callback(err, null);
+                callback(err, null); // Report received error back to caller
             }
         });
     }

test/testComma.js

@@ -76,14 +76,14 @@ var json2csvTests = function () {
 
             it('should throw an error about not having been passed data - 1', function (done) {
                 converter.json2csv(null, function (err, csv) {
-                    err.message.should.equal('Cannot call json2csv on null');
+                    err.message.should.equal('Cannot call json2csv on null.');
                     done();
                 }, options);
             });
 
             it('should throw an error about not having been passed data - 2', function (done) {
                 converter.json2csv(undefined, function (err, csv) {
-                    err.message.should.equal('Cannot call json2csv on undefined');
+                    err.message.should.equal('Cannot call json2csv on undefined.');
                     done();
                 }, options);
             });
@@ -176,14 +176,14 @@ var json2csvTests = function () {
 
             it('should throw an error about not having been passed data - 1', function (done) {
                 converter.json2csv(null, function (err, csv) {
-                    err.message.should.equal('Cannot call json2csv on null');
+                    err.message.should.equal('Cannot call json2csv on null.');
                     done();
                 });
             });
 
             it('should throw an error about not having been passed data - 2', function (done) {
                 converter.json2csv(undefined, function (err, csv) {
-                    err.message.should.equal('Cannot call json2csv on undefined');
+                    err.message.should.equal('Cannot call json2csv on undefined.');
                     done();
                 });
             });

test/testSemi.js

@@ -77,14 +77,14 @@ var json2csvTests = function () {
 
             it('should throw an error about not having been passed data - 1', function (done) {
                 converter.json2csv(null, function (err, csv) {
-                    err.message.should.equal('Cannot call json2csv on null');
+                    err.message.should.equal('Cannot call json2csv on null.');
                     done();
                 }, options);
             });
 
             it('should throw an error about not having been passed data - 2', function (done) {
                 converter.json2csv(undefined, function (err, csv) {
-                    err.message.should.equal('Cannot call json2csv on undefined');
+                    err.message.should.equal('Cannot call json2csv on undefined.');
                     done();
                 }, options);
             });
@@ -178,14 +178,14 @@ var json2csvTests = function () {
 
             it('should throw an error about not having been passed data - 1', function (done) {
                 converter.json2csv(null, function (err, csv) {
-                    err.message.should.equal('Cannot call json2csv on null');
+                    err.message.should.equal('Cannot call json2csv on null.');
                     done();
                 });
             });
 
             it('should throw an error about not having been passed data - 2', function (done) {
                 converter.json2csv(undefined, function (err, csv) {
-                    err.message.should.equal('Cannot call json2csv on undefined');
+                    err.message.should.equal('Cannot call json2csv on undefined.');
                     done();
                 });
             });