convert-csv-to-json 3.14.0 → 3.15.0

package/README.md

@@ -8,8 +8,11 @@
 [![Downloads](https://img.shields.io/npm/dm/convert-csv-to-json.svg)](https://npmjs.org/package/convert-csv-to-json)
 [![NPM total downloads](https://img.shields.io/npm/dt/convert-csv-to-json.svg?style=flat)](https://npmjs.org/package/convert-csv-to-json)
 
-![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white)
+
+![NodeJS](https://img.shields.io/badge/node.js-6DA55F?style=for-the-badge&logo=node.js&logoColor=white)
+![Browser Support](https://img.shields.io/badge/browser-supported-brightgreen.svg?style=for-the-badge&logo=google-chrome&logoColor=white) 
 ![JavaScript](https://img.shields.io/badge/javascript-%23323330.svg?style=for-the-badge&logo=javascript&logoColor=%23F7DF1E)
+![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white) 
 
 **This project is not dependent on others packages or libraries, and supports both synchronous and Promise-based asynchronous APIs.**
 
@@ -23,10 +26,9 @@ show your :heart: and support.
 <!-- toc -->
 
 - [Description](#description)
-- [Support for JS & TS](#support-for-js--ts)
+- [Support for NodeJS, Browser, JS, TS](#support-for-nodejs-browser-js-ts)
 - [Prerequisites](#prerequisites)
 - [Install npm *convert-csv-to-json package*](#install-npm-convert-csv-to-json-package)
-  * [Install](#install)
   * [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)
@@ -38,17 +40,38 @@ show your :heart: and support.
     + [Index header](#index-header)
     + [Empty rows](#empty-rows)
     + [Format property value by type](#format-property-value-by-type)
-      - [Number](#number)
+      - [Numbers](#numbers)
       - [Boolean](#boolean)
+      - [Complete Example](#complete-example)
     + [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)
+  * [Sync API (TypeScript)](#sync-api-typescript)
+- [Browser API Usage](#browser-api-usage)
+  * [Basic Browser Operations](#basic-browser-operations)
+  * [Parsing File/Blob](#parsing-fileblob)
+  * [Browser API Notes](#browser-api-notes)
+  * [Browser API (TypeScript)](#browser-api-typescript)
+- [Async API Usage](#async-api-usage)
+  * [Async API (TypeScript)](#async-api-typescript)
+  * [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)
+  * [Synchronous Chaining](#synchronous-chaining)
+  * [Asynchronous Chaining](#asynchronous-chaining)
+- [Common Use Cases](#common-use-cases)
+  * [1. Processing CSV from HTTP Response](#1-processing-csv-from-http-response)
+  * [2. Batch Processing Multiple Files](#2-batch-processing-multiple-files)
+  * [3. Data Transformation Pipeline](#3-data-transformation-pipeline)
+  * [4. Error Recovery and Logging](#4-error-recovery-and-logging)
+- [Troubleshooting](#troubleshooting)
+  * [Memory Issues with Large Files](#memory-issues-with-large-files)
+  * [Handling Different CSV Formats](#handling-different-csv-formats)
+  * [Common Error Solutions](#common-error-solutions)
+  * [Performance Optimization](#performance-optimization)
+  * [TypeScript Support](#typescript-support)
 - [Development](#development)
 - [CI CD github action](#ci-cd-github-action)
 - [License](#license)
@@ -98,9 +121,14 @@ will generate:
  }
 ]
 ```
-## Support for JS & TS
+## Support for NodeJS, Browser, JS, TS
+
+This package is compatible with: 
 
-This package is compatible with ![JavaScript](https://img.shields.io/badge/javascript-%23323330.svg?style=for-the-badge&logo=javascript&logoColor=%23F7DF1E) and ![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white).
+![NodeJS](https://img.shields.io/badge/node.js-6DA55F?style=for-the-badge&logo=node.js&logoColor=white)
+![Browser Support](https://img.shields.io/badge/browser-supported-brightgreen.svg?style=for-the-badge&logo=google-chrome&logoColor=white) 
+![JavaScript](https://img.shields.io/badge/javascript-%23323330.svg?style=for-the-badge&logo=javascript&logoColor=%23F7DF1E)
+![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white) 
 
 ## Prerequisites
 **NPM** (see [Installing Npm](https://docs.npmjs.com/getting-started/installing-node)).
@@ -108,7 +136,6 @@ This package is compatible with ![JavaScript](https://img.shields.io/badge/javas
 ## Install npm *convert-csv-to-json package*
 Go to NPM package [convert-csv-to-json](https://www.npmjs.com/package/convert-csv-to-json).
 
-### Install
 Install package in your *package.json*
 ```bash
 $ npm install convert-csv-to-json --save
@@ -357,10 +384,138 @@ let jsonArray = csvToJson
   .csvStringToJson(csvString);
 ```
 
+### Sync API (TypeScript)
+
+TypeScript typings are available via the included `index.d.ts`. You can import the default converter or use named imports. Below are common patterns when using the synchronous API from TypeScript.
+
+```ts
+// Named import (recommended when using ES modules)
+import converter, { /* or */ } from 'convert-csv-to-json';
+// Access the default converter
+const csvToJson = require('convert-csv-to-json');
+
+// Define a type for your CSV records
+interface Person {
+  name: string;
+  age: number;
+}
+
+// Parse CSV string synchronously and assert the returned type
+const csv = 'name,age\nAlice,30';
+const parsed = csvToJson.csvStringToJson(csv) as Person[];
+
+// Chain configuration and call sync methods
+const result = csvToJson
+  .fieldDelimiter(',')
+  .formatValueByType()
+  .csvStringToJson('name,age\nBob,25') as Person[];
+```
+
+## Browser API Usage
+
+The package exposes a `browser` helper that reuses the library's parsing logic but provides browser-friendly helpers for parsing CSV strings and `File`/`Blob` objects. The API mirrors the synchronous and asynchronous Node APIs and supports method chaining for configuration.
+
+### Basic Browser Operations
+
+```js
+const convert = require('convert-csv-to-json');
+
+// Parse CSV string synchronously
+const arr = convert.browser
+  .supportQuotedField(true)
+  .fieldDelimiter(',')
+  .csvStringToJson('name,age\nAlice,30');
+
+// Parse CSV string asynchronously (returns Promise)
+const arrAsync = await convert.browser.csvStringToJsonAsync('name;age\nBob;25');
+
+// Get stringified JSON synchronously
+const jsonString = convert.browser.csvStringToJsonStringified('name;age\nEve;40');
+```
+
+### Parsing File/Blob
+
+`parseFile(file, options)` reads a `File` or `Blob` and returns a Promise that resolves with the parsed array of objects.
+
+```js
+// In a browser environment with an <input type="file">
+const file = document.querySelector('input[type=file]').files[0];
+convert.browser
+  .fieldDelimiter(',')
+  .formatValueByType()
+  .parseFile(file)
+  .then(json => console.log(json))
+  .catch(err => console.error(err));
+```
+
+`parseFile` accepts an optional `options` object with `encoding` (passed to `FileReader.readAsText`). If `FileReader` is not available, `parseFile` will reject.
+
+### Browser API Notes
+
+- The `browser` API proxies the same configuration methods as the Node API and follows the same behavior for quoted fields, sub-array parsing, trimming, and value formatting.
+- `parseFile` depends on the browser `FileReader` API; calling it in Node.js will reject with an informative error.
+
+### Browser API (TypeScript)
+
+TypeScript typings are provided via the included `index.d.ts`. You can import the default converter and access the `browser` helper, or import `browser` directly. Below are common usage patterns.
+
+```ts
+// Named import (recommended for direct use)
+import { browser } from 'convert-csv-to-json';
+
+// Or default import and access the browser helper
+import converter from 'convert-csv-to-json';
+const browserApi = converter.browser;
+
+// Define a type for your CSV records
+interface Person {
+  name: string;
+  age: number;
+}
+
+// Synchronous parse (assert the returned type)
+const csv = 'name,age\nAlice,30';
+const parsed = browser.csvStringToJson(csv) as Person[];
+
+// Async parse
+const parsedAsync = await browser.csvStringToJsonAsync(csv) as Person[];
+
+// Parse a File in the browser
+const inputEl = document.querySelector('input[type=file]') as HTMLInputElement;
+const file = inputEl.files![0];
+const data = await browser.parseFile(file) as Person[];
+```
+
+The `BrowserApi` interface in `index.d.ts` exposes typed method signatures for IDE autocompletion and compile-time checks.
+
 ## Async API Usage
 
 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).
 
+### Async API (TypeScript)
+
+The async API also has TypeScript typings. Typical usage in TypeScript looks like this:
+
+```ts
+import csvToJson from 'convert-csv-to-json';
+
+interface Person {
+  name: string;
+  age: number;
+}
+
+// Using async/await
+async function load(): Promise<Person[]> {
+  const csv = 'name,age\nAlice,30';
+  const parsed = await csvToJson.getJsonFromCsvAsync(csv, { raw: true }) as Person[];
+  return parsed;
+}
+
+// Using the async helper that parses CSV strings
+const parsedDirect = await csvToJson.csvStringToJsonAsync('name;age\nBob;25') as Person[];
+```
+
+
 ### Basic Async Operations
 
 1. Convert CSV file to JSON:

package/index.d.ts

@@ -116,4 +116,28 @@ declare module 'convert-csv-to-json' {
   }
   const converter: ConvertCsvToJson;
   export default converter;
+  
+  /**
+   * Browser API exposes parsing helpers for browser environments
+   */
+  export interface BrowserApi {
+    formatValueByType(active: boolean): this;
+    trimHeaderFieldWhiteSpace(active: boolean): this;
+    supportQuotedField(active: boolean): this;
+    fieldDelimiter(delimiter: string): this;
+    indexHeader(index: number): this;
+    parseSubArray(delimiter: string, separator: string): this;
+
+    csvStringToJson(csvString: string): any[];
+    csvStringToJsonStringified(csvString: string): string;
+    csvStringToJsonAsync(csvString: string): Promise<any[]>;
+    csvStringToJsonStringifiedAsync(csvString: string): Promise<string>;
+
+    /**
+     * Parse a File or Blob and return a Promise that resolves to the JSON array
+     */
+    parseFile(file: Blob | File, options?: { encoding?: string }): Promise<any[]>;
+  }
+
+  export const browser: BrowserApi;
 }

package/index.js

@@ -202,3 +202,9 @@ exports.csvStringToJsonStringified = function(csvString) {
 exports.jsonToCsv = function(inputFileName, outputFileName) {
   csvToJson.generateJsonFileFromCsv(inputFileName, outputFileName);
 };
+
+/**
+ * Browser API
+ * Provides parsing helpers suitable for browser environments (parsing strings and File/Blob objects)
+ */
+exports.browser = require('./src/browserApi');

package/jest.config.js

@@ -1,9 +1,13 @@
 /** @type {import('jest').Config} */
 const config = {
-
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    transform: {
+        '^.+\\.(ts|tsx)$': 'ts-jest'
+    },
+    testMatch: ['**/?(*.)+(spec|test).[tj]s?(x)'],
     coverageReporters: ['clover', 'html' ,'json', 'lcov', ['text', {skipFull: true}]],
     collectCoverage: true
-    
 };
 
 module.exports = config;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convert-csv-to-json",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "description": "Convert CSV to JSON",
   "main": "index.js",
   "types": "index.d.ts",
@@ -35,7 +35,8 @@
     "js",
     "javascript",
     "ts",
-    "typescript"
+    "typescript",
+    "browser"
   ],
   "author": "iuccio",
   "license": "MIT",
@@ -44,6 +45,9 @@
   },
   "homepage": "https://github.com/iuccio/CSVtoJSON#readme",
   "devDependencies": {
-    "jest": "^29.7.0"
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.1.6",
+    "@types/jest": "^29.5.3"
   }
 }

package/src/browserApi.js

@@ -0,0 +1,105 @@
+"use strict";
+
+const csvToJson = require('./csvToJson');
+
+class BrowserApi {
+  constructor() {
+    // reuse the existing csvToJson instance for parsing and configuration
+    this.csvToJson = csvToJson;
+  }
+
+  // Configuration proxies (chainable)
+  formatValueByType(active = true) {
+    this.csvToJson.formatValueByType(active);
+    return this;
+  }
+
+  supportQuotedField(active = false) {
+    this.csvToJson.supportQuotedField(active);
+    return this;
+  }
+
+  fieldDelimiter(delimiter) {
+    this.csvToJson.fieldDelimiter(delimiter);
+    return this;
+  }
+
+  trimHeaderFieldWhiteSpace(active = false) {
+    this.csvToJson.trimHeaderFieldWhiteSpace(active);
+    return this;
+  }
+
+  indexHeader(index) {
+    this.csvToJson.indexHeader(index);
+    return this;
+  }
+
+  parseSubArray(delimiter = '*', separator = ',') {
+    this.csvToJson.parseSubArray(delimiter, separator);
+    return this;
+  }
+
+  // Synchronous parse from CSV string (browser friendly)
+  csvStringToJson(csvString) {
+    if (csvString === undefined || csvString === null) {
+      throw new Error('csvString is not defined!!!');
+    }
+    return this.csvToJson.csvToJson(csvString);
+  }
+
+  csvStringToJsonStringified(csvString) {
+    if (csvString === undefined || csvString === null) {
+      throw new Error('csvString is not defined!!!');
+    }
+    return this.csvToJson.csvStringToJsonStringified(csvString);
+  }
+
+  // Async parse from CSV string (returns a Promise)
+  csvStringToJsonAsync(csvString) {
+    return Promise.resolve(this.csvStringToJson(csvString));
+  }
+
+  csvStringToJsonStringifiedAsync(csvString) {
+    return Promise.resolve(this.csvStringToJsonStringified(csvString));
+  }
+
+  /**
+   * 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[]>}
+   */
+  parseFile(file, options = {}) {
+    if (!file) {
+      return Promise.reject(new Error('file is not defined!!!'));
+    }
+
+    return new Promise((resolve, reject) => {
+      if (typeof FileReader === 'undefined') {
+        reject(new Error('FileReader is not available in this environment'));
+        return;
+      }
+
+      const reader = new FileReader();
+      reader.onerror = () => reject(reader.error || new Error('Failed to read file'));
+      reader.onload = () => {
+        try {
+          const text = reader.result;
+          const result = this.csvToJson.csvToJson(String(text));
+          resolve(result);
+        } catch (err) {
+          reject(err);
+        }
+      };
+
+      // If encoding is provided, pass it to readAsText
+      if (options.encoding) {
+        reader.readAsText(file, options.encoding);
+      } else {
+        reader.readAsText(file);
+      }
+    });
+  }
+}
+
+module.exports = new BrowserApi();

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2019",
+    "module": "CommonJS",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "types": ["node", "jest"]
+  },
+  "baseUrl": ".",
+  "paths": {
+    "convert-csv-to-json": ["./index.d.ts", "./index.js"]
+  },
+  "include": ["test/**/*.ts"]
+}