### Generate Dependency Graph with Grunt Wiki

Source: https://github.com/keyang/node-csvtojson/wiki/dependencyHeader.txt

Run this command if all dependencies are installed to generate the dependency graph and push changes to the wiki repository.

```bash
grunt wiki
```

--------------------------------

### Install csvtojson Globally

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Installs the csvtojson command-line tool globally on your system.

```bash
$ npm i -g csvtojson
```

--------------------------------

### Install csvtojson Package

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Installs the csvtojson package as a project dependency.

```bash
npm i --save csvtojson
```

--------------------------------

### Install csvtojson as Library or CLI Tool

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Install the csvtojson package as a dependency for your Node.js project or as a global command-line tool.

```bash
# As a library dependency
npm install --save csvtojson

# As a global CLI tool
npm install -g csvtojson
```

--------------------------------

### converter.fromFile(filePath, options?)

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Reads a CSV file from disk by path and starts piping it through the converter. Returns the `Converter` for chaining. Supports Promise and async/await.

```APIDOC
## converter.fromFile(filePath, options?)

### Description
Reads a CSV file from disk by path and starts piping it through the converter. Returns the `Converter` for chaining.

### Parameters
#### filePath
- **filePath** (string) - Required - The path to the CSV file.

#### options
- **options** (object) - Optional - Configuration options for parsing and filtering.
  - **checkType** (boolean) - Optional - Cast values to their appropriate types (e.g., "95000" to 95000).
  - **includeColumns** (RegExp) - Optional - A regular expression to specify which columns to include.

### Request Example
```javascript
const csv = require('csvtojson');
const path = require('path');

const filePath = path.join(__dirname, 'employees.csv');
// employees.csv:
// id,name,department,salary
// 1,Alice,Engineering,95000
// 2,Bob,Marketing,72000
// 3,Carol,Engineering,105000

// Promise / async-await
async function loadEmployees() {
  try {
    const employees = await csv({
      checkType: true,
      includeColumns: /(id|name|salary)/
    }).fromFile(filePath);

    console.log(employees);
    // [
    //   { id: 1, name: 'Alice', salary: 95000 },
    //   { id: 2, name: 'Bob',   salary: 72000  },
    //   { id: 3, name: 'Carol', salary: 105000 }
    // ]
  } catch (err) {
    console.error('Parse failed:', err.message);
  }
}

loadEmployees();
```
```

--------------------------------

### Promise and Async/Await Support in csvtojson

Source: https://github.com/keyang/node-csvtojson/blob/master/docs/csvtojson-v2.md

Demonstrates how to use Promises and async/await for file processing with csvtojson. Includes examples for direct file reading and chaining promises for stream processing.

```javascript
// Promise
csv()
.fromFile(myCSVFilePath)
.then((jsonArray)=>{

}, errorHandle);

// async / await
const jsonArray= await csv().fromFile(myCSVFilePath);

// Promise chain
request.get(csvUrl)
.then((csvdata)=>{
  return csv().fromString(csvdata)
})
.then((jsonArray)=>{

})
```

--------------------------------

### Command-Line Tool (CLI) Examples

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Utilize the csvtojson command-line tool to convert CSV files to JSON, pipe data, and configure parsing options using flags. Supports various options like delimiter, column filtering, and error suppression.

```bash
# Convert a CSV file to JSON
csvtojson ./employees.csv > employees.json

# Pipe CSV data
cat ./data.csv | csvtojson > data.json

# Tab-separated file with type checking
csvtojson --delimiter=\t --checkType=true ./report.tsv

# Drop columns matching a regex
csvtojson --ignoreColumns=/(password|token)/ ./users.csv

# Include only specific columns
csvtojson --includeColumns=/(id|name|email)/ ./users.csv

# Suppress parse errors (--quiet), set max row length
csvtojson --quiet=true --maxRowLength=65535 ./large.csv

# Print version
csvtojson version

# Print help with all options
csvtojson
```

--------------------------------

### Define Custom Headers

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Provides examples for defining custom headers when the CSV source lacks a header row or when the first row needs replacement.

```javascript
// replace header row (first row) from original source with 'header1, header2'
csv({
	noheader: false,
	headers: ['header1','header2']
})

// original source has no header row. add 'field1' 'field2' ... 'fieldN' as csv header
csv({
	noheader: true
})

// original source has no header row. use 'header1' 'header2' as its header row
csv({
	noheader: true,
	headers: ['header1','header2']
})

```

--------------------------------

### Generate Dependency Graph with Madge

Source: https://github.com/keyang/node-csvtojson/wiki/dependencyHeader.txt

Use this command to generate a dependency graph, excluding specific modules. Ensure Graphviz is installed and its bin directory is in your PATH.

```bash
madge -x "node_modules|util|stream|os|assert|fs|http" -i graph.png ./
```

--------------------------------

### Promise Chain for File Parsing and Filtering

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Chain `.then()` calls after `fromFile` to process the full JSON array. This example filters rows based on a 'region' property.

```javascript
const csv = require('csvtojson');

// Promise chain
csv()
  .fromFile('./sales.csv')
  .then((jsonArray) => {
    console.log(`Parsed ${jsonArray.length} rows`);
    return jsonArray.filter(r => r.region === 'EMEA');
  })
  .then((emea) => {
    console.log('EMEA rows:', emea);
  })
  .catch((err) => {
    console.error('Error:', err);
  });
```

