convert-csv-to-json 3.27.0 → 4.0.0

package/docs/SYNC.md

@@ -0,0 +1,239 @@
+# Synchronous API Documentation
+
+Transform CSV files into JSON objects synchronously. Perfect for simple use cases and straightforward data processing workflows.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Generate JSON File](#generate-json-file)
+- [Generate Array of Objects](#generate-array-of-objects)
+- [Configuration Options](#configuration-options)
+- [Advanced Features](#advanced-features)
+- [TypeScript Support](#typescript-support)
+
+## Basic Usage
+
+```js
+const csvToJson = require('convert-csv-to-json');
+
+// Parse CSV file
+const json = csvToJson.getJsonFromCsv('input.csv');
+console.log(json);
+```
+
+## Generate JSON File
+
+```js
+const csvToJson = require('convert-csv-to-json');
+
+csvToJson.generateJsonFileFromCsv('input.csv', 'output.json');
+```
+
+## Generate Array of Objects
+
+```js
+const csvToJson = require('convert-csv-to-json');
+
+const json = csvToJson.getJsonFromCsv('input.csv');
+json.forEach(record => {
+  console.log(record);
+});
+```
+
+## Configuration Options
+
+### Field Delimiter
+
+Comma (`,`) is the default delimiter per RFC 4180. Use `fieldDelimiter()` for other delimiters:
+
+```js
+// Semicolon-delimited
+csvToJson.fieldDelimiter(';').getJsonFromCsv('file.csv');
+
+// Tab-delimited
+csvToJson.fieldDelimiter('\t').getJsonFromCsv('file.tsv');
+
+// Pipe-delimited
+csvToJson.fieldDelimiter('|').getJsonFromCsv('file.psv');
+```
+
+### Quoted Fields
+
+Enable support for fields wrapped in quotes (useful when fields contain delimiters, newlines, or quotes):
+
+```js
+csvToJson
+  .supportQuotedField(true)
+  .getJsonFromCsv('file.csv');
+```
+
+**Example Input:**
+```csv
+name,description
+"Smith, John","He said ""Hello"""
+Jane,"Multi-line
+description"
+```
+
+**Output:**
+```json
+[
+  { "name": "Smith, John", "description": "He said \"Hello\"" },
+  { "name": "Jane", "description": "Multi-line\ndescription" }
+]
+```
+
+### Format Values by Type
+
+Automatically convert string values to appropriate types (numbers, booleans):
+
+```js
+csvToJson.formatValueByType().getJsonFromCsv('file.csv');
+```
+
+**Conversion Rules:**
+- `"true"` / `"false"` (case-insensitive) → boolean
+- `"123"` → number
+- `"0012"` → string (preserves leading zeros)
+- Other values → string
+
+**Example:**
+```csv
+name,age,active,id
+John,30,true,0012
+Jane,25,false,987
+```
+
+**Output:**
+```json
+[
+  { "name": "John", "age": 30, "active": true, "id": "0012" },
+  { "name": "Jane", "age": 25, "active": false, "id": "987" }
+]
+```
+
+### Trim Header Field
+
+Remove whitespace from header names:
+
+```js
+// Trim leading/trailing spaces
+csvToJson.trimHeaderField().getJsonFromCsv('file.csv');
+
+// Remove all whitespace from headers
+csvToJson.trimHeaderFieldWhiteSpace(true).getJsonFromCsv('file.csv');
+```
+
+**Example:**
+```csv
+ First Name , Last Name 
+John,Doe
+```
+
+**With `trimHeaderFieldWhiteSpace(true)`:**
+```json
+[{ "FirstName": "John", "LastName": "Doe" }]
+```
+
+### Custom Encoding
+
+Read files with specific encoding:
+
+```js
+csvToJson.utf8Encoding().getJsonFromCsv('file.csv');          // UTF-8
+csvToJson.latin1Encoding().getJsonFromCsv('file.csv');        // Latin-1
+csvToJson.ucs2Encoding().getJsonFromCsv('file.csv');          // UCS-2
+csvToJson.utf16leEncoding().getJsonFromCsv('file.csv');       // UTF-16LE
+csvToJson.asciiEncoding().getJsonFromCsv('file.csv');         // ASCII
+csvToJson.base64Encoding().getJsonFromCsv('file.csv');        // Base64
+csvToJson.hexEncoding().getJsonFromCsv('file.csv');           // Hex
+csvToJson.customEncoding('utf8').getJsonFromCsv('file.csv');  // Custom
+```
+
+### Header Index
+
+Specify which row contains headers (default is row 0):
+
+```js
+// Headers in row 2 (3rd row)
+csvToJson.indexHeader(2).getJsonFromCsv('file.csv');
+```
+
+## Advanced Features
+
+### Parse Sub-Arrays
+
+Parse delimited values within fields into arrays:
+
+```js
+csvToJson
+  .parseSubArray('*', ',')  // Fields wrapped in * contain comma-separated values
+  .getJsonFromCsv('file.csv');
+```
+
+**Example Input:**
+```csv
+name,email,tags
+John,john@example.com,*javascript,nodejs,typescript*
+Jane,jane@example.com,*python,django*
+```
+
+**Output:**
+```json
+[
+  { "name": "John", "email": "john@example.com", "tags": ["javascript", "nodejs", "typescript"] },
+  { "name": "Jane", "email": "jane@example.com", "tags": ["python", "django"] }
+]
+```
+
+### Work with CSV Strings
+
+Parse CSV content directly from strings:
+
+```js
+const csv = 'name,age\nJohn,30\nJane,25';
+const json = csvToJson.csvStringToJson(csv);
+// Output: [{ name: 'John', age: '30' }, { name: 'Jane', age: '25' }]
+
+// Get as JSON string
+const jsonString = csvToJson.csvStringToJsonStringified(csv);
+```
+
+### Method Chaining
+
+Combine multiple configuration options:
+
+```js
+const json = csvToJson
+  .fieldDelimiter(';')
+  .formatValueByType()
+  .supportQuotedField(true)
+  .trimHeaderFieldWhiteSpace(true)
+  .getJsonFromCsv('file.csv');
+```
+
+## TypeScript Support
+
+```ts
+import csvToJson from 'convert-csv-to-json';
+
+interface Person {
+  name: string;
+  age: number;
+  email: string;
+}
+
+// Parse with type assertion
+const people = csvToJson
+  .formatValueByType()
+  .getJsonFromCsv('people.csv') as Person[];
+
+// Parse CSV string
+const csv = 'name,age\nAlice,30';
+const parsed = csvToJson.csvStringToJson(csv) as Person[];
+```
+
+## See Also
+
+- [Main README](../README.md) - Overview and installation
+- [Async API](ASYNC.md) - Asynchronous operations with Promises/async-await
+- [Browser API](BROWSER.md) - Client-side CSV parsing

package/index.d.ts

@@ -72,6 +72,14 @@ declare module 'convert-csv-to-json' {
      */
     hexEncoding(): this;
 
+    /**
+     * Sets 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 mapperFn Function that receives (row: any, index: number) => any | null
+     */
+    mapRows(mapperFn: (row: any, index: number) => any | null): this;
+
     /**
      * Parses .csv file and put its content into a file in json format.
      * @param {inputFileName} path/filename
@@ -105,14 +113,7 @@ declare module 'convert-csv-to-json' {
     */
     csvStringToJsonStringified(csvString: string): string;
     
-    /**
-     * Parses .csv file and put its content into a file in json format.
-     * @param {inputFileName} path/filename
-     * @param {outputFileName} path/filename
-     *
-     * @deprecated Use generateJsonFileFromCsv()
-     */
-    jsonToCsv(inputFileName: string, outputFileName: string): void;
+
   }
   const converter: ConvertCsvToJson;
   export default converter;
@@ -127,6 +128,7 @@ declare module 'convert-csv-to-json' {
     fieldDelimiter(delimiter: string): this;
     indexHeader(index: number): this;
     parseSubArray(delimiter: string, separator: string): this;
+    mapRows(mapperFn: (row: any, index: number) => any | null): this;
 
     csvStringToJson(csvString: string): any[];
     csvStringToJsonStringified(csvString: string): string;

package/index.js

@@ -123,6 +123,18 @@ exports.hexEncoding = function () {
   return this;
 };
 
+/**
+ * Sets 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
+ */
+exports.mapRows = function (mapperFn) {
+  csvToJson.mapRows(mapperFn);
+  return this;
+};
+
 /**
  * Parses .csv file and put its content into a file in json format.
  * @param {inputFileName} path/filename
@@ -192,16 +204,7 @@ exports.csvStringToJsonStringified = function(csvString) {
   return csvToJson.csvStringToJsonStringified(csvString);
 };
 
-/**
- * Parses .csv file and put its content into a file in json format.
- * @param {inputFileName} path/filename
- * @param {outputFileName} path/filename
- *
- * @deprecated Use generateJsonFileFromCsv()
- */
-exports.jsonToCsv = function(inputFileName, outputFileName) {
-  csvToJson.generateJsonFileFromCsv(inputFileName, outputFileName);
-};
+
 
 /**
  * Browser API

package/package.json

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

package/src/browserApi.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const csvToJson = require('./csvToJson');
+const { InputValidationError, BrowserApiError } = require('./util/errors');
 
 class BrowserApi {
   constructor() {
@@ -39,17 +40,32 @@ class BrowserApi {
     return this;
   }
 
+  mapRows(mapperFn) {
+    this.csvToJson.mapRows(mapperFn);
+    return this;
+  }
+
   // Synchronous parse from CSV string (browser friendly)
   csvStringToJson(csvString) {
     if (csvString === undefined || csvString === null) {
-      throw new Error('csvString is not defined!!!');
+      throw new InputValidationError(
+        'csvString',
+        'string',
+        `${typeof csvString}`,
+        'Provide valid CSV content as a string to parse.'
+      );
     }
     return this.csvToJson.csvToJson(csvString);
   }
 
   csvStringToJsonStringified(csvString) {
     if (csvString === undefined || csvString === null) {
-      throw new Error('csvString is not defined!!!');
+      throw new InputValidationError(
+        'csvString',
+        'string',
+        `${typeof csvString}`,
+        'Provide valid CSV content as a string to parse.'
+      );
     }
     return this.csvToJson.csvStringToJsonStringified(csvString);
   }
@@ -71,24 +87,31 @@ class BrowserApi {
    */
   parseFile(file, options = {}) {
     if (!file) {
-      return Promise.reject(new Error('file is not defined!!!'));
+      return Promise.reject(new InputValidationError(
+        'file',
+        'File or Blob object',
+        `${typeof file}`,
+        'Provide a valid File or Blob object to parse.'
+      ));
     }
 
     return new Promise((resolve, reject) => {
       if (typeof FileReader === 'undefined') {
-        reject(new Error('FileReader is not available in this environment'));
+        reject(BrowserApiError.fileReaderNotAvailable());
         return;
       }
 
       const reader = new FileReader();
-      reader.onerror = () => reject(reader.error || new Error('Failed to read file'));
+      reader.onerror = () => reject(BrowserApiError.parseFileError(
+        reader.error || new Error('Unknown file reading error')
+      ));
       reader.onload = () => {
         try {
           const text = reader.result;
           const result = this.csvToJson.csvToJson(String(text));
           resolve(result);
         } catch (err) {
-          reject(err);
+          reject(BrowserApiError.parseFileError(err));
         }
       };