convert-csv-to-json 4.46.0 → 4.48.0

package/src/csvToJson.js

@@ -8,7 +8,9 @@ const {
     ConfigurationError,
     CsvFormatError,
     JsonValidationError
-} = require('./util/errors');
+} = require('./core/errors');
+const Configurable = require('./core/configurable');
+const ParserConfig = require('./core/parserConfig');
 
 const DEFAULT_FIELD_DELIMITER = ",";
 const QUOTE_CHAR = '"';
@@ -21,114 +23,52 @@ const CR = '\r';
  * Provides chainable API for configuring and converting CSV data
  * @category 2-Sync 
  */
-class CsvToJson {
+class CsvToJson extends Configurable {
 
   /**
-   * Enable or disable automatic type formatting for values
-   * When enabled, numeric strings are converted to numbers, 'true'/'false' to booleans
-   * @param {boolean} active - Whether to format values by type
-   * @returns {this} For method chaining
-   */
-  formatValueByType(active) {
-    this.printValueFormatByType = active;
-    return this;
-  }
-
-  /**
-   * Enable or disable support for RFC 4180 quoted fields
-   * When enabled, fields wrapped in double quotes can contain delimiters and newlines
-   * @param {boolean} active - Whether to support quoted fields
-   * @returns {this} For method chaining
-   */
-  supportQuotedField(active) {
-    this.isSupportQuotedField = active;
-    return this;
-  }
-
-  /**
-   * Set the field delimiter character
-   * @param {string} delimiter - Character(s) to use as field separator (default: ',')
-   * @returns {this} For method chaining
+   * Parse CSV content using a frozen configuration snapshot.
+   * @param {string} parsedCsv - Raw CSV content as string
+   * @param {ParserConfig} config - Frozen parser configuration
+   * @returns {Array<object>} Parsed JSON array
    */
-  fieldDelimiter(delimiter) {
-    this.delimiter = delimiter;
-    return this;
-  }
+  csvToJsonWithConfig(parsedCsv, config) {
+    this.validateInputConfig(config);
 
-  /**
-   * Configure whitespace handling in header field names
-   * @param {boolean} active - If true, removes all whitespace from header names; if false, only trims edges
-   * @returns {this} For method chaining
-   */
-  trimHeaderFieldWhiteSpace(active) {
-    this.isTrimHeaderFieldWhiteSpace = active;
-    return this;
-  }
+    const records = this.parseRecords(parsedCsv);
+    const fieldDelimiter = this.getFieldDelimiter(config);
+    let index = this.getIndexHeader(config);
+    let headers;
 
-  /**
-   * Set the row index where CSV headers are located
-   * @param {number} indexHeaderValue - Zero-based row index containing headers
-   * @returns {this} For method chaining
-   * @throws {ConfigurationError} If not a valid number
-   */
-  indexHeader(indexHeaderValue) {
-    if (isNaN(indexHeaderValue)) {
-      throw ConfigurationError.invalidHeaderIndex(indexHeaderValue);
+    while (index < records.length) {
+      headers = this.getFields(records[index], config, fieldDelimiter);
+      if (stringUtils.hasContent(headers)) {
+        break;
+      }
+      index++;
     }
-    this.indexHeaderValue = indexHeaderValue;
-    return this;
-  }
-
-
-  /**
-   * Configure sub-array parsing for special field values
-   * Fields bracketed by delimiter and containing separator are parsed into arrays
-   * @param {string} delimiter - Bracket character (default: '*')
-   * @param {string} separator - Item separator within brackets (default: ',')
-   * @returns {this} For method chaining
-   * @example
-   * // Input: "*val1,val2,val3*"  
-   * // Output: ["val1", "val2", "val3"]
-   * .parseSubArray('*', ',')
-   */
-  parseSubArray(delimiter = '*',separator = ',') {
-    this.parseSubArrayDelimiter = delimiter;
-    this.parseSubArraySeparator = separator;
-    return this;
-  }
 
-  /**
-   * Set file encoding for reading CSV files
-   * @param {string} encoding - Node.js supported encoding (e.g., 'utf8', 'latin1', 'ascii')
-   * @returns {this} For method chaining
-   */
-  encoding(encoding){
-    this.encoding = encoding;
-    return this;
-  }
-
-  /**
-   * Configure columns to exclude from output
-   * @param {Array<number>} indexes - Column indexes to ignore
-   * @returns {this} For method chaining
-   * @private Used internally after validation in index.js
-   */
-  ignoreColumnIndexes(indexes) {
-    this.indexesToIgnore = new Set(indexes);
-    return this;
-  }
+    if (!headers) {
+      throw CsvFormatError.missingHeader();
+    }
 
-  /**
-   * Sets a mapper function to transform each row after conversion
-   * @param {function(object, number): (object|null)} mapperFn - Function that receives (row, index) and returns transformed row or null to filter out
-   * @returns {this} For method chaining
-   */
-  mapRows(mapperFn) {
-    if (typeof mapperFn !== 'function') {
-      throw new TypeError('mapperFn must be a function');
+    const jsonResult = [];
+    for (let i = index + 1; i < records.length; i++) {
+      const currentLine = this.getFields(records[i], config, fieldDelimiter);
+
+      if (stringUtils.hasContent(currentLine)) {
+        let row = this.buildJsonResult(headers, currentLine, config);
+        if (config.rowMapper) {
+          row = config.rowMapper(row, i - (index + 1));
+          if (row != null) {
+            jsonResult.push(row);
+          }
+        } else {
+          jsonResult.push(row);
+        }
+      }
     }
-    this.rowMapper = mapperFn;
-    return this;
+
+    return jsonResult;
   }
 
   /**
@@ -174,7 +114,8 @@ class CsvToJson {
    * console.log(rows);
    */
   getJsonFromCsv(fileInputName) {
-    let parsedCsv = fileUtils.readFile(fileInputName, this.encoding);
+    const config = this.getParserConfig();
+    const parsedCsv = fileUtils.readFile(fileInputName, config.encoding || 'utf8');
     return this.csvToJson(parsedCsv);
   }
 
@@ -219,58 +160,7 @@ class CsvToJson {
    * @private
    */
   csvToJson(parsedCsv) {
-  	this.validateInputConfig();
-    
-    // Parse CSV into individual records, respecting quoted fields that may contain newlines
-    let records = this.parseRecords(parsedCsv);
-    
-    let fieldDelimiter = this.getFieldDelimiter();
-    let index = this.getIndexHeader();
-    let headers;
-    
-    // Find the header row
-    while (index < records.length) {
-      if (this.isSupportQuotedField) {
-        headers = this.split(records[index]);
-      } else {
-        headers = records[index].split(fieldDelimiter);
-      }
-      
-      if (stringUtils.hasContent(headers)) {
-        break;
-      }
-      index++;
-    }
-    
-    if (!headers) {
-      throw CsvFormatError.missingHeader();
-    }
-
-    let jsonResult = [];
-    for (let i = (index + 1); i < records.length; i++) {
-        let currentLine;
-        if (this.isSupportQuotedField) {
-            currentLine = this.split(records[i]);
-        } else {
-            currentLine = records[i].split(fieldDelimiter);
-        }
-        
-        if (stringUtils.hasContent(currentLine)) {
-            let row = this.buildJsonResult(headers, currentLine);
-            
-            // Apply row mapper if defined
-            if (this.rowMapper) {
-              row = this.rowMapper(row, i - (index + 1)); // Pass row and 0-based row index
-              // If mapper returns null/undefined, skip this row (allows filtering)
-              if (row != null) {
-                jsonResult.push(row);
-              }
-            } else {
-              jsonResult.push(row);
-            }
-        }
-    }
-    return jsonResult;
+    return this.csvToJsonWithConfig(parsedCsv, this.getParserConfig());
   }
 
   /**
@@ -353,51 +243,71 @@ class CsvToJson {
 
   /**
    * Get the configured field delimiter, or default if not set
+   * @param {ParserConfig} [config] - Parser configuration
    * @returns {string} Field delimiter character
    * @private
    */
-  getFieldDelimiter() {
-    if (this.delimiter) {
-      return this.delimiter;
+  getFieldDelimiter(config = this.config) {
+    if (config.delimiter) {
+      return config.delimiter;
     }
     return DEFAULT_FIELD_DELIMITER;
   }
 
   /**
    * Get the configured header row index, or default (0) if not set
+   * @param {ParserConfig} [config] - Parser configuration
    * @returns {number} Header row index
    * @private
    */
-  getIndexHeader(){
-    if(this.indexHeaderValue !== null && !isNaN(this.indexHeaderValue)){
-        return this.indexHeaderValue;
+  getIndexHeader(config = this.config) {
+    if (config.indexHeaderValue !== null && !isNaN(config.indexHeaderValue)) {
+      return config.indexHeaderValue;
     }
     return 0;
   }
 
+  /**
+   * Get fields for a CSV record line according to configured parser rules.
+   * Uses quoted-field splitting when RFC 4180 support is enabled.
+   * @param {string} line - CSV record line
+   * @param {ParserConfig} [config] - Parser configuration
+   * @param {string} [fieldDelimiter] - Field delimiter
+   * @returns {string[]} Parsed fields
+   * @private
+   */
+  getFields(line, config = this.config, fieldDelimiter = this.getFieldDelimiter(config)) {
+    if (config.isSupportQuotedField) {
+      return this.split(line, config);
+    }
+    return line.split(fieldDelimiter);
+  }
+
   /**
    * Build a JSON object from headers and field values
    * Applies type formatting and sub-array parsing as configured
    * @param {string[]} headers - Array of header field names
    * @param {string[]} currentLine - Array of field values
+   * @param {ParserConfig} [config] - Frozen parser configuration
    * @returns {object} JSON object with header names as keys
    * @private
    */
-  buildJsonResult(headers, currentLine) {
+  buildJsonResult(headers, currentLine, config = this.config) {
     let jsonObject = {};
+    const ignoredIndexes = config.indexesToIgnore ? new Set(config.indexesToIgnore) : new Set();
     for (let j = 0; j < headers.length; j++) {
-      if (this.indexesToIgnore?.has(j)) {
+      if (ignoredIndexes.has(j)) {
         continue;
       }
 
-      let propertyName = stringUtils.trimPropertyName(this.isTrimHeaderFieldWhiteSpace, headers[j]);
+      let propertyName = stringUtils.trimPropertyName(config.isTrimHeaderFieldWhiteSpace, headers[j]);
       let value = currentLine[j];
 
-      if(this.isParseSubArray(value)){
-        value = this.buildJsonSubArray(value);
+      if (this.isParseSubArray(value, config)) {
+        value = this.buildJsonSubArray(value, config);
       }
 
-      if (this.printValueFormatByType && !Array.isArray(value)) {
+      if (config.printValueFormatByType && !Array.isArray(value)) {
         value = stringUtils.getValueFormatByType(currentLine[j]);
       }
 
@@ -409,18 +319,19 @@ class CsvToJson {
   /**
    * Parse a field value into a sub-array using configured delimiter and separator
    * @param {string} value - Field value to parse
+   * @param {ParserConfig} [config] - Frozen parser configuration
    * @returns {Array<string|number|boolean>} Array of parsed values
    * @private
    */
-  buildJsonSubArray(value) {
+  buildJsonSubArray(value, config = this.config) {
     let extractedValues = value.substring(
-        value.indexOf(this.parseSubArrayDelimiter) + 1,
-        value.lastIndexOf(this.parseSubArrayDelimiter)
+        value.indexOf(config.parseSubArrayDelimiter) + 1,
+        value.lastIndexOf(config.parseSubArrayDelimiter)
     );
     extractedValues.trim();
-    value = extractedValues.split(this.parseSubArraySeparator);
-    if(this.printValueFormatByType){
-      for(let i=0; i < value.length; i++){
+    value = extractedValues.split(config.parseSubArraySeparator);
+    if (config.printValueFormatByType) {
+      for (let i = 0; i < value.length; i++) {
         value[i] = stringUtils.getValueFormatByType(value[i]);
       }
     }
@@ -430,12 +341,13 @@ class CsvToJson {
   /**
    * Check if a field value should be parsed as a sub-array
    * @param {string} value - Field value to check
+   * @param {ParserConfig} [config] - Frozen parser configuration
    * @returns {boolean} True if value is bracketed with sub-array delimiter
    * @private
    */
-  isParseSubArray(value){
-    if(this.parseSubArrayDelimiter){
-      if (value && (value.indexOf(this.parseSubArrayDelimiter) === 0 && value.lastIndexOf(this.parseSubArrayDelimiter) === (value.length - 1))) {
+  isParseSubArray(value, config = this.config) {
+    if (config.parseSubArrayDelimiter) {
+      if (value && (value.indexOf(config.parseSubArrayDelimiter) === 0 && value.lastIndexOf(config.parseSubArrayDelimiter) === (value.length - 1))) {
         return true;
       }
     }
@@ -444,18 +356,19 @@ class CsvToJson {
 
   /**
    * Validate configuration for conflicts and incompatibilities
+   * @param {ParserConfig} [config] - Parser configuration
    * @throws {ConfigurationError} If incompatible options are set
    * @private
    */
-  validateInputConfig(){
-    if(this.isSupportQuotedField) {
-      if(this.getFieldDelimiter() === '"'){
+  validateInputConfig(config = this.config) {
+    if (config.isSupportQuotedField) {
+      if (this.getFieldDelimiter(config) === '"') {
         throw ConfigurationError.quotedFieldConflict('fieldDelimiter', '"');
       }
-      if(this.parseSubArraySeparator === '"'){
+      if (config.parseSubArraySeparator === '"') {
         throw ConfigurationError.quotedFieldConflict('parseSubArraySeparator', '"');
       }
-      if(this.parseSubArrayDelimiter === '"'){
+      if (config.parseSubArrayDelimiter === '"') {
         throw ConfigurationError.quotedFieldConflict('parseSubArrayDelimiter', '"');
       }
     }
@@ -478,9 +391,10 @@ class CsvToJson {
    * - Escaped quotes (double quotes within quoted fields)
    * - Empty quoted fields
    * @param {string} line - A single CSV record line
+   * @param {ParserConfig} [config] - Parser configuration
    * @returns {string[]} Array of field values
    */
-  split(line) {
+  split(line, config = this.config) {
     if (line.length === 0) {
       return [];
     }
@@ -488,7 +402,7 @@ class CsvToJson {
     let fields = [];
     let currentField = '';
     let insideQuotes = false;
-    let delimiter = this.getFieldDelimiter();
+    let delimiter = this.getFieldDelimiter(config);
     
     for (let i = 0; i < line.length; i++) {
       let char = line[i];
@@ -568,3 +482,4 @@ class CsvToJson {
 }
 
 module.exports = new CsvToJson();
+module.exports.CsvToJson = CsvToJson;

package/src/csvToJsonAsync.js

@@ -3,115 +3,24 @@
 
 const fileUtils = require('./util/fileUtils');
 const csvToJson = require('./csvToJson');
-const { InputValidationError } = require('./util/errors');
-const StreamProcessor = require('./streamProcessor');
+const Configurable = require('./core/configurable');
+const { InputValidationError } = require('./core/errors');
+const StreamProcessor = require('./core/streamProcessor');
 
 /**
  * Asynchronous CSV to JSON converter
- * Proxies configuration to sync instance but provides async file I/O methods
+ * Provides async file I/O methods and isolated parser configuration
  * @category 3-Async
  */
-class CsvToJsonAsync {
+class CsvToJsonAsync extends Configurable {
     /**
      * Constructor initializes proxy to sync csvToJson instance
      */
     constructor() {
-        // Proxy the configuration methods to the sync instance
+        super();
         this.csvToJson = csvToJson;
     }
 
-    /**
-     * Enable or disable automatic type formatting for values
-     * @param {boolean} active - Whether to format values by type
-     * @returns {this} For method chaining
-     */
-    formatValueByType(active) {
-        this.csvToJson.formatValueByType(active);
-        return this;
-    }
-
-    /**
-     * Enable or disable support for RFC 4180 quoted fields
-     * @param {boolean} active - Whether to support quoted fields
-     * @returns {this} For method chaining
-     */
-    supportQuotedField(active) {
-        this.csvToJson.supportQuotedField(active);
-        return this;
-    }
-
-    /**
-     * Set the field delimiter character
-     * @param {string} delimiter - Character(s) to use as field separator
-     * @returns {this} For method chaining
-     */
-    fieldDelimiter(delimiter) {
-        this.csvToJson.fieldDelimiter(delimiter);
-        return this;
-    }
-
-    /**
-     * Configure whitespace handling in header field names
-     * @param {boolean} active - If true, removes all whitespace; if false, only trims edges
-     * @returns {this} For method chaining
-     */
-    trimHeaderFieldWhiteSpace(active) {
-        this.csvToJson.trimHeaderFieldWhiteSpace(active);
-        return this;
-    }
-
-    /**
-     * Set the row index where CSV headers are located
-     * @param {number} indexHeader - Zero-based row index containing headers
-     * @returns {this} For method chaining
-     */
-    indexHeader(indexHeader) {
-        this.csvToJson.indexHeader(indexHeader);
-        return this;
-    }
-
-    /**
-     * Configure sub-array parsing for special field values
-     * @param {string} delimiter - Bracket character (default: '*')
-     * @param {string} separator - Item separator within brackets (default: ',')
-     * @returns {this} For method chaining
-     */
-    parseSubArray(delimiter = '*', separator = ',') {
-        this.csvToJson.parseSubArray(delimiter, separator);
-        return this;
-    }
-
-    /**
-     * Set a mapper function to transform each row after conversion
-     * @param {function(object, number): (object|null)} mapperFn - Function receiving (row, index) that returns transformed row or null to filter
-     * @returns {this} For method chaining
-     */
-    mapRows(mapperFn) {
-        this.csvToJson.mapRows(mapperFn);
-        return this;
-    }
-
-    /**
-     * Set file encoding for reading CSV files
-     * @param {string} encoding - Node.js supported encoding (e.g., 'utf8', 'latin1')
-     * @returns {this} For method chaining
-     */
-    encoding(encoding) {
-        this.csvToJson.encoding = encoding;
-        return this;
-    }
-
-    /**
-     * Configure columns to exclude from output
-     * @param {Array<number>} indexes - Column indexes to ignore
-     * @returns {this} For method chaining
-     * @private Used internally after validation in index.js
-     */
-    ignoreColumnIndexes(indexes) {
-        this.csvToJson.ignoreColumnIndexes(indexes);
-        return this;
-    }
-
     /**
      * Read a CSV file and write parsed JSON to an output file (async)
      * @param {string} fileInputName - Path to input CSV file
@@ -162,15 +71,17 @@ class CsvToJsonAsync {
             );
         }
 
+        const config = this.getParserConfig();
+
         if (options.raw) {
             if (inputFileNameOrCsv === '') {
                 return [];
             }
-            return this.csvToJson.csvToJson(inputFileNameOrCsv);
+            return this.csvToJson.csvToJsonWithConfig(inputFileNameOrCsv, config);
         }
 
-        const parsedCsv = await fileUtils.readFileAsync(inputFileNameOrCsv, this.csvToJson.encoding || 'utf8');
-        return this.csvToJson.csvToJson(parsedCsv);
+        const parsedCsv = await fileUtils.readFileAsync(inputFileNameOrCsv, config.encoding || 'utf8');
+        return this.csvToJson.csvToJsonWithConfig(parsedCsv, config);
     }
 
     /**
@@ -205,7 +116,8 @@ class CsvToJsonAsync {
     async getJsonFromStreamAsync(stream) {
         this._validateStream(stream);
 
-        const streamProcessor = new StreamProcessor(this.csvToJson, { isBrowser: false });
+        const config = this.getParserConfig();
+        const streamProcessor = new StreamProcessor(config, { isBrowser: false });
         return streamProcessor.processStream(stream);
     }
 
@@ -249,7 +161,8 @@ class CsvToJsonAsync {
         }
 
         const fs = require('fs');
-        const encoding = typeof this.csvToJson.encoding === 'string' ? this.csvToJson.encoding : 'utf8';
+        const config = this.getParserConfig();
+        const encoding = typeof config.encoding === 'string' ? config.encoding : 'utf8';
         const stream = fs.createReadStream(filePath, { encoding });
         return this.getJsonFromStreamAsync(stream);
     }