--------------------------------

### Transform Result Object Synchronously

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Use the 'subscribe' method to transform each parsed JSON object. This synchronous example directly modifies the object and returns it.

```javascript
const csv=require('csvtojson')
csv()
.subscribe((jsonObj,index)=>{
	jsonObj.myNewKey='some value'
	// OR asynchronously
	return new Promise((resolve,reject)=>{
		jsonObj.myNewKey='some value';
		resolve();
	})
})
.on('data',(jsonObj)=>{
	console.log(jsonObj.myNewKey) // some value
});
```

--------------------------------

### Await Full Result Array from String

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Use `await` with `fromString` to get the complete array of parsed JSON objects. The `checkType` option is enabled here.

```javascript
const csv = require('csvtojson');

// Async / await
async function run() {
  const rows = await csv({ checkType: true }).fromString('a,b\n1,2\n3,4');
  console.log(rows); // [{ a: 1, b: 2 }, { a: 3, b: 4 }]
}
```

--------------------------------

### Require csvtojson in JavaScript for Browser

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Use `require` or `import` to include `csvtojson` when using a module packager like webpack or browserify. This example demonstrates loading a CSV file using the Fetch API.

```javascript
var csv=require("csvtojson");

// or with import
import {csv} from "csvtojson";

//then use csv as normal, you'll need to load the CSV first, this example is using Fetch https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch 
fetch('http://mywebsite.com/mycsvfile.csv')
  .then(response => response.text())
  .then(text => csv.fromString(text));
  .then(function(result){
  
  })
```

--------------------------------

### Handle Data Event for Parsed CSV Lines

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

The 'data' event is emitted for each parsed CSV line. By default, it provides a buffer in ndjson format. Convert the buffer to a UTF-8 string to get the JSON string.

```javascript
const csv=require('csvtojson')
csv()
.on('data',(data)=>{
	//data is a buffer object
	const jsonStr= data.toString('utf8')
})
```

--------------------------------

### Display CLI Help

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Prints the help message for the csvtojson command-line tool, showing available options and usage.

```bash
$ csvtojson
```

--------------------------------

### Callback to Promise/Async-Await for fromFile

Source: https://github.com/keyang/node-csvtojson/blob/master/docs/csvtojson-v2.md

In v2.0.0, fromFile, fromStream, and fromString no longer accept callbacks. Use .then for Promises or await for async functions.

```javascript
csv().fromFile(myFile,function(err,jsonArr){})
```

```javascript
//Promise
csv().fromFile(myFile).then(function(jsonArr){},function(err){})

// Async 
const jsonArr=await csv().fromFile(myFile);
```

--------------------------------

### Configure csvtojson Converter with Parameters

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Initialize a csvtojson Converter with detailed parser and stream options to control parsing behavior and output format.

```javascript
const csv = require('csvtojson');

// Full parameter example
const converter = csv({
  delimiter: ',',          // column separator; "auto" for auto-detect; or array [",", "|"]
  quote: '"',              // quote character; "off" disables quoting
  trim: true,              // trim whitespace around cell values
  checkType: false,        // auto-detect and cast value types (number, bool, etc.)
  ignoreEmpty: false,      // skip cells with no value
  noheader: false,         // treat first row as data (not header)
  headers: undefined,      // override or supply headers: ["col1","col2"]
  flatKeys: false,         // disable dot-notation → nested object expansion
  maxRowLength: 0,         // max chars per row (0 = unlimited)
  checkColumn: false,      // emit error on column count mismatch
  eol: undefined,          // end-of-line char; auto-detected if omitted
  escape: '"',             // escape char inside quoted fields
  ignoreColumns: undefined,   // RegExp — columns to drop
  includeColumns: undefined,  // RegExp — columns to keep (whitelist)
  colParser: {},
  alwaysSplitAtEOL: false, // never allow EOL inside quoted field
  nullObject: false,       // convert literal "null" string → null
  output: 'json',          // "json" | "csv" | "line"
  downstreamFormat: 'line',// piped output: "line" (ndjson) | "array"
  needEmitAll: true,       // collect full array for .then() / await
}, {
  objectMode: false        // Node.js stream option; true = emit objects not buffers
});

```

--------------------------------

### Importing CSV to JSON Library Versions

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Demonstrates how to import different versions of the csvtojson library.

```javascript
// v1
const csvtojsonV1=require("csvtojson/v1");
// v2
const csvtojsonV2=require("csvtojson");
const csvtojsonV2=require("csvtojson/v2");
```

--------------------------------

### Initialize csvtojson Constructor

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Instantiate the csvtojson constructor with optional parser parameters and stream options.

```javascript
const csv=require('csvtojson')
const converter=csv(parserParameters, streamOptions)
```

--------------------------------

### Configure Output Formats (JSON, CSV, Line)

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Control the structure of each emitted row. Choose between JSON objects, string arrays, or raw CSV line strings. The 'json' format is the default.

