Merge pull request #21 from mrodrig/refactor-code

Cleaning up code and comments

Author: mrodrig

README.md

@@ -144,10 +144,10 @@ $ npm run coverage
 
 Current Coverage is:
 ```
-Statements   : 93.63% ( 147/157 )
-Branches     : 87.91% ( 80/91 )
-Functions    : 100% ( 36/36 )
-Lines        : 95.86% ( 139/145 )
+Statements   : 94.49% ( 120/127 )
+Branches     : 90.24% ( 74/82 )
+Functions    : 100% ( 30/30 )
+Lines        : 97.39% ( 112/115 )
 ```
 
 ## Features

bower.json

@@ -1,10 +1,11 @@
 {
   "name": "json-2-csv",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "homepage": "https://github.com/mrodrig/json-2-csv",
   "moduleType": [
     "node"
   ],
+  "main": "lib/converter.js",
   "license": "MIT",
   "ignore": [
     "**/.*",
@@ -14,7 +15,7 @@
     "tests"
   ],
   "dependencies": {
-    "underscore": "1.6.0",
+    "underscore": "1.8.3",
     "bluebird": "2.9.24"
   }
 }

lib/converter.js

@@ -3,6 +3,7 @@
 var json2Csv = require('./json-2-csv'), // Require our json-2-csv code
     csv2Json = require('./csv-2-json'), // Require our csv-2-json code
     constants = require('./constants'), // Require in constants
+    Promise = require('bluebird'),
     _ = require('underscore'); // Require underscore
 
 /**
@@ -17,8 +18,10 @@ var defaultOptions = constants.DefaultOptions;
  */
 var buildOptions = function (opts, cb) {
     opts = _.defaults(opts || {}, defaultOptions);
+
     // Note: _.defaults does a shallow default, we need to deep copy the DELIMITER object
     opts.DELIMITER = _.defaults(opts.DELIMITER || {}, defaultOptions.DELIMITER);
+
     // If the delimiter fields are the same, report an error to the caller
     if (opts.DELIMITER.FIELD === opts.DELIMITER.ARRAY) { return cb(new Error(constants.Errors.delimitersMustDiffer)); }
     // Otherwise, send the options back
@@ -28,17 +31,22 @@ var buildOptions = function (opts, cb) {
 // Export the following functions that will be client accessible
 module.exports = {
 
-    // Client accessible json2csv function
-    // Takes an array of JSON documents to be converted,
-    // a callback that will be called with (err, csv) after
-    // processing is completed, and optional options
+    /**
+     * Client accessible json2csv function
+     * Takes an array of JSON documents to be converted, a callback that will be called with (err, csv)
+     * after processing is complete, and optional options
+     * @param array Object[] data to be converted
+     * @param callback Function callback
+     * @param opts Object options object
+     */
     json2csv: function (array, callback, opts) {
         // If this was promisified (callback and opts are swapped) then fix the argument order.
         if (_.isObject(callback) && !_.isFunction(callback)) {
             var func = opts;
             opts = callback;
             callback = func;
         }
+
         buildOptions(opts, function (err, options) { // Build the options
             if (err) {
                 return callback(err);
@@ -49,17 +57,22 @@ module.exports = {
     },
 
 
-    // Client accessible csv2json function
-    // Takes a string of CSV to be converted to a JSON document array,
-    // a callback that will be called with (err, csv) after
-    // processing is completed, and optional options
+    /**
+     * Client accessible csv2json function
+     * Takes a string of CSV to be converted to a JSON document array, a callback that will be called
+     * with (err, json) after processing is complete, and optional options
+     * @param csv
+     * @param callback
+     * @param opts
+     */
     csv2json: function (csv, callback, opts) {
         // If this was promisified (callback and opts are swapped) then fix the argument order.
         if (_.isObject(callback) && !_.isFunction(callback)) {
             var func = opts;
             opts = callback;
             callback = func;
         }
+
         buildOptions(opts, function (err, options) { // Build the options
             if (err) {
                 return callback(err);

lib/csv-2-json.js

@@ -1,113 +1,136 @@
 'use strict';
 
 var _ = require('underscore'),
+    path = require('doc-path'),
     constants = require('./constants');
 
 var options = {}; // Initialize the options - this will be populated when the csv2json function is called.
 
-// Generate the JSON heading from the CSV
+/**
+ * Generate the JSON heading from the CSV
+ * @param lines
+ * @param callback
+ * @returns {*}
+ */
 var retrieveHeading = function (lines, callback) {
-    if (!lines.length) { // If there are no lines passed in, then throw an error
+    // If there are no lines passed in, return an error
+    if (!lines.length) {
         return callback(new Error(constants.Errors.csv2json.noDataRetrieveHeading)); // Pass an error back to the user
     }
-    var heading = lines[0].split(options.DELIMITER.FIELD); // Grab the top line (header line) and split by the field delimiter
-    heading = _.map(heading, function (headerKey, index) {
-        return {
-            value: headerKey,
-            index: index
-        }
-    });
-    return heading;
-};
 
-// Add a nested key and its value in the given document
-var addNestedKey = function (key, value, doc) {
-    var subDocumentRoot = doc, // This is the document that we will be using to add the nested keys to.
-        trackerDocument = subDocumentRoot, // This is the document that will use to iterate through the subDocument, starting at the root
-        nestedKeys = key.split('.'), // Array of all keys and sub keys for the document
-        finalKey = nestedKeys.pop(); // Retrieve the last sub key.
-    _.each(nestedKeys, function (nestedKey) {
-        if (keyExists(nestedKey, trackerDocument)) { // This nestedKey already exists, use an existing doc
-            trackerDocument = trackerDocument[nestedKey]; // Update the trackerDocument to use the existing document
-        } else {
-            trackerDocument[nestedKey] = {}; // Add document at the current subKey
-            trackerDocument = trackerDocument[nestedKey]; // Update trackerDocument to be the added doc for the subKey
-        }
-    });
-    trackerDocument[finalKey] = value; // Set the final layer key to the value
-    return subDocumentRoot; // Return the document with the nested document structure setup
-};
-
-// Helper function to check if the given key already exists in the given document
-var keyExists = function (key, doc) {
-    return (!_.isUndefined(doc[key])); // If the key doesn't exist, then the type is 'undefined'
+    // Generate and return the heading keys
+    return _.map(lines[0].split(options.DELIMITER.FIELD),
+        function (headerKey, index) {
+            return {
+                value: headerKey,
+                index: index
+            };
+        });
 };
 
+/**
+ * Does the given value represent an array?
+ * @param value
+ * @returns {boolean}
+ */
 var isArrayRepresentation = function (value) {
-    return (value && value.indexOf('[') === 0 && value.lastIndexOf(']') === value.length-1);
+    // Verify that there is a value and it starts with '[' and ends with ']'
+    return (value && /^\[.*\]$/.test(value));
 };
 
-var convertArrayRepresentation = function (val) {
-    val = _.filter(val.substring(1, val.length-1).split(options.DELIMITER.ARRAY), function (value) {
+/**
+ * Converts the value from a CSV 'array'
+ * @param val
+ * @returns {Array}
+ */
+var convertArrayRepresentation = function (arrayRepresentation) {
+    // Remove the '[' and ']' characters
+    arrayRepresentation = arrayRepresentation.replace(/(\[|\])/g, '');
+
+    // Split the arrayRepresentation into an array by the array delimiter
+    arrayRepresentation = arrayRepresentation.split(options.DELIMITER.ARRAY);
+
+    // Filter out non-empty strings
+    return _.filter(arrayRepresentation, function (value) {
         return value;
     });
-    _.each(val, function (value, indx) {
-        if (isArrayRepresentation(value)) {
-            val[indx] = convertArrayRepresentation(value);
-        }
-    });
-    return val;
 };
 
-// Create a JSON document with the given keys (designated by the CSV header) and the values (from the given line)
-var createDoc = function (keys, line) {
-    if (line == '') { return false; } // If we have an empty line, then return false so we can remove all blank lines (falsy values)
-    var doc = {}, // JSON document to start with and manipulate
-        val,      // Temporary variable to set the current key's value to
-        line = line.trim().split(options.DELIMITER.FIELD); // Split the line using the given field delimiter after trimming whitespace
-    _.each(keys, function (key, indx) {
-        val = line[key.index] === '' ? null : line[key.index];
+/**
+ * Create a JSON document with the given keys (designated by the CSV header)
+ *   and the values (from the given line)
+ * @param keys String[]
+ * @param line String
+ * @returns {Object} created json document
+ */
+var createDocument = function (keys, line) {
+    var line = line.split(options.DELIMITER.FIELD), // Split the line using the given field delimiter after trimming whitespace
+        val; // Temporary variable to set the current key's value to
+
+    // Reduce the keys into a JSON document representing the given line
+    return _.reduce(keys, function (document, key) {
+        // If there is a value at the key's index in the line, set the value; otherwise null
+        val = line[key.index] ? line[key.index] : null;
+
+        // If the value is an array representation, convert it
         if (isArrayRepresentation(val)) {
             val = convertArrayRepresentation(val);
         }
-        if (key.value.indexOf('.')) { // If key has '.' representing nested document
-            doc = addNestedKey(key.value, val, doc); // Update the document to add the nested key structure
-        } else { // Else we just have a straight key:value mapping
-            doc[key] = val; // Set the value at the current key
-        }
-    });
-    return doc; // Return the created document
+        // Otherwise add the key and value to the document
+        return path.setPath(document, key.value, val);
+    }, {});
 };
 
-// Main wrapper function to convert the CSV to the JSON document array
+/**
+ * Main helper function to convert the CSV to the JSON document array
+ * @param lines String[]
+ * @param callback Function callback function
+ * @returns {Array}
+ */
 var convertCSV = function (lines, callback) {
     var generatedHeaders = retrieveHeading(lines, callback), // Retrieve the headings from the CSV, unless the user specified the keys
-        jsonDocs = [], // Create an array that we can add the generated documents to
+        nonHeaderLines = lines.splice(1), // All lines except for the header line
+    // If the user provided keys, filter the generated keys to just the user provided keys so we also have the key index
         headers = options.KEYS ? _.filter(generatedHeaders, function (headerKey) {
             return _.contains(options.KEYS, headerKey.value);
         }) : generatedHeaders;
-    lines = lines.splice(1); // Grab all lines except for the header
-    _.each(lines, function (line) { // For each line, create the document and add it to the array of documents
-        jsonDocs.push(createDoc(headers, line));
-    });
-    return _.filter(jsonDocs, function (doc) { return doc !== false; }); // Return all non 'falsey' values to filter blank lines
+
+    return _.reduce(nonHeaderLines, function (documentArray, line) { // For each line, create the document and add it to the array of documents
+        if (!line) { return documentArray; } // skip over empty lines
+        var generatedDocument = createDocument(headers, line.trim());
+        return documentArray.concat(generatedDocument);
+    }, []);
 };
 
 module.exports = {
-    
-    // Function to export internally
-    // Takes options as a document, data as a CSV string, and a callback that will be used to report the results
+
+    /**
+     * Internally exported csv2json function
+     * Takes options as a document, data as a CSV string, and a callback that will be used to report the results
+     * @param opts Object options object
+     * @param data String csv string
+     * @param callback Function callback function
+     */
     csv2json: function (opts, data, callback) {
-        if (!callback) { throw new Error(constants.Errors.callbackRequired); } // If a callback wasn't provided, throw an error
-        if (!opts) { return callback(new Error(constants.Errors.optionsRequired)); return null; } // Shouldn't happen, but just in case
-        else { options = opts; } // Options were passed, set the global options value
-        if (!data) { return callback(new Error(constants.Errors.csv2json.cannotCallCsv2JsonOn + data + '.')); return null; } // If we don't receive data, report an error
-        if (!_.isString(data)) { // The data is not a string
+        // If a callback wasn't provided, throw an error
+        if (!callback) { throw new Error(constants.Errors.callbackRequired); }
+
+        // Shouldn't happen, but just in case
+        if (!opts) { return callback(new Error(constants.Errors.optionsRequired)); return null; }
+        options = opts; // Options were passed, set the global options value
+
+        // If we don't receive data, report an error
+        if (!data) { return callback(new Error(constants.Errors.csv2json.cannotCallCsv2JsonOn + data + '.')); return null; }
+
+        // The data provided is not a string
+        if (!_.isString(data)) {
             return callback(new Error(constants.Errors.csv2json.csvNotString)); // Report an error back to the caller
         }
-        var lines = data.split(options.EOL); // Split the CSV into lines using the specified EOL option
-        var json = convertCSV(lines, callback); // Retrieve the JSON document array
-        callback(null, json); // Send the data back to the caller
+
+        // Split the CSV into lines using the specified EOL option
+        var lines = data.split(options.EOL),
+            json = convertCSV(lines, callback); // Retrieve the JSON document array
+        return callback(null, json); // Send the data back to the caller
     }
 
 };