convert-csv-to-json 4.13.0 → 4.15.0

package/.github/workflows/ci-cd.yml

@@ -10,7 +10,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x, 20.x, 22.x, 24.x, 25.x]
+        node-version: [20.x, 22.x, 24.x, 25.x]
         experimental: [true]
 
     steps:

package/eslint.config.js

@@ -0,0 +1,115 @@
+const js = require('@eslint/js');
+const jsdocPlugin = require('eslint-plugin-jsdoc');
+
+const jsdocRules = {
+  'jsdoc/check-alignment': 'error',
+  'jsdoc/check-param-names': 'error',
+  'jsdoc/check-tag-names': 'error',
+  'jsdoc/check-types': 'warn',
+  'jsdoc/no-undefined-types': 'warn',
+  'jsdoc/require-description': 'warn',
+  'jsdoc/require-param': 'error',
+  'jsdoc/require-returns': 'error',
+  'jsdoc/require-jsdoc': [
+    'warn',
+    {
+      require: {
+        FunctionDeclaration: true,
+        MethodDefinition: true,
+        ClassDeclaration: false,
+        ArrowFunctionExpression: false,
+        FunctionExpression: false,
+      },
+    },
+  ],
+};
+
+const sharedGlobals = {
+  // Node.js globals
+  console: 'readonly',
+  process: 'readonly',
+  Buffer: 'readonly',
+  __dirname: 'readonly',
+  __filename: 'readonly',
+  global: 'readonly',
+  clearInterval: 'readonly',
+  clearTimeout: 'readonly',
+  setInterval: 'readonly',
+  setTimeout: 'readonly',
+  // Browser globals
+  window: 'readonly',
+  document: 'readonly',
+  navigator: 'readonly',
+  location: 'readonly',
+  fetch: 'readonly',
+  XMLHttpRequest: 'readonly',
+  Blob: 'readonly',
+  File: 'readonly',
+  FileReader: 'readonly',
+  // Jest globals
+  describe: 'readonly',
+  it: 'readonly',
+  expect: 'readonly',
+  beforeEach: 'readonly',
+  afterEach: 'readonly',
+  beforeAll: 'readonly',
+  afterAll: 'readonly',
+  test: 'readonly',
+  jest: 'readonly',
+};
+
+module.exports = [
+  {
+    ignores: ['node_modules', 'coverage', 'docs', '.eslintignore'],
+  },
+  {
+    files: ['**/*.js'],
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType: 'commonjs',
+      globals: sharedGlobals,
+    },
+    plugins: {
+      jsdoc: jsdocPlugin,
+    },
+    settings: {
+      jsdoc: {
+        tagNamePreference: {
+          category: 'category'
+        }
+      }
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...jsdocPlugin.configs.recommended.rules,
+      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+      ...jsdocRules,
+      'no-mixed-spaces-and-tabs': 'off',
+      'no-prototype-builtins': 'off',
+    },
+  },
+  {
+    files: ['jest.config.js'],
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType: 'commonjs',
+      globals: sharedGlobals,
+    },
+    rules: {
+      'jsdoc/require-jsdoc': 'off',
+    },
+  },
+  {
+    files: ['test/**/*.js', 'test/**/*.spec.js'],
+    languageOptions: {
+      ecmaVersion: 2024,
+      sourceType: 'commonjs',
+      globals: sharedGlobals,
+    },
+    rules: {
+      'jsdoc/require-jsdoc': 'off',
+      'no-unused-vars': 'off',
+    },
+  },
+];
+

package/index.js

