convert-csv-to-json 4.46.0 → 4.47.0

package/index.js

@@ -19,6 +19,24 @@ const encodingOps = {
     hex: 'hex'
 };
 
+const csvToJsonAsync = require('./src/csvToJsonAsync');
+
+/**
+ * Apply the same parser configuration update to every parser client.
+ * This keeps root-level chainable API calls in sync across sync, async, and browser clients.
+ * @param {function(object): void} configFn - Function that applies configuration to a client instance
+ * @returns {object} Module exports for chaining
+ * @private
+ */
+function applyConfigToAllClients(configFn) {
+  configFn(csvToJson);
+  configFn(csvToJsonAsync);
+  if (exports.browser) {
+    configFn(exports.browser);
+  }
+  return exports;
+}
+
 /**
  * Enable or disable automatic type formatting for values
  * Converts numeric strings to numbers, 'true'/'false' to booleans
@@ -27,8 +45,7 @@ const encodingOps = {
  * @returns {object} Module context for method chaining
  */
 exports.formatValueByType = function (active = true) {
-  csvToJson.formatValueByType(active);
-  return this;
+  return applyConfigToAllClients(client => client.formatValueByType(active));
 };
 
 /**
@@ -39,8 +56,7 @@ exports.formatValueByType = function (active = true) {
  * @returns {object} Module context for method chaining
  */
 exports.supportQuotedField = function (active = false) {
-  csvToJson.supportQuotedField(active);
-  return this;
+  return applyConfigToAllClients(client => client.supportQuotedField(active));
 };
 /**
  * Set the field delimiter character used to separate CSV fields
@@ -49,8 +65,7 @@ exports.supportQuotedField = function (active = false) {
  * @returns {object} Module context for method chaining
  */
 exports.fieldDelimiter = function (delimiter) {
-  csvToJson.fieldDelimiter(delimiter);
-  return this;
+  return applyConfigToAllClients(client => client.fieldDelimiter(delimiter));
 };
 
 /**
@@ -62,8 +77,7 @@ exports.fieldDelimiter = function (delimiter) {
  * @returns {object} Module context for method chaining
  */
 exports.trimHeaderFieldWhiteSpace = function (active = false) {
-  csvToJson.trimHeaderFieldWhiteSpace(active);
-  return this;
+  return applyConfigToAllClients(client => client.trimHeaderFieldWhiteSpace(active));
 };
 
 /**
@@ -74,8 +88,7 @@ exports.trimHeaderFieldWhiteSpace = function (active = false) {
  * @returns {object} Module context for method chaining
  */
 exports.indexHeader = function (index) {
-  csvToJson.indexHeader(index);
-  return this;
+  return applyConfigToAllClients(client => client.indexHeader(index));
 };
 
 /**
@@ -91,8 +104,7 @@ exports.indexHeader = function (index) {
  * csvToJson.parseSubArray('*', ',')
  */
 exports.parseSubArray = function (delimiter, separator) {
-  csvToJson.parseSubArray(delimiter, separator);
-  return this;
+  return applyConfigToAllClients(client => client.parseSubArray(delimiter, separator));
 };
 
 /**
@@ -111,8 +123,7 @@ exports.ignoreColumnIndexes = function (indexes) {
   if (!indexes.every(idx => Number.isInteger(idx) && idx >= 0)) {
     throw new TypeError('All elements in indexes must be valid non-negative numbers (>= 0)');
   }
-  csvToJson.ignoreColumnIndexes(indexes);
-  return this;
+  return applyConfigToAllClients(client => client.ignoreColumnIndexes(indexes));
 };
 
 /**
@@ -123,8 +134,7 @@ exports.ignoreColumnIndexes = function (indexes) {
  * @returns {object} Module context for method chaining
  */
 exports.customEncoding = function (encoding) {
-  csvToJson.encoding = encoding;
-  return this;
+  return applyConfigToAllClients(client => client.encoding(encoding));
 };
 
 /**
@@ -133,8 +143,7 @@ exports.customEncoding = function (encoding) {
  * @returns {object} Module context for method chaining
  */
 exports.utf8Encoding = function utf8Encoding() {
-  csvToJson.encoding = encodingOps.utf8;
-  return this;
+  return applyConfigToAllClients(client => client.encoding(encodingOps.utf8));
 };
 
 /**
@@ -143,8 +152,7 @@ exports.utf8Encoding = function utf8Encoding() {
  * @returns {object} Module context for method chaining
  */
 exports.ucs2Encoding = function () {
-  csvToJson.encoding = encodingOps.ucs2;
-  return this;
+  return applyConfigToAllClients(client => client.encoding(encodingOps.ucs2));
 };
 
 /**
@@ -153,8 +161,7 @@ exports.ucs2Encoding = function () {
  * @returns {object} Module context for method chaining
  */
 exports.utf16leEncoding = function () {
-  csvToJson.encoding = encodingOps.utf16le;
-  return this;
+  return applyConfigToAllClients(client => client.encoding(encodingOps.utf16le));
 };
 
 /**
@@ -163,8 +170,7 @@ exports.utf16leEncoding = function () {
  * @returns {object} Module context for method chaining
  */
 exports.latin1Encoding = function () {
-  csvToJson.encoding = encodingOps.latin1;
-  return this;
+  return applyConfigToAllClients(client => client.encoding(encodingOps.latin1));
 };
 
 /**
@@ -173,8 +179,7 @@ exports.latin1Encoding = function () {
  * @returns {object} Module context for method chaining
  */
 exports.asciiEncoding = function () {
-  csvToJson.encoding = encodingOps.ascii;
-  return this;
+  return applyConfigToAllClients(client => client.encoding(encodingOps.ascii));
 };
 
 /**
@@ -183,8 +188,7 @@ exports.asciiEncoding = function () {
  * @returns {object} Module context for method chaining
  */
 exports.base64Encoding = function () {
-  this.csvToJson = encodingOps.base64;
-  return this;
+  return applyConfigToAllClients(client => client.encoding(encodingOps.base64));
 };
 
 /**
@@ -193,8 +197,7 @@ exports.base64Encoding = function () {
  * @returns {object} Module context for method chaining
  */
 exports.hexEncoding = function () {
-  this.csvToJson = encodingOps.hex;
-  return this;
+  return applyConfigToAllClients(client => client.encoding(encodingOps.hex));
 };
 
 /**
@@ -210,8 +213,7 @@ exports.hexEncoding = function () {
  *   .getJsonFromCsv('input.csv')
  */
 exports.mapRows = function (mapperFn) {
-  csvToJson.mapRows(mapperFn);
-  return this;
+  return applyConfigToAllClients(client => client.mapRows(mapperFn));
 };
 
 /**
@@ -257,8 +259,8 @@ exports.getJsonFromCsv = function(inputFileName) {
 };
 
 /**
- * Parse CSV file asynchronously and return parsed data as JSON array
- * @param {string} inputFileNameOrCsv - Path to file or CSV string
+ * Parse CSV file asynchronously and return parsed data as JSON array.
+ * @param {string} input - Path to file or CSV string
  * @param {object} options - Configuration options
  * @param {boolean} options.raw - If true, treats first param as CSV content; if false, reads from file
  * @returns {Promise<Array<object>>} Promise resolving to array of objects
@@ -271,11 +273,46 @@ exports.getJsonFromCsv = function(inputFileName) {
  * const data = await csvToJson.getJsonFromCsvAsync('resource/input.csv');
  * console.log(data);
  */
