Skip to content

Simple, ultra-light (10kb) JS library for CSV parsing. Works in browser and node with zero dependencies.

License

Notifications You must be signed in to change notification settings

rufuspollock/csv.js

Repository files navigation

CSV.js

Simple, ultra light (10kb uncompressed) javascript CSV library for browser and node with zero dependencies.

Originally developed as part of ReclineJS but now fully standalone.

Usage

Grab the csv.js file and include it in your application.

Depends on jQuery or underscore.deferred (for deferred) in fetch (and jQuery if you need ajax). parse and serialize have zero dependencies.

fetch

A convenient way to load a CSV file from various different sources. fetch supports 3 options depending on the attribute provided on the info argument:

CSV.fetch({
    data: 'raw csv string'
    // or ...
    url: 'url to a csv file'
    // or ...
    file: an HTML 5 file object

    // optional options about structure of the CSV file
    // following the CSV Dialect Description Format 
    // https://frictionlessdata.io/specs/csv-dialect/
    dialect: {
      ...
    }
  }
).done(function(dataset) {
  // dataset object doc'd below
  console.log(dataset);
});

Some more detail on the argument object:

  • data is a string in CSV format. This is passed directly to the CSV parser
  • url: a url to an online CSV file that is ajax accessible (note this usually requires either local or on a server that is CORS enabled). The file is then loaded using jQuery.ajax and parsed using the CSV parser (NB: this requires jQuery) All options generates similar data and use the memory store outcome, that is they return something like:
  • file: is an HTML5 file object. This is opened and parsed with the CSV parser.
  • dialect: hash / dictionary following the same structure as for parse method below.

Returned dataset object looks like:

{
  // an array of arrays - one array each row in the CSV
  // (excluding header row - i.e. first row)
  records: [ [...], [...], ... ],
  // list of fields
  fields: [ 'field-name-1', 'field-name-2', ... ],
  metadata: { may be some metadata e.g. file name }
}

Raw parsing

var out = CSV.parse(csvString, dialect);

Converts a Comma Separated Values string into an array of arrays. Each line in the CSV becomes an array.

Empty fields are converted to nulls and non-quoted numbers are converted to integers or floats.

  • csvString: the csv string to parse

  • dialect: [optional] hash with keys as per the CSV dialect description format. It also supports the following additional keys:

    • skipInitialRows: [optional] integer number of rows to skip (default 0)

    For backwards compatability with earlier versions of the library the dialect also supports the following:

Serialize

Convert an Object or a simple array of arrays into a Comma Separated Values string.

var out = CSV.serialize(dataToSerialize, dialect);

Returns a string representing the array serialized as a CSV.

dataToSerialize is an Object or array of arrays to convert. Object structure must be as follows:

{
  fields: [ {id: .., ...}, {id: ..., 
  records: [ { record }, { record }, ... ]
  ... // more attributes we do not care about
}

Nulls are converted to empty fields and integers or floats are converted to non-quoted numbers.

You may optionally specify a label inside each field so that the serialized data will use it as the column heading instead of the id.


Other JS CSV Libs

Node

Development

Requirements

  • webpack
  • jquery
npm install
npm install jquery
webpack-dev-server

Run tests

Requirements

  • karma
  • phantomjs
npm -g install karma karma-cli phantomjs-prebuilt
npm install
npm install jquery
npm test

About

Simple, ultra-light (10kb) JS library for CSV parsing. Works in browser and node with zero dependencies.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published