csvtojson

You can control how values are typed in the resulting JSON.

Implicit Typing

When checkType is enabled, the parser automatically converts values to their inferred type (e.g., true becomes a boolean, 12 becomes a number, and JSON strings become objects).

Explicit Typing

You can force a type by prefixing the column name with #! in the CSV header. Supported types include:

• string
• number

Example:

string#!appNumber, string#!finished
201401010002, true

Result:

{
  "appNumber": "201401010002",
  "finished": "true"
}

By default, csvtojson supports converting CSV headers into nested JSON objects and arrays using dot notation (e.g., fieldA.children.0.name).

Example Header Mapping:

• fieldA.title $\rightarrow$ { "fieldA": { "title": "..." } }
• fieldA.address.0 $\rightarrow$ { "fieldA": { "address": ["..."] } }

To disable this behavior and keep keys flat (e.g., {"a.b": 1}), set flatKeys: true in the configuration object.

/**
csvStr: 
a.b,a.c
1,2
*/
csv({flatKeys:true})
.fromString(csvStr)
.on('json',(jsonObj)=>{
	//{"a.b":1,"a.c":2}  rather than  {"a":{"b":1,"c":2}}
});

The library can replicate complex JSON graphs using specific header naming conventions:

• Dot notation (.): Represents nested objects. field1.field2 becomes { "field1": { "field2": value } }.
• Square brackets ([]): Represents arrays. field1.field2[0].name creates an array of objects.
• Implicit Arrays: Different columns with the same header name are automatically added to the same array.

Note: To prevent information loss in arrays containing objects with multiple fields, you should explicitly include the index (e.g., field[0].name, field[1].name).

To prevent the parser from interpreting these headers as literal keys, use the --flatKeys=true flag.

To prevent the main Node.js process from blocking during large CSV parsing, you can enable experimental multi-core support. This spawns worker processes to handle the parsing work.

Usage:

• Library: Pass workerNum (integer $\ge 1$) in the options object.
• CLI: Use the --workerNum flag.

Limitations:

• Does not support columns containing line breaks.
• You cannot use custom functions in the colParser parameter because worker processes cannot access them.

Since version 0.3, the Converter class inherits from Node.js stream.Transform. To convert a file, create a file read stream and pipe it into a new Converter instance.

Use the end_parsed event to receive the final parsed JSON object once the stream has finished processing.

var fs = require("fs");
var Converter = require("csvtojson").Converter;
var fileStream = fs.createReadStream("./file.csv");

// new converter instance
var converter = new Converter({constructResult:true});

// end_parsed will be emitted once parsing finished
converter.on("end_parsed", function (jsonObj) {
   console.log(jsonObj); // your result json object
});

// read from file
fileStream.pipe(converter);

In v2, csvtojson supports native Promises and async/await syntax. Methods like fromFile, fromStream, and fromString no longer accept callbacks; instead, you should use .then() or await to handle the resulting JSON array.

// Using Promises
csv()
.fromFile(myCSVFilePath)
.then((jsonArray) => {
  // handle success
}, errorHandle);

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

// Chaining with other promises
request.get(csvUrl)
.then((csvdata) => {
  return csv().fromString(csvdata);
})
.then((jsonArray) => {
  // handle final json array
});

// 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)=>{

})

You can install csvtojson either as a global command-line tool or as a local dependency for your Node.js project.

To install globally:

npm install -g csvtojson

To install as a project dependency:

npm install csvtojson --save