-const csvToJsonAsync = require('./src/csvToJsonAsync');
+exports.getJsonFromCsvAsync = function(input, options) {
+  return csvToJsonAsync.getJsonFromCsvAsync(input, options);
+};
 
 /**
- * Parse CSV from a Readable stream and return parsed data as JSON array
- * Processes data in chunks for memory-efficient handling of large files
+ * Parse a raw CSV string asynchronously and return parsed JSON objects.
+ * @param {string} input - CSV content as a string
+ * @param {object} [options] - Configuration options
+ * @param {boolean} [options.raw] - If true, treats input as CSV content
+ * @returns {Promise<Array<object>>} Promise resolving to array of parsed objects
+ * @category 1-Core API
+ */
+exports.csvStringToJsonAsync = function(input, options) {
+  return csvToJsonAsync.csvStringToJsonAsync(input, options);
+};
+
+/**
+ * Parse a raw CSV string asynchronously and return a JSON string.
+ * @param {string} input - CSV content as a string
+ * @returns {Promise<string>} Promise resolving to JSON string
+ * @category 1-Core API
+ */
+exports.csvStringToJsonStringifiedAsync = function(input) {
+  return csvToJsonAsync.csvStringToJsonStringifiedAsync(input);
+};
+
+/**
+ * Parse a CSV file asynchronously and write the parsed JSON to an output file.
+ * @param {string} input - Path to the input CSV file
+ * @param {string} output - Path to the output JSON file
+ * @returns {Promise<void>} Promise resolving when file is written
+ * @category 1-Core API
+ */
+exports.generateJsonFileFromCsvAsync = function(input, output) {
+  return csvToJsonAsync.generateJsonFileFromCsv(input, output);
+};
+
+/**
+ * Parse CSV from a Readable stream and return parsed data as JSON array.
+ * Processes data in chunks for memory-efficient handling of large files.
  * @param {object} stream - Node.js Readable stream containing CSV data
  * @returns {Promise<Array<object>>} Promise resolving to array of objects representing CSV rows
  * @throws {InputValidationError} If stream is invalid
@@ -288,9 +325,12 @@ const csvToJsonAsync = require('./src/csvToJsonAsync');
  * const data = await csvToJson.getJsonFromStreamAsync(stream);
  * console.log(data);
  */