@@ -22,6 +22,7 @@ const encodingOps = {
 /**
  * Enable or disable automatic type formatting for values
  * Converts numeric strings to numbers, 'true'/'false' to booleans
+ * @category 1-Core API
  * @param {boolean} active - Whether to format values by type (default: true)
  * @returns {object} Module context for method chaining
  */
@@ -33,6 +34,7 @@ exports.formatValueByType = function (active = true) {
 /**
  * Enable or disable support for RFC 4180 quoted fields
  * When enabled, fields wrapped in double quotes can contain delimiters and newlines
+ * @category 1-Core API
  * @param {boolean} active - Whether to support quoted fields (default: false)
  * @returns {object} Module context for method chaining
  */
@@ -42,6 +44,7 @@ exports.supportQuotedField = function (active = false) {
 };
 /**
  * Set the field delimiter character used to separate CSV fields
+ * @category 1-Core API
  * @param {string} delimiter - Character(s) to use as field separator (default: ',')
  * @returns {object} Module context for method chaining
  */
@@ -54,6 +57,7 @@ exports.fieldDelimiter = function (delimiter) {
  * 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
+ * @category 1-Core API
  * @param {boolean} active - Whether to remove all whitespace from headers (default: false)
  * @returns {object} Module context for method chaining
  */
@@ -65,6 +69,7 @@ exports.trimHeaderFieldWhiteSpace = function (active = false) {
 /**
  * Set the row index where CSV headers are located
  * Use this if headers are not on the first line (row 0)
+ * @category 1-Core API
  * @param {number} index - Zero-based row index containing headers
  * @returns {object} Module context for method chaining
  */
@@ -76,6 +81,7 @@ exports.indexHeader = function (index) {
 /**
  * Configure sub-array parsing for special field values
  * Fields bracketed by delimiter and containing separator are parsed into arrays
+ * @category 1-Core API
  * @param {string} delimiter - Bracket character (default: '*')
  * @param {string} separator - Item separator within brackets (default: ',')
  * @returns {object} Module context for method chaining
@@ -92,6 +98,7 @@ exports.parseSubArray = function (delimiter, separator) {
 /**
  * Set custom file encoding for reading CSV files
  * Useful for non-UTF8 encoded files
+ * @category 1-Core API
  * @param {string} encoding - Node.js supported encoding (e.g., 'utf8', 'latin1', 'ascii')
  * @returns {object} Module context for method chaining
  */
@@ -102,6 +109,7 @@ exports.customEncoding = function (encoding) {
 
 /**
  * Set UTF-8 encoding (default encoding)
+ * @category 1-Core API
  * @returns {object} Module context for method chaining
  */
 exports.utf8Encoding = function utf8Encoding() {
@@ -111,6 +119,7 @@ exports.utf8Encoding = function utf8Encoding() {
 
 /**
  * Set UCS-2 encoding for reading files
+ * @category 1-Core API
  * @returns {object} Module context for method chaining
  */
 exports.ucs2Encoding = function () {
@@ -120,6 +129,7 @@ exports.ucs2Encoding = function () {
 
 /**
  * Set UTF-16 LE encoding for reading files
+ * @category 1-Core API
  * @returns {object} Module context for method chaining
  */
 exports.utf16leEncoding = function () {
@@ -129,6 +139,7 @@ exports.utf16leEncoding = function () {
 
 /**
  * Set Latin-1 (ISO-8859-1) encoding for reading files
+ * @category 1-Core API
  * @returns {object} Module context for method chaining
  */
 exports.latin1Encoding = function () {
@@ -138,6 +149,7 @@ exports.latin1Encoding = function () {
 
 /**
  * Set ASCII encoding for reading files
+ * @category 1-Core API
  * @returns {object} Module context for method chaining
  */
 exports.asciiEncoding = function () {
@@ -147,6 +159,7 @@ exports.asciiEncoding = function () {
 
 /**
  * Set Base64 encoding for reading files
+ * @category 1-Core API
  * @returns {object} Module context for method chaining
  */
 exports.base64Encoding = function () {
@@ -156,6 +169,7 @@ exports.base64Encoding = function () {
 
 /**
  * Set Hex encoding for reading files
+ * @category 1-Core API
  * @returns {object} Module context for method chaining
  */
 exports.hexEncoding = function () {
@@ -167,7 +181,8 @@ exports.hexEncoding = function () {
  * 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: `(row, index) => transformedRow | null`
+ * @category 1-Core API
+ * @param {function(object, number): (object|null)} mapperFn - Function to transform each row
  * @returns {object} Module context for method chaining
  * @example
  * csvToJson
@@ -186,6 +201,7 @@ exports.mapRows = function (mapperFn) {
  * @throws {Error} If inputFileName or outputFileName is not defined
  * @throws {FileOperationError} If file operations fail
  * @throws {CsvFormatError} If CSV is malformed
+ * @category 1-Core API
  * @example
  * const csvToJson = require('convert-csv-to-json');
  * csvToJson.generateJsonFileFromCsv('input.csv', 'output.json');
@@ -207,6 +223,7 @@ exports.generateJsonFileFromCsv = function(inputFileName, outputFileName) {
  * @throws {Error} If inputFileName is not defined
  * @throws {FileOperationError} If file read fails
  * @throws {CsvFormatError} If CSV is malformed
+ * @category 1-Core API
  * @example
  * const csvToJson = require('convert-csv-to-json');
  * const rows = csvToJson.getJsonFromCsv('resource/input.csv');
@@ -228,6 +245,7 @@ exports.getJsonFromCsv = function(inputFileName) {
  * @throws {InputValidationError} If input is invalid
  * @throws {FileOperationError} If file read fails
  * @throws {CsvFormatError} If CSV is malformed
+ * @category 1-Core API
  * @example
  * const csvToJson = require('convert-csv-to-json');
  * const data = await csvToJson.getJsonFromCsvAsync('resource/input.csv');
@@ -257,6 +275,7 @@ Object.assign(exports, {
  * @returns {Array<object>} Array of objects representing CSV rows
  * @throws {InputValidationError} If csvString is invalid
  * @throws {CsvFormatError} If CSV is malformed
+ * @category 1-Core API
  * @example
  * const csvToJson = require('convert-csv-to-json');
  * const rows = csvToJson.csvStringToJson('name,age\nAlice,30');
@@ -273,6 +292,7 @@ exports.csvStringToJson = function(csvString) {
  * @throws {InputValidationError} If csvString is invalid
  * @throws {CsvFormatError} If CSV is malformed
  * @throws {JsonValidationError} If JSON generation fails
+ * @category 1-Core API
  */
 exports.csvStringToJsonStringified = function(csvString) {
   if (csvString === undefined || csvString === null) {
@@ -283,8 +303,4 @@ exports.csvStringToJsonStringified = function(csvString) {
 
 
 
-/**
- * Browser API
- * Provides parsing helpers suitable for browser environments (parsing strings and File/Blob objects)
- */
 exports.browser = require('./src/browserApi');

package/jsdoc.json

@@ -5,13 +5,38 @@
     "excludePattern": "(^|/)node_modules(/|$)"
   },
   "opts": {
-    "destination": "./docs/jsdoc",
+    "destination": "./docs/api",
     "recurse": true,
-    "readme": "./README.md"
+    "readme": "./README.md",
+    "template": "./node_modules/better-docs"
+  },
+  "plugins": ["plugins/markdown", "node_modules/better-docs/category"],
+  "tags": {
+    "allowUnknownTags": ["category"]
   },
-  "plugins": ["plugins/markdown"],
   "templates": {
     "cleverLinks": false,
-    "monospaceLinks": false
+    "monospaceLinks": false,
+    "default": {
+      "outputSourceFiles": true,
+      "useLongNameInNav": true
+    },
+    "better-docs": {
+      "name": "Convert CSV to JSON",
+      "logo": "https://raw.githubusercontent.com/iuccio/CSVtoJSON/master/CSVtoJSON.png",
+      "css": "./node_modules/better-docs/css/better-docs.css",
+      "hideGenerator": false,
+      "trackingCode": "",
+      "navLinks": [
+        {
+          "label": "GitHub",
+          "href": "https://github.com/iuccio/CSVtoJSON"
+        },
+        {
+          "label": "NPM",
+          "href": "https://www.npmjs.com/package/convert-csv-to-json"
+        }
+      ]
+    }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convert-csv-to-json",
-  "version": "4.13.0",
+  "version": "4.15.0",
   "description": "Convert CSV to JSON",
   "main": "index.js",
   "types": "index.d.ts",
@@ -49,9 +49,11 @@
   },
   "homepage": "https://github.com/iuccio/CSVtoJSON#readme",
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/jest": "^30.0.0",
-    "eslint": "^8.57.0",
-    "eslint-plugin-jsdoc": "^44.1.0",
+    "better-docs": "^2.7.3",
+    "eslint": "^10.1.0",
+    "eslint-plugin-jsdoc": "^62.8.0",
     "jest": "^30.2.0",
     "jsdoc": "^4.0.5",
     "ts-jest": "^29.4.5",

package/src/browserApi.js

@@ -9,6 +9,7 @@ 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
+ * @category 4-Browser
  */
 class BrowserApi {
   /**
@@ -82,7 +83,7 @@ class BrowserApi {
 
   /**
    * 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
+   * @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) {
@@ -169,8 +170,8 @@ 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[]>} Promise resolving to parsed JSON rows
+   * @param {object} [options] - options: { encoding?: string }
+   * @returns {Promise<object[]>} Promise resolving to parsed JSON rows
    * @example
    * const csvToJson = require('convert-csv-to-json');
    * const fileInput = document.querySelector('#csvfile').files[0];

package/src/csvToJson.js

@@ -19,6 +19,7 @@ const CR = '\r';
 /**
  * Main CSV to JSON converter class
  * Provides chainable API for configuring and converting CSV data
+ * @category 2-Sync 
  */
 class CsvToJson {
 
@@ -108,8 +109,8 @@ class CsvToJson {
 
   /**
    * 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
+   * @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') {

package/src/csvToJsonAsync.js

@@ -8,6 +8,7 @@ const { InputValidationError } = require('./util/errors');
 /**
  * Asynchronous CSV to JSON converter
  * Proxies configuration to sync instance but provides async file I/O methods
+ * @category 3-Async
  */
 class CsvToJsonAsync {
     /**
@@ -81,7 +82,7 @@ class CsvToJsonAsync {
 
     /**
      * 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
+     * @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) {

package/src/util/errors.js

@@ -3,11 +3,13 @@
 /**
  * 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
+ * @category Error Classes
  */
 class CsvParsingError extends Error {
     /**
@@ -43,7 +45,7 @@ class CsvParsingError extends Error {
 
     /**
      * Format a context value for display in error message
-     * @param {*} value - Value to format
+     * @param {unknown} value - Value to format
      * @returns {string} Formatted value string
      * @private
      */
@@ -59,6 +61,7 @@ class CsvParsingError extends Error {
 /**
  * Input validation errors
  * Thrown when function parameters don't meet expected type or value requirements
+ * @category Error Classes
  */
 class InputValidationError extends CsvParsingError {
     /**
@@ -86,6 +89,7 @@ class InputValidationError extends CsvParsingError {
 /**
  * Configuration-related errors
  * Thrown when configuration options conflict or are invalid
+ * @category Error Classes
  */
 class ConfigurationError extends CsvParsingError {
     /**
@@ -121,7 +125,7 @@ class ConfigurationError extends CsvParsingError {
     /**
      * Create error for invalid header index
      * Occurs when indexHeader() receives non-numeric value
-     * @param {*} value - Invalid header index value
+     * @param {unknown} value - Invalid header index value
      * @returns {ConfigurationError} Configured error instance
      * @static
      */
@@ -141,6 +145,7 @@ class ConfigurationError extends CsvParsingError {
 /**
  * CSV parsing errors with detailed context
  * Thrown when CSV format is invalid or malformed
+ * @category Error Classes
  */
 class CsvFormatError extends CsvParsingError {
     /**
@@ -200,6 +205,7 @@ class CsvFormatError extends CsvParsingError {
 /**
  * File operation errors
  * Thrown when file read or write operations fail
+ * @category Error Classes
  */
 class FileOperationError extends CsvParsingError {
     /**
@@ -232,6 +238,7 @@ class FileOperationError extends CsvParsingError {
 /**
  * JSON validation errors
  * Thrown when parsed CSV data cannot be converted to valid JSON
+ * @category Error Classes
  */
 class JsonValidationError extends CsvParsingError {
     /**
@@ -262,6 +269,7 @@ class JsonValidationError extends CsvParsingError {
 /**
  * Browser-specific errors
  * Thrown when browser API operations fail
+ * @category Error Classes
  */
 class BrowserApiError extends CsvParsingError {
     /**

package/src/util/fileUtils.js

@@ -6,6 +6,7 @@ const { FileOperationError } = require('./errors');
 /**
  * File I/O utilities for reading and writing CSV/JSON files
  * Provides both synchronous and asynchronous file operations
+ * @category Utilities
  */
 class FileUtils {
 

package/src/util/jsonUtils.js

@@ -4,6 +4,7 @@ const { JsonValidationError } = require('./errors');
 
 /**
  * JSON validation utilities
+ * @category Utilities
  */
 class JsonUtil {
 

package/src/util/stringUtils.js

@@ -1,5 +1,9 @@
 'use strict';
 
+/**
+ * String processing utilities for CSV parsing
+ * @category Utilities
+ */
 class StringUtils {
     // Regular expressions as constants for better maintainability
     static PATTERNS = {
@@ -66,7 +70,7 @@ class StringUtils {
     // Private helper methods for type checking and conversion
     /**
      * Check if a value is empty (undefined or empty string)
-     * @param {*} value - Value to check
+     * @param {unknown} value - Value to check
      * @returns {boolean} True if value is undefined or empty string
      * @private
      */

package/.eslintignore

@@ -1,3 +0,0 @@
-node_modules
-coverage
-docs/api

package/.eslintrc.json

@@ -1,48 +0,0 @@
-{
-  "root": true,
-  "env": {
-    "node": true,
-    "browser": true,
-    "es2024": true,
-    "jest": true
-  },
-  "extends": [
-    "eslint:recommended",
-    "plugin:jsdoc/recommended"
-  ],
-  "plugins": ["jsdoc"],
-  "overrides": [
-    {
-      "files": ["test/**/*.js", "test/**/*.spec.js"],
-      "rules": {
-        "jsdoc/require-jsdoc": "off",
-        "no-unused-vars": "off"
-      }
-    }
-  ],
-  "rules": {
-    "no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }],
-    "jsdoc/check-alignment": "error",
-    "jsdoc/check-param-names": "error",
-    "jsdoc/check-tag-names": "error",
-    "jsdoc/check-types": "warn",
-    "jsdoc/no-undefined-types": "warn",
-    "jsdoc/require-description": "warn",
-    "jsdoc/require-param": "error",
-    "jsdoc/require-returns": "error",
-    "jsdoc/require-jsdoc": [
-      "warn",
-      {
-        "require": {
-          "FunctionDeclaration": true,
-          "MethodDefinition": true,
-          "ClassDeclaration": false,
-          "ArrowFunctionExpression": false,
-          "FunctionExpression": false
-        }
-      }
-    ],
-    "no-mixed-spaces-and-tabs": "off",
-    "no-prototype-builtins": "off"
-  }
-}