Allow column titles to be specified in the keys option. (#173)

mrodrig · web-flow · commit 78f32f7361e0 · 2020-12-05T01:07:49.000-05:00
* Converts the options object to accept Objects in the keys option property and optionally accept a title property in that Object. If a title property is specified, that will be used to set the column header instead of using the key field name.
diff --git a/README.md b/README.md
@@ -82,10 +82,12 @@ Looking for examples? Check out the Wiki: [json-2-csv Wiki](https://github.com/m
   	* `false` uses the following keys:
   		* `['specifications']`
     * Note: This may result in CSV output that does not map back exactly to the original JSON. See #102 for more information.
-  * `keys` - Array - Specify the keys (as strings) that should be converted. 
-    * 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.
+  * `keys` - Array - Specify the keys (as strings) that should be converted.
+    * Default: These will be auto-detected from your data by default.
+    * Keys can either be specified as a String representing the key path that should be converted, or as an Object with the `key` property specifying the path. When specifying keys as an Object, you can also optionally specify a `title` which will be used for that column in the header. The list specified can contain a combination of Objects and Strings. 
+      * `[ 'key1', 'key2', ... ]`
+      * `[ { key: 'key1', title: 'Key 1' }, { key: 'key2' }, 'key3', ... ]`
+    * Key Paths - If you are converting a nested object (ie. {info : {name: 'Mike'}}), then set this to ['info.name']
   * `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? 
diff --git a/lib/json2csv.js b/lib/json2csv.js
@@ -129,7 +129,12 @@ const Json2Csv = function(options) {
      * @returns {*}
      */
     function generateCsvHeader(params) {
-        params.header = params.headerFields.join(options.delimiter.field);
+        params.header = params.headerFields
+            .map(function(field) {
+                const headerKey = options.fieldTitleMap[field] ? options.fieldTitleMap[field] : field;
+                return wrapFieldValueIfNecessary(headerKey);
+            })
+            .join(options.delimiter.field);
         return params;
     }
 
@@ -140,6 +145,16 @@ const Json2Csv = function(options) {
      * @returns {Promise}
      */
     function retrieveHeaderFields(data) {
+        if (options.keys) {
+            options.keys = options.keys.map((key) => {
+                if (utils.isObject(key) && key.field) {
+                    options.fieldTitleMap[key.field] = key.title || key.field;
+                    return key.field;
+                }
+                return key;
+            });
+        }
+
         if (options.keys && !options.unwindArrays) {
             return Promise.resolve(options.keys)
                 .then(sortHeaderFields);
@@ -157,6 +172,7 @@ const Json2Csv = function(options) {
      *   expandArrayObjects option. If not specified, this passes the params
      *   argument through to the next function in the promise chain.
      * @param params {Object}
+     * @param finalPass {boolean} Used to trigger one last pass to ensure no more arrays need to be expanded
      * @returns {Promise}
      */
     function unwindRecordsIfNecessary(params, finalPass = false) {
diff --git a/lib/utils.js b/lib/utils.js
@@ -38,6 +38,7 @@ module.exports = {
  */
 function buildOptions(opts) {
     opts = {...constants.defaultOptions, ...opts || {}};
+    opts.fieldTitleMap = new Map();
 
     // Copy the delimiter fields over since the spread operator does a shallow copy
     opts.delimiter.field = opts.delimiter.field || constants.defaultOptions.delimiter.field;
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -5,7 +5,7 @@
     },
     "name": "json-2-csv",
     "description": "A JSON to CSV and CSV to JSON converter that natively supports sub-documents and auto-generates the CSV heading.",
-    "version": "3.7.13",
+    "version": "3.8.0",
     "homepage": "https://mrodrig.github.io/json-2-csv",
     "repository": {
         "type": "git",
diff --git a/test/config/testCsvFilesList.js b/test/config/testCsvFilesList.js
@@ -33,6 +33,7 @@ const fs = require('fs'),
         {key: 'unwind', file: '../data/csv/unwind.csv'},
         {key: 'unwindEmptyArray', file: '../data/csv/unwindEmptyArray.csv'},
         {key: 'unwindWithSpecifiedKeys', file: '../data/csv/unwindWithSpecifiedKeys.csv'},
+        {key: 'withSpecifiedKeys', file: '../data/csv/withSpecifiedKeys.csv'},
         {key: 'localeFormat', file: '../data/csv/localeFormat.csv'},
         {key: 'invalidParsedValues', file: '../data/csv/invalidParsedValues.csv'},
         {key: 'firstColumnWrapCRLF', file: '../data/csv/firstColumnWrapCRLF.csv'},
diff --git a/test/data/csv/withSpecifiedKeys.csv b/test/data/csv/withSpecifiedKeys.csv
@@ -0,0 +1,3 @@
+data.category,data.options.name
+Computers,"[""MacBook Pro 15"",""MacBook Air 13""]"
+Cars,"[""Supercharger"",""Turbocharger""]"
diff --git a/test/json2csv.js b/test/json2csv.js
@@ -474,6 +474,76 @@ function runTests(jsonTestData, csvTestData) {
                     done();
                 }, { useDateIso8601Format: true });
             });
+
+            it('should allow keys to be specified without titles', (done) => {
+                converter.json2csv(jsonTestData.unwind, (err, csv) => {
+                    if (err) done(err);
+                    csv.should.equal(csvTestData.unwindWithSpecifiedKeys);
+                    done();
+                }, {
+                    unwindArrays: true,
+                    keys: [
+                        {field: 'data.category'},
+                        'data.options.name'
+                    ]
+                });
+            });
+
+            it('should allow titles to be specified for certain keys, but not others when not unwinding arrays', (done) => {
+                converter.json2csv(jsonTestData.unwind, (err, csv) => {
+                    if (err) done(err);
+                    csv.should.equal(csvTestData.withSpecifiedKeys.replace('data.category,data.options.name', 'Category,data.options.name'));
+                    done();
+                }, {
+                    unwindArrays: false,
+                    keys: [
+                        {field: 'data.category', title: 'Category'},
+                        'data.options.name'
+                    ]
+                });
+            });
+
+            it('should allow titles to be specified for certain keys, but not others', (done) => {
+                converter.json2csv(jsonTestData.unwind, (err, csv) => {
+                    if (err) done(err);
+                    csv.should.equal(csvTestData.unwindWithSpecifiedKeys.replace('data.category,data.options.name', 'Category,data.options.name'));
+                    done();
+                }, {
+                    unwindArrays: true,
+                    keys: [
+                        {field: 'data.category', title: 'Category'},
+                        'data.options.name'
+                    ]
+                });
+            });
+
+            it('should allow titles to be specified', (done) => {
+                converter.json2csv(jsonTestData.unwind, (err, csv) => {
+                    if (err) done(err);
+                    csv.should.equal(csvTestData.withSpecifiedKeys.replace('data.category,data.options.name', 'Category,Option Name'));
+                    done();
+                }, {
+                    unwindArrays: false,
+                    keys: [
+                        {field: 'data.category', title: 'Category'},
+                        {field: 'data.options.name', title: 'Option Name'}
+                    ]
+                });
+            });
+
+            it('should allow titles to be specified when not unwinding arrays', (done) => {
+                converter.json2csv(jsonTestData.unwind, (err, csv) => {
+                    if (err) done(err);
+                    csv.should.equal(csvTestData.unwindWithSpecifiedKeys.replace('data.category,data.options.name', 'Category,Option Name'));
+                    done();
+                }, {
+                    unwindArrays: true,
+                    keys: [
+                        {field: 'data.category', title: 'Category'},
+                        {field: 'data.options.name', title: 'Option Name'}
+                    ]
+                });
+            });
         });
     });
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+data.category,data.options.name`
	`2`	`+Computers,"[""MacBook Pro 15"",""MacBook Air 13""]"`
	`3`	`+Cars,"[""Supercharger"",""Turbocharger""]"`