csv

What is csv?

The csv npm package is a comprehensive library for parsing and handling CSV data in Node.js. It provides a range of tools for reading, writing, transforming, and streaming CSV data, making it a versatile choice for developers working with CSV files in JavaScript.

What are csv's main functionalities?

Parsing CSV

This feature allows you to parse CSV data into arrays or objects. The code sample demonstrates how to parse a simple CSV string.

"use strict";
const parse = require('csv-parse');
const assert = require('assert');

const input = 'a,b,c\nd,e,f';
parse(input, function(err, output){
  assert.deepEqual(
    output,
    [['a', 'b', 'c'], ['d', 'e', 'f']]
  );
});

Stringifying CSV

This feature allows you to convert arrays or objects into CSV strings. The code sample shows how to stringify an array of arrays into a CSV string.

"use strict";
const stringify = require('csv-stringify');
const assert = require('assert');

const input = [['a', 'b', 'c'], ['d', 'e', 'f']];
stringify(input, function(err, output){
  assert.equal(
    output,
    'a,b,c\nd,e,f\n'
  );
});

Transforming Data

This feature allows you to apply a transformation to the CSV data. The code sample demonstrates how to convert all the values in the CSV to uppercase.

"use strict";
const transform = require('stream-transform');
const assert = require('assert');

const input = [['a', 'b', 'c'], ['d', 'e', 'f']];
const transformer = transform(function(record, callback){
  callback(null, record.map(value => value.toUpperCase()));
});

transformer.write(input[0]);
transformer.write(input[1]);
transformer.end();

const output = [];
transformer.on('readable', function(){
  let row;
  while ((row = transformer.read()) !== null) {
    output.push(row);
  }
});

transformer.on('end', function(){
  assert.deepEqual(
    output,
    [['A', 'B', 'C'], ['D', 'E', 'F']]
  );
});

Streaming API

This feature provides a streaming API for working with large CSV files without loading the entire file into memory. The code sample demonstrates how to read a CSV file as a stream and parse it.

"use strict";
const fs = require('fs');
const parse = require('csv-parse');

const parser = parse({columns: true});
const input = fs.createReadStream('/path/to/input.csv');

input.pipe(parser);

parser.on('readable', function(){
  let record;
  while ((record = parser.read()) !== null) {
    // Work with each record
  }
});

parser.on('end', function(){
  // Handle end of parsing
});

Other packages similar to csv

papaparse

PapaParse is a robust and powerful CSV parser for JavaScript with a similar feature set to csv. It supports browser and server-side parsing, auto-detection of delimiters, and streaming large files. Compared to csv, PapaParse is known for its ease of use and strong browser-side capabilities.

fast-csv

fast-csv is another popular CSV parsing and formatting library for Node.js. It offers a simple API, flexible parsing options, and support for streams. While csv provides a comprehensive set of tools for various CSV operations, fast-csv focuses on performance and ease of use for common tasks.

README

     _   _           _        _____  _______      __
    | \ | |         | |      / ____|/ ____\ \    / /
    |  \| | ___   __| | ___ | |    | (___  \ \  / / 
    | . ` |/ _ \ / _` |/ _ \| |     \___ \  \ \/ /  
    | |\  | (_) | (_| |  __/| |____ ____) |  \  /   
    |_| \_|\___/ \__,_|\___| \_____|_____/    \/     New BSD License

This project provides CSV generation, parsing, transformation and serialization. It has been tested and used on by a large community over the years and should be considered reliable. It provides every option you would expect from an advanced CSV parser and stringifier.

The project is splitted into 4 packages:

• csv-generate, a flexible generator of CSV string and Javascript objects.
• csv-parse, a parser converting CSV text into arrays or objects.
• stream-transform, a transformation framework.
• csv-stringify, a stringifier converting records into a CSV text.

The full documentation for the current version 0.4 isn't yet available other then the links to the README provided just above. The official documentation still cover the version 0.3.

Call for feedback

The redesign is an important step forward for this package. A lot of sugar has been removed in favor of straightforward implementations of the Stream API into the 4 sub-packages.

We now need your input. Help us with the documentation, write your impressions discuss additionnal APIs.

Usage

Installation command is npm install csv.

Each modules are fully be compatible with the stream 2 and 3 specifications. Also, a simple callback-based API is alwasy provided for conveniency.

Callback example

Execute this script with the command node samples/callback.js.

var csv = require('csv');

csv.generate({seed: 1, columns: 2, length: 20}, function(err, data){
  csv.parse(data, function(err, data){
    csv.transform(data, function(data){
      return data.map(function(value){return value.toUpperCase()});
    }, function(err, data){
      csv.stringify(data, function(err, data){
        process.stdout.write(data);
      });
    });
  });
});

Stream example

Execute this script with the command node samples/stream.js.

var csv = require('csv');

var generator = csv.generate({seed: 1, columns: 2, length: 20});
var parser = csv.parse();
var transformer = csv.transform(function(data){
  return data.map(function(value){return value.toUpperCase()});
});
var stringifier = csv.stringify();

generator.on('readable', function(){
  while(data = generator.read()){
    parser.write(data);
  }
});

parser.on('readable', function(){
  while(data = parser.read()){
    transformer.write(data);
  }
});

transformer.on('readable', function(){
  while(data = transformer.read()){
    stringifier.write(data);
  }
});

stringifier.on('readable', function(){
  while(data = stringifier.read()){
    process.stdout.write(data);
  }
});

Pipe example

Execute this script with the command node samples/pipe.js.

var csv = require('csv');

csv.generate  ({seed: 1, columns: 2, length: 20}).pipe(
csv.parse     ()).pipe(
csv.transform (function(record){
                return record.map(function(value){return value.toUpperCase()});
              })).pipe(
csv.stringify ()).pipe(process.stdout);

Migration

This README covers the current version 0.2.x of the node csv parser. The documentation for the previous version (0.1.0) is available here. The documentation for the incoming 0.3.x version is not yet released.

The functions 'from*' and 'to*' are now rewritten as 'from.' and 'to.'. The 'data' event is now the 'record' event. The 'data' now receives a stringified version of the 'record' event.

The documentation for olders version are available on GitHub: 0.1.x, 0.2.x.

Development

Tests are executed with mocha. To install it, simple run npm install, it will install mocha and its dependencies in your project "node_modules" directory.

To run the tests:

npm test

The tests run against the CoffeeScript source files.

To generate the JavaScript files:

make build

The test suite is run online with Travis against Node.js version 0.6, 0.7, 0.8 and 0.9.

Contributors

• David Worms: https://github.com/wdavidw

Related projects

• Pavel Kolesnikov "ya-csv": http://github.com/koles/ya-csv
• Chris Williams "node-csv": http://github.com/voodootikigod/node-csv