```javascript
const csv = require('csvtojson');
const src  = `a,b,c
1,2,3
4,5,6`;

// "json" (default) — array of objects
csv({ output: 'json' }).fromString(src).then(console.log);
// [ { a: '1', b: '2', c: '3' }, { a: '4', b: '5', c: '6' } ]

// "csv" — array of string arrays (preserves original columns)
csv({ output: 'csv', noheader: true }).fromString(src).then(console.log);
// [ ['a','b','c'], ['1','2','3'], ['4','5','6'] ]

// "line" — array of raw CSV line strings (no parsing into columns)
csv({ output: 'line', noheader: true }).fromString(src).then(console.log);
// [ 'a,b,c', '1,2,3', '4,5,6' ]
```

--------------------------------

### Basic Parser Configuration

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Configure basic parser options like disabling headers and enabling trimming of column content.

```javascript
const converter=csv({
	noheader:true,
	trim:true,
})
```

--------------------------------

### Migrating from csvtojson v1 Events to v2 Subscribe/Then

Source: https://github.com/keyang/node-csvtojson/blob/master/docs/csvtojson-v2.md

Illustrates the code changes required to migrate from v1 event-based processing ('json', 'record_parsed', 'csv', 'end_parsed') to v2's Promise-based '.then' and '.subscribe' methods.

```javascript
//before -- get json object
csv().fromString(myCSV).on("json",function(json){});
csv().fromString(myCSV).on("record_parsed",function(json){});
//now
csv().fromString(myCSV).subscribe(function(json){});

//before -- get csv row
csv().fromString(myCSV).on("csv",function(csvRow){});
//now
csv({output:"csv"}).fromString(myCSV).subscribe(function(csvRow){});

//before -- get final json array
csv().fromString(myCSV).on("end_parsed",function(jsonArray){});
//now
csv().fromString(myCSV).then(function(jsonArray){}); // Promise
const jsonArray=await csv().fromString(myCSV);  // async /await
```

--------------------------------

### Async Hooks for Data Transformation in csvtojson

Source: https://github.com/keyang/node-csvtojson/blob/master/docs/csvtojson-v2.md

Shows how to use the .preRawData and .preFileLine hooks to perform asynchronous or synchronous transformations on the raw CSV data or individual file lines before parsing.

```javascript
csv().fromFile(csvFile)
.preRawData((data)=>{
  //async
  return new Promise((resolve,reject)=>{
    //async process
  });
  //sync
  return data.replace("a","b");
})
```

```javascript
csv().fromFile(csvFile)
.preFileLine((fileLine,lineNumber)=>{
  //async
  return new Promise((resolve,reject)=>{
    //async process
  });
  //sync
  return fileLine.replace("a","b");
})
```

--------------------------------

### Parse CSV File with Options using Async/Await

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Read a CSV file from disk and parse it into JSON objects, applying options like type checking and column inclusion. Handles potential parsing errors.

```javascript
const csv = require('csvtojson');
const path = require('path');

const filePath = path.join(__dirname, 'employees.csv');
// employees.csv:
// id,name,department,salary
// 1,Alice,Engineering,95000
// 2,Bob,Marketing,72000
// 3,Carol,Engineering,105000

// Promise / async-await
async function loadEmployees() {
  try {
    const employees = await csv({
      checkType: true,          // cast "95000" → 95000 (number)
      includeColumns: /(id|name|salary)/  // drop "department" column
    }).fromFile(filePath);

    console.log(employees);
    // [
    //   { id: 1, name: 'Alice', salary: 95000 },
    //   { id: 2, name: 'Bob',   salary: 72000  },
    //   { id: 3, name: 'Carol', salary: 105000 }
    // ]
  } catch (err) {
    console.error('Parse failed:', err.message);
  }
}

loadEmployees();

```

--------------------------------

### Asynchronous Line-by-Line Processing with csvtojson

Source: https://github.com/keyang/node-csvtojson/blob/master/docs/csvtojson-v2.md

Shows how to process CSV data line by line asynchronously or synchronously using the .subscribe method. This is useful for handling large files or performing operations on each record.

```javascript
// async process
csv()
.fromFile(csvFilePath)
.subscribe((json,lineNumber)=>{
  return Promise((resolve,reject)=>{
    // process the json line in asynchronous.
  })
},onError, onComplete)

// sync process
csv()
.fromFile(csvFilePath)
.subscribe((json,lineNumber)=>{
    // process the json line in synchronous.
},onError, onComplete)
```

--------------------------------

### Replace .transf with .subscribe

Source: https://github.com/keyang/node-csvtojson/blob/master/docs/csvtojson-v2.md

The .transf method has been removed due to poor performance. Use .subscribe for result transformation instead.

```javascript
csv()
.transf((jsonObj)=>{
	jsonObj.myNewKey='some value'
}).pipe(downstream)
```

```javascript
csv()
.subscribe((jsonObj)=>{
	jsonObj.myNewKey='some value'
}).pipe(downstream)
```

--------------------------------

### Initialize csvtojson Converter Factory

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Create a new csvtojson Converter instance using the default factory function. This instance is a Node.js Transform stream.

```javascript
const csv = require('csvtojson');

// Minimal usage — all defaults
const converter = csv();
```

--------------------------------

### TypeScript Integration with csvtojson

Source: https://github.com/keyang/node-csvtojson/blob/master/docs/csvtojson-v2.md

Illustrates how to import the TypeScript definition file for csvtojson, enabling type checking and autocompletion in TypeScript projects.

