convert-csv-to-json 4.46.0 → 4.47.0

package/src/{util → core}/errors.js

@@ -1,15 +1,10 @@
 'use strict';
 
 /**
- * Custom error classes following clean code principles
- * Provides clear, actionable error messages with context
- * @category Error Classes
- */
-
-/**
- * Base class for all CSV parsing errors
- * Provides consistent error formatting and context
+ * Base class for all CSV parsing errors.
+ * Provides consistent error formatting and context.
  * @category Error Classes
+ * @augments Error
  */
 class CsvParsingError extends Error {
     /**
@@ -59,9 +54,10 @@ class CsvParsingError extends Error {
 }
 
 /**
- * Input validation errors
- * Thrown when function parameters don't meet expected type or value requirements
+ * Input validation errors.
+ * Thrown when function parameters don't meet expected type or value requirements.
  * @category Error Classes
+ * @augments CsvParsingError
  */
 class InputValidationError extends CsvParsingError {
     /**
@@ -87,9 +83,10 @@ class InputValidationError extends CsvParsingError {
 }
 
 /**
- * Configuration-related errors
- * Thrown when configuration options conflict or are invalid
+ * Configuration-related errors.
+ * Thrown when configuration options conflict or are invalid.
  * @category Error Classes
+ * @augments CsvParsingError
  */
 class ConfigurationError extends CsvParsingError {
     /**
@@ -143,9 +140,10 @@ class ConfigurationError extends CsvParsingError {
 }
 
 /**
- * CSV parsing errors with detailed context
- * Thrown when CSV format is invalid or malformed
+ * CSV parsing errors with detailed context.
+ * Thrown when CSV format is invalid or malformed.
  * @category Error Classes
+ * @augments CsvParsingError
  */
 class CsvFormatError extends CsvParsingError {
     /**
@@ -203,9 +201,10 @@ class CsvFormatError extends CsvParsingError {
 }
 
 /**
- * File operation errors
- * Thrown when file read or write operations fail
+ * File operation errors.
+ * Thrown when file read or write operations fail.
  * @category Error Classes
+ * @augments CsvParsingError
  */
 class FileOperationError extends CsvParsingError {
     /**
@@ -236,9 +235,10 @@ class FileOperationError extends CsvParsingError {
 }
 
 /**
- * JSON validation errors
- * Thrown when parsed CSV data cannot be converted to valid JSON
+ * JSON validation errors.
+ * Thrown when parsed CSV data cannot be converted to valid JSON.
  * @category Error Classes
+ * @augments CsvParsingError
  */
 class JsonValidationError extends CsvParsingError {
     /**
@@ -267,9 +267,10 @@ class JsonValidationError extends CsvParsingError {
 }
 
 /**
- * Browser-specific errors
- * Thrown when browser API operations fail
+ * Browser-specific errors.
+ * Thrown when browser API operations fail.
  * @category Error Classes
+ * @augments CsvParsingError
  */
 class BrowserApiError extends CsvParsingError {
     /**

package/src/core/parserConfig.js

@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * Immutable parser configuration snapshot used for concurrent parsing.
+ */
+class ParserConfig {
+  /**
+   * Create a frozen parser configuration snapshot.
+   * @param {object} options - Parser configuration options
+   * @param {string} [options.delimiter] - Field delimiter
+   * @param {string} [options.encoding] - File encoding
+   * @param {boolean} [options.isSupportQuotedField] - Support quoted fields
+   * @param {boolean} [options.isTrimHeaderFieldWhiteSpace] - Trim whitespace in header names
+   * @param {number} [options.indexHeaderValue] - Header row index
+   * @param {string} [options.parseSubArrayDelimiter] - Sub-array delimiter character
+   * @param {string} [options.parseSubArraySeparator] - Sub-array item separator
+   * @param {boolean} [options.printValueFormatByType] - Format values by type
+   * @param {function(object, number): object|null} [options.rowMapper] - Row mapper function
+   * @param {Array<number>} [options.indexesToIgnore] - Column indexes to ignore
+   */
+  constructor(options = {}) {
+    this.delimiter = options.delimiter;
+    this.encoding = options.encoding;
+    this.isSupportQuotedField = options.isSupportQuotedField;
+    this.isTrimHeaderFieldWhiteSpace = options.isTrimHeaderFieldWhiteSpace;
+    this.indexHeaderValue = options.indexHeaderValue;
+    this.parseSubArrayDelimiter = options.parseSubArrayDelimiter;
+    this.parseSubArraySeparator = options.parseSubArraySeparator;
+    this.printValueFormatByType = options.printValueFormatByType;
+    this.rowMapper = options.rowMapper;
+    this.indexesToIgnore = options.indexesToIgnore ? Object.freeze([...options.indexesToIgnore]) : Object.freeze([]);
+
+    Object.freeze(this);
+  }
+}
+
+module.exports = ParserConfig;

package/src/{streamProcessor.js → core/streamProcessor.js}

@@ -1,7 +1,7 @@
 /* globals CsvFormatError */
 'use strict';
 
-const stringUtils = require('./util/stringUtils');
+const stringUtils = require('../util/stringUtils');
 
 const QUOTE_CHAR = '"';
 const CRLF = '\r\n';
@@ -21,9 +21,9 @@ class StreamProcessor {
      * @param {object} options - Environment options
      * @param {boolean} options.isBrowser - Whether running in browser environment
      * @param {number} options.chunkSize - Number of rows per chunk for callback processing
-     * @param {function} options.onChunk - Callback for each chunk
-     * @param {function} options.onComplete - Callback when processing complete
-     * @param {function} options.onError - Callback for errors
+     * @param {function(Array<object>, number, number): void} [options.onChunk] - Callback for each chunk
+     * @param {function(Array<object>): void} [options.onComplete] - Callback when processing complete
+     * @param {function(Error): void} [options.onError] - Callback for errors
      */
     constructor(csvConfig, options = {}) {
         this.csvConfig = csvConfig;
@@ -31,10 +31,13 @@ class StreamProcessor {
         this.buffer = '';
         this.isInsideQuotes = false;
         this.headers = null;
-        this.headerRowIndex = csvConfig.getIndexHeader();
+        this.headerRowIndex = csvConfig.indexHeaderValue !== null && !isNaN(csvConfig.indexHeaderValue)
+            ? csvConfig.indexHeaderValue
+            : 0;
         this.currentRecordIndex = 0;
         this.parsedRecords = [];
         this.dataRowIndex = 0;
+        this.ignoredIndexes = new Set(csvConfig.indexesToIgnore || []);
 
         // Chunked processing options
         this.chunkSize = options.chunkSize || 1000;
@@ -69,7 +72,7 @@ class StreamProcessor {
 
     /**
      * Process a stream with chunked callbacks (for large files)
-     * @param {Readable|ReadableStream} stream - The stream to process
+     * @param {object} stream - The stream to process (Node.js Readable or browser ReadableStream)
      * @returns {Promise<void>} Promise that resolves when streaming starts
      */
     async processStreamWithCallbacks(stream) {
@@ -176,7 +179,7 @@ class StreamProcessor {
 
     /**
      * Process a stream directly (unified interface for both environments)
-     * @param {Readable|ReadableStream} stream - The stream to process
+     * @param {object} stream - The stream to process (Node.js Readable or browser ReadableStream)
      * @returns {Promise<Array<object>>} Promise resolving to parsed records
      */
     async processStream(stream) {
@@ -324,7 +327,7 @@ class StreamProcessor {
     _processDataRecord(record) {
         const dataFields = this._splitRecord(record);
         if (stringUtils.hasContent(dataFields)) {
-            const row = this.csvConfig.buildJsonResult(this.headers, dataFields);
+            const row = this._buildJsonResult(this.headers, dataFields);
             const processedRow = this._applyRowMapper(row);
             if (processedRow !== null) {
                 this.parsedRecords.push(processedRow);
@@ -356,11 +359,120 @@ class StreamProcessor {
      */
     _splitRecord(record) {
         if (this.csvConfig.isSupportQuotedField) {
-            return this.csvConfig.split(record);
+            return this._splitWithConfig(record, this.csvConfig);
         }
         return record.split(this.csvConfig.delimiter || ',');
     }
 
+    /**
+     * Split a CSV line into fields using parser configuration rules
+     * @param {string} line - The CSV line to split
+     * @param {object} config - The CSV parser configuration object
+     * @returns {string[]} Array of parsed field values
+     * @private
+     */
+    _splitWithConfig(line, config) {
+        if (line.length === 0) {
+            return [];
+        }
+
+        const fields = [];
+        let currentField = '';
+        let insideQuotes = false;
+        const delimiter = config.delimiter || ',';
+
+        for (let i = 0; i < line.length; i++) {
+            const char = line[i];
+
+            if (char === QUOTE_CHAR) {
+                if (insideQuotes && i + 1 < line.length && line[i + 1] === QUOTE_CHAR) {
+                    currentField += QUOTE_CHAR;
+                    i++;
+                } else {
+                    insideQuotes = !insideQuotes;
+                }
+            } else if (char === delimiter && !insideQuotes) {
+                fields.push(currentField);
+                currentField = '';
+            } else {
+                currentField += char;
+            }
+        }
+
+        fields.push(currentField);
+
+        if (insideQuotes) {
+            throw CsvFormatError.mismatchedQuotes('row');
+        }
+
+        return fields;
+    }
+
+    /**
+     * Convert a parsed CSV row into a JSON object using header names
+     * @param {string[]} headers - Array of header names
+     * @param {string[]} currentLine - Array of field values for the current row
+     * @returns {object} Parsed row object keyed by header names
+     * @private
+     */
+    _buildJsonResult(headers, currentLine) {
+        const jsonObject = {};
+        for (let j = 0; j < headers.length; j++) {
+            if (this.ignoredIndexes.has(j)) {
+                continue;
+            }
+
+            const propertyName = stringUtils.trimPropertyName(this.csvConfig.isTrimHeaderFieldWhiteSpace, headers[j]);
+            let value = currentLine[j];
+
+            if (this._isParseSubArray(value)) {
+                value = this._buildJsonSubArray(value);
+            }
+
+            if (this.csvConfig.printValueFormatByType && !Array.isArray(value)) {
+                value = stringUtils.getValueFormatByType(currentLine[j]);
+            }
+
+            jsonObject[propertyName] = value;
+        }
+        return jsonObject;
+    }
+
+    /**
+     * Determine whether a field value represents a sub-array expression
+     * @param {string} value - The field value to inspect
+     * @returns {boolean} True when the value is wrapped in the configured sub-array delimiters
+     * @private
+     */
+    _isParseSubArray(value) {
+        if (this.csvConfig.parseSubArrayDelimiter) {
+            return value && (value.indexOf(this.csvConfig.parseSubArrayDelimiter) === 0 && value.lastIndexOf(this.csvConfig.parseSubArrayDelimiter) === value.length - 1);
+        }
+        return false;
+    }
+
+    /**
+     * Parse a field value into a JSON sub-array based on configured delimiters and separators
+     * @param {string} value - The quoted sub-array string to parse
+     * @returns {Array<string|number|boolean>} Parsed sub-array values
+     * @private
+     */
+    _buildJsonSubArray(value) {
+        const extractedValues = value.substring(
+            value.indexOf(this.csvConfig.parseSubArrayDelimiter) + 1,
+            value.lastIndexOf(this.csvConfig.parseSubArrayDelimiter)
+        );
+        const items = extractedValues.split(this.csvConfig.parseSubArraySeparator);
+
+        if (this.csvConfig.printValueFormatByType) {
+            for (let i = 0; i < items.length; i++) {
+                items[i] = stringUtils.getValueFormatByType(items[i]);
+            }
+        }
+
+        return items;
+    }
+
     /**
      * Parse complete records from buffer, handling quoted fields across chunks
      * @param {string} buffer - Current buffer content