convert-csv-to-json 3.12.1 → 3.14.0

package/MIGRATION.md

@@ -0,0 +1,174 @@
+# Migration Guide: Moving from Sync to Async
+
+This guide will help you transition from the synchronous API to the new asynchronous API in csvToJson.
+
+## Table of Contents
+
+- [Basic Migration Patterns](#basic-migration-patterns)
+- [Common Patterns and Best Practices](#common-patterns-and-best-practices)
+- [Advanced Use Cases](#advanced-use-cases)
+- [Migration Tips](#migration-tips)
+
+## Basic Migration Patterns
+
+1. Direct file reading:
+```js
+// Before (sync)
+const json = csvToJson.getJsonFromCsv('input.csv');
+console.log(json);
+
+// After (async) - using Promises
+csvToJson.getJsonFromCsvAsync('input.csv')
+  .then(json => console.log(json))
+  .catch(err => console.error('Error:', err));
+
+// After (async) - using async/await
+async function readCsv() {
+  try {
+    const json = await csvToJson.getJsonFromCsvAsync('input.csv');
+    console.log(json);
+  } catch (err) {
+    console.error('Error:', err);
+  }
+}
+```
+
+2. File generation:
+```js
+// Before (sync)
+csvToJson.generateJsonFileFromCsv('input.csv', 'output.json');
+
+// After (async) - using Promises
+csvToJson.generateJsonFileFromCsvAsync('input.csv', 'output.json')
+  .then(() => console.log('File created'))
+  .catch(err => console.error('Error:', err));
+```
+
+3. Chained operations:
+```js
+// Before (sync)
+const json = csvToJson
+  .fieldDelimiter(',')
+  .formatValueByType()
+  .getJsonFromCsv('input.csv');
+
+// After (async)
+await csvToJson
+  .fieldDelimiter(',')
+  .formatValueByType()
+  .getJsonFromCsvAsync('input.csv');
+```
+
+## Common Patterns and Best Practices
+
+1. Processing multiple files:
+```js
+// Sequential processing
+async function processFiles(files) {
+  const results = [];
+  for (const file of files) {
+    const json = await csvToJson.getJsonFromCsvAsync(file);
+    results.push(json);
+  }
+  return results;
+}
+
+// Parallel processing
+async function processFilesParallel(files) {
+  const promises = files.map(file => 
+    csvToJson.getJsonFromCsvAsync(file)
+  );
+  return Promise.all(promises);
+}
+```
+
+2. Error handling:
+```js
+// Robust error handling
+async function processWithRetry(file, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await csvToJson.getJsonFromCsvAsync(file);
+    } catch (err) {
+      if (i === maxRetries - 1) throw err;
+      await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
+    }
+  }
+}
+```
+
+3. Processing raw CSV data:
+```js
+// Processing CSV from network request
+async function processCsvFromApi() {
+  const response = await fetch('https://api.example.com/data.csv');
+  const csvText = await response.text();
+  return csvToJson.getJsonFromCsvAsync(csvText, { raw: true });
+}
+```
+
+## Advanced Use Cases
+
+1. Streaming large files with async iteration:
+```js
+const { createReadStream } = require('fs');
+const { createInterface } = require('readline');
+
+async function* processLargeCsv(filePath) {
+  const fileStream = createReadStream(filePath);
+  const lines = createInterface({
+    input: fileStream,
+    crlfDelay: Infinity
+  });
+
+  const headers = await lines.next();
+  for await (const line of lines) {
+    const json = await csvToJson
+      .getJsonFromCsvAsync(headers.value + '\n' + line, { raw: true });
+    yield json[0];
+  }
+}
+
+// Usage
+for await (const record of processLargeCsv('large.csv')) {
+  console.log(record);
+}
+```
+
+2. Custom data transformation:
+```js
+async function processWithTransform(file) {
+  const json = await csvToJson
+    .formatValueByType()
+    .getJsonFromCsvAsync(file);
+  
+  return json.map(record => ({
+    ...record,
+    timestamp: new Date().toISOString(),
+    processed: true
+  }));
+}
+```
+
+3. Validation and filtering:
+```js
+async function processWithValidation(file) {
+  const json = await csvToJson.getJsonFromCsvAsync(file);
+  
+  return json.filter(record => {
+    // Validate required fields
+    if (!record.id || !record.name) return false;
+    // Validate data types
+    if (typeof record.age !== 'number') return false;
+    return true;
+  });
+}
+```
+
+## Migration Tips
+
+1. **Gradual Migration**: You can mix sync and async code during migration
+2. **Error Handling**: Always include proper error handling with async code
+3. **Testing**: Test both success and error cases
+4. **Performance**: Consider using `Promise.all()` for parallel processing
+5. **Memory**: For large files, consider streaming approaches

package/README.md

@@ -11,7 +11,7 @@
 ![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white)
 ![JavaScript](https://img.shields.io/badge/javascript-%23323330.svg?style=for-the-badge&logo=javascript&logoColor=%23F7DF1E)
 
-**This project is not dependent on others packages or libraries.**
+**This project is not dependent on others packages or libraries, and supports both synchronous and Promise-based asynchronous APIs.**
 
 This repository uses [![GitHub Action  - iuccio/npm-semantic-publish-action@latest](https://img.shields.io/badge/GitHub_Action_-iuccio%2Fnpm--semantic--publish--action%40latest-2ea44f)](https://github.com/marketplace/actions/npm-semver-publish)
 
@@ -27,7 +27,7 @@ show your :heart: and support.
 - [Prerequisites](#prerequisites)
 - [Install npm *convert-csv-to-json package*](#install-npm-convert-csv-to-json-package)
   * [Install](#install)
-  * [Usage](#usage)
+  * [Sync API Usage](#sync-api-usage)
     + [Generate JSON file](#generate-json-file)
     + [Generate Array of Object in JSON format](#generate-array-of-object-in-json-format)
     + [Generate Object with sub array](#generate-object-with-sub-array)
@@ -42,6 +42,12 @@ show your :heart: and support.
       - [Boolean](#boolean)
     + [Encoding](#encoding)
     + [Working with CSV strings directly](#working-with-csv-strings-directly)
+  * [Async API Usage](#async-api-usage)
+    + [Basic Async Operations](#basic-async-operations)
+    + [Working with Raw CSV Data](#working-with-raw-csv-data)
+    + [Processing Large Files](#processing-large-files)
+    + [Error Handling and Retries](#error-handling-and-retries)
+    + [Batch Processing](#batch-processing)
   * [Chaining Pattern](#chaining-pattern)
 - [Development](#development)
 - [CI CD github action](#ci-cd-github-action)
@@ -51,7 +57,7 @@ show your :heart: and support.
 <!-- tocstop -->
 
 ## Description
-Converts *csv* files to *JSON* files with Node.js. 
+Converts *csv* files to *JSON* files with Node.js. Supports both synchronous operations and Promise-based asynchronous operations, allowing integration with modern async/await patterns.
 
 Give an input file like:
 
@@ -112,7 +118,7 @@ Install package on your machine
 $ npm install -g convert-csv-to-json
 ```
 
-### Usage
+### Sync API Usage
 
 #### Generate JSON file
 ```js
@@ -221,13 +227,49 @@ If the header is not on the first line you can define the header index like:
 Empty rows are ignored and not parsed.
 
 #### Format property value by type
-If you want that a number will be printed as a Number type, and values *true* or *false* is printed as a boolean Type, use:
+The `formatValueByType()` function intelligently converts string values to their appropriate types while preserving data integrity. To enable automatic type conversion:
+
 ```js
- csvToJson.formatValueByType()
-            .getJsonFromCsv(fileInputName);
+csvToJson.formatValueByType()
+         .getJsonFromCsv(fileInputName);
+```
+
+This conversion follows these rules:
+
+##### Numbers
+- Regular integers and decimals are converted to Number type
+- Numbers with leading zeros are preserved as strings (e.g., "0012" stays "0012")
+- Large integers outside JavaScript's safe range are preserved as strings
+- Valid decimal numbers are converted to Number type
+
+For example:
+```json
+{
+  "normalInteger": 42,           // Converted to number
+  "decimal": 3.14,              // Converted to number
+  "leadingZeros": "0012345",    // Kept as string to preserve leading zeros
+  "largeNumber": "9007199254740992"  // Kept as string to preserve precision
+}
 ```
-For example: 
 
+##### Boolean
+Case-insensitive "true" or "false" strings are converted to boolean values:
+```json
+{
+  "registered": true,     // From "true" or "TRUE" or "True"
+  "active": false        // From "false" or "FALSE" or "False"
+}
+```
+
+##### Complete Example
+Input CSV:
+```csv
+first_name;last_name;email;gender;age;id;zip;registered
+Constantin;Langsdon;clangsdon0@hc360.com;Male;96;00123;123;true
+Norah;Raison;nraison1@wired.com;Female;32;987;00456;FALSE
+```
+
+Output JSON:
 ```json
 [
  {
@@ -236,8 +278,9 @@ For example:
   "email": "clangsdon0@hc360.com",
   "gender": "Male",
   "age": 96,
-  "zip": 123,
-  "registered": true
+  "id": "00123",        // Preserved leading zeros
+  "zip": 123,          // Converted to number
+  "registered": true   // Converted to boolean
  },
  {
   "first_name": "Norah",
@@ -245,29 +288,12 @@ For example:
   "email": "nraison1@wired.com",
   "gender": "Female",
   "age": 32,
-  "zip": "",
-  "registered": false
+  "id": "987",
+  "zip": "00456",      // Preserved leading zeros
+  "registered": false  // Case-insensitive boolean conversion
  }
 ]
 ```
-##### Number
-The property **age** is printed as 
-```json
- "age": 32
-```
-instead of
-```json
-  "age": "32"
- ```
-##### Boolean
-The property **registered** is printed as 
-```json
- "registered": true
-```
-instead of
-```json
-  "registered": "true"
- ```
 
 #### Encoding
 You can read and decode files with the following encoding:
@@ -331,21 +357,417 @@ let jsonArray = csvToJson
   .csvStringToJson(csvString);
 ```
 
-### Chaining Pattern
+## Async API Usage
 
-The exposed API is implemented with the [Method Chaining Pattern](https://en.wikipedia.org/wiki/Method_chaining), which means that multiple methods can be chained, e.g.:
+This library provides a Promise-based async API that's perfect for modern Node.js applications. For a detailed migration guide from sync to async API, see [MIGRATION.md](MIGRATION.md).
 
+### Basic Async Operations
+
+1. Convert CSV file to JSON:
 ```js
-let csvToJson = require('convert-csv-to-json');
+const csvToJson = require('convert-csv-to-json');
+
+// Using Promises
+csvToJson.getJsonFromCsvAsync('input.csv')
+  .then(json => console.log(json))
+  .catch(err => console.error('Error:', err));
+
+// Using async/await
+async function convertCsv() {
+  try {
+    const json = await csvToJson.getJsonFromCsvAsync('input.csv');
+    console.log(json);
+  } catch (err) {
+    console.error('Error:', err);
+  }
+}
+```
+
+2. Generate JSON file from CSV:
+```js
+// Using async/await with chain configuration
+async function convertAndSave() {
+  await csvToJson
+    .fieldDelimiter(',')
+    .formatValueByType()
+    .generateJsonFileFromCsvAsync('input.csv', 'output.json');
+}
+```
 
-csvToJson.fieldDelimiter(',')
-            .formatValueByType()
-            .parseSubArray("*",',')
-            .supportQuotedField(true)
-            .getJsonFromCsv('myInputFile.csv');
+### Working with Raw CSV Data
 
+Process CSV data from memory or network sources:
+
+```js
+// Example: Processing CSV from an API
+async function processCsvFromApi() {
+  const response = await fetch('https://api.example.com/data.csv');
+  const csvText = await response.text();
+  
+  const json = await csvToJson
+    .formatValueByType()
+    .getJsonFromCsvAsync(csvText, { raw: true });
+    
+  return json;
+}
+```
+
+### Processing Large Files
+
+For large files, use streaming to manage memory efficiently:
+
+```js
+const { createReadStream } = require('fs');
+const { createInterface } = require('readline');
+
+async function* processLargeFile(filePath) {
+  const fileStream = createReadStream(filePath);
+  const rl = createInterface({
+    input: fileStream,
+    crlfDelay: Infinity
+  });
+
+  for await (const line of rl) {
+    yield await csvToJson.getJsonFromCsvAsync(line, { raw: true });
+  }
+}
+
+// Usage
+async function processData() {
+  for await (const record of processLargeFile('large.csv')) {
+    await saveToDatabase(record);
+  }
+}
+```
+
+### Error Handling and Retries
+
+Implement robust error handling with retries:
+
+```js
+async function processWithRetry(filePath, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const json = await csvToJson
+        .formatValueByType()
+        .getJsonFromCsvAsync(filePath);
+      
+      return json;
+    } catch (err) {
+      if (i === maxRetries - 1) throw err;
+      // Exponential backoff
+      await new Promise(resolve => 
+        setTimeout(resolve, Math.pow(2, i) * 1000)
+      );
+    }
+  }
+}
+```
+
+### Batch Processing
+
+Process multiple files efficiently:
+
+```js
+async function batchProcess(files, batchSize = 3) {
+  const results = new Map();
+  
+  for (let i = 0; i < files.length; i += batchSize) {
+    const batch = files.slice(i, i + batchSize);
+    const processed = await Promise.all(
+      batch.map(async file => {
+        const json = await csvToJson.getJsonFromCsvAsync(file);
+        return [file, json];
+      })
+    );
+    
+    processed.forEach(([file, json]) => results.set(file, json));
+  }
+  
+  return results;
+}
+
+// Usage
+const files = ['data1.csv', 'data2.csv', 'data3.csv', 'data4.csv'];
+const results = await batchProcess(files, 2);
+```
+
+## Chaining Pattern
+
+The exposed API is implemented with the [Method Chaining Pattern](https://en.wikipedia.org/wiki/Method_chaining), which means that multiple methods can be chained. This pattern works with both synchronous and asynchronous methods:
+
+### Synchronous Chaining
+
+```js
+const csvToJson = require('convert-csv-to-json');
+
+// Chain configuration methods with sync operation
+const json = csvToJson
+    .fieldDelimiter(',')
+    .formatValueByType()
+    .parseSubArray("*", ',')
+    .supportQuotedField(true)
+    .getJsonFromCsv('myInputFile.csv');
+
+// Chain with file generation
+csvToJson
+    .fieldDelimiter(';')
+    .utf8Encoding()
+    .formatValueByType()
+    .generateJsonFileFromCsv('input.csv', 'output.json');
+
+// Chain with string parsing
+const jsonArray = csvToJson
+    .fieldDelimiter(',')
+    .trimHeaderFieldWhiteSpace(true)
+    .csvStringToJson('name,age\nJohn,30\nJane,25');
 ```
 
+### Asynchronous Chaining
+
+```js
+const csvToJson = require('convert-csv-to-json');
+
+// Using async/await
+async function processCSV() {
+    // Chain configuration methods with async operation
+    const json = await csvToJson
+        .fieldDelimiter(',')
+        .formatValueByType()
+        .parseSubArray("*", ',')
+        .supportQuotedField(true)
+        .getJsonFromCsvAsync('myInputFile.csv');
+
+    // Chain with async file generation
+    await csvToJson
+        .fieldDelimiter(';')
+        .utf8Encoding()
+        .formatValueByType()
+        .generateJsonFileFromCsvAsync('input.csv', 'output.json');
+}
+
+// Using Promises
+csvToJson
+    .fieldDelimiter(',')
+    .formatValueByType()
+    .getJsonFromCsvAsync('input.csv')
+    .then(json => console.log(json))
+    .catch(err => console.error('Error:', err));
+```
+
+All configuration methods can be chained in any order before calling the final operation method (like `getJsonFromCsv`, `getJsonFromCsvAsync`, etc.). The configuration will be applied in the order it is chained.
+
+## Common Use Cases
+
+Here are some common use cases and how to implement them:
+
+### 1. Processing CSV from HTTP Response
+```js
+const https = require('https');
+
+async function processRemoteCsv(url) {
+  const csvData = await new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => resolve(data));
+      res.on('error', reject);
+    });
+  });
+
+  return csvToJson.getJsonFromCsvAsync(csvData, { raw: true });
+}
+```
+
+### 2. Batch Processing Multiple Files
+```js
+async function batchProcess(files) {
+  const results = new Map();
+  
+  // Process in chunks of 3 files at a time
+  for (let i = 0; i < files.length; i += 3) {
+    const chunk = files.slice(i, i + 3);
+    const processed = await Promise.all(
+      chunk.map(async file => {
+        const json = await csvToJson.getJsonFromCsvAsync(file);
+        return [file, json];
+      })
+    );
+    
+    processed.forEach(([file, json]) => results.set(file, json));
+  }
+  
+  return results;
+}
+```
+
+### 3. Data Transformation Pipeline
+```js
+async function transformData(csvFile) {
+  // Step 1: Parse CSV
+  const json = await csvToJson
+    .formatValueByType()
+    .getJsonFromCsvAsync(csvFile);
+    
+  // Step 2: Transform data
+  const transformed = json.map(record => ({
+    id: record.id,
+    fullName: `${record.firstName} ${record.lastName}`,
+    age: Number(record.age),
+    isAdult: Number(record.age) >= 18,
+    email: record.email.toLowerCase()
+  }));
+  
+  // Step 3: Filter invalid records
+  return transformed.filter(record => 
+    record.id && 
+    record.fullName.length > 0 &&
+    !isNaN(record.age)
+  );
+}
+```
+
+### 4. Error Recovery and Logging
+```js
+async function processWithLogging(file) {
+  const logger = {
+    info: (msg) => console.log(`[INFO] ${msg}`),
+    error: (msg, err) => console.error(`[ERROR] ${msg}`, err)
+  };
+
+  try {
+    logger.info(`Starting processing ${file}`);
+    const startTime = Date.now();
+    
+    const json = await csvToJson.getJsonFromCsvAsync(file);
+    
+    const duration = Date.now() - startTime;
+    logger.info(`Processed ${file} in ${duration}ms`);
+    
+    return json;
+  } catch (err) {
+    logger.error(`Failed to process ${file}`, err);
+    throw err;
+  }
+}
+```
+
+## Troubleshooting
+
+Here are solutions to common issues you might encounter:
+
+### Memory Issues with Large Files
+
+If you're processing large CSV files and encountering memory issues:
+
+```js
+// Instead of loading the entire file
+const json = await csvToJson.getJsonFromCsvAsync('large.csv'); // ❌
+
+// Use streaming with async iteration
+for await (const record of processLargeCsv('large.csv')) {  // ✅
+  // Process one record at a time
+  await processRecord(record);
+}
+```
+
+### Handling Different CSV Formats
+
+1. **Mixed Quote Types**:
+```js
+csvToJson
+  .supportQuotedField(true)     // Enable quoted field support
+  .getJsonFromCsvAsync(file);
+```
+
+2. **Custom Delimiters**:
+```js
+csvToJson
+  .fieldDelimiter(';')          // Change delimiter
+  .getJsonFromCsvAsync(file);
+```
+
+3. **UTF-8 with BOM**:
+```js
+csvToJson
+  .encoding('utf8')             // Specify encoding
+  .getJsonFromCsvAsync(file);
+```
+
+### Common Error Solutions
+
+1. **ENOENT: no such file or directory**
+   - Check if the file path is correct and absolute
+   - Verify file permissions
+   - Ensure the file exists in the specified location
+
+2. **Invalid CSV Structure**
+   - Verify CSV format matches expected structure
+   - Check for missing or extra delimiters
+   - Validate header row exists if expected
+
+3. **Memory Leaks**
+   - Use streaming for large files
+   - Process files in smaller chunks
+   - Implement proper cleanup in try/finally blocks
+
+4. **Encoding Issues**
+   - Specify correct encoding using .encoding()
+   - Check for BOM markers
+   - Verify source file encoding
+
+### Performance Optimization
+
+1. **Parallel Processing**:
+```js
+// Instead of sequential processing
+for (const file of files) {
+  await process(file);  // ❌
+}
+
+// Use parallel processing with limits
+async function processWithLimit(files, limit = 3) {
+  const results = [];
+  for (let i = 0; i < files.length; i += limit) {
+    const chunk = files.slice(i, i + limit);
+    const chunkResults = await Promise.all(
+      chunk.map(file => csvToJson.getJsonFromCsvAsync(file))
+    );
+    results.push(...chunkResults);
+  }
+  return results;
+}  // ✅
+```
+
+2. **Memory Usage**:
+```js
+// Clear references when done
+async function processWithCleanup(file) {
+  let json;
+  try {
+    json = await csvToJson.getJsonFromCsvAsync(file);
+    return await processData(json);
+  } finally {
+    json = null;  // Clear reference
+  }
+}
+```
+
+### TypeScript Support
+
+If you're using TypeScript and encounter type issues:
+
+```typescript
+// Define custom types for your CSV structure
+interface MyCsvRecord {
+  id: number;
+  name: string;
+  age?: number;
+}
+
+// Use type assertion
+const json = await csvToJson.getJsonFromCsvAsync<MyCsvRecord>('data.csv');
+```
 
 ## Development
 * Download all csvToJson dependencies:

package/index.d.ts

@@ -91,6 +91,11 @@ declare module 'convert-csv-to-json' {
      */
     getJsonFromCsv(inputFileName: string): any[];
 
+  /**
+   * Async version of getJsonFromCsv. When options.raw is true the input is treated as a CSV string
+   */
+  getJsonFromCsvAsync(inputFileNameOrCsv: string, options?: { raw?: boolean }): Promise<any[]>;
+
     csvStringToJson(csvString: string): any[];
 
     /**

package/index.js

@@ -152,6 +152,30 @@ exports.getJsonFromCsv = function(inputFileName) {
   return csvToJson.getJsonFromCsv(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
+ */
+const csvToJsonAsync = require('./src/csvToJsonAsync');
+
+// 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);
+  }
+});
+
 exports.csvStringToJson = function(csvString) {
   return csvToJson.csvStringToJson(csvString);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convert-csv-to-json",
-  "version": "3.12.1",
+  "version": "3.14.0",
   "description": "Convert CSV to JSON",
   "main": "index.js",
   "types": "index.d.ts",

package/src/csvToJsonAsync.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const fileUtils = require('./util/fileUtils');
+const csvToJson = require('./csvToJson');
+
+class CsvToJsonAsync {
+    constructor() {
+        // Proxy the configuration methods to the sync instance
+        this.csvToJson = csvToJson;
+    }
+
+    /**
+     * Set value type formatting
+     */
+    formatValueByType(active) {
+        this.csvToJson.formatValueByType(active);
+        return this;
+    }
+
+    /**
+     * Set quoted field support
+     */
+    supportQuotedField(active) {
+        this.csvToJson.supportQuotedField(active);
+        return this;
+    }
+
+    /**
+     * Set field delimiter
+     */
+    fieldDelimiter(delimiter) {
+        this.csvToJson.fieldDelimiter(delimiter);
+        return this;
+    }
+
+    /**
+     * Trim header field whitespace
+     */
+    trimHeaderFieldWhiteSpace(active) {
+        this.csvToJson.trimHeaderFieldWhiteSpace(active);
+        return this;
+    }
+
+    /**
+     * Set header index
+     */
+    indexHeader(indexHeader) {
+        this.csvToJson.indexHeader(indexHeader);
+        return this;
+    }
+
+    /**
+     * Set sub-array parsing options
+     */
+    parseSubArray(delimiter = '*', separator = ',') {
+        this.csvToJson.parseSubArray(delimiter, separator);
+        return this;
+    }
+
+    /**
+     * Set encoding
+     */
+    encoding(encoding) {
+        this.csvToJson.encoding = encoding;
+        return this;
+    }
+
+    /**
+     * Async version of generateJsonFileFromCsv
+     */
+    async generateJsonFileFromCsv(fileInputName, fileOutputName) {
+        const jsonStringified = await this.getJsonFromCsvStringified(fileInputName);
+        await fileUtils.writeFileAsync(jsonStringified, fileOutputName);
+    }
+
+    /**
+     * Async version that returns stringified JSON from CSV file
+     */
+    async getJsonFromCsvStringified(fileInputName) {
+        const json = await this.getJsonFromCsvAsync(fileInputName);
+        return JSON.stringify(json, undefined, 1);
+    }
+
+    /**
+     * Main async API method. If options.raw is true, treats input as CSV string.
+     * Otherwise reads from file path.
+     */
+    async getJsonFromCsvAsync(inputFileNameOrCsv, options = {}) {
+        if (inputFileNameOrCsv === null || inputFileNameOrCsv === undefined) {
+            throw new Error('inputFileNameOrCsv is not defined!!!');
+        }
+
+        if (options.raw) {
+            if (inputFileNameOrCsv === '') {
+                return [];
+            }
+            return this.csvToJson.csvToJson(inputFileNameOrCsv);
+        }
+
+        const parsedCsv = await fileUtils.readFileAsync(inputFileNameOrCsv, this.csvToJson.encoding || 'utf8');
+        return this.csvToJson.csvToJson(parsedCsv);
+    }
+
+    /**
+     * Parse CSV string to JSON asynchronously
+     */
+    csvStringToJsonAsync(csvString, options = { raw: true }) {
+        return this.getJsonFromCsvAsync(csvString, options);
+    }
+
+    /**
+     * Parse CSV string to stringified JSON asynchronously
+     */
+    async csvStringToJsonStringifiedAsync(csvString) {
+        const json = await this.csvStringToJsonAsync(csvString);
+        return JSON.stringify(json, undefined, 1);
+    }
+}
+
+module.exports = new CsvToJsonAsync();

package/src/util/fileUtils.js

@@ -8,6 +8,23 @@ class FileUtils {
         return fs.readFileSync(fileInputName, encoding).toString();
     }
 
+    readFileAsync(fileInputName, encoding = 'utf8') {
+        // Use fs.promises when available for a Promise-based API
+        if (fs.promises && typeof fs.promises.readFile === 'function') {
+            return fs.promises.readFile(fileInputName, encoding)
+                .then(buf => buf.toString());
+        }
+        return new Promise((resolve, reject) => {
+            fs.readFile(fileInputName, encoding, (err, data) => {
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                resolve(data.toString());
+            });
+        });
+    }
+
     writeFile(json, fileOutputName) {
         fs.writeFile(fileOutputName, json, function (err) {
             if (err) {
@@ -18,5 +35,17 @@ class FileUtils {
         });
     }
 
+    writeFileAsync(json, fileOutputName) {
+        if (fs.promises && typeof fs.promises.writeFile === 'function') {
+            return fs.promises.writeFile(fileOutputName, json);
+        }
+        return new Promise((resolve, reject) => {
+            fs.writeFile(fileOutputName, json, (err) => {
+                if (err) return reject(err);
+                resolve();
+            });
+        });
+    }
+
 }
 module.exports = new FileUtils();

package/src/util/stringUtils.js

@@ -1,40 +1,109 @@
 'use strict';
 
 class StringUtils {
+    // Regular expressions as constants for better maintainability
+    static PATTERNS = {
+        INTEGER: /^-?\d+$/,
+        FLOAT: /^-?\d*\.\d+$/,
+        WHITESPACE: /\s/g
+    };
 
-    trimPropertyName(isTrimHeaderFieldWhiteSpace,value) {
-        if(isTrimHeaderFieldWhiteSpace) {
-            return value.replace(/\s/g, '');
+    static BOOLEAN_VALUES = {
+        TRUE: 'true',
+        FALSE: 'false'
+    };
+
+    /**
+     * Removes whitespace from property names based on configuration
+     * @param {boolean} shouldTrimAll - If true, removes all whitespace, otherwise only trims edges
+     * @param {string} propertyName - The property name to process
+     * @returns {string} The processed property name
+     */
+    trimPropertyName(shouldTrimAll, propertyName) {
+        if (!propertyName) {
+            return '';
         }
-        return value.trim();
-        
+        return shouldTrimAll ? 
+            propertyName.replace(StringUtils.PATTERNS.WHITESPACE, '') : 
+            propertyName.trim();
     }
 
+    /**
+     * Converts a string value to its appropriate type while preserving data integrity
+     * @param {string} value - The input value to convert
+     * @returns {string|number|boolean} The converted value
+     */
     getValueFormatByType(value) {
-        if(value === undefined || value === ''){
+        if (this.isEmpty(value)) {
             return String();
         }
-        //is Number
-        let isNumber = !isNaN(value);
-        if (isNumber) {
-            return Number(value);
+
+        if (this.isBoolean(value)) {
+            return this.convertToBoolean(value);
+        }
+
+        if (this.isInteger(value)) {
+            return this.convertInteger(value);
         }
-        // is Boolean
-        if(value === "true" || value === "false"){
-            return JSON.parse(value.toLowerCase());
+
+        if (this.isFloat(value)) {
+            return this.convertFloat(value);
         }
+
         return String(value);
     }
 
-    hasContent(values) {
-        if (values.length > 0) {
-            for (let i = 0; i < values.length; i++) {
-                if (values[i]) {
-                    return true;
-                }
-            }
+    /**
+     * Checks if a value array contains any non-empty values
+     * @param {Array} values - Array to check for content
+     * @returns {boolean} True if array has any non-empty values
+     */
+    hasContent(values = []) {
+        return Array.isArray(values) && 
+               values.some(value => Boolean(value));
+    }
+
+    // Private helper methods for type checking and conversion
+    isEmpty(value) {
+        return value === undefined || value === '';
+    }
+
+    isBoolean(value) {
+        const normalizedValue = value.toLowerCase();
+        return normalizedValue === StringUtils.BOOLEAN_VALUES.TRUE || 
+               normalizedValue === StringUtils.BOOLEAN_VALUES.FALSE;
+    }
+
+    isInteger(value) {
+        return StringUtils.PATTERNS.INTEGER.test(value);
+    }
+
+    isFloat(value) {
+        return StringUtils.PATTERNS.FLOAT.test(value);
+    }
+
+    hasLeadingZero(value) {
+        const isPositiveWithLeadingZero = value.length > 1 && value[0] === '0';
+        const isNegativeWithLeadingZero = value.length > 2 && value[0] === '-' && value[1] === '0';
+        return isPositiveWithLeadingZero || isNegativeWithLeadingZero;
+    }
+
+    convertToBoolean(value) {
+        return JSON.parse(value.toLowerCase());
+    }
+
+    convertInteger(value) {
+        if (this.hasLeadingZero(value)) {
+            return String(value);
         }
-        return false;
+
+        const num = Number(value);
+        return Number.isSafeInteger(num) ? num : String(value);
+    }
+
+    convertFloat(value) {
+        const num = Number(value);
+        return Number.isFinite(num) ? num : String(value);
     }
 }