```typescript
// csvtojson/index.d.ts file
import csv from "csvtojson";
```

--------------------------------

### Pipe CSV Stream to HTTP PUT Request

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Demonstrates piping a file read stream through `csvtojson` and then piping the output to an HTTP PUT request stream.

```javascript
const fs = require('fs');
const http = require('http');
const csv = require('csvtojson');

const readStream  = fs.createReadStream('./data.csv');
const writeStream = http.request({ method: 'PUT', hostname: 'api.example.com', path: '/import' });

readStream.pipe(csv()).pipe(writeStream);
writeStream.on('finish', () => console.log('Upload complete'));
```

--------------------------------

### Include csvtojson in HTML

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Embed the pre-built script directly into your HTML using a script tag. This makes the `csv` function globally available.

```html
<script src="node_modules/csvtojson/browser/csvtojson.min.js"></script>
<!-- or use cdn -->
<script src="https://cdn.rawgit.com/Keyang/node-csvtojson/d41f44aa/browser/csvtojson.min.js"></script>
```

```html
<script>
csv({
	output: "csv"
})
.fromString("a,b,c\n1,2,3")
.then(function(result){

})
</script>
```

--------------------------------

### Header Row Configuration (noheader, headers)

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Configure how the parser identifies JSON keys when the CSV lacks a header, has an incorrect header, or requires programmatic header injection using `noheader` and `headers` options.

```javascript
const csv = require('csvtojson');

const noHeaderCsv = `Alice,30,Engineering
Bob,25,Marketing`;

// Auto-generate field1, field2, ... fieldN keys
csv({ noheader: true })
  .fromString(noHeaderCsv)
  .then(rows => console.log(rows));
// [{ field1: 'Alice', field2: '30', field3: 'Engineering' }, ...]

// Provide explicit headers for a header-less CSV
csv({ noheader: true, headers: ['name', 'age', 'dept'] })
  .fromString(noHeaderCsv)
  .then(rows => console.log(rows));
// [{ name: 'Alice', age: '30', dept: 'Engineering' }, ...]

// Override the actual header row in the CSV (noheader: false = first row IS present but replace it)
const csvWithBadHeader = `FNAME,YRS,DIV\nAlice,30,Engineering`;
csv({ noheader: false, headers: ['name', 'age', 'dept'] })
  .fromString(csvWithBadHeader)
  .then(rows => console.log(rows));
// [{ name: 'Alice', age: '30', dept: 'Engineering' }]
```

--------------------------------

### Output Formatting Options in csvtojson

Source: https://github.com/keyang/node-csvtojson/blob/master/docs/csvtojson-v2.md

Demonstrates how to configure csvtojson to output data in different formats: JSON array, CSV rows, or an array of CSV lines. The 'noheader' option is used to handle CSVs without headers.

```javascript
/**
 * csv data:
 * a,b,c
 * 1,2,3
 * const csvStr;
 */

let result= await csv().fromString(csvStr);
/**
 * result is json array:
 * [{
 *  a: "1",
 *  b: "2",
 *  c: "3:
 * }]
*/
result= await csv({output:"csv",noheader: true}).fromString(csvStr);
/**
 * result is array of csv rows:
 * [
 *  ["a","b","c"],
 *  ["1","2","3"]
 * ]
 */
result= await csv({output:"line",noheader: true}).fromString(csvStr);
/**
 * result is array of csv line in string (including end of line in cells if exists):
 * [
 *  "a,b,c",
 *  "1,2,3"
 * ]
 */
```

--------------------------------

### .preRawData Promise/Callback Change

Source: https://github.com/keyang/node-csvtojson/blob/master/docs/csvtojson-v2.md

.preRawData now uses Promises instead of callbacks. It can return data synchronously or asynchronously via a Promise.

```javascript
csv()
.preRawData((csvRawData,cb)=>{
	var newData=csvRawData.replace('some value','another value')
	cb(newData);
})
```

```javascript
csv()
.preRawData((csvRawData)=>{
  var newData=csvRawData.replace('some value','another value')
  // synchronous
  return newData;
  // or asynchronously
  return Promise.resolve(newData);
})
```

--------------------------------

### Events: `header`, `data`, `error`, `done`

Source: https://context7.com/keyang/node-csvtojson/llms.txt

As a Transform stream, `Converter` emits standard events like `header`, `data`, `error`, and `done` for fine-grained control over the parsing process.

```APIDOC
## Events: `header`, `data`, `error`, `done`

`Converter` is a Transform stream and emits standard events for fine-grained control.

```js
const csv = require('csvtojson');

csv()
  .on('header', (headers) => {
    // Fired once; headers is always string[]
    console.log('Columns:', headers); // e.g. ['id', 'name', 'email']
  })
  .on('data', (chunk) => {
    // Fired per row; chunk is a Buffer in ndjson format
    const obj = JSON.parse(chunk.toString('utf8'));
    console.log('Row object:', obj);
  })
  .on('error', (err) => {
    // Fired on parse error; stream stops automatically
    console.error('Parse error:', err.message, '| line:', err.line);
  })
  .on('done', (err) => {
    // Fired when parsing finishes or after an error
    if (err) {
      console.error('Finished with error:', err);
    } else {
      console.log('Done — no more rows');
    }
  })
  .fromFile('./users.csv');
```
```

