add browser api

Author: iuccio

README.md

@@ -25,30 +25,34 @@ show your :heart: and support.
 - [Description](#description)
 - [Support for JS & TS](#support-for-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)
-    + [Generate Object with sub array](#generate-object-with-sub-array)
-    + [Define field delimiter](#define-field-delimiter)
-    + [Trim header field](#trim-header-field)
-    + [Trim header field with whitespaces](#trim-header-field-with-whitespaces)
-    + [Support Quoted Fields](#support-quoted-fields)
-    + [Index header](#index-header)
-    + [Empty rows](#empty-rows)
-    + [Format property value by type](#format-property-value-by-type)
-      - [Number](#number)
-      - [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)
+ - [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)
+   + [Generate Object with sub array](#generate-object-with-sub-array)
+   + [Define field delimiter](#define-field-delimiter)
+   + [Trim header field](#trim-header-field)
+   + [Trim header field with whitespaces](#trim-header-field-with-whitespaces)
+   + [Support Quoted Fields](#support-quoted-fields)
+   + [Index header](#index-header)
+   + [Empty rows](#empty-rows)
+   + [Format property value by type](#format-property-value-by-type)
+     - [Number](#number)
+     - [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)
+ * [Browser API Usage](#browser-api-usage)
+   + [Basic Browser Operations](#basic-browser-operations)
+   + [Parsing File/Blob](#parsing-fileblob)
+   + [Notes](#browser-api-notes)
+ * [Chaining Pattern](#chaining-pattern)
 - [Development](#development)
 - [CI CD github action](#ci-cd-github-action)
 - [License](#license)
@@ -108,7 +112,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 +360,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.
+
+### 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:

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;
 }

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');

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;