+exports.getJsonFromStreamAsync = function(stream) {
+  return csvToJsonAsync.getJsonFromStreamAsync(stream);
+};
 
 /**
- * Parse CSV from a file path using streaming for memory-efficient processing
+ * Parse CSV from a file path using streaming for memory-efficient processing.
  * @param {string} filePath - Path to the CSV file
  * @returns {Promise<Array<object>>} Promise resolving to array of objects representing CSV rows
  * @throws {InputValidationError} If filePath is invalid
@@ -302,28 +342,9 @@ const csvToJsonAsync = require('./src/csvToJsonAsync');
  * const data = await csvToJson.getJsonFromFileStreamingAsync('large.csv');
  * console.log(data);
  */
-
-// Re-export all async API methods
-Object.assign(exports, {
-  getJsonFromCsvAsync: function(input, options) {
-    return csvToJsonAsync.getJsonFromCsvAsync(input, options);
-  },
-  csvStringToJsonAsync: function(input, options) {
-    return csvToJsonAsync.csvStringToJsonAsync(input, options);
-  },
-  csvStringToJsonStringifiedAsync: function(input) {
-    return csvToJsonAsync.csvStringToJsonStringifiedAsync(input);
-  },
-  generateJsonFileFromCsvAsync: function(input, output) {
-    return csvToJsonAsync.generateJsonFileFromCsv(input, output);
-  },
-  getJsonFromStreamAsync: function(stream) {
-    return csvToJsonAsync.getJsonFromStreamAsync(stream);
-  },
-  getJsonFromFileStreamingAsync: function(filePath) {
-    return csvToJsonAsync.getJsonFromFileStreamingAsync(filePath);
-  }
-});
+exports.getJsonFromFileStreamingAsync = function(filePath) {
+  return csvToJsonAsync.getJsonFromFileStreamingAsync(filePath);
+};
 
 /**
  * Parse a CSV string and return as JSON array of objects (synchronous)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convert-csv-to-json",
-  "version": "4.46.0",
+  "version": "4.47.0",
   "description": "Convert CSV to JSON",
   "main": "index.js",
   "types": "index.d.ts",
@@ -10,6 +10,7 @@
     "lint": "eslint .",
     "docs": "jsdoc -c jsdoc.json",
     "docs:api": "jsdoc -c jsdoc.json -d demo/api",
+    "demo": "npx http-server demo -p 8000",
     "prepublishOnly": "npm run docs:api",
     "version-patch": "npm version patch",
     "version-minor": "npm version minor",
@@ -55,6 +56,7 @@
     "browserify": "^17.0.1",
     "eslint": "^10.1.0",
     "eslint-plugin-jsdoc": "^63.0.0",
+    "http-server": "^14.1.1",
     "jest": "^30.2.0",
     "jsdoc": "^4.0.5",
     "ts-jest": "^29.4.5",

package/src/browserApi.js

@@ -3,104 +3,52 @@
 "use strict";
 
 const csvToJson = require('./csvToJson');
-const { InputValidationError, BrowserApiError } = require('./util/errors');
-const StreamProcessor = require('./streamProcessor');
+const Configurable = require('./core/configurable');
+const { InputValidationError, BrowserApiError } = require('./core/errors');
+const StreamProcessor = require('./core/streamProcessor');
 
 /**
  * Browser-friendly CSV to JSON API
  * Provides methods for parsing CSV strings and File/Blob objects in browser environments
- * Proxies configuration to sync csvToJson instance
+ * Uses isolated parser configuration via ParserConfig snapshots
  * @category 4-Browser
  */