--------------------------------

### csv(parserParameters?, streamOptions?)

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Factory function to create a new Converter instance, which is a Node.js Transform stream. It accepts optional parser parameters and stream options.

```APIDOC
## csv(parserParameters?, streamOptions?)

### Description
Factory function that returns a new `Converter` instance (a Transform stream). Both arguments are optional. `parserParameters` controls parsing behavior; `streamOptions` are passed directly to Node.js `Transform`.

### Parameters
#### parserParameters
- **delimiter** (string | array) - Optional - Column separator; "auto" for auto-detect; or array [",", "|"]
- **quote** (string) - Optional - Quote character; "off" disables quoting
- **trim** (boolean) - Optional - Trim whitespace around cell values
- **checkType** (boolean) - Optional - Auto-detect and cast value types (number, bool, etc.)
- **ignoreEmpty** (boolean) - Optional - Skip cells with no value
- **noheader** (boolean) - Optional - Treat first row as data (not header)
- **headers** (array) - Optional - Override or supply headers: ["col1","col2"]
- **flatKeys** (boolean) - Optional - Disable dot-notation → nested object expansion
- **maxRowLength** (number) - Optional - Max chars per row (0 = unlimited)
- **checkColumn** (boolean) - Optional - Emit error on column count mismatch
- **eol** (string) - Optional - End-of-line char; auto-detected if omitted
- **escape** (string) - Optional - Escape char inside quoted fields
- **ignoreColumns** (RegExp) - Optional - Columns to drop
- **includeColumns** (RegExp) - Optional - Columns to keep (whitelist)
- **colParser** (object) - Optional - Per-column type overrides / custom parsers
- **alwaysSplitAtEOL** (boolean) - Optional - Never allow EOL inside quoted field
- **nullObject** (boolean) - Optional - Convert literal "null" string → null
- **output** (string) - Optional - "json" | "csv" | "line"
- **downstreamFormat** (string) - Optional - Piped output: "line" (ndjson) | "array"
- **needEmitAll** (boolean) - Optional - Collect full array for .then() / await

#### streamOptions
- **objectMode** (boolean) - Optional - Node.js stream option; true = emit objects not buffers

### Request Example
```javascript
const csv = require('csvtojson');

// Minimal usage — all defaults
const converter = csv();

// Full parameter example
const converter = csv({
  delimiter: ',',
  quote: '"',
  trim: true,
  checkType: false,
  ignoreEmpty: false,
  noheader: false,
  headers: undefined,
  flatKeys: false,
  maxRowLength: 0,
  checkColumn: false,
  eol: undefined,
  escape: '"',
  ignoreColumns: undefined,
  includeColumns: undefined,
  colParser: {},
  alwaysSplitAtEOL: false,
  nullObject: false,
  output: 'json',
  downstreamFormat: 'line',
  needEmitAll: true
}, {
  objectMode: false
});
```
```

--------------------------------

### `.then(onFulfilled, onRejected?)` / `await`

Source: https://context7.com/keyang/node-csvtojson/llms.txt

The `Converter` object implements `PromiseLike`, allowing it to be used directly with `await` or `.then()`. The resolved value is the complete array of all parsed rows.

```APIDOC
## `.then(onFulfilled, onRejected?)` / `await` — Collect full result array

`Converter` implements `PromiseLike`, so it can be used directly with `await` or `.then()`. The resolved value is the complete array of all parsed rows.

```js
const csv = require('csvtojson');

// Async / await
async function run() {
  const rows = await csv({ checkType: true }).fromString('a,b\n1,2\n3,4');
  console.log(rows); // [{ a: 1, b: 2 }, { a: 3, b: 4 }]
}

// Promise chain
csv()
  .fromFile('./sales.csv')
  .then((jsonArray) => {
    console.log(`Parsed ${jsonArray.length} rows`);
    return jsonArray.filter(r => r.region === 'EMEA');
  })
  .then((emea) => {
    console.log('EMEA rows:', emea);
  })
  .catch((err) => {
    console.error('Error:', err);
  });
```
```

--------------------------------

### Header Row Configuration

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Configure how the parser identifies JSON keys, especially for CSVs without headers, with incorrect headers, or when programmatic header injection is needed.

```APIDOC
## Header row configuration (`noheader`, `headers`)

Controls how the parser determines JSON keys when the source CSV has no header row, has an incorrect header, or needs column names injected programmatically.

```js
const csv = require('csvtojson');

const noHeaderCsv = `Alice,30,Engineering
Bob,25,Marketing`;

// Auto-generate field1, field2, ... fieldN keys
csv({ noheader: true })
  .fromString(noHeaderCsv)
  .then(rows => console.log(rows));
// [{ field1: 'Alice', field2: '30', field3: 'Engineering' }, ...]

// Provide explicit headers for a header-less CSV
csv({ noheader: true, headers: ['name', 'age', 'dept'] })
  .fromString(noHeaderCsv)
  .then(rows => console.log(rows));
// [{ name: 'Alice', age: '30', dept: 'Engineering' }, ...]

// Override the actual header row in the CSV (noheader: false = first row IS present but replace it)
const csvWithBadHeader = `FNAME,YRS,DIV\nAlice,30,Engineering`;
csv({ noheader: false, headers: ['name', 'age', 'dept'] })
  .fromString(csvWithBadHeader)
  .then(rows => console.log(rows));
