Read and write CSV data in JavaScript.
IMPORTANT: This is an ESM only package.
Writing and reading CSV data is a common task performed by software developers. CSV files have been used for exporting and importing data for a very long time. It is not used as much these days, but you will still find it cropping up in modern applications and is still one of the fallback methods of transferring data.
This library is used to take a list of records and write them into a CSV string. It can also take a CSV string and convert it into a list of records. Both writing and reading methods come with a number of options to allow you to handle the different CSV formatting.
In this example we are writing the list of records using the default formatting options.
In this example we are reading in CSV data to create a list of records using default formatting options.
There is one static function for writing out a list records into a CSV string.
Convert a list of records into CSV string.
'\r\n', '\r', '\n', etc).';', ',', '\t', etc).'', 'NULL', 'N/A').\n, \t). If false then it uses the RFC 4180 double quote method.Returns the formatted CSV text.
There is one static function for reading in CSV string and converting it into a list of records. By default it will try to workout what type each field is, but you can set them manually if required.
Convert CSV text into a list of records.
';', ',', '\t', etc).TRUE fields.FALSE fields."null" or just not added to the record.\n, \t). If false then it uses the RFC 4180 double quote method.'number', 'string', 'boolean' or 'date'.'date').'boolean').'boolean').typeConvertCallback(field, header, headerIndex options) = value.
Returns an array of objects. Each object is a record, a line within the CSV data, contain all the header fields, converted from strings into the related data types. If nothing (undefined) is returned then something went wrong.
At the end of each CSV line there needs to be an "end of line" character.
Normally this would be either \n (new line), \r (carriage return), or \r\n (both together).
Each field is separated with a special character. This is normally ,, ; or \t (tab), but you can use any character you need.
If one of the strings of text also contains the same separator character then it will be placed inside quotes.
Some fields in a record will either not exist (undefined) or will be set to null.
This option will set what is written with these types of fields.
Boolean fields are written using the boolean text values.
By default these are either TRUE or FALSE.
These can be changed to any other required values.
For example you could set them to 1 and 0, or Yes and No.
When reading, if these options are set to AUTO then it will try to workout how the booleans are formatted.
There are some characters inside text data that are going to create problems. For example, if a field contains new line characters, then they would output an end of line character, spliting the record in two. There are two method for dealing with this.
Escape Character
This replaces problem characters with a \ backslash character and a code character.
For example, the new line character 0x0A become \n (a backslash + n character).
This surrounds the whole text field with quotation marks. If there is another quotation inside the field text then it is replaced with two quotation characters.
There are two different quotation characters we can use.
Either single quote ', or double quote ".
When writing you can choose to surround all the fields and headers with quotes.
Or, if you want, you can just quote all the string fields.
If the string field is empty (not null or undefined) then instead of writing nothing, you can write two quotation marks.
All the dates can be put inside quotes.
You can have all the header names placed inside quotes too.
Date fields can be formatted in different ways. When writing the default format is ISO. You can set the formatting pattern. You can use the following formatting characters.
When reading, if the date format is set to AUTO then it will try to work out the format of the date.
When reading in field data, if the data is empty, should the record's field property not be set, or should it be set to null.
If all the fields in a line are empty, should a record be created containing null field properties,
or should the record, which doesn't contain any data, be skipped.
When reading in, should all the values be converted into different types.
For example, should the text value TRUE be converted into a boolean true property.
If no conversion is performed then all the fields are set to string values.
When reading in text fields that contain escape characters, should they be converted.
For example, when reading in \n (a backslash + n character), should it convert them in to a new line character (0x0A).
There maybe times when the default field type convert is not good enough. You can replace the whole type conversion function with your own. Take a look at the example below. You can look out for the fields in the header you required, convert the value manually yourself, and then convert all the rest using the `CsvWrite.defaultTypeConvertCallback` function.
This same type of thing can be performed when reading in data too.
By default the headers are workout automatically and you therefore do not need to create this information yourself. However, there maybe times when you need to have more control over what is happening.
number, string, boolean or date.