CSVtoJSON

Overview

Demo and JSDoc

Features

RFC 4180 Standard

RFC 4180 Example

firstName,lastName,email
"Smith, John",Smith,john@example.com
Jane,Doe,jane@example.com
"Cooper, Andy",Cooper,andy@company.com

Quick Start

Installation

npm install convert-csv-to-json

Synchronous (Simple)

const csvToJson = require('convert-csv-to-json');
const json = csvToJson.getJsonFromCsv('input.csv');

Asynchronous (Modern)

const csvToJson = require('convert-csv-to-json');
const json = await csvToJson.getJsonFromCsvAsync('input.csv');

Browser

const convert = require('convert-csv-to-json');
const json = await convert.browser.parseFile(file);

Documentation

Common Tasks

Parse CSV String

const json = csvToJson.csvStringToJson('name,age\nAlice,30');

Custom Delimiter

const json = csvToJson
 .fieldDelimiter(';')
 .getJsonFromCsv('input.csv');

Format Values

const json = csvToJson
 .formatValueByType()
 .getJsonFromCsv('input.csv');
// Converts "30" → 30, "true" → true, etc.

Handle Quoted Fields

const json = csvToJson
 .supportQuotedField(true)
 .getJsonFromCsv('input.csv');

Batch Process Files (Async)

const files = ['file1.csv', 'file2.csv', 'file3.csv'];
const results = await Promise.all(
 files.map(f => csvToJson.getJsonFromCsvAsync(f))
);

Configuration Options

Examples

fieldDelimiter(char) - Set field delimiter (default: ,)

// Semicolon-delimited
csvToJson.fieldDelimiter(';').getJsonFromCsv('data.csv');
// Tab-delimited
csvToJson.fieldDelimiter('\t').getJsonFromCsv('data.tsv');
// Pipe-delimited
csvToJson.fieldDelimiter('|').getJsonFromCsv('data.psv');

formatValueByType() - Auto-convert numbers, booleans

// Input: name,age,active
// John,30,true
csvToJson.formatValueByType().getJsonFromCsv('data.csv');
// Output: { name: 'John', age: 30, active: true }

supportQuotedField(bool) - Handle quoted fields with embedded delimiters

// Input: name,description
// "Smith, John","He said ""Hello"""
csvToJson.supportQuotedField(true).getJsonFromCsv('data.csv');
// Output: { name: 'Smith, John', description: 'He said "Hello"' }

indexHeader(num) - Specify header row (default: 0)

// If headers are in row 2 (3rd line):
csvToJson.indexHeader(2).getJsonFromCsv('data.csv');

trimHeaderFieldWhiteSpace(bool) - Remove spaces from headers

// Input: " First Name ", " Last Name "
csvToJson.trimHeaderFieldWhiteSpace(true).getJsonFromCsv('data.csv');
// Output: { FirstName: 'John', LastName: 'Doe' }

parseSubArray(delim, sep) - Parse delimited arrays

// Input: name,tags
// John,*javascript,nodejs,typescript*
csvToJson.parseSubArray('*', ',').getJsonFromCsv('data.csv');
// Output: { name: 'John', tags: ['javascript', 'nodejs', 'typescript'] }

ignoreColumnIndexes(indexes) - Exclude specific columns by index

// Input: firstName,lastName,age
// John,Doe,30
// Jane,Smith,25
csvToJson.ignoreColumnIndexes([1]).getJsonFromCsv('data.csv');
// Output: [{ firstName: 'John', age: '30' }, { firstName: 'Jane', age: '25' }]

mapRows(fn) - Transform, filter, or enrich each row

// Filter out rows that don't match a condition
const result = csvToJson
 .fieldDelimiter(',')
 .mapRows((row) => {
 // Only keep rows where age >= 30
 if (parseInt(row.age) >= 30) {
 return row;
 }
 return null; // Filters out this row
 })
 .getJsonFromCsv('input.csv');

utf8Encoding(), latin1Encoding(), etc. - Set file encoding

// UTF-8 encoding
csvToJson.utf8Encoding().getJsonFromCsv('data.csv');
// Latin-1 encoding
csvToJson.latin1Encoding().getJsonFromCsv('data.csv');
// Custom encoding
csvToJson.customEncoding('ucs2').getJsonFromCsv('data.csv');

getJsonFromStreamAsync(stream) - Process CSV from Readable streams

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

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

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

Example: Complete Workflow

const csvToJson = require('convert-csv-to-json');
async function processCSV() {
 const data = await csvToJson
 .fieldDelimiter(',')
 .formatValueByType()
 .supportQuotedField(true)
 .getJsonFromCsvAsync('data.csv');
 
 console.log(`Parsed ${data.length} records`);
 return data;
}

Migration Guides

Development

npm install

npm test

npm run test-debug

CI/CD GitHub Action

Release

License

Support

Buy Me a Coffee