// [{ name: 'Alice', age: '30', dept: 'Engineering' }]
```
```

--------------------------------

### csvtojson Constructor

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

The csvtojson constructor accepts optional parser parameters and stream options to customize the conversion process.

```APIDOC
## csvtojson Constructor

### Description

Initializes the csvtojson converter with optional parser parameters and stream options.

### Method

`require('csvtojson')`

### Parameters

1. **Parser Parameters** (Object) - Optional. A JSON object to configure parsing behavior.
2. **Stream Options** (Object) - Optional. Options for the Node.js stream transform.

### Example

```javascript
const csv = require('csvtojson');
const converter = csv(parserParameters, streamOptions);
```

### Parser Parameters Details

*   **output** (String) - The format to be converted to. Options: "json" (default), "csv", "line".
*   **delimiter** (String | Array) - Delimiter used for separating columns. Use "auto" for auto-detection or an array of potential delimiters. Default: ",".
*   **quote** (String) - Quote character used for columns containing delimiters. Set to "off" to ignore quotes. Default: " (double quote).
*   **trim** (Boolean) - Indicates if parser should trim spaces surrounding column content. Default: true.
*   **checkType** (Boolean) - Turns on/off field type checking. Default: false (true if version < 1.1.4).
*   **ignoreEmpty** (Boolean) - Ignores empty values in CSV columns. Default: false.
*   **fork** (Boolean) - Forks another process to parse the CSV stream (experimental). Default: false.
*   **noheader** (Boolean) - Indicates CSV data has no header row. Default: false.
*   **headers** (Array) - An array to specify the headers of CSV data. Overrides CSV header row if `noheader` is false. Default: null.
*   **flatKeys** (Boolean) - Prevents interpretation of dots (.) and square brackets in header fields as nested object or array identifiers. Default: false.
*   **maxRowLength** (Number) - The maximum character a CSV row could have. 0 means infinite. Default: 0.
*   **checkColumn** (Boolean) - Checks if the column number of a row matches the headers number. Default: false.
*   **eol** (String) - End of line character. If omitted, parser attempts to retrieve it from the first chunks of CSV data.
*   **escape** (String) - Escape character used in quoted columns. Default is double quote (").
*   **includeColumns** (RegExp) - Includes only columns matching the regular expression.
*   **ignoreColumns** (RegExp) - Ignores columns matching the regular expression.
*   **colParser** (Object) - Allows overriding parsing logic for a specific column. Example: `{field1: 'number'}`.
*   **alwaysSplitAtEOL** (Boolean) - Always interprets each line as a row, preventing `eol` characters within a row. Default: false.
*   **nullObject** (Boolean) - Parses "null" string as a null object. Default: false.
*   **downstreamFormat** (String) - Sets the JSON array format for the downstream. Options: "line" (ndjson), "array". Default: "line".
*   **needEmitAll** (Boolean) - If false, the parser will not build the JSON result when `.then` is called or `await` is used. Default: true.
```

--------------------------------

### Row-by-Row Async Processing with Subscribe

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Use the `subscribe` method for row-by-row asynchronous processing. Callbacks can perform async operations and mutate rows before they are passed downstream.

```javascript
const csv = require('csvtojson');
const db  = require('./db');  // hypothetical database client

csv()
  .fromFile('./orders.csv')
  .subscribe(
    async (order, lineNumber) => {
      // Mutate the object — change is reflected downstream
      order.processedAt = new Date().toISOString();
      order.total = parseFloat(order.total);

      // Async work per row (e.g., DB insert)
      await db.orders.insert(order);
      console.log(`Line ${lineNumber}: inserted order ${order.id}`);
    },
    (err) => {
      console.error('Row error:', err.message);
    },
    () => {
      console.log('All rows processed');
    }
  );
```

--------------------------------

### Define Custom Column Parser Function

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Illustrates how to define a custom parser function for the 'birthday' column to convert date strings into JavaScript Date objects.

```javascript
/*csv data
name, birthday
Joe, 1970-01-01
*/
csv({
	colParser:{
		"birthday":function(item, head, resultRow, row , colIdx){
			/*
				item - "1970-01-01"
				head - "birthday"
				resultRow - {name:"Joe"}
				row - ["Joe","1970-01-01"]
				colIdx - 1
			*/
			return new Date(item);
		}
	}
})

```

--------------------------------

### `converter.subscribe(onNext, onError?, onComplete?)`

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Registers a callback function that is invoked for every parsed row. The callback can return a `Promise` to process rows asynchronously and apply in-place transformations before the row is passed downstream.

```APIDOC
## `converter.subscribe(onNext, onError?, onComplete?)` — Row-by-row async processing

Registers a callback invoked for every parsed row. The callback may return a `Promise` to process rows asynchronously and apply in-place transformations before the row reaches downstream consumers.

```js
const csv = require('csvtojson');
const db  = require('./db');  // hypothetical database client

csv()
  .fromFile('./orders.csv')
  .subscribe(
    async (order, lineNumber) => {
      // Mutate the object — change is reflected downstream
      order.processedAt = new Date().toISOString();
      order.total = parseFloat(order.total);

      // Async work per row (e.g., DB insert)
      await db.orders.insert(order);
      console.log(`Line ${lineNumber}: inserted order ${order.id}`);
    },
    (err) => {
      console.error('Row error:', err.message);
    },
    () => {
      console.log('All rows processed');
    }
  );
