convert-csv-to-json 4.2.0 → 4.4.0

package/index.js

@@ -1,3 +1,10 @@
+/**
+ * CsvToJson - CSV to JSON converter library
+ * Main entry point providing chainable API for CSV parsing with multiple configuration options
+ */
+
+/* globals FileOperationError, CsvFormatError, JsonValidationError, InputValidationError */
+
 "use strict";
 
 let csvToJson = require("./src/csvToJson.js");
@@ -13,7 +20,10 @@ const encodingOps = {
 };
 
 /**
- * Prints a digit as Number type (for example 32 instead of '32')
+ * Enable or disable automatic type formatting for values
+ * Converts numeric strings to numbers, 'true'/'false' to booleans
+ * @param {boolean} active - Whether to format values by type (default: true)
+ * @returns {object} Module context for method chaining
  */
 exports.formatValueByType = function (active = true) {
   csvToJson.formatValueByType(active);
@@ -21,14 +31,19 @@ exports.formatValueByType = function (active = true) {
 };
 
 /**
- * If enabled, allows fields wrapped by quotation marks to be parsed correctly and not splitted 
+ * 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 (default: false)
+ * @returns {object} Module context for method chaining
  */
 exports.supportQuotedField = function (active = false) {
   csvToJson.supportQuotedField(active);
   return this;
 };
 /**
- * Defines the field delimiter which will be used to split the fields
+ * Set the field delimiter character used to separate CSV fields
+ * @param {string} delimiter - Character(s) to use as field separator (default: ',')
+ * @returns {object} Module context for method chaining
  */
 exports.fieldDelimiter = function (delimiter) {
   csvToJson.fieldDelimiter(delimiter);
@@ -36,7 +51,11 @@ exports.fieldDelimiter = function (delimiter) {
 };
 
 /**
- * If active the content of the Header Fields is trimmed including the white spaces, e.g. "My Name" -> "MyName"
+ * Configure whitespace handling in CSV header field names
+ * When active, removes all whitespace from header names (e.g., "My Name" → "MyName")
+ * When inactive, only trims leading and trailing whitespace
+ * @param {boolean} active - Whether to remove all whitespace from headers (default: false)
+ * @returns {object} Module context for method chaining
  */
 exports.trimHeaderFieldWhiteSpace = function (active = false) {
   csvToJson.trimHeaderFieldWhiteSpace(active);
@@ -44,7 +63,10 @@ exports.trimHeaderFieldWhiteSpace = function (active = false) {
 };
 
 /**
- * Defines the index where the header is defined
+ * Set the row index where CSV headers are located
+ * Use this if headers are not on the first line (row 0)
+ * @param {number} index - Zero-based row index containing headers
+ * @returns {object} Module context for method chaining
  */
 exports.indexHeader = function (index) {
   csvToJson.indexHeader(index);
@@ -52,7 +74,15 @@ exports.indexHeader = function (index) {
 };
 
 /**
- * Defines how to match and parse a sub array
+ * 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 {object} Module context for method chaining
+ * @example
+ * // Input field: "*val1,val2,val3*"
+ * // Output array: ["val1", "val2", "val3"]
+ * csvToJson.parseSubArray('*', ',')
  */
 exports.parseSubArray = function (delimiter, separator) {
   csvToJson.parseSubArray(delimiter, separator);
@@ -60,7 +90,10 @@ exports.parseSubArray = function (delimiter, separator) {
 };
 
 /**
- * Defines a custom encoding to decode a file
+ * Set custom file encoding for reading CSV files
+ * Useful for non-UTF8 encoded files
+ * @param {string} encoding - Node.js supported encoding (e.g., 'utf8', 'latin1', 'ascii')
+ * @returns {object} Module context for method chaining
  */
 exports.customEncoding = function (encoding) {
   csvToJson.encoding = encoding;
@@ -68,7 +101,8 @@ exports.customEncoding = function (encoding) {
 };
 
 /**
- * Defines a custom encoding to decode a file
+ * Set UTF-8 encoding (default encoding)
+ * @returns {object} Module context for method chaining
  */
 exports.utf8Encoding = function utf8Encoding() {
   csvToJson.encoding = encodingOps.utf8;
@@ -76,7 +110,8 @@ exports.utf8Encoding = function utf8Encoding() {
 };
 
 /**
- * Defines ucs2 encoding to decode a file
+ * Set UCS-2 encoding for reading files
+ * @returns {object} Module context for method chaining
  */
 exports.ucs2Encoding = function () {
   csvToJson.encoding = encodingOps.ucs2;
@@ -84,7 +119,8 @@ exports.ucs2Encoding = function () {
 };
 
 /**
- * Defines utf16le encoding to decode a file
+ * Set UTF-16 LE encoding for reading files
+ * @returns {object} Module context for method chaining
  */
 exports.utf16leEncoding = function () {
   csvToJson.encoding = encodingOps.utf16le;
@@ -92,7 +128,8 @@ exports.utf16leEncoding = function () {
 };
 
 /**
- * Defines latin1 encoding to decode a file
+ * Set Latin-1 (ISO-8859-1) encoding for reading files
+ * @returns {object} Module context for method chaining
  */
 exports.latin1Encoding = function () {
   csvToJson.encoding = encodingOps.latin1;
@@ -100,7 +137,8 @@ exports.latin1Encoding = function () {
 };
 
 /**
- * Defines ascii encoding to decode a file
+ * Set ASCII encoding for reading files
+ * @returns {object} Module context for method chaining
  */
 exports.asciiEncoding = function () {
   csvToJson.encoding = encodingOps.ascii;
@@ -108,7 +146,8 @@ exports.asciiEncoding = function () {
 };
 
 /**
- * Defines base64 encoding to decode a file
+ * Set Base64 encoding for reading files
+ * @returns {object} Module context for method chaining
  */
 exports.base64Encoding = function () {
   this.csvToJson = encodingOps.base64;
@@ -116,7 +155,8 @@ exports.base64Encoding = function () {
 };
 
 /**
- * Defines hex encoding to decode a file
+ * Set Hex encoding for reading files
+ * @returns {object} Module context for method chaining
  */
 exports.hexEncoding = function () {
   this.csvToJson = encodingOps.hex;
@@ -124,11 +164,15 @@ exports.hexEncoding = function () {
 };
 
 /**
- * Sets a mapper function to transform each row after conversion.
+ * Set a mapper function to transform each row after conversion
  * The mapper function receives (row, index) where row is the JSON object 
  * and index is the 0-based row number. Return null/undefined to filter out rows.
- * @param {Function} mapperFn - Function to transform each row
- * @return {object} this for chaining
+ * @param {Function} mapperFn - Function to transform each row: `(row, index) => transformedRow | null`
+ * @returns {object} Module context for method chaining
+ * @example
+ * csvToJson
+ *   .mapRows((row, idx) => idx % 2 === 0 ? row : null) // Keep every other row
+ *   .getJsonFromCsv('input.csv')
  */
 exports.mapRows = function (mapperFn) {
   csvToJson.mapRows(mapperFn);
@@ -136,10 +180,15 @@ exports.mapRows = function (mapperFn) {
 };
 
 /**
- * Parses .csv file and put its content into a file in json format.
- * @param {inputFileName} path/filename
- * @param {outputFileName} path/filename
- *
+ * Parse CSV file and write the parsed JSON to an output file (synchronous)
+ * @param {string} inputFileName - Path to input CSV file
+ * @param {string} outputFileName - Path to output JSON file
+ * @throws {Error} If inputFileName or outputFileName is not defined
+ * @throws {FileOperationError} If file operations fail
+ * @throws {CsvFormatError} If CSV is malformed
+ * @example
+ * const csvToJson = require('convert-csv-to-json');
+ * csvToJson.generateJsonFileFromCsv('input.csv', 'output.json');
  */
 exports.generateJsonFileFromCsv = function(inputFileName, outputFileName) {
   if (!inputFileName) {
@@ -152,10 +201,16 @@ exports.generateJsonFileFromCsv = function(inputFileName, outputFileName) {
 };
 
 /**
- * Parses .csv file and put its content into an Array of Object in json format.
- * @param {inputFileName} path/filename
- * @return {Array} Array of Object in json format
- *
+ * Parse CSV file and return parsed data as JSON array of objects (synchronous)
+ * @param {string} inputFileName - Path to input CSV file
+ * @returns {Array<object>} Array of objects representing CSV rows
+ * @throws {Error} If inputFileName is not defined
+ * @throws {FileOperationError} If file read fails
+ * @throws {CsvFormatError} If CSV is malformed
+ * @example
+ * const csvToJson = require('convert-csv-to-json');
+ * const rows = csvToJson.getJsonFromCsv('resource/input.csv');
+ * console.log(rows);
  */
 exports.getJsonFromCsv = function(inputFileName) {
   if (!inputFileName) {
@@ -165,10 +220,18 @@ exports.getJsonFromCsv = function(inputFileName) {
 };
 
 /**
- * Async version of getJsonFromCsv.
- * @param {string} inputFileNameOrCsv path to file or CSV string
- * @param {object} options { raw: boolean } when raw=true the first param is treated as CSV content
- * @returns {Promise<Array>} resolves with the array of objects
+ * Parse CSV file asynchronously and return parsed data as JSON array
+ * @param {string} inputFileNameOrCsv - 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
+ * @throws {InputValidationError} If input is invalid
+ * @throws {FileOperationError} If file read fails
+ * @throws {CsvFormatError} If CSV is malformed
+ * @example
+ * const csvToJson = require('convert-csv-to-json');
+ * const data = await csvToJson.getJsonFromCsvAsync('resource/input.csv');
+ * console.log(data);
  */
 const csvToJsonAsync = require('./src/csvToJsonAsync');
 
@@ -188,14 +251,28 @@ Object.assign(exports, {
   }
 });
 
+/**
+ * Parse a CSV string and return as JSON array of objects (synchronous)
+ * @param {string} csvString - CSV content as string
+ * @returns {Array<object>} Array of objects representing CSV rows
+ * @throws {InputValidationError} If csvString is invalid
+ * @throws {CsvFormatError} If CSV is malformed
+ * @example
+ * const csvToJson = require('convert-csv-to-json');
+ * const rows = csvToJson.csvStringToJson('name,age\nAlice,30');
+ * console.log(rows); // [{ name: 'Alice', age: '30' }]
+ */
 exports.csvStringToJson = function(csvString) {
   return csvToJson.csvStringToJson(csvString);
 };
 
 /**
- * Parses a csv string and returns a JSON string (validated)
- * @param {csvString} csvString CSV content as string
- * @return {string} JSON stringified result
+ * Parse CSV string and return as stringified JSON (synchronous)
+ * @param {string} csvString - CSV content as string
+ * @returns {string} JSON stringified array of objects
+ * @throws {InputValidationError} If csvString is invalid
+ * @throws {CsvFormatError} If CSV is malformed
+ * @throws {JsonValidationError} If JSON generation fails
  */
 exports.csvStringToJsonStringified = function(csvString) {
   if (csvString === undefined || csvString === null) {

package/jsdoc.json

@@ -0,0 +1,17 @@
+{
+  "source": {
+    "include": ["src", "index.js"],
+    "includePattern": ".+\\.js(doc|x)?$",
+    "excludePattern": "(^|/)node_modules(/|$)"
+  },
+  "opts": {
+    "destination": "./docs/jsdoc",
+    "recurse": true,
+    "readme": "./README.md"
+  },
+  "plugins": ["plugins/markdown"],
+  "templates": {
+    "cleverLinks": false,
+    "monospaceLinks": false
+  }
+}

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "convert-csv-to-json",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "description": "Convert CSV to JSON",
   "main": "index.js",
   "types": "index.d.ts",
   "scripts": {
     "test": "jest",
     "test-debug": "node --inspect-brk node_modules/.bin/jest --runInBand --detectOpenHandles",
+    "lint": "eslint .",
+    "docs": "jsdoc -c jsdoc.json",
+    "docs:api": "jsdoc -c jsdoc.json -d docs/api",
+    "prepublishOnly": "npm run docs:api",
     "version-patch": "npm version patch",
     "version-minor": "npm version minor",
     "version-major": "npm version major",
@@ -45,10 +49,13 @@
   },
   "homepage": "https://github.com/iuccio/CSVtoJSON#readme",
   "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "eslint": "^8.57.0",
+    "eslint-plugin-jsdoc": "^44.1.0",
     "jest": "^30.2.0",
+    "jsdoc": "^4.0.5",
     "ts-jest": "^29.4.5",
-    "typescript": "^5.9.3",
-    "@types/jest": "^30.0.0"
+    "typescript": "^5.9.3"
   },
   "publishConfig": {
     "provenance": true,

package/src/browserApi.js

@@ -1,51 +1,106 @@
+/* globals CsvFormatError */
+
 "use strict";
 
 const csvToJson = require('./csvToJson');
 const { InputValidationError, BrowserApiError } = require('./util/errors');
 
+/**
+ * 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
+ */
 class BrowserApi {
+  /**
+   * Constructor initializes proxy to sync csvToJson instance
+   */
   constructor() {
     // reuse the existing csvToJson instance for parsing and configuration
     this.csvToJson = csvToJson;
   }
 
-  // Configuration proxies (chainable)
+  /**
+   * 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 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} 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;
   }
 
-  // Synchronous parse from CSV string (browser friendly)
+  /**
+   * Parse a CSV string and return as JSON array of objects
+   * @param {string} csvString - CSV content as string
+   * @returns {Array<object>} Array of objects representing CSV rows
+   * @throws {InputValidationError} If csvString is invalid
+   * @throws {CsvFormatError} If CSV is malformed
+   * @example
+   * const csvToJson = require('convert-csv-to-json');
+   * const rows = csvToJson.browser.csvStringToJson('name,age\nAlice,30');
+   * console.log(rows); // [{ name: 'Alice', age: '30' }]
+   */
   csvStringToJson(csvString) {
     if (csvString === undefined || csvString === null) {
       throw new InputValidationError(
@@ -58,6 +113,17 @@ class BrowserApi {
     return this.csvToJson.csvToJson(csvString);
   }
 
+  /**
+   * Parse a CSV string and return as stringified JSON
+   * @param {string} csvString - CSV content as string
+   * @returns {string} JSON stringified array of objects
+   * @throws {InputValidationError} If csvString is invalid
+   * @throws {CsvFormatError} If CSV is malformed
+   * @example
+   * const csvToJson = require('convert-csv-to-json');
+   * const jsonString = csvToJson.browser.csvStringToJsonStringified('name,age\nAlice,30');
+   * console.log(jsonString);
+   */
   csvStringToJsonStringified(csvString) {
     if (csvString === undefined || csvString === null) {
       throw new InputValidationError(
@@ -70,11 +136,32 @@ class BrowserApi {
     return this.csvToJson.csvStringToJsonStringified(csvString);
   }
 
-  // Async parse from CSV string (returns a Promise)
+  /**
+   * Parse a CSV string asynchronously (returns resolved Promise)
+   * @param {string} csvString - CSV content as string
+   * @returns {Promise<Array<object>>} Promise resolving to array of objects
+   * @throws {InputValidationError} If csvString is invalid
+   * @throws {CsvFormatError} If CSV is malformed
+   * @example
+   * const csvToJson = require('convert-csv-to-json');
+   * const rows = await csvToJson.browser.csvStringToJsonAsync('name,age\nAlice,30');
+   * console.log(rows);
+   */
   csvStringToJsonAsync(csvString) {
     return Promise.resolve(this.csvStringToJson(csvString));
   }
 
+  /**
+   * Parse a CSV string asynchronously and return as stringified JSON
+   * @param {string} csvString - CSV content as string
+   * @returns {Promise<string>} Promise resolving to JSON stringified array
+   * @throws {InputValidationError} If csvString is invalid
+   * @throws {CsvFormatError} If CSV is malformed
+   * @example
+   * const csvToJson = require('convert-csv-to-json');
+   * const json = await csvToJson.browser.csvStringToJsonStringifiedAsync('name,age\nAlice,30');
+   * console.log(json);
+   */
   csvStringToJsonStringifiedAsync(csvString) {
     return Promise.resolve(this.csvStringToJsonStringified(csvString));
   }
@@ -83,7 +170,12 @@ class BrowserApi {
    * Parse a browser File or Blob object to JSON array.
    * @param {File|Blob} file - File or Blob to read as text
    * @param {object} options - options: { encoding?: string }
-   * @returns {Promise<any[]>}
+   * @returns {Promise<any[]>} Promise resolving to parsed JSON rows
+   * @example
+   * const csvToJson = require('convert-csv-to-json');
+   * const fileInput = document.querySelector('#csvfile').files[0];
+   * const rows = await csvToJson.browser.parseFile(fileInput);
+   * console.log(rows);
    */
   parseFile(file, options = {}) {
     if (!file) {