Merge pull request #248 from mrodrig/feat/add-escapeNestedDots-option

Add escapeHeaderNestedDots option

Author: mrodrig

README.md

@@ -62,6 +62,27 @@ Returns the CSV `string` or rejects with an `Error` if there was an issue.
       * Default: `\n`
   * `emptyFieldValue` - Any - Value that, if specified, will be substituted in for field values that are `undefined`, `null`, or an empty string.
     * Default: none
+  * `escapeHeaderNestedDots` - Boolean - Should nested dots in header keys be escaped?
+    * Default: `true`
+    * Example:
+    ```json
+    [
+      {
+        "a.a": "1"
+      }
+    ]
+    ```
+      * `true` will generate the following CSV:
+      ```csv
+      a\.a
+      1
+      ```
+      * `false` will generate the following CSV:
+      ```csv
+      a.a
+      1
+      ```
+    * Note: This may result in CSV output that does not map back exactly to the original JSON.
   * `excelBOM` - Boolean - Should a unicode character be prepended to allow Excel to open a UTF-8 encoded file with non-ASCII characters present.
   * `excludeKeys` - Array - Specify the keys that should be excluded from the output. Provided keys will also be used as a RegExp to help exclude keys under a specified prefix, such as all keys of Objects in an Array when `expandArrayObjects` is `true`.
     * Default: `[]`

src/constants.ts

@@ -25,6 +25,7 @@ export const defaultJson2CsvOptions: DefaultJson2CsvOptions = {
         eol   : '\n'
     },
     emptyFieldValue: undefined,
+    escapeHeaderNestedDots: true,
     excelBOM: false,
     excludeKeys: [],
     expandNestedObjects: true,

src/json2csv.ts

@@ -15,7 +15,7 @@ export const Json2Csv = function(options: FullJson2CsvOptions) {
             expandNestedObjects: options.expandNestedObjects,
             expandArrayObjects: expandingWithoutUnwinding,
             ignoreEmptyArraysWhenExpanding: expandingWithoutUnwinding,
-            escapeNestedDots: true
+            escapeNestedDots: true,
         };
 
     /** HEADER FIELD FUNCTIONS **/
@@ -144,7 +144,16 @@ export const Json2Csv = function(options: FullJson2CsvOptions) {
 
         params.header = params.headerFields
             .map(function(field) {
-                const headerKey = fieldTitleMapKeys.includes(field) ? options.fieldTitleMap[field] : field;
+                let headerKey = field;
+
+                // If a custom field title was provided for this field, use that
+                if (fieldTitleMapKeys.includes(field)) {
+                    headerKey = options.fieldTitleMap[field];
+                } else if (!options.escapeHeaderNestedDots) { 
+                    // Otherwise, if the user doesn't want nested dots in keys to be escaped, then unescape them
+                    headerKey = headerKey.replace(/\\\./g, '.');
+                }
+
                 return wrapFieldValueIfNecessary(headerKey);
             })
             .join(options.delimiter.field);

src/types.ts

@@ -98,6 +98,12 @@ export interface Json2CsvOptions extends SharedConverterOptions {
    */
   emptyFieldValue?: unknown;
 
+  /**
+   * Should dots (`.`) appearing in header keys be escaped with a preceding slash (`\`)?
+   * @default true
+   */
+  escapeHeaderNestedDots?: boolean;
+
   /**
    *  Should nested objects be deep-converted to CSV
    *  @default true

test/json2csv.ts

@@ -523,6 +523,18 @@ export function runTests() {
                 assert.equal(csv, csvTestData.excludeKeyPattern);
             });
 
+            // Test case for #245
+            it('should not escape nested dots in keys with nested dots in them if turned on via the option', () => {
+                const csv = json2csv(jsonTestData.nestedDotKeys, { escapeHeaderNestedDots: true }); // Default option value
+                assert.equal(csv, csvTestData.nestedDotKeys);
+            });
+
+            // Test case for #245
+            it('should not escape nested dots in keys with nested dots in them if turned off via the option', () => {
+                const csv = json2csv(jsonTestData.nestedDotKeys, { escapeHeaderNestedDots: false });
+                assert.equal(csv, csvTestData.nestedDotKeys.replace(/\\\./g, '.'));
+            });
+
             it('should use a custom value parser function when provided', () => {
                 const updatedCsv = csvTestData.trimmedFields.split('\n');
                 const textRow = 'Parsed Value,Parsed Value,Parsed Value,Parsed Value,Parsed Value';