```
```

--------------------------------

### RegExp for ignoreColumns/includeColumns

Source: https://github.com/keyang/node-csvtojson/blob/master/docs/csvtojson-v2.md

The ignoreColumns and includeColumns options now exclusively accept RegExp objects, replacing string arrays.

```javascript
csv({
  ignoreColumns:["gender","age"]
})
```

```javascript
csv({
  ignoreColumns: /gender|age/
})
```

--------------------------------

### Pipe CSV Data to CLI for Conversion

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Converts CSV data piped from standard input to JSON format using the command-line interface.

```bash
$ cat ./source.csv | csvtojson > converted.json
```

--------------------------------

### Handle CSV Parsing Events

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Use event listeners (`.on()`) for fine-grained control over the parsing process, including 'header', 'data', 'error', and 'done' events.

```javascript
const csv = require('csvtojson');

csv()
  .on('header', (headers) => {
    // Fired once; headers is always string[]
    console.log('Columns:', headers); // e.g. ['id', 'name', 'email']
  })
  .on('data', (chunk) => {
    // Fired per row; chunk is a Buffer in ndjson format
    const obj = JSON.parse(chunk.toString('utf8'));
    console.log('Row object:', obj);
  })
  .on('error', (err) => {
    // Fired on parse error; stream stops automatically
    console.error('Parse error:', err.message, '| line:', err.line);
  })
  .on('done', (err) => {
    // Fired when parsing finishes or after an error
    if (err) {
      console.error('Finished with error:', err);
    } else {
      console.log('Done — no more rows');
    }
  })
  .fromFile('./users.csv');
```

--------------------------------

### Transform Each Line with preFileLine Hook

Source: https://context7.com/keyang/node-csvtojson/llms.txt

The `preFileLine` hook allows transformation of each line individually before it's parsed. It can be used to normalize headers, skip comment lines, or perform line-specific modifications.

```javascript
const csv = require('csvtojson');

csv()
  .preFileLine((line, lineNumber) => {
    if (lineNumber === 0) {
      // Normalize header row to lowercase
      return line.toLowerCase();
    }
    // Skip comment lines (lines starting with #)
    if (line.startsWith('#')) {
      return '';
    }
    return line;
  })
  .fromFile('./data.csv')
  .then((rows) => console.log(rows));
```

--------------------------------

### Use Built-in Column Parsers

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Configures column parsing to override inferred types, using 'omit' for 'column1' and 'string' for 'column2'. Requires `checkType: true`.

```javascript
/*csv string
column1,column2
hello,1234
*/
csv({
	colParser:{
		"column1":"omit",
		"column2":"string",
	},
	checkType:true
})
.fromString(csvString)
.subscribe((jsonObj)=>{
	//jsonObj: {column2:"1234"}
})

```

--------------------------------

### Load Employees from CSV with TypeScript

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Loads employee data from a CSV file using specified parameters for type checking and column inclusion. Requires the 'csvtojson' package and TypeScript.

```typescript
import csv from 'csvtojson';
import { CSVParseParam } from 'csvtojson/v2/Parameters';
import { Converter }     from 'csvtojson/v2/Converter';

interface Employee {
  id: number;
  name: string;
  salary: number;
}

async function loadEmployees(filePath: string): Promise<Employee[]> {
  const params: Partial<CSVParseParam> = {
    checkType: true,
    includeColumns: /(id|name|salary)/,
  };

  const rows = await csv(params).fromFile(filePath) as Employee[];
  return rows;
}

loadEmployees('./employees.csv').then(console.log);
```

--------------------------------

### Column Parser (colParser)

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Configure per-column type overrides and custom parsing logic using the `colParser` option. It supports built-in types, custom functions, and `ColumnParam` objects for advanced control.

```APIDOC
## `colParser` — Per-column type overrides and custom parsers

The `colParser` parameter accepts a map of column name → built-in type string (`"number"`, `"string"`, `"omit"`), a custom function, or a `ColumnParam` object with `flat` and `cellParser` fields.

```js
const csv = require('csvtojson');

const csvStr = `name,dob,score,notes,person.id
Alice,1990-04-15,98.5,ignore me,42
Bob,1985-11-02,74.0,ignore me,17`;

csv({
  colParser: {
    // Built-in: cast to number
    score: 'number',

    // Built-in: drop entire column from output
    notes: 'omit',

    // Custom function: parse date string → Date object
    dob: (value, header, resultRow, rawRow, colIndex) => {
      return new Date(value);
    },

    // Flat key: keep dot-key literal instead of nesting
    'person.id': {
      flat: true,
      cellParser: 'number'
    }
  }
})
.fromString(csvStr)
.then((rows) => {
  console.log(rows);
  // [
  //   { name: 'Alice', dob: Date('1990-04-15'), score: 98.5, 'person.id': 42 },
  //   { name: 'Bob',   dob: Date('1985-11-02'), score: 74,   'person.id': 17 }
  // ]
});
```
```

--------------------------------

### Filter Columns with Regex (Include/Ignore)

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Use regular expressions to whitelist or blacklist columns by their header names. This is useful for selecting specific data or excluding sensitive information.

