convert-csv-to-json 4.1.0 → 4.3.0

package/src/util/fileUtils.js

@@ -3,8 +3,19 @@
 const fs = require('fs');
 const { FileOperationError } = require('./errors');
 
+/**
+ * File I/O utilities for reading and writing CSV/JSON files
+ * Provides both synchronous and asynchronous file operations
+ */
 class FileUtils {
 
+    /**
+     * Read a file synchronously with specified encoding
+     * @param {string} fileInputName - Path to file to read
+     * @param {string} encoding - File encoding (e.g., 'utf8', 'latin1')
+     * @returns {string} File contents as string
+     * @throws {FileOperationError} If file read fails
+     */
     readFile(fileInputName, encoding) {
         try {
             return fs.readFileSync(fileInputName, encoding).toString();
@@ -13,6 +24,14 @@ class FileUtils {
         }
     }
 
+    /**
+     * Read a file asynchronously with specified encoding
+     * Uses fs.promises when available, falls back to callback-based API
+     * @param {string} fileInputName - Path to file to read
+     * @param {string} encoding - File encoding (default: 'utf8')
+     * @returns {Promise<string>} Promise resolving to file contents
+     * @throws {FileOperationError} If file read fails
+     */
     readFileAsync(fileInputName, encoding = 'utf8') {
         // Use fs.promises when available for a Promise-based API
         if (fs.promises && typeof fs.promises.readFile === 'function') {
@@ -33,6 +52,13 @@ class FileUtils {
         });
     }
 
+    /**
+     * Write content to a file synchronously
+     * Logs confirmation message to console on success
+     * @param {string} json - Content to write to file
+     * @param {string} fileOutputName - Path to output file
+     * @throws {FileOperationError} If file write fails
+     */
     writeFile(json, fileOutputName) {
         fs.writeFile(fileOutputName, json, function (err) {
             if (err) {
@@ -43,6 +69,14 @@ class FileUtils {
         });
     }
 
+    /**
+     * Write content to a file asynchronously
+     * Uses fs.promises when available, falls back to callback-based API
+     * @param {string} json - Content to write to file
+     * @param {string} fileOutputName - Path to output file
+     * @returns {Promise<void>} Promise that resolves when write completes
+     * @throws {FileOperationError} If file write fails
+     */
     writeFileAsync(json, fileOutputName) {
         if (fs.promises && typeof fs.promises.writeFile === 'function') {
             return fs.promises.writeFile(fileOutputName, json)

package/src/util/jsonUtils.js

@@ -2,8 +2,16 @@
 
 const { JsonValidationError } = require('./errors');
 
+/**
+ * JSON validation utilities
+ */
 class JsonUtil {
 
+    /**
+     * Validate that a string is valid JSON
+     * @param {string} json - JSON string to validate
+     * @throws {JsonValidationError} If JSON is invalid
+     */
     validateJson(json) {
         try {
             JSON.parse(json);

package/src/util/stringUtils.js

@@ -64,34 +64,79 @@ 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
+     * @returns {boolean} True if value is undefined or empty string
+     * @private
+     */
     isEmpty(value) {
         return value === undefined || value === '';
     }
 
+    /**
+     * Check if a value is a boolean string ('true' or 'false', case-insensitive)
+     * @param {string} value - Value to check
+     * @returns {boolean} True if value is 'true' or 'false'
+     * @private
+     */
     isBoolean(value) {
         const normalizedValue = value.toLowerCase();
         return normalizedValue === StringUtils.BOOLEAN_VALUES.TRUE || 
                normalizedValue === StringUtils.BOOLEAN_VALUES.FALSE;
     }
 
+    /**
+     * Check if a value is an integer string (with optional leading minus sign)
+     * @param {string} value - Value to check
+     * @returns {boolean} True if value matches integer pattern
+     * @private
+     */
     isInteger(value) {
         return StringUtils.PATTERNS.INTEGER.test(value);
     }
 
+    /**
+     * Check if a value is a float string (decimal number with optional leading minus sign)
+     * @param {string} value - Value to check
+     * @returns {boolean} True if value matches float pattern
+     * @private
+     */
     isFloat(value) {
         return StringUtils.PATTERNS.FLOAT.test(value);
     }
 
+    /**
+     * Check if a numeric string has a leading zero (e.g., '01' or '-01')
+     * Leading zeros indicate the value should be kept as a string to preserve formatting
+     * @param {string} value - Numeric string value to check
+     * @returns {boolean} True if value has a leading zero
+     * @private
+     */
     hasLeadingZero(value) {
         const isPositiveWithLeadingZero = value.length > 1 && value[0] === '0';
         const isNegativeWithLeadingZero = value.length > 2 && value[0] === '-' && value[1] === '0';
         return isPositiveWithLeadingZero || isNegativeWithLeadingZero;
     }
 
+    /**
+     * Convert a boolean string to native boolean value
+     * Safely converts 'true' to true and 'false' to false
+     * @param {string} value - Boolean string ('true' or 'false')
+     * @returns {boolean} Native boolean value
+     * @private
+     */
     convertToBoolean(value) {
         return JSON.parse(value.toLowerCase());
     }
 
+    /**
+     * Convert an integer string to number or keep as string if it has leading zeros
+     * Preserves leading zeros in strings (e.g., '007' stays as string)
+     * @param {string} value - Integer string to convert
+     * @returns {number|string} Number if safe, otherwise string value
+     * @private
+     */
     convertInteger(value) {
         if (this.hasLeadingZero(value)) {
             return String(value);
@@ -101,6 +146,12 @@ class StringUtils {
         return Number.isSafeInteger(num) ? num : String(value);
     }
 
+    /**
+     * Convert a float string to number or keep as string if conversion is unsafe
+     * @param {string} value - Float string to convert
+     * @returns {number|string} Number if finite and valid, otherwise string value
+     * @private
+     */
     convertFloat(value) {
         const num = Number(value);
         return Number.isFinite(num) ? num : String(value);