convert-csv-to-json 3.28.0 → 4.1.0

package/src/csvToJson.js

@@ -1,11 +1,19 @@
 "use strict";
 
-let fileUtils = require("././util/fileUtils");
-let stringUtils = require("././util/stringUtils");
-let jsonUtils = require("././util/jsonUtils");
-
-const newLine = /\r?\n/;
-const defaultFieldDelimiter = ";";
+const fileUtils = require('./util/fileUtils');
+const stringUtils = require('./util/stringUtils');
+const jsonUtils = require('./util/jsonUtils');
+const {
+    ConfigurationError,
+    CsvFormatError,
+    JsonValidationError
+} = require('./util/errors');
+
+const DEFAULT_FIELD_DELIMITER = ",";
+const QUOTE_CHAR = '"';
+const CRLF = '\r\n';
+const LF = '\n';
+const CR = '\r';
 
 class CsvToJson {
 
@@ -30,8 +38,8 @@ class CsvToJson {
   }
 
   indexHeader(indexHeaderValue) {
-    if(isNaN(indexHeaderValue)){
-        throw new Error('The index Header must be a Number!');
+    if (isNaN(indexHeaderValue)) {
+      throw ConfigurationError.invalidHeaderIndex(indexHeaderValue);
     }
     this.indexHeaderValue = indexHeaderValue;
     return this;
@@ -48,6 +56,19 @@ class CsvToJson {
     return this;
   }
 
+  /**
+   * Sets a mapper function to transform each row after conversion
+   * @param {Function} 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');
+    }
+    this.rowMapper = mapperFn;
+    return this;
+  }
+
   generateJsonFileFromCsv(fileInputName, fileOutputName) {
     let jsonStringified = this.getJsonFromCsvStringified(fileInputName);
     fileUtils.writeFile(jsonStringified, fileOutputName);
@@ -78,43 +99,142 @@ class CsvToJson {
 
   csvToJson(parsedCsv) {
   	this.validateInputConfig();
-    let lines = parsedCsv.split(newLine);
+    
+    // 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;
     
-    if(this.isSupportQuotedField){
-      headers = this.split(lines[index]);
-    } else {
-      headers = lines[index].split(fieldDelimiter);
+    // 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++;
     }
     
-    while(!stringUtils.hasContent(headers) && index <= lines.length){
-        index = index + 1;
-        headers = lines[index].split(fieldDelimiter);
+    if (!headers) {
+      throw CsvFormatError.missingHeader();
     }
 
     let jsonResult = [];
-    for (let i = (index + 1); i < lines.length; i++) {
+    for (let i = (index + 1); i < records.length; i++) {
         let currentLine;
-        if(this.isSupportQuotedField){
-            currentLine = this.split(lines[i]);
-        }
-        else{
-            currentLine = lines[i].split(fieldDelimiter);
+        if (this.isSupportQuotedField) {
+            currentLine = this.split(records[i]);
+        } else {
+            currentLine = records[i].split(fieldDelimiter);
         }
+        
         if (stringUtils.hasContent(currentLine)) {
-            jsonResult.push(this.buildJsonResult(headers, 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;
   }
 
+  /**
+   * Parse CSV content into individual records, respecting quoted fields that may span multiple lines.
+   * RFC 4180 compliant parsing - handles quoted fields that may contain newlines.
+   * @param {string} csvContent - The raw CSV content
+   * @returns {string[]} Array of record strings
+   */
+  parseRecords(csvContent) {
+    let records = [];
+    let currentRecord = '';
+    let insideQuotes = false;
+    let i = 0;
+    
+    while (i < csvContent.length) {
+      let char = csvContent[i];
+      
+      // Handle quote characters
+      if (char === QUOTE_CHAR) {
+        if (insideQuotes && i + 1 < csvContent.length && csvContent[i + 1] === QUOTE_CHAR) {
+          // Escaped quote: two consecutive quotes = single quote representation
+          currentRecord += QUOTE_CHAR + QUOTE_CHAR;
+          i += 2;
+        } else {
+          // Toggle quote state
+          insideQuotes = !insideQuotes;
+          currentRecord += char;
+          i++;
+        }
+        continue;
+      }
+      
+      // Handle line endings (only outside quoted fields)
+      if (!insideQuotes) {
+        let lineEndingLength = this.getLineEndingLength(csvContent, i);
+        if (lineEndingLength > 0) {
+          records.push(currentRecord);
+          currentRecord = '';
+          i += lineEndingLength;
+          continue;
+        }
+      }
+      
+      // Regular character
+      currentRecord += char;
+      i++;
+    }
+    
+    // Add the last record if not empty
+    if (currentRecord.length > 0) {
+      records.push(currentRecord);
+    }
+    
+    // Validate matching quotes
+    if (insideQuotes) {
+      throw CsvFormatError.mismatchedQuotes('CSV');
+    }
+    
+    return records;
+  }
+
+  /**
+   * Get the length of line ending at current position (CRLF=2, LF=1, CR=1, or 0)
+   * @param {string} content - CSV content
+   * @param {number} index - Current index to check
+   * @returns {number} Length of line ending (0 if none)
+   */
+  getLineEndingLength(content, index) {
+    if (content.slice(index, index + 2) === CRLF) {
+      return 2;
+    }
+    if (content[index] === LF) {
+      return 1;
+    }
+    if (content[index] === CR && content[index + 1] !== LF) {
+      return 1;
+    }
+    return 0;
+  }
+
   getFieldDelimiter() {
     if (this.delimiter) {
       return this.delimiter;
     }
-    return defaultFieldDelimiter;
+    return DEFAULT_FIELD_DELIMITER;
   }
 
   getIndexHeader(){
@@ -168,74 +288,105 @@ class CsvToJson {
   }
 
   validateInputConfig(){
-  	if(this.isSupportQuotedField) {
-  	 	if(this.getFieldDelimiter() === '"'){
-  	 		throw new Error('When SupportQuotedFields is enabled you cannot defined the field delimiter as quote -> ["]');
-  	 	}
-  	 	if(this.parseSubArraySeparator === '"'){
-  	 		throw new Error('When SupportQuotedFields is enabled you cannot defined the field parseSubArraySeparator as quote -> ["]');
-  	 	}
-  	 	if(this.parseSubArrayDelimiter === '"'){
-  	 		throw new Error('When SupportQuotedFields is enabled you cannot defined the field parseSubArrayDelimiter as quote -> ["]');
-  	 	}
-  	}
+    if(this.isSupportQuotedField) {
+      if(this.getFieldDelimiter() === '"'){
+        throw ConfigurationError.quotedFieldConflict('fieldDelimiter', '"');
+      }
+      if(this.parseSubArraySeparator === '"'){
+        throw ConfigurationError.quotedFieldConflict('parseSubArraySeparator', '"');
+      }
+      if(this.parseSubArrayDelimiter === '"'){
+        throw ConfigurationError.quotedFieldConflict('parseSubArrayDelimiter', '"');
+      }
+    }
   }
 
   hasQuotes(line) {
     return line.includes('"');
   }
 
+  /**
+   * Split a CSV record line into fields, respecting quoted fields per RFC 4180.
+   * Handles:
+   * - Quoted fields with embedded delimiters and newlines
+   * - Escaped quotes (double quotes within quoted fields)
+   * - Empty quoted fields
+   * @param {string} line - A single CSV record line
+   * @returns {string[]} Array of field values
+   */
   split(line) {
-    if(line.length == 0){
+    if (line.length === 0) {
       return [];
     }
-    let delim = this.getFieldDelimiter();
-    let subSplits = [''];
-    if (this.hasQuotes(line)) {
-        let chars = line.split('');
-
-        let subIndex = 0;
-        let startQuote = false;
-        let isDouble = false;
-        chars.forEach((c, i, arr) => {
-            if (isDouble) { //when run into double just pop it into current and move on
-                subSplits[subIndex] += c;
-                isDouble = false;
-                return;
-            }
-
-            if (c != '"' && c != delim ) {
-                subSplits[subIndex] += c;
-            } else if(c == delim && startQuote){
-                subSplits[subIndex] += c;
-            } else if( c == delim ){
-                subIndex++
-                subSplits[subIndex] = '';
-                return;
-            } else {
-                if (arr[i + 1] === '"') {
-                    //Double quote
-                    isDouble = true;
-                    //subSplits[subIndex] += c; //Skip because this is escaped quote
-                } else {
-                    if (!startQuote) {
-                        startQuote = true;
-                        //subSplits[subIndex] += c; //Skip because we don't want quotes wrapping value
-                    } else {
-                        //end
-                        startQuote = false;
-                        //subSplits[subIndex] += c; //Skip because we don't want quotes wrapping value
-                    }
-                }
-            }
-        });
-        if(startQuote){
-            throw new Error('Row contains mismatched quotes!');
+    
+    let fields = [];
+    let currentField = '';
+    let insideQuotes = false;
+    let delimiter = this.getFieldDelimiter();
+    
+    for (let i = 0; i < line.length; i++) {
+      let char = line[i];
+      
+      // Handle quote character
+      if (char === QUOTE_CHAR) {
+        if (this.isEscapedQuote(line, i, insideQuotes)) {
+          // Two consecutive quotes inside quoted field = escaped quote
+          currentField += QUOTE_CHAR;
+          i++; // Skip next quote
+        } else if (this.isEmptyQuotedField(line, i, insideQuotes, currentField, delimiter)) {
+          // Empty quoted field: "" at field start before delimiter/end
+          i++; // Skip closing quote
+        } else {
+          // Regular quote: toggle quoted state
+          insideQuotes = !insideQuotes;
         }
-        return subSplits;
-    } else {
-        return line.split(delim);
+      } else if (char === delimiter && !insideQuotes) {
+        // Delimiter outside quotes marks field boundary
+        fields.push(currentField);
+        currentField = '';
+      } else {
+        // Regular character (including embedded newlines in quoted fields)
+        currentField += char;
+      }
+    }
+    
+    // Add final field
+    fields.push(currentField);
+    
+    // Validate matching quotes
+    if (insideQuotes) {
+      throw CsvFormatError.mismatchedQuotes('row');
     }
+    
+    return fields;
+  }
+
+  /**
+   * Check if character at index is an escaped quote (double quote)
+   * @returns {boolean}
+   */
+  isEscapedQuote(line, index, insideQuoted) {
+    return insideQuoted && 
+           index + 1 < line.length && 
+           line[index + 1] === QUOTE_CHAR;
+  }
+
+  /**
+   * Check if this is an empty quoted field: "" before delimiter or end of line
+   * @returns {boolean}
+   */
+  isEmptyQuotedField(line, index, insideQuoted, currentField, delimiter) {
+    if (insideQuoted || currentField !== '' || index + 1 >= line.length) {
+      return false;
+    }
+    
+    let nextChar = line[index + 1];
+    if (nextChar !== QUOTE_CHAR) {
+      return false; // Not a quote pair
+    }
+    
+    let afterQuotes = index + 2;
+    return afterQuotes === line.length || line[afterQuotes] === delimiter;
   }
 }
 

package/src/csvToJsonAsync.js

@@ -2,6 +2,7 @@
 
 const fileUtils = require('./util/fileUtils');
 const csvToJson = require('./csvToJson');
+const { InputValidationError } = require('./util/errors');
 
 class CsvToJsonAsync {
     constructor() {
@@ -57,6 +58,14 @@ class CsvToJsonAsync {
         return this;
     }
 
+    /**
+     * Set row mapper function to transform each row
+     */
+    mapRows(mapperFn) {
+        this.csvToJson.mapRows(mapperFn);
+        return this;
+    }
+
     /**
      * Set encoding
      */
@@ -87,7 +96,12 @@ class CsvToJsonAsync {
      */
     async getJsonFromCsvAsync(inputFileNameOrCsv, options = {}) {
         if (inputFileNameOrCsv === null || inputFileNameOrCsv === undefined) {
-            throw new Error('inputFileNameOrCsv is not defined!!!');
+            throw new InputValidationError(
+                'inputFileNameOrCsv',
+                'string (file path) or CSV string content',
+                `${typeof inputFileNameOrCsv}`,
+                'Either provide a valid file path or CSV content as a string.'
+            );
         }
 
         if (options.raw) {

package/src/util/errors.js

@@ -0,0 +1,227 @@
+'use strict';
+
+/**
+ * Custom error classes following clean code principles
+ * Provides clear, actionable error messages with context
+ */
+
+/**
+ * Base class for all CSV parsing errors
+ * Provides consistent error formatting and context
+ */
+class CsvParsingError extends Error {
+    constructor(message, code, context = {}) {
+        super(message);
+        this.name = 'CsvParsingError';
+        this.code = code;
+        this.context = context;
+        Error.captureStackTrace(this, this.constructor);
+    }
+
+    toString() {
+        let output = `${this.name}: ${this.message}`;
+        
+        if (this.context && Object.keys(this.context).length > 0) {
+            output += '\n\nContext:';
+            Object.entries(this.context).forEach(([key, value]) => {
+                output += `\n  ${key}: ${this.formatValue(value)}`;
+            });
+        }
+        
+        return output;
+    }
+
+    formatValue(value) {
+        if (value === null) return 'null';
+        if (value === undefined) return 'undefined';
+        if (typeof value === 'string') return `"${value}"`;
+        if (typeof value === 'object') return JSON.stringify(value);
+        return String(value);
+    }
+}
+
+/**
+ * Input validation errors
+ */
+class InputValidationError extends CsvParsingError {
+    constructor(paramName, expectedType, receivedType, details = '') {
+        const message = 
+            `Invalid input: Parameter '${paramName}' is required.\n` +
+            `Expected: ${expectedType}\n` +
+            `Received: ${receivedType}${details ? '\n' + details : ''}`;
+        
+        super(message, 'INPUT_VALIDATION_ERROR', {
+            parameter: paramName,
+            expectedType,
+            receivedType
+        });
+        this.name = 'InputValidationError';
+    }
+}
+
+/**
+ * Configuration-related errors
+ */
+class ConfigurationError extends CsvParsingError {
+    constructor(message, conflictingOptions = {}) {
+        super(message, 'CONFIGURATION_ERROR', conflictingOptions);
+        this.name = 'ConfigurationError';
+    }
+
+    static quotedFieldConflict(optionName, value) {
+        return new ConfigurationError(
+            `Configuration conflict: supportQuotedField() is enabled, but ${optionName} is set to '${value}'.\n` +
+            `The quote character (") cannot be used as a field delimiter, separator, or sub-array delimiter when quoted field support is active.\n\n` +
+            `Solutions:\n` +
+            `  1. Use a different character for ${optionName} (e.g., '|', '\\t', ';')\n` +
+            `  2. Disable supportQuotedField() if your CSV doesn't contain quoted fields\n` +
+            `  3. Refer to RFC 4180 for proper CSV formatting: https://tools.ietf.org/html/rfc4180`,
+            { optionName, value, conflictingOption: 'supportQuotedField' }
+        );
+    }
+
+    static invalidHeaderIndex(value) {
+        return new ConfigurationError(
+            `Invalid configuration: indexHeader() expects a numeric value.\n` +
+            `Received: ${typeof value} (${value})\n\n` +
+            `Solutions:\n` +
+            `  1. Ensure indexHeader() receives a number: indexHeader(0), indexHeader(1), etc.\n` +
+            `  2. Headers are typically found on row 0 (first line)\n` +
+            `  3. Use indexHeader(2) if headers are on the 3rd line`,
+            { parameterName: 'indexHeader', value, type: typeof value }
+        );
+    }
+}
+
+/**
+ * CSV parsing errors with detailed context
+ */
+class CsvFormatError extends CsvParsingError {
+    constructor(message, context = {}) {
+        super(message, 'CSV_FORMAT_ERROR', context);
+        this.name = 'CsvFormatError';
+    }
+
+    static missingHeader() {
+        return new CsvFormatError(
+            `CSV parsing error: No header row found.\n` +
+            `The CSV file appears to be empty or has no valid header line.\n\n` +
+            `Solutions:\n` +
+            `  1. Ensure your CSV file contains at least one row (header row)\n` +
+            `  2. Verify the file is not empty or contains only whitespace\n` +
+            `  3. Check if you need to use indexHeader(n) to specify a non-standard header row\n` +
+            `  4. Refer to RFC 4180 for proper CSV format: https://tools.ietf.org/html/rfc4180`
+        );
+    }
+
+    static mismatchedQuotes(location = 'CSV') {
+        return new CsvFormatError(
+            `CSV parsing error: Mismatched quotes detected in ${location}.\n` +
+            `A quoted field was not properly closed with a matching quote character.\n\n` +
+            `RFC 4180 rules for quoted fields:\n` +
+            `  • Fields containing delimiters or quotes MUST be enclosed in double quotes\n` +
+            `  • To include a quote within a quoted field, use two consecutive quotes: ""\n` +
+            `  • Example: "Smith, John" (name contains comma)\n` +
+            `  • Example: "He said ""Hello""" (text contains quotes)\n\n` +
+            `Solutions:\n` +
+            `  1. Review your CSV for properly paired quote characters\n` +
+            `  2. Use double quotes ("") to escape quotes within quoted fields\n` +
+            `  3. Ensure all commas within field values are inside quotes\n` +
+            `  4. Enable supportQuotedField(true) if you're using quoted fields`,
+            { location }
+        );
+    }
+}
+
+/**
+ * File operation errors
+ */
+class FileOperationError extends CsvParsingError {
+    constructor(operation, filePath, originalError) {
+        const message = 
+            `File operation error: Failed to ${operation} file.\n` +
+            `File path: ${filePath}\n` +
+            `Reason: ${originalError.message}\n\n` +
+            `Solutions:\n` +
+            `  1. Verify the file path is correct: ${filePath}\n` +
+            `  2. Check file permissions (read access for input, write access for output)\n` +
+            `  3. Ensure the directory exists and is writable for output files\n` +
+            `  4. Verify the file is not in use by another process`;
+        
+        super(message, 'FILE_OPERATION_ERROR', {
+            operation,
+            filePath,
+            originalError: originalError.message
+        });
+        this.name = 'FileOperationError';
+        this.originalError = originalError;
+    }
+}
+
+/**
+ * JSON validation errors
+ */
+class JsonValidationError extends CsvParsingError {
+    constructor(csvData, originalError) {
+        const message = 
+            `JSON validation error: The parsed CSV data generated invalid JSON.\n` +
+            `This typically indicates malformed field names or values in the CSV.\n` +
+            `Original error: ${originalError.message}\n\n` +
+            `Solutions:\n` +
+            `  1. Check that field names are valid JavaScript identifiers (or will be converted safely)\n` +
+            `  2. Review the CSV data for special characters that aren't properly escaped\n` +
+            `  3. Enable supportQuotedField(true) for fields containing special characters\n` +
+            `  4. Verify that formatValueByType() isn't converting values incorrectly`;
+        
+        super(message, 'JSON_VALIDATION_ERROR', {
+            originalError: originalError.message,
+            csvPreview: csvData ? csvData.substring(0, 200) : 'N/A'
+        });
+        this.name = 'JsonValidationError';
+        this.originalError = originalError;
+    }
+}
+
+/**
+ * Browser-specific errors
+ */
+class BrowserApiError extends CsvParsingError {
+    constructor(message, context = {}) {
+        super(message, 'BROWSER_API_ERROR', context);
+        this.name = 'BrowserApiError';
+    }
+
+    static fileReaderNotAvailable() {
+        return new BrowserApiError(
+            `Browser compatibility error: FileReader API is not available.\n` +
+            `Your browser does not support the FileReader API required for file parsing.\n\n` +
+            `Solutions:\n` +
+            `  1. Use a modern browser that supports FileReader (Chrome 13+, Firefox 10+, Safari 6+)\n` +
+            `  2. Consider using csvStringToJson() or csvStringToJsonAsync() for string-based parsing\n` +
+            `  3. Implement a polyfill or alternative file reading method`
+        );
+    }
+
+    static parseFileError(originalError) {
+        return new BrowserApiError(
+            `Browser file parsing error: Failed to read and parse the file.\n` +
+            `Error details: ${originalError.message}\n\n` +
+            `Solutions:\n` +
+            `  1. Verify the file is a valid CSV file\n` +
+            `  2. Check the file encoding (UTF-8 is recommended)\n` +
+            `  3. Try a smaller file to isolate the issue\n` +
+            `  4. Check browser console for additional error details`,
+            { originalError: originalError.message }
+        );
+    }
+}
+
+module.exports = {
+    CsvParsingError,
+    InputValidationError,
+    ConfigurationError,
+    CsvFormatError,
+    FileOperationError,
+    JsonValidationError,
+    BrowserApiError
+};