```javascript
const csv = require('csvtojson');

const csvStr = `id,firstName,lastName,email,password,age
1,Alice,Smith,alice@example.com,secret123,30
2,Bob,Jones,bob@example.com,hunter2,25`;

// Keep only id, firstName, lastName
csv({ includeColumns: /(id|firstName|lastName)/ })
  .fromString(csvStr)
  .then(rows => console.log(rows));
// [{ id: '1', firstName: 'Alice', lastName: 'Smith' }, ...] 

// Drop sensitive columns
csv({ ignoreColumns: /(password|email)/ })
  .fromString(csvStr)
  .then(rows => console.log(rows));
// [{ id: '1', firstName: 'Alice', lastName: 'Smith', age: '30' }, ...]
```

--------------------------------

### Browser Usage: Script Tag and ES Module

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Integrate csvtojson in the browser using either a direct script tag, which exposes a global `csv` object, or via ES modules for use with bundlers like Webpack.

```html
<!-- Option 1: script tag (exposes global `csv`) -->
<script src="node_modules/csvtojson/browser/csvtojson.min.js"></script>
<script>
  csv({ checkType: true })
    .fromString("product,price\nApple,1.20\nBanana,0.50")
    .then(function(rows) {
      console.log(rows);
      // [{ product: 'Apple', price: 1.2 }, { product: 'Banana', price: 0.5 }]
    });
</script>

<!-- Option 2: ES module / bundler (webpack, browserify) -->
<script type="module">
  import csv from 'csvtojson';

  // Parse CSV fetched from a URL
  const response = await fetch('/api/report.csv');
  const text     = await response.text();
  const rows     = await csv({ checkType: true }).fromString(text);
  console.log(rows);
</script>
```

--------------------------------

### Asynchronous CSV File Line Hook

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

The 'preFileLine' hook can be asynchronous, accepting a promise that resolves with the modified CSV line. This is useful for performing async operations on each line.

```javascript
const csv=require('csvtojson')
csv()
.preFileLine((fileLineString, lineIdx)=>{
	return new Promise((resolve,reject)=>{
			// async function processing the data.
	})
	
	
})
```

--------------------------------

### Convert CSV to Nested JSON

Source: https://github.com/keyang/node-csvtojson/blob/master/readme.md

Demonstrates the default behavior of csvtojson in creating nested JSON structures based on the CSV header row. No special configuration is required.

```csv
fieldA.title, fieldA.children.0.name, fieldA.children.0.id,fieldA.children.1.name, fieldA.children.1.employee.0.name,fieldA.children.1.employee.1.name, fieldA.address.0,fieldA.address.1, description
Food Factory, Oscar, 0023, Tikka, Tim, Joe, 3 Lame Road, Grantstown, A fresh new food factory
Kindom Garden, Ceil, 54, Pillow, Amst, Tom, 24 Shaker Street, HelloTown, Awesome castle

```

```json
[
    {
        "fieldA": {
            "title": "Food Factory",
            "children": [{
                "name": "Oscar",
                "id": "0023"
            }, {
                "name": "Tikka",
                "employee": [{
                    "name": "Tim"
                }, {
                    "name": "Joe"
                }]
            }],
            "address": ["3 Lame Road", "Grantstown"]
        },
        "description": "A fresh new food factory"
    }, {
        "fieldA": {
            "title": "Kindom Garden",
            "children": [{
                "name": "Ceil",
                "id": "54"
            }, {
                "name": "Pillow",
                "employee": [{
                    "name": "Amst"
                }, {
                    "name": "Tom"
                }]
            }],
            "address": ["24 Shaker Street", "HelloTown"]
        },
        "description": "Awesome castle"
    }
]
```

--------------------------------

### preFileLine Hook

Source: https://context7.com/keyang/node-csvtojson/llms.txt

The `preFileLine` hook is invoked for each raw line of the CSV before it's parsed into columns. It receives the line string and its 0-based line number. You can return a modified line synchronously or asynchronously.

```APIDOC
## `converter.preFileLine(callback)` — Hook: transform each raw line

Called for every raw line string before it is parsed into columns. `lineNumber` is 0-based. Return the modified line (sync) or a `Promise<string>` (async).

```js
const csv = require('csvtojson');

csv()
  .preFileLine((line, lineNumber) => {
    if (lineNumber === 0) {
      // Normalize header row to lowercase
      return line.toLowerCase();
    }
    // Skip comment lines (lines starting with #)
    if (line.startsWith('#')) {
      return '';
    }
    return line;
  })
  .fromFile('./data.csv')
  .then((rows) => console.log(rows));
```
```

--------------------------------

### Parse CSV String to Raw CSV Row Arrays

Source: https://context7.com/keyang/node-csvtojson/llms.txt

Use `fromString` with the `output: 'csv'` and `noheader: true` options to parse CSV data into raw row arrays, excluding the header.

```javascript
const csv = require('csvtojson');

const csvData = `product,price,inStock
Widget,9.99,true
Gadget,24.50,false
Gizmo,4.00,true`;

async function parseProducts() {
  // Output as raw CSV row arrays instead of JSON objects
  const rows = await csv({ output: 'csv', noheader: true })
    .fromString(csvData);
  console.log(rows);
}
```