-class BrowserApi {
+class BrowserApi extends Configurable {
   /**
    * Constructor initializes proxy to sync csvToJson instance
    */
   constructor() {
-    // reuse the existing csvToJson instance for parsing and configuration
+    super();
+    // reuse the existing csvToJson instance for parsing
     this.csvToJson = csvToJson;
   }
 
   /**
-   * Enable or disable automatic type formatting for values
-   * @param {boolean} active - Whether to format values by type (default: true)
-   * @returns {this} For method chaining
-   */
-  formatValueByType(active = true) {
-    this.csvToJson.formatValueByType(active);
-    return this;
-  }
-
-  /**
-   * Enable or disable support for RFC 4180 quoted fields
-   * @param {boolean} active - Whether to support quoted fields (default: false)
-   * @returns {this} For method chaining
-   */
-  supportQuotedField(active = false) {
-    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 (default: false)
-   * @returns {this} For method chaining
-   */
-  trimHeaderFieldWhiteSpace(active = false) {
-    this.csvToJson.trimHeaderFieldWhiteSpace(active);
-    return this;
-  }
-
-  /**
-   * Set the row index where CSV headers are located
-   * @param {number} index - Zero-based row index containing headers
-   * @returns {this} For method chaining
-   */
-  indexHeader(index) {
-    this.csvToJson.indexHeader(index);
-    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;
-  }
-
-  /**
-   * 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
+   * Validate CSV text input for browser methods.
+   * @param {string} csvString - CSV content as string
+   * @throws {InputValidationError} If the input is not a valid string
+   * @private
    */
-  parseSubArray(delimiter = '*', separator = ',') {
-    this.csvToJson.parseSubArray(delimiter, separator);
-    return this;
+  _validateCsvString(csvString) {
+    if (csvString === undefined || csvString === null) {
+      throw new InputValidationError(
+        'csvString',
+        'string',
+        `${typeof csvString}`,
+        'Provide valid CSV content as a string to parse.'
+      );
+    }
   }
 
   /**
-   * 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
+   * Parse CSV text using a frozen parser configuration snapshot.
+   * @param {string} csvString - CSV content as string
+   * @returns {Array<object>} Parsed CSV rows
+   * @private
    */
-  mapRows(mapperFn) {
-    this.csvToJson.mapRows(mapperFn);
-    return this;
+  _parseCsvText(csvString) {
+    const config = this.getParserConfig();
+    return this.csvToJson.csvToJsonWithConfig(String(csvString), config);
   }
 
   /**
@@ -115,15 +63,8 @@ class BrowserApi {
    * console.log(rows); // [{ name: 'Alice', age: '30' }]
    */
   csvStringToJson(csvString) {
-    if (csvString === undefined || csvString === null) {
-      throw new InputValidationError(
-        'csvString',
-        'string',
-        `${typeof csvString}`,
-        'Provide valid CSV content as a string to parse.'
-      );
-    }
-    return this.csvToJson.csvToJson(csvString);
+    this._validateCsvString(csvString);
+    return this._parseCsvText(csvString);
   }
 
   /**
@@ -138,15 +79,9 @@ class BrowserApi {
    * console.log(jsonString);
    */
   csvStringToJsonStringified(csvString) {
-    if (csvString === undefined || csvString === null) {
-      throw new InputValidationError(
-        'csvString',
-        'string',
-        `${typeof csvString}`,
-        'Provide valid CSV content as a string to parse.'
-      );
-    }
-    return this.csvToJson.csvStringToJsonStringified(csvString);
+    this._validateCsvString(csvString);
+    const rows = this._parseCsvText(csvString);
+    return JSON.stringify(rows, undefined, 1);
   }
 
   /**
@@ -212,9 +147,7 @@ class BrowserApi {
       ));
       reader.onload = () => {
         try {
-          const text = reader.result;
-          const result = this.csvToJson.csvToJson(String(text));
-          resolve(result);
+          resolve(this._parseCsvText(reader.result));
         } catch (err) {
           reject(BrowserApiError.parseFileError(err));
         }
@@ -257,7 +190,8 @@ class BrowserApi {
       );
     }
 
-    const streamProcessor = new StreamProcessor(this.csvToJson, { isBrowser: true });
+    const config = this.getParserConfig();
+    const streamProcessor = new StreamProcessor(config, { isBrowser: true });
     return streamProcessor.processStream(stream);
   }
 
@@ -302,7 +236,7 @@ class BrowserApi {
    * @param {function(Array<object>, number, number): void} options.onChunk - Callback for each chunk of processed rows
    * @param {function(Array<object>): void} [options.onComplete] - Callback when processing is complete
    * @param {function(Error): void} [options.onError] - Callback for errors
-   * @param {number} [options.chunkSize=1000] - Number of rows per chunk
+   * @param {number} [options.chunkSize] - Number of rows per chunk (default: 1000)
    * @returns {Promise<void>} Promise that resolves when streaming starts
    * @throws {InputValidationError} If file or options are invalid
    * @example
@@ -343,7 +277,8 @@ class BrowserApi {
     }
 
     const chunkSize = options.chunkSize || 1000;
-    const streamProcessor = new StreamProcessor(this.csvToJson, {
+    const config = this.getParserConfig();
+    const streamProcessor = new StreamProcessor(config, {
       isBrowser: true,
       chunkSize,
       onChunk: options.onChunk,
@@ -393,8 +328,7 @@ class BrowserApi {
 
       reader.onload = () => {
         try {
-          const text = reader.result;
-          const allRows = this.csvToJson.csvToJson(String(text));
+          const allRows = this._parseCsvText(reader.result);
 
           // Process in chunks
           let processed = 0;

package/src/core/configurable.js

@@ -0,0 +1,126 @@
+'use strict';
+
+const { ConfigurationError } = require('./errors');
+const ParserConfig = require('./parserConfig');
+
+/**
+ * Shared configuration builder for CSV parser clients.
+ * Provides chainable methods for parser options and snapshots.
+ */
+class Configurable {
+  /**
+   * Initialize a configurable parser instance.
+   * @param {object} [initialConfig] - Initial parser configuration values
+   */
+  constructor(initialConfig = {}) {
+    this.config = { ...initialConfig };
+  }
+
+  /**
+   * Enable or disable automatic type formatting for values.
+   * @param {boolean} active - Whether to format values by type
+   * @returns {this} For method chaining
+   */
+  formatValueByType(active = true) {
+    this.config.printValueFormatByType = 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 = false) {
+    this.config.isSupportQuotedField = 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.config.delimiter = delimiter;
+    return this;
+  }
+
+  /**
+   * Configure whitespace handling in header field names.
+   * @param {boolean} active - Whether to trim whitespace in header names
+   * @returns {this} For method chaining
+   */
+  trimHeaderFieldWhiteSpace(active = false) {
+    this.config.isTrimHeaderFieldWhiteSpace = active;
+    return this;
+  }
+
+  /**
+   * Set the row index where CSV headers are located.
+   * @param {number} indexHeaderValue - Zero-based row index containing headers
+   * @returns {this} For method chaining
+   */
+  indexHeader(indexHeaderValue) {
+    if (isNaN(indexHeaderValue)) {
+      throw ConfigurationError.invalidHeaderIndex(indexHeaderValue);
+    }
+    this.config.indexHeaderValue = indexHeaderValue;
+    return this;
+  }
+
+  /**
+   * Configure sub-array parsing for special field values.
+   * @param {string} delimiter - Bracket character
+   * @param {string} separator - Item separator within brackets
+   * @returns {this} For method chaining
+   */
+  parseSubArray(delimiter = '*', separator = ',') {
+    this.config.parseSubArrayDelimiter = delimiter;
+    this.config.parseSubArraySeparator = separator;
+    return this;
+  }
+
+  /**
+   * Set a mapper function for row transformation.
+   * @param {function(object, number): object|null} mapperFn - Function receiving (row, index)
+   * @returns {this} For method chaining
+   */
+  mapRows(mapperFn) {
+    if (typeof mapperFn !== 'function') {
+      throw new TypeError('mapperFn must be a function');
+    }
+    this.config.rowMapper = mapperFn;
+    return this;
+  }
+
+  /**
+   * Configure column indexes to exclude from output.
+   * @param {Array<number>} indexes - Column indexes to ignore
+   * @returns {this} For method chaining
+   */
+  ignoreColumnIndexes(indexes) {
+    this.config.indexesToIgnore = Array.isArray(indexes) ? [...indexes] : [...indexes];
+    return this;
+  }
+
+  /**
+   * Set the file encoding for reading CSV files.
+   * @param {string} encoding - Node.js supported encoding
+   * @returns {this} For method chaining
+   */
+  encoding(encoding) {
+    this.config.encoding = encoding;
+    return this;
+  }
+
+  /**
+   * Create an immutable parser configuration snapshot.
+   * @returns {ParserConfig} Frozen parser configuration
+   */
+  getParserConfig() {
+    return new ParserConfig(this.config);
+  }
+}
+
+module.exports = Configurable;