Add optional value parser (#179)

* Add an option to specify a custom value parser fn.

One of the commonly requested features for both json2csv and csv2json is
the ability to specify a custom value parser function. This
functionality also provides a way to customize the behavior of the
library as well to ensure that custom values are converted correctly
when converting to the other format.

* Add tests for parseValue option.

Author: mrodrig

README.md

@@ -91,6 +91,9 @@ Looking for examples? Check out the Wiki: [json-2-csv Wiki](https://github.com/m
       * `[ 'key1', 'key2', ... ]`
       * `[ { field: 'key1', title: 'Key 1' }, { field: 'key2' }, 'key3', ... ]`
     * Key Paths - If you are converting a nested object (ie. {info : {name: 'Mike'}}), then set this to ['info.name']
+  * `parseValue` - Function - Specify how values should be converted into CSV format. This function is provided a single field value at a time and must return a `String`.
+    * Default: A built-in method is used to parse out a variety of different value types to well-known formats.
+    * Note: Using this option may override other options, including `useDateIso8601Format` and `useLocaleFormat`.
   * `prependHeader` - Boolean - Should the auto-generated header be prepended as the first line in the CSV?
     * Default: `true`
   * `sortHeader` - Boolean - Should the header keys be sorted in alphabetical order? 
@@ -161,6 +164,8 @@ Available in version `2.2.0`, this functionality makes use of promises from the
     * Default: `null`
     * If you have a nested object (ie. `{info : {name: 'Mike'}}`), then set this to `['info.name']`
     * If you want all keys to be converted, then specify `null` or don't specify the option to utilize the default.
+  * `parseValue` - Function - Specify how `String` representations of field values should be parsed when converting back to JSON. This function is provided a single `String` and can return any value.
+    * Default: `JSON.parse` - An attempt is made to convert the String back to its original value using `JSON.parse`.
   * `trimHeaderFields` - Boolean - Should the header fields be trimmed? 
     * Default: `false`
   * `trimFieldValues` - Boolean - Should the field values be trimmed? 

lib/constants.json

@@ -34,7 +34,8 @@
     "expandArrayObjects": false,
     "unwindArrays": false,
     "useDateIso8601Format": false,
-    "useLocaleFormat": false
+    "useLocaleFormat": false,
+    "parseValue": null
   },
 
   "values" : {

lib/csv2json.js

@@ -6,7 +6,8 @@ let path = require('doc-path'),
 
 const Csv2Json = function(options) {
     const escapedWrapDelimiterRegex = new RegExp(options.delimiter.wrap + options.delimiter.wrap, 'g'),
-        excelBOMRegex = new RegExp('^' + constants.values.excelBOM);
+        excelBOMRegex = new RegExp('^' + constants.values.excelBOM),
+        valueParserFn = options.parseValue && typeof options.parseValue === 'function' ? options.parseValue : JSON.parse;
 
     /**
      * Trims the header key, if specified by the user via the provided options
@@ -355,7 +356,7 @@ const Csv2Json = function(options) {
                 return value;
             }
 
-            let parsedJson = JSON.parse(value);
+            let parsedJson = valueParserFn(value);
 
             // If the parsed value is an array, then we also need to trim record values, if specified
             if (Array.isArray(parsedJson)) {

lib/json2csv.js

@@ -8,6 +8,7 @@ let path = require('doc-path'),
 const Json2Csv = function(options) {
     const wrapDelimiterCheckRegex = new RegExp(options.delimiter.wrap, 'g'),
         crlfSearchRegex = /\r?\n|\r/,
+        valueParserFn = options.parseValue && typeof options.parseValue === 'function' ? options.parseValue : recordFieldValueToString,
         expandingWithoutUnwinding = options.expandArrayObjects && !options.unwindArrays,
         deeksOptions = {
             expandArrayObjects: expandingWithoutUnwinding,
@@ -246,7 +247,7 @@ const Json2Csv = function(options) {
                 // Process the data in this record and return the
                 processedRecordData = recordFieldData.map((fieldValue) => {
                     fieldValue = trimRecordFieldValue(fieldValue);
-                    fieldValue = recordFieldValueToString(fieldValue);
+                    fieldValue = valueParserFn(fieldValue);
                     fieldValue = wrapFieldValueIfNecessary(fieldValue);
 
                     return fieldValue;

test/csv2json.js

@@ -385,6 +385,25 @@ function runTests(jsonTestData, csvTestData) {
                     keys: ['arrayOfStrings', 'object.subField']
                 });
             });
+
+            it('should use a custom value parser function when provided', (done) => {
+                let updatedJson = jsonTestData.trimmedFields.map((doc) => {
+                    doc.arrayOfStrings = 'Parsed Value';
+                    doc.object.subField = 'Parsed Value';
+                    doc.number = 'Parsed Value';
+                    doc.isBoolean = 'Parsed Value';
+                    doc.optionalField = 'Parsed Value';
+                    return doc;
+                });
+
+                converter.csv2json(csvTestData.trimmedFields, (err, json) => {
+                    if (err) done(err);
+                    json.should.deepEqual(updatedJson);
+                    done();
+                }, {
+                    parseValue: () => 'Parsed Value'
+                });
+            });
         });
     });
 

test/json2csv.js

@@ -594,6 +594,22 @@ function runTests(jsonTestData, csvTestData) {
                     excludeKeys: ['data.options.name']
                 });
             });
+
+            it('should use a custom value parser function when provided', (done) => {
+                let updatedCsv = csvTestData.trimmedFields.split('\n');
+                const textRow = 'Parsed Value,Parsed Value,Parsed Value,Parsed Value,Parsed Value';
+                updatedCsv[1] = textRow;
+                updatedCsv[2] = textRow;
+                updatedCsv = updatedCsv.join('\n');
+
+                converter.json2csv(jsonTestData.trimmedFields, (err, csv) => {
+                    if (err) done(err);
+                    csv.should.equal(updatedCsv);
+                    done();
+                }, {
+                    parseValue: () => 'Parsed Value'
+                });
+            });
         });
     });