Sync loading of a small .csv file

Usage no npm install needed!

<script type="module">
  import csvLoadSync from 'https://cdn.skypack.dev/csv-load-sync';



Sync loading routine for a small comma-separated values file (.csv). Returns an array of objects, takes property names from the first line. Assumes everything is a string in quotes.

Package info

ci status semantic-release


Requires nodejs

npm install -S csv-load-sync


Example CSV file with two records

"1","iPhone 4"
"2","iPhone 4S"

Example CSV file with three records

"1","John","Smith","US","2013-08-04 23:57:38"
"2","Greg","Smith","US","2013-07-12 13:27:18"
"3","Harold","Smith","GB","2013-07-16 21:17:28"

Simple example

const {load} = require('csv-load-sync');
const csv = load('path/to/file.csv');
// csv is an Array of objects

Convert values

You can convert every value from string to a desired type for the specified columns. For example to convert device IDs to an integer, while make the descriptions all uppercase:

const {load} = require('csv-load-sync')
const csv = load('./phone.csv', {
  convert: {
    deviceId: parseInt,
    description: (s) => s.toUpperCase(),
// objects:
// deviceId: 1, description: "IPHONE 4"
// deviceId: 2, description: "IPHONE 4S"

Useful conversions:

  • to boolean: (s) => (s === 'true' ? true : false)
  • to integer: parseInt
  • to floats: parseFloat

Custom line splitting

Sometimes CSV data includes commas naturally, for example the follwing file has GPS location numbers which should be considered together.


We need to split each record line differently. You can pass the line to columns splitter function when calling load

function split(line, lineNumber) {
  if (lineNumber === 0) { // title line
    return line.split(',')
  // our line will be <location>,<lat>,<lon>
  // and we want to combine lat and lon
  var parts = line.split(',')
  return [parts[0], parts[1] + ',' + parts[2]];
var results = load(filename, {
  getColumns: split
  place: 'home',
  location: '-41.20,20.11'
}, {
  place: 'work',
  location: '-41.3,20.2'


Blank lines and lines starting with # are skipped.

Skip columns

Sometimes you want to skip certain columns. Use an option:

const results = load(filename, {
  skip: ['lastLogin', 'country'],

Parse given text

If you load the CSV text yourself, you can use `` to parse it

const {parseCSV} = require('csv-load-sync')
// csv is your text to be parsed
const records = parseCSV(csv)

Get columns

You can just get the header names from the CSV file

const {getHeaders} = require('csv-load-sync')
const names = getHeaders('path/to/file.csv')
// names is an array of strings

Fine print

Author: Gleb Bahmutov © 2015

License: MIT - do anything with the code, but don't blame me if it does not work.

Spread the word: tweet, star on github, etc.