convert-csv-to-json 4.35.0 → 4.37.0

package/.github/workflows/ci-cd.yml

@@ -80,7 +80,7 @@ jobs:
     - name: Upload pages artifact
       uses: actions/upload-pages-artifact@v5
       with:
-        path: docs
+        path: demo
     - name: Deploy to GitHub Pages
       uses: actions/deploy-pages@v5
       

package/README.md

@@ -3,7 +3,6 @@
 [![Node CI](https://github.com/iuccio/csvToJson/actions/workflows/ci-cd.yml/badge.svg?branch=master)](https://github.com/iuccio/csvToJson/actions/workflows/ci-cd.yml)
 ![CodeQL](https://github.com/iuccio/csvToJson/actions/workflows/codeql-analysis.yml/badge.svg)
 [![Maintainability](https://qlty.sh/gh/iuccio/projects/csvToJson/maintainability.svg)](https://qlty.sh/gh/iuccio/projects/csvToJson)
-[![Code Climate](https://codeclimate.com/github/iuccio/csvToJson/badges/gpa.svg)](https://codeclimate.com/github/iuccio/csvToJson)
 [![NPM Version](https://img.shields.io/npm/v/convert-csv-to-json.svg)](https://npmjs.org/package/convert-csv-to-json)
 ![NodeJS Version](https://img.shields.io/badge/nodeJS-%3E=18.x-brightgreen.svg)
 [![Downloads](https://img.shields.io/npm/dm/convert-csv-to-json.svg)](https://npmjs.org/package/convert-csv-to-json)
@@ -17,14 +16,14 @@
 ![TypeScript](https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&logo=typescript&logoColor=white)
 
 >
-Convert CSV files to JSON with **no dependencies**. Supports Node.js (Sync & Async), and Browser environments with full RFC 4180 compliance.
+Convert CSV files to JSON with **no dependencies**. Supports Node.js (Sync & Async), and Browser environments with full RFC 4180 compliance. **Memory-efficient streaming** for processing large files without loading them entirely into memory.
 
 ## Overview
 
 Transform CSV data into JSON with a simple, chainable API. Choose your implementation style:
 
 - **[Synchronous API](docs/SYNC.md)** - Blocking operations for simple workflows
-- **[Asynchronous API](docs/ASYNC.md)** - Promise-based for modern async/await patterns
+- **[Asynchronous API](docs/ASYNC.md)** - Promise-based for modern async/await patterns with **memory-efficient streaming** for large files
 - **[Browser API](docs/BROWSER.md)** - Client-side CSV parsing for web applications
 
 ## Demo and JSDoc
@@ -40,7 +39,7 @@ Transform CSV data into JSON with a simple, chainable API. Choose your implement
 ✅ **Full TypeScript Support** - Included type definitions for all APIs  
 ✅ **Flexible Configuration** - Custom delimiters, encoding, trimming, and more  
 ✅ **Method Chaining** - Fluent API for readable code  
-✅ **Large File Support** - Stream processing for memory-efficient handling  
+✅ **Memory-Efficient Streaming** - Process large files without loading them entirely into memory  
 ✅ **Comprehensive Error Handling** - Detailed, actionable error messages with solutions (see [ERROR_HANDLING.md](docs/ERROR_HANDLING.md))
 
 ## RFC 4180 Standard
@@ -150,6 +149,9 @@ All APIs (Sync, Async and Browser) support the same configuration methods:
 - `trimHeaderFieldWhiteSpace(bool)` - Remove spaces from headers
 - `parseSubArray(delim, sep)` - Parse delimited arrays
 - `mapRows(fn)` - Transform, filter, or enrich each row
+- `getJsonFromStreamAsync(stream)` - Process CSV from Readable streams for NodeJS and Browser
+- `getJsonFromFileStreamingAsync(filePath)` - Stream processing for large files for NodeJS and Browser
+- `getJsonFromFileStreamingAsyncWithCallback(filePath, options = {})` -  Parse CSV from a File using streaming with progress callbacks for large files
 - `utf8Encoding()`, `latin1Encoding()`, etc. - Set file encoding
 
 ### Examples
@@ -233,6 +235,64 @@ csvToJson.latin1Encoding().getJsonFromCsv('data.csv');
 csvToJson.customEncoding('ucs2').getJsonFromCsv('data.csv');
 ```
 
+#### `getJsonFromStreamAsync(stream)` - Process CSV from Readable streams
+```js
+const fs = require('fs');
+const csvToJson = require('convert-csv-to-json');
+
+// Process large files without loading them entirely into memory
+async function processLargeCSV() {
+  const stream = fs.createReadStream('large-dataset.csv');
+  const jsonData = await csvToJson
+    .fieldDelimiter(';')
+    .supportQuotedField(true)
+    .getJsonFromStreamAsync(stream);
+    
+  console.log(`Processed ${jsonData.length} records efficiently`);
+  return jsonData;
+}
+```
+
+#### `getJsonFromFileStreamingAsync(filePath)` - Stream processing for large files
+```js
+const csvToJson = require('convert-csv-to-json');
+
+// Most efficient way to process large CSV files
+async function processLargeCSV(filePath) {
+  const jsonData = await csvToJson
+    .fieldDelimiter(',')
+    .formatValueByType()
+    .getJsonFromFileStreamingAsync(filePath);
+    
+  console.log(`Streamed and processed ${jsonData.length} records`);
+  return jsonData;
+}
+
+// Usage - handles files of any size without memory constraints
+const data = await processLargeCSV('massive-dataset.csv');
+```
+
+#### `getJsonFromFileStreamingAsyncWithCallback(filePath, options = {})` - Parse CSV from a File object using streaming with progress callbacks for large files
+
+```js
+const csvToJson = require('convert-csv-to-json');
+const fileInput = document.querySelector('#csvfile').files[0];
+
+ csvToJson.browser.getJsonFromFileStreamingAsyncWithCallback(fileInput, {
+   chunkSize: 500,
+   onChunk: (rows, processed, total) => {
+     console.log(`Processed ${processed}/${total} rows`);
+     // Handle chunk of rows here
+   },
+   onComplete: (allRows) => {
+     console.log('Processing complete!');
+   },
+   onError: (error) => {
+     console.error('Error:', error);
+   }
+ });
+```
+
 See [SYNC.md](docs/SYNC.md), [ASYNC.md](docs/ASYNC.md) or [BROWSER.md](docs/BROWSER.md) for complete configuration details.
 
 ## Example: Complete Workflow

package/docs/ASYNC.md

@@ -7,6 +7,8 @@ Promise-based async/await API for modern Node.js applications. Perfect for handl
 - [File Operations](#file-operations)
 - [Working with Raw CSV Data](#working-with-raw-csv-data)
 - [Processing Large Files](#processing-large-files)
+- [Stream Processing](#stream-processing)
+- [File Streaming](#file-streaming)
 - [Batch Processing](#batch-processing)
 - [Error Handling](#error-handling)
 - [Method Chaining](#method-chaining)
@@ -158,6 +160,112 @@ async function processChunk(records) {
 }
 ```
 
+## Stream Processing
+
+For true memory-efficient processing of large CSV files, use the stream API which processes data in chunks without loading the entire file into memory.
+
+### Basic Stream Usage
+
+```js
+const fs = require('fs');
+const csvToJson = require('convert-csv-to-json');
+
+async function processLargeCSV(filePath) {
+  const stream = fs.createReadStream(filePath);
+  const jsonData = await csvToJson.getJsonFromStreamAsync(stream);
+  
+  console.log(`Processed ${jsonData.length} records`);
+  return jsonData;
+}
+
+// Usage
+const data = await processLargeCSV('large-dataset.csv');
+```
+
+### Stream with Configuration
+
+```js
+const fs = require('fs');
+const csvToJson = require('convert-csv-to-json');
+
+async function processConfiguredStream(filePath) {
+  const stream = fs.createReadStream(filePath, { encoding: 'utf8' });
+  
+  const jsonData = await csvToJson
+    .fieldDelimiter(';')
+    .supportQuotedField(true)
+    .getJsonFromStreamAsync(stream);
+    
+  return jsonData;
+}
+```
+
+### File Streaming with getJsonFromFileStreamingAsync
+
+For simplified file streaming without manually creating streams, use `getJsonFromFileStreamingAsync`:
+
+```js
+const csvToJson = require('convert-csv-to-json');
+
+async function processLargeCSV(filePath) {
+  const jsonData = await csvToJson
+    .fieldDelimiter(';')
+    .supportQuotedField(true)
+    .getJsonFromFileStreamingAsync(filePath);
+    
+  console.log(`Processed ${jsonData.length} records efficiently`);
+  return jsonData;
+}
+
+// Usage - processes large files without loading them entirely into memory
+const data = await processLargeCSV('large-dataset.csv');
+```
+
+### Stream from Other Sources
+
+```js
+const { Readable } = require('stream');
+const csvToJson = require('convert-csv-to-json');
+
+// Create a stream from a string
+function createCSVStream(csvString) {
+  const stream = new Readable();
+  stream.push(csvString);
+  stream.push(null); // End the stream
+  return stream;
+}
+
+async function processStringAsStream() {
+  const csvData = 'name,age\nAlice,30\nBob,25';
+  const stream = createCSVStream(csvData);
+  
+  const json = await csvToJson.getJsonFromStreamAsync(stream);
+  console.log(json);
+  // Output: [{ name: 'Alice', age: '30' }, { name: 'Bob', age: '25' }]
+}
+```
+
+### File Streaming
+
+For the most efficient processing of large CSV files, use the built-in file streaming API which handles all the complexity of chunked reading and parsing:
+
+```js
+const csvToJson = require('convert-csv-to-json');
+
+async function processLargeCSV(filePath) {
+  const jsonData = await csvToJson
+    .fieldDelimiter(';')
+    .supportQuotedField(true)
+    .getJsonFromFileStreamingAsync(filePath);
+    
+  console.log(`Processed ${jsonData.length} records`);
+  return jsonData;
+}
+
+// Usage
+const data = await processLargeCSV('large-dataset.csv');
+```
+
 ## Batch Processing
 
 ### Sequential Processing

package/docs/BROWSER.md

@@ -6,6 +6,7 @@ Client-side CSV parsing for web browsers. Supports parsing CSV strings and file/
 - [Basic Usage](#basic-usage)
 - [Parsing CSV Strings](#parsing-csv-strings)
 - [Parsing Files and Blobs](#parsing-files-and-blobs)
+- [Streaming Large Files](#streaming-large-files)
 - [Configuration Options](#configuration-options)
 - [File Upload Examples](#file-upload-examples)
 - [TypeScript Support](#typescript-support)
@@ -122,6 +123,57 @@ async function parseWithEncoding(file) {
 }
 ```
 
+## Streaming Large Files
+
+For memory-efficient processing of large CSV files in browsers, use the streaming API which processes data in chunks without loading the entire file into memory.
+
+### Stream from ReadableStream
+
+```js
+const convert = require('convert-csv-to-json');
+
+async function processStream(stream) {
+  const jsonData = await convert.browser
+    .fieldDelimiter(';')
+    .supportQuotedField(true)
+    .getJsonFromStreamAsync(stream);
+    
+  console.log(`Processed ${jsonData.length} records`);
+  return jsonData;
+}
+
+// Usage with fetch
+const response = await fetch('large-dataset.csv');
+const stream = response.body;
+const data = await processStream(stream);
+```
+
+### Stream from File Object
+
+```js
+const convert = require('convert-csv-to-json');
+
+async function processLargeFile(file) {
+  const jsonData = await convert.browser
+    .fieldDelimiter(',')
+    .formatValueByType()
+    .getJsonFromFileStreamingAsync(file);
+    
+  console.log(`Streamed and processed ${jsonData.length} records`);
+  return jsonData;
+}
+
+// Usage with file input
+const fileInput = document.querySelector('#csvfile');
+fileInput.addEventListener('change', async (event) => {
+  const file = event.target.files[0];
+  const data = await processLargeFile(file);
+  console.log(data);
+});
+```
+
+**Note:** Streaming requires modern browsers that support the `ReadableStream` API (Chrome 43+, Firefox 65+, Safari 10.1+). For older browsers, the method falls back to regular file parsing.
+
 ## Configuration Options
 
 All configuration methods from the [Sync API](SYNC.md) are available:

package/index.d.ts

@@ -99,10 +99,21 @@ 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[]>;
+    /**
+     * 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[]>;
+
+    /**
+     * Parse CSV from a Readable stream and return parsed data as JSON array
+     * Processes data in chunks for memory-efficient handling of large files
+     */
+    getJsonFromStreamAsync(stream: NodeJS.ReadableStream): Promise<any[]>;
+
+    /**
+     * Parse CSV from a file path using streaming for memory-efficient processing
+     */
+    getJsonFromFileStreamingAsync(filePath: string): Promise<any[]>;
 
     csvStringToJson(csvString: string): any[];
 
@@ -139,6 +150,16 @@ declare module 'convert-csv-to-json' {
      * Parse a File or Blob and return a Promise that resolves to the JSON array
      */
     parseFile(file: Blob | File, options?: { encoding?: string }): Promise<any[]>;
+
+    /**
+     * Parse CSV from a ReadableStream and return parsed data as JSON array
+     */
+    getJsonFromStreamAsync(stream: any): Promise<any[]>;
+
+    /**
+     * Parse CSV from a File object using streaming for memory-efficient processing
+     */
+    getJsonFromFileStreamingAsync(file: File): Promise<any[]>;
   }
 
   export const browser: BrowserApi;

package/index.js

@@ -253,6 +253,36 @@ exports.getJsonFromCsv = function(inputFileName) {
  */
 const csvToJsonAsync = require('./src/csvToJsonAsync');
 
+/**
+ * Parse CSV from a Readable stream and return parsed data as JSON array
+ * Processes data in chunks for memory-efficient handling of large files
+ * @param {object} stream - Node.js Readable stream containing CSV data
+ * @returns {Promise<Array<object>>} Promise resolving to array of objects representing CSV rows
+ * @throws {InputValidationError} If stream is invalid
+ * @throws {CsvFormatError} If CSV is malformed
+ * @category 1-Core API
+ * @example
+ * const fs = require('fs');
+ * const csvToJson = require('convert-csv-to-json');
+ * const stream = fs.createReadStream('large.csv');
+ * const data = await csvToJson.getJsonFromStreamAsync(stream);
+ * console.log(data);
+ */
+
+/**
+ * Parse CSV from a file path using streaming for memory-efficient processing
+ * @param {string} filePath - Path to the CSV file
+ * @returns {Promise<Array<object>>} Promise resolving to array of objects representing CSV rows
+ * @throws {InputValidationError} If filePath is invalid
+ * @throws {FileOperationError} If file cannot be read
+ * @throws {CsvFormatError} If CSV is malformed
+ * @category 1-Core API
+ * @example
+ * const csvToJson = require('convert-csv-to-json');
+ * const data = await csvToJson.getJsonFromFileStreamingAsync('large.csv');
+ * console.log(data);
+ */
+
 // Re-export all async API methods
 Object.assign(exports, {
   getJsonFromCsvAsync: function(input, options) {
@@ -266,6 +296,12 @@ Object.assign(exports, {
   },
   generateJsonFileFromCsvAsync: function(input, output) {
     return csvToJsonAsync.generateJsonFileFromCsv(input, output);
+  },
+  getJsonFromStreamAsync: function(stream) {
+    return csvToJsonAsync.getJsonFromStreamAsync(stream);
+  },
+  getJsonFromFileStreamingAsync: function(filePath) {
+    return csvToJsonAsync.getJsonFromFileStreamingAsync(filePath);
   }
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convert-csv-to-json",
-  "version": "4.35.0",
+  "version": "4.37.0",
   "description": "Convert CSV to JSON",
   "main": "index.js",
   "types": "index.d.ts",
@@ -9,7 +9,7 @@
     "test-debug": "node --inspect-brk node_modules/.bin/jest --runInBand --detectOpenHandles",
     "lint": "eslint .",
     "docs": "jsdoc -c jsdoc.json",
-    "docs:api": "jsdoc -c jsdoc.json -d docs/api",
+    "docs:api": "jsdoc -c jsdoc.json -d demo/api",
     "prepublishOnly": "npm run docs:api",
     "version-patch": "npm version patch",
     "version-minor": "npm version minor",
@@ -52,6 +52,7 @@
     "@eslint/js": "^10.0.1",
     "@types/jest": "^30.0.0",
     "better-docs": "^2.7.3",
+    "browserify": "^17.0.1",
     "eslint": "^10.1.0",
     "eslint-plugin-jsdoc": "^62.8.0",
     "jest": "^30.2.0",

package/src/browserApi.js

@@ -4,6 +4,7 @@
 
 const csvToJson = require('./csvToJson');
 const { InputValidationError, BrowserApiError } = require('./util/errors');
+const StreamProcessor = require('./streamProcessor');
 
 /**
  * Browser-friendly CSV to JSON API
@@ -216,6 +217,203 @@ class BrowserApi {
       }
     });
   }
+
+  /**
+   * Parse CSV from a browser ReadableStream and return parsed data as JSON array
+   * Processes data in chunks for memory-efficient handling of large streams
+   * @param {object} stream - Browser ReadableStream containing CSV data
+   * @returns {Promise<Array<object>>} Promise resolving to array of objects representing CSV rows
+   * @throws {InputValidationError} If stream is invalid
+   * @throws {BrowserApiError} If streaming is not supported or parsing fails
+   * @example
+   * const csvToJson = require('convert-csv-to-json');
+   * const response = await fetch('large-dataset.csv');
+   * const stream = response.body;
+   * const data = await csvToJson.browser.getJsonFromStreamAsync(stream);
+   * console.log(data);
+   */
+  async getJsonFromStreamAsync(stream) {
+    if (typeof ReadableStream === 'undefined') {
+      throw BrowserApiError.streamingNotSupported();
+    }
+
+    if (!stream || typeof stream.getReader !== 'function') {
+      throw new InputValidationError(
+        'stream',
+        'ReadableStream',
+        typeof stream,
+        'Provide a valid browser ReadableStream.'
+      );
+    }
+
+    const streamProcessor = new StreamProcessor(this.csvToJson, { isBrowser: true });
+    return streamProcessor.processStream(stream);
+  }
+
+  /**
+   * Parse CSV from a File object using streaming for memory-efficient processing
+   * @param {File} file - File object containing CSV data
+   * @returns {Promise<Array<object>>} Promise resolving to array of objects representing CSV rows
+   * @throws {InputValidationError} If file is invalid
+   * @throws {BrowserApiError} If streaming is not supported or parsing fails
+   * @example
+   * const csvToJson = require('convert-csv-to-json');
+   * const fileInput = document.querySelector('#csvfile').files[0];
+   * const data = await csvToJson.browser.getJsonFromFileStreamingAsync(fileInput);
+   * console.log(data);
+   */
+  async getJsonFromFileStreamingAsync(file) {
+    if (!file || !(file instanceof File)) {
+      throw new InputValidationError(
+        'file',
+        'File object',
+        typeof file,
+        'Provide a valid File object.'
+      );
+    }
+
+    // Check if the file supports streaming
+    if (typeof file.stream === 'function') {
+      // Use native streaming if available
+      const stream = file.stream();
+      return this.getJsonFromStreamAsync(stream);
+    } else {
+      // Fallback to regular file parsing for older browsers
+      return this.parseFile(file);
+    }
+  }
+
+  /**
+   * Parse CSV from a File object using streaming with progress callbacks for large files
+   * Processes data in chunks to avoid memory issues with large datasets
+   * @param {File} file - File object containing CSV data
+   * @param {object} options - Processing options
+   * @param {function(Array<object>, number, number): void} options.onChunk - Callback for each chunk of processed rows
+   * @param {function(Array<object>): void} [options.onComplete] - Callback when processing is complete
+   * @param {function(Error): void} [options.onError] - Callback for errors
+   * @param {number} [options.chunkSize=1000] - Number of rows per chunk
+   * @returns {Promise<void>} Promise that resolves when streaming starts
+   * @throws {InputValidationError} If file or options are invalid
+   * @example
+   * const csvToJson = require('convert-csv-to-json');
+   * const fileInput = document.querySelector('#csvfile').files[0];
+   *
+   * await csvToJson.browser.getJsonFromFileStreamingAsyncWithCallback(fileInput, {
+   *   chunkSize: 500,
+   *   onChunk: (rows, processed, total) => {
+   *     console.log(`Processed ${processed}/${total} rows`);
+   *     // Handle chunk of rows here
+   *   },
+   *   onComplete: (allRows) => {
+   *     console.log('Processing complete!');
+   *   },
+   *   onError: (error) => {
+   *     console.error('Error:', error);
+   *   }
+   * });
+   */
+  async getJsonFromFileStreamingAsyncWithCallback(file, options = {}) {
+    if (!file || !(file instanceof File)) {
+      throw new InputValidationError(
+        'file',
+        'File object',
+        typeof file,
+        'Provide a valid File object.'
+      );
+    }
+
+    if (!options.onChunk || typeof options.onChunk !== 'function') {
+      throw new InputValidationError(
+        'options.onChunk',
+        'function',
+        typeof options.onChunk,
+        'Provide a callback function to handle processed chunks.'
+      );
+    }
+
+    const chunkSize = options.chunkSize || 1000;
+    const streamProcessor = new StreamProcessor(this.csvToJson, {
+      isBrowser: true,
+      chunkSize,
+      onChunk: options.onChunk,
+      onComplete: options.onComplete,
+      onError: options.onError
+    });
+
+    // Check if the file supports streaming
+    if (typeof file.stream === 'function') {
+      // Use native streaming if available
+      const stream = file.stream();
+      return streamProcessor.processStreamWithCallbacks(stream);
+    } else {
+      // Fallback to regular file parsing for older browsers
+      return this.parseFileWithCallbacks(file, options);
+    }
+  }
+
+  /**
+   * Parse a File object with progress callbacks (fallback for non-streaming browsers)
+   * @param {File} file - File object to parse
+   * @param {object} options - Processing options
+   * @private
+   */
+  async parseFileWithCallbacks(file, options) {
+    const chunkSize = options.chunkSize || 1000;
+    const onChunk = options.onChunk;
+    const onComplete = options.onComplete;
+    const onError = options.onError;
+
+    return new Promise((resolve, reject) => {
+      if (typeof FileReader === 'undefined') {
+        const error = BrowserApiError.fileReaderNotAvailable();
+        if (onError) onError(error);
+        reject(error);
+        return;
+      }
+
+      const reader = new FileReader();
+      reader.onerror = () => {
+        const error = BrowserApiError.parseFileError(
+          reader.error || new Error('Unknown file reading error')
+        );
+        if (onError) onError(error);
+        reject(error);
+      };
+
+      reader.onload = () => {
+        try {
+          const text = reader.result;
+          const allRows = this.csvToJson.csvToJson(String(text));
+
+          // Process in chunks
+          let processed = 0;
+          const total = allRows.length;
+
+          const processChunk = () => {
+            const chunk = allRows.slice(processed, processed + chunkSize);
+            if (chunk.length > 0) {
+              onChunk(chunk, processed + chunk.length, total);
+              processed += chunk.length;
+              // Use setTimeout to avoid blocking the UI
+              setTimeout(processChunk, 0);
+            } else {
+              if (onComplete) onComplete(allRows);
+              resolve();
+            }
+          };
+
+          processChunk();
+        } catch (err) {
+          const error = BrowserApiError.parseFileError(err);
+          if (onError) onError(error);
+          reject(error);
+        }
+      };
+
+      reader.readAsText(file);
+    });
+  }
+
 }
 
-module.exports = new BrowserApi();
+module.exports = new BrowserApi();

package/src/csvToJsonAsync.js

@@ -4,6 +4,7 @@
 const fileUtils = require('./util/fileUtils');
 const csvToJson = require('./csvToJson');
 const { InputValidationError } = require('./util/errors');
+const StreamProcessor = require('./streamProcessor');
 
 /**
  * Asynchronous CSV to JSON converter
@@ -177,18 +178,69 @@ class CsvToJsonAsync {
     }
 
     /**
-     * Parse CSV string to stringified JSON (async)
-     * @param {string} csvString - CSV content as string
-     * @returns {Promise<string>} JSON stringified array of objects
+     * Parse CSV from a Readable stream and return parsed data as JSON array
+     * Processes data in chunks for memory-efficient handling of large files
+     * @param {object} stream - Node.js Readable stream containing CSV data
+     * @returns {Promise<Array<object>>} Promise resolving to array of objects representing CSV rows
+     * @throws {InputValidationError} If stream is invalid
      * @throws {CsvFormatError} If CSV is malformed
      * @example
+     * const fs = require('fs');
      * const csvToJson = require('convert-csv-to-json');
-     * const jsonString = await csvToJson.csvStringToJsonStringifiedAsync('name,age\nAlice,30');
-     * console.log(jsonString);
+     * const stream = fs.createReadStream('large.csv');
+     * const data = await csvToJson.getJsonFromStreamAsync(stream);
+     * console.log(data);
      */
-    async csvStringToJsonStringifiedAsync(csvString) {
-        const json = await this.csvStringToJsonAsync(csvString);
-        return JSON.stringify(json, undefined, 1);
+    async getJsonFromStreamAsync(stream) {
+        this._validateStream(stream);
+
+        const streamProcessor = new StreamProcessor(this.csvToJson, { isBrowser: false });
+        return streamProcessor.processStream(stream);
+    }
+
+    /**
+     * Validate that the provided stream is a valid Readable stream
+     * @param {object} stream - The stream to validate
+     * @throws {InputValidationError} If stream is invalid
+     * @private
+     */
+    _validateStream(stream) {
+        if (!stream || typeof stream.pipe !== 'function') {
+            throw new InputValidationError(
+                'stream',
+                'Readable stream',
+                typeof stream,
+                'Provide a valid Node.js Readable stream.'
+            );
+        }
+    }
+
+    /**
+     * Parse CSV from a file path using streaming for memory-efficient processing
+     * @param {string} filePath - Path to the CSV file
+     * @returns {Promise<Array<object>>} Promise resolving to array of objects representing CSV rows
+     * @throws {InputValidationError} If filePath is invalid
+     * @throws {FileOperationError} If file cannot be read
+     * @throws {CsvFormatError} If CSV is malformed
+     * @example
+     * const csvToJson = require('convert-csv-to-json');
+     * const data = await csvToJson.getJsonFromFileStreamingAsync('large.csv');
+     * console.log(data);
+     */
+    async getJsonFromFileStreamingAsync(filePath) {
+        if (!filePath || typeof filePath !== 'string') {
+            throw new InputValidationError(
+                'filePath',
+                'string (file path)',
+                typeof filePath,
+                'Provide a valid file path as a string.'
+            );
+        }
+
+        const fs = require('fs');
+        const encoding = typeof this.csvToJson.encoding === 'string' ? this.csvToJson.encoding : 'utf8';
+        const stream = fs.createReadStream(filePath, { encoding });
+        return this.getJsonFromStreamAsync(stream);
     }
 }
 

package/src/streamProcessor.js

@@ -0,0 +1,469 @@
+/* globals CsvFormatError */
+'use strict';
+
+const stringUtils = require('./util/stringUtils');
+
+const QUOTE_CHAR = '"';
+const CRLF = '\r\n';
+const LF = '\n';
+const CR = '\r';
+
+/**
+ * Handles the processing of CSV data from a stream
+ * Encapsulates all stream processing logic following single responsibility principle
+ * Works with both Node.js streams and browser ReadableStream
+ * @private
+ */
+class StreamProcessor {
+    /**
+     * Initialize the stream processor with CSV configuration
+     * @param {object} csvConfig - The CSV configuration object
+     * @param {object} options - Environment options
+     * @param {boolean} options.isBrowser - Whether running in browser environment
+     * @param {number} options.chunkSize - Number of rows per chunk for callback processing
+     * @param {function} options.onChunk - Callback for each chunk
+     * @param {function} options.onComplete - Callback when processing complete
+     * @param {function} options.onError - Callback for errors
+     */
+    constructor(csvConfig, options = {}) {
+        this.csvConfig = csvConfig;
+        this.isBrowser = options.isBrowser || (typeof window !== 'undefined' && typeof document !== 'undefined');
+        this.buffer = '';
+        this.isInsideQuotes = false;
+        this.headers = null;
+        this.headerRowIndex = csvConfig.getIndexHeader();
+        this.currentRecordIndex = 0;
+        this.parsedRecords = [];
+        this.dataRowIndex = 0;
+
+        // Chunked processing options
+        this.chunkSize = options.chunkSize || 1000;
+        this.onChunk = options.onChunk;
+        this.onComplete = options.onComplete;
+        this.onError = options.onError;
+        this.allRecords = []; // For collecting all records when using callbacks
+    }
+
+    /**
+     * Process a chunk of data from the stream
+     * @param {Buffer|string|Uint8Array} chunk - The data chunk to process
+     */
+    processChunk(chunk) {
+        // Convert chunk to string, handling both Node.js Buffers and browser Uint8Array
+        let chunkString;
+        if (typeof chunk === 'string') {
+            chunkString = chunk;
+        } else if (this.isBrowser && typeof globalThis.TextDecoder !== 'undefined') {
+            chunkString = new globalThis.TextDecoder().decode(chunk);
+        } else if (this.isBrowser) {
+            // Fallback for older browsers without TextDecoder
+            chunkString = String.fromCharCode.apply(null, new Uint8Array(chunk));
+        } else {
+            // Node.js environment
+            chunkString = chunk.toString();
+        }
+
+        this.buffer += chunkString;
+        this._processCompleteRecords();
+    }
+
+    /**
+     * Process a stream with chunked callbacks (for large files)
+     * @param {Readable|ReadableStream} stream - The stream to process
+     * @returns {Promise<void>} Promise that resolves when streaming starts
+     */
+    async processStreamWithCallbacks(stream) {
+        return new Promise((resolve, reject) => {
+            if (this.isBrowser) {
+                // Browser ReadableStream
+                if (!stream || typeof stream.getReader !== 'function') {
+                    const error = new Error('Invalid ReadableStream provided');
+                    if (this.onError) this.onError(error);
+                    reject(error);
+                    return;
+                }
+
+                const reader = stream.getReader();
+
+                const processChunk = async () => {
+                    try {
+                        while (true) {
+                            const { done, value } = await reader.read();
+
+                            if (done) {
+                                this.finalizeProcessing();
+                                this._sendRemainingChunks();
+                                if (this.onComplete) this.onComplete(this.allRecords);
+                                resolve();
+                                return;
+                            }
+
+                            this.processChunk(value);
+                            this._sendPendingChunks();
+                        }
+                    } catch (error) {
+                        if (this.onError) this.onError(error);
+                        reject(error);
+                    }
+                };
+
+                processChunk();
+            } else {
+                // Node.js Readable stream
+                if (!stream || typeof stream.pipe !== 'function') {
+                    const error = new Error('Invalid Readable stream provided');
+                    if (this.onError) this.onError(error);
+                    reject(error);
+                    return;
+                }
+
+                stream.on('data', (chunk) => {
+                    try {
+                        this.processChunk(chunk);
+                        this._sendPendingChunks();
+                    } catch (error) {
+                        if (this.onError) this.onError(error);
+                        reject(error);
+                    }
+                });
+
+                stream.on('end', () => {
+                    try {
+                        this.finalizeProcessing();
+                        this._sendRemainingChunks();
+                        if (this.onComplete) this.onComplete(this.allRecords);
+                        resolve();
+                    } catch (error) {
+                        if (this.onError) this.onError(error);
+                        reject(error);
+                    }
+                });
+
+                stream.on('error', (error) => {
+                    if (this.onError) this.onError(error);
+                    reject(error);
+                });
+            }
+        });
+    }
+
+    /**
+     * Send pending chunks when they reach the chunk size
+     * @private
+     */
+    _sendPendingChunks() {
+        if (!this.onChunk) return;
+
+        while (this.parsedRecords.length >= this.chunkSize) {
+            const chunk = this.parsedRecords.splice(0, this.chunkSize);
+            this.allRecords.push(...chunk);
+            this.onChunk(chunk, this.allRecords.length, null); // null for total when streaming
+        }
+    }
+
+    /**
+     * Send any remaining chunks at the end of processing
+     * @private
+     */
+    _sendRemainingChunks() {
+        if (!this.onChunk || this.parsedRecords.length === 0) return;
+
+        const chunk = [...this.parsedRecords];
+        this.parsedRecords.length = 0; // Clear the array
+        this.allRecords.push(...chunk);
+        this.onChunk(chunk, this.allRecords.length, this.allRecords.length);
+    }
+
+    /**
+     * Process a stream directly (unified interface for both environments)
+     * @param {Readable|ReadableStream} stream - The stream to process
+     * @returns {Promise<Array<object>>} Promise resolving to parsed records
+     */
+    async processStream(stream) {
+        return new Promise((resolve, reject) => {
+            if (this.isBrowser) {
+                // Browser ReadableStream
+                if (!stream || typeof stream.getReader !== 'function') {
+                    reject(new Error('Invalid ReadableStream provided'));
+                    return;
+                }
+
+                const reader = stream.getReader();
+
+                const processChunk = async () => {
+                    try {
+                        while (true) {
+                            const { done, value } = await reader.read();
+
+                            if (done) {
+                                this.finalizeProcessing();
+                                resolve(this.getResult());
+                                return;
+                            }
+
+                            this.processChunk(value);
+                        }
+                    } catch (error) {
+                        reject(error);
+                    }
+                };
+
+                processChunk();
+            } else {
+                // Node.js Readable stream
+                if (!stream || typeof stream.pipe !== 'function') {
+                    reject(new Error('Invalid Readable stream provided'));
+                    return;
+                }
+
+                stream.on('data', (chunk) => {
+                    try {
+                        this.processChunk(chunk);
+                    } catch (error) {
+                        reject(error);
+                    }
+                });
+
+                stream.on('end', () => {
+                    try {
+                        this.finalizeProcessing();
+                        resolve(this.getResult());
+                    } catch (error) {
+                        reject(error);
+                    }
+                });
+
+                stream.on('error', (error) => {
+                    reject(error);
+                });
+            }
+        });
+    }
+
+    /**
+     * Finalize processing when the stream ends
+     */
+    finalizeProcessing() {
+        this._processRemainingBuffer();
+        this._validateProcessingResult();
+    }
+
+    /**
+     * Get the final processed result
+     * @returns {Array<object>} Array of parsed JSON objects
+     */
+    getResult() {
+        return this.parsedRecords;
+    }
+
+    /**
+     * Process all complete records currently in the buffer
+     * @private
+     */
+    _processCompleteRecords() {
+        const parseResult = this._parseRecordsFromBuffer(this.buffer, this.isInsideQuotes);
+
+        this.buffer = parseResult.remainingBuffer;
+        this.isInsideQuotes = parseResult.isInsideQuotes;
+
+        for (const record of parseResult.completeRecords) {
+            this._processRecord(record);
+            this.currentRecordIndex++;
+        }
+    }
+
+    /**
+     * Process any remaining buffer content when stream ends
+     * @private
+     */
+    _processRemainingBuffer() {
+        if (this.buffer.length > 0) {
+            if (this.isInsideQuotes) {
+                throw CsvFormatError.mismatchedQuotes('CSV stream');
+            }
+
+            const parseResult = this._parseRecordsFromBuffer(this.buffer + '\n', false);
+
+            for (const record of parseResult.completeRecords) {
+                this._processRecord(record);
+                this.currentRecordIndex++;
+            }
+        }
+    }
+
+    /**
+     * Process a single CSV record
+     * @param {string} record - The CSV record to process
+     * @private
+     */
+    _processRecord(record) {
+        if (this.headers === null && this.currentRecordIndex === this.headerRowIndex) {
+            this._processHeaderRecord(record);
+        } else if (this.headers !== null) {
+            this._processDataRecord(record);
+        }
+    }
+
+    /**
+     * Process a header record
+     * @param {string} record - The header record
+     * @private
+     */
+    _processHeaderRecord(record) {
+        const headerFields = this._splitRecord(record);
+        if (stringUtils.hasContent(headerFields)) {
+            this.headers = headerFields;
+        }
+    }
+
+    /**
+     * Process a data record
+     * @param {string} record - The data record
+     * @private
+     */
+    _processDataRecord(record) {
+        const dataFields = this._splitRecord(record);
+        if (stringUtils.hasContent(dataFields)) {
+            const row = this.csvConfig.buildJsonResult(this.headers, dataFields);
+            const processedRow = this._applyRowMapper(row);
+            if (processedRow !== null) {
+                this.parsedRecords.push(processedRow);
+            }
+        }
+    }
+
+    /**
+     * Apply row mapper function if configured
+     * @param {object} row - The parsed row object
+     * @returns {object|null} The processed row or null if filtered out
+     * @private
+     */
+    _applyRowMapper(row) {
+        if (this.csvConfig.rowMapper) {
+            const mappedRow = this.csvConfig.rowMapper(row, this.dataRowIndex);
+            this.dataRowIndex++;
+            return mappedRow;
+        }
+        this.dataRowIndex++;
+        return row;
+    }
+
+    /**
+     * Split a CSV record into fields based on configuration
+     * @param {string} record - The record to split
+     * @returns {string[]} Array of field values
+     * @private
+     */
+    _splitRecord(record) {
+        if (this.csvConfig.isSupportQuotedField) {
+            return this.csvConfig.split(record);
+        }
+        return record.split(this.csvConfig.delimiter || ',');
+    }
+
+    /**
+     * Parse complete records from buffer, handling quoted fields across chunks
+     * @param {string} buffer - Current buffer content
+     * @param {boolean} insideQuotes - Whether we're currently inside quotes
+     * @returns {object} Object with completeRecords array and remaining buffer/quote state
+     * @private
+     */
+    _parseRecordsFromBuffer(buffer, insideQuotes) {
+        const completeRecords = [];
+        let currentRecord = '';
+        let i = 0;
+
+        while (i < buffer.length) {
+            const char = buffer[i];
+
+            if (char === QUOTE_CHAR) {
+                const escapedQuoteResult = this._handleEscapedQuote(buffer, i, insideQuotes);
+                if (escapedQuoteResult.wasEscaped) {
+                    currentRecord += QUOTE_CHAR + QUOTE_CHAR;
+                    i = escapedQuoteResult.newIndex;
+                    continue;
+                } else {
+                    insideQuotes = !insideQuotes;
+                }
+            } else if (!insideQuotes && this._isLineEnding(buffer, i)) {
+                const lineEndingLength = this._getLineEndingLength(buffer, i);
+                completeRecords.push(currentRecord);
+                currentRecord = '';
+                i += lineEndingLength;
+                continue;
+            }
+
+            currentRecord += char;
+            i++;
+        }
+
+        return {
+            completeRecords,
+            remainingBuffer: currentRecord,
+            isInsideQuotes: insideQuotes
+        };
+    }
+
+    /**
+     * Handle escaped quotes in quoted fields
+     * @param {string} buffer - The buffer content
+     * @param {number} index - Current index in buffer
+     * @param {boolean} insideQuotes - Whether currently inside quotes
+     * @returns {object} Result indicating if quote was escaped and new index
+     * @private
+     */
+    _handleEscapedQuote(buffer, index, insideQuotes) {
+        if (insideQuotes && index + 1 < buffer.length && buffer[index + 1] === QUOTE_CHAR) {
+            return { wasEscaped: true, newIndex: index + 2 };
+        }
+        return { wasEscaped: false, newIndex: index + 1 };
+    }
+
+    /**
+     * Check if character at index is a line ending
+     * @param {string} buffer - The buffer content
+     * @param {number} index - Current index
+     * @returns {boolean} True if line ending
+     * @private
+     */
+    _isLineEnding(buffer, index) {
+        return this._getLineEndingLength(buffer, index) > 0;
+    }
+
+    /**
+     * Get the length of line ending at current position
+     * @param {string} content - Content to check
+     * @param {number} index - Current index
+     * @returns {number} Length of line ending
+     * @private
+     */
+    _getLineEndingLength(content, index) {
+        if (content.slice(index, index + 2) === CRLF) {
+            return 2;
+        }
+        if (content[index] === LF) {
+            return 1;
+        }
+        if (content[index] === CR && content[index + 1] !== LF) {
+            return 1;
+        }
+        return 0;
+    }
+
+    /**
+     * Validate the final processing result
+     * @private
+     */
+    _validateProcessingResult() {
+        if (!this.headers && this.parsedRecords.length === 0) {
+            // Empty stream - this is OK
+            return;
+        }
+
+        if (!this.headers) {
+            throw CsvFormatError.missingHeader();
+        }
+    }
+}
+
+module.exports = StreamProcessor;

package/src/util/errors.js

@@ -318,6 +318,24 @@ class BrowserApiError extends CsvParsingError {
             { originalError: originalError.message }
         );
     }
+
+    /**
+     * Create error for unsupported streaming API in browser
+     * Occurs when browser doesn't support ReadableStream
+     * @returns {BrowserApiError} Configured error instance
+     * @static
+     */
+    static streamingNotSupported() {
+        return new BrowserApiError(
+            `Browser compatibility error: ReadableStream API is not available.\n` +
+            `Your browser does not support the ReadableStream API required for streaming.\n\n` +
+            `Solutions:\n` +
+            `  1. Use a modern browser that supports ReadableStream (Chrome 43+, Firefox 65+, Safari 10.1+)\n` +
+            `  2. Use getJsonFromFileStreamingAsync() which falls back to regular file parsing\n` +
+            `  3. Consider using parseFile() for non-streaming file parsing\n` +
+            `  4. Implement a polyfill for ReadableStream support`
+        );
+    }
 }
 
 module.exports = {