Convert objects/arrays into a CSV string or write them into a CSV file (portable version)
npm install csv-writer-portableThis repository serves as an enhanced version of an existing project, ryu1kn/csv-writer.
The original project appeared to be unmaintained, leaving issues such as TypeScript compilation errors unresolved.
---
This library enables the conversion of JavaScript objects and arrays to CSV strings or writes them directly to a file. The generated CSV complies with RFC 4180.
- Node.js (Version 16 or higher)
Creating browser-compatible JavaScript files is now possible, thanks to the included Webpack configurations.
Here's what you can do with the available NPM scripts:
- bundle:dev: It bundles the code and includes source maps.
- bundle:prod: This is for production.
- compile: Compiles TypeScript based on tsconfig.json.
- compile-and-bundle: Compile and bundle sources in one go.
- serve: Starts a basic HTTP server to show files from the ./public directory at http://localhost:8080.
1. To bundle and serve the application, run the following commands in sequence:
``bash`
npm run bundle:dev
npm run serve
Then, navigate to http://localhost:8080.
2. To compile TypeScript and bundle in one go:
`bash`
npm run compile-and-bundle
npm run serve
#### Writing Records as Array of Objects to a File
The following code snippet demonstrates how to write records, defined as an array of objects, to a file.
`ts
import { createObjectCsvWriter } from 'csv-writer-portable';
const csvWriter = createObjectCsvWriter({
path: 'path/to/file.csv',
header: [
{id: 'name', title: 'NAME'},
{id: 'lang', title: 'LANGUAGE'}
]
});
const records = [
{name: 'Bob', lang: 'French, English'},
{name: 'Mary', lang: 'English'}
];
csvWriter.writeRecords(records) // returns a promise
.then(() => {
console.log('...Done');
});
`
The generated CSV file will contain the following:
`csv`
NAME,LANGUAGE
Bob,"French, English"
Mary,English
#### Using Custom Filter Functions
You can pass custom filter functions to manipulate field strings. Here’s an example that removes non-printable characters like \r and \n:
`ts
import { createObjectCsvWriter } from 'csv-writer-portable';
const csvPath = 'test.csv';
const csvWriter = createObjectCsvWriter({
path: csvPath,
header: [
{ id: 'phone_number', title: 'phone_number' },
{ id: 'name', title: 'name' }
],
filterFunction: (value: any) => {
const str = String(value);
// a simple regex to remove \r and \n chars
return str.replace(/[\r\n]/g, '');
},
alwaysQuote: true
});
const data = [
{ phone_number: 9978789799, name: "John \nDoe\r" },
{ phone_number: 8898988989, name: "Bob Marlin" }
];
async function writeCsv() {
await csvWriter.writeRecords(data);
}
writeCsv().catch(err => console.error('Error writing CSV:', err));
`
#### Multiple Writes to the Same File
To append more records, simply call writeRecords again after the promise from the previous call is fulfilled.
`ts`
// Usage in an async function
await csvWriter.writeRecords(records1);
await csvWriter.writeRecords(records2);
#### Writing Large Data Sets
For large data sets, you may want to create a Node.js transform stream and use CsvStringifier. This enables you to pipe the stream to a file write stream.
#### Skipping Header Line
To omit the header line, provide only the field IDs without titles.
`ts`
const csvWriter = createCsvWriter({
path: 'path/to/file.csv',
header: ['name', 'lang']
});
If each record is defined as an array, use createArrayCsvWriter to get a csvWriter instance.
`ts
import { createArrayCsvWriter } from 'csv-writer-portable';
const csvWriter = createArrayCsvWriter({
header: ['NAME', 'LANGUAGE'],
path: 'path/to/file.csv'
});
const records = [
['Bob', 'French, English'],
['Mary', 'English']
];
csvWriter.writeRecords(records) // returns a promise
.then(() => {
console.log('...Done');
});
`
This will produce a file path/to/file.csv with following contents:
`csv`
NAME,LANGUAGE
Bob,"French, English"
Mary,English
If you just want to get a CSV string but don't want to write into a file, you can use createObjectCsvStringifier (or createArrayCsvStringifier) to get a csvStringifier.
`ts
import { createObjectCsvStringifier } from 'csv-writer-portable';
const csvStringifier = createObjectCsvStringifier({
header: [
{id: 'name', title: 'NAME'},
{id: 'lang', title: 'LANGUAGE'}
]
});
const records = [
{name: 'Bob', lang: 'French, English'},
{name: 'Mary', lang: 'English'}
];
`
`ts
console.log(csvStringifier.getHeaderString());
// => 'NAME,LANGUAGE\n'
console.log(csvStringifier.stringifyRecords(records));
// => 'Bob,"French, English"\nMary,English\n'
`
The following tables describe the methods exposed by the CSV Writer Portable library.
#### createObjectCsvWriter(params)
| Description | Link |
| --- | --- |
| Creates a CsvWriter instance | Source Code |
| Parameter | Type | Description | Default | Allowed |
| --- | --- | --- | --- | --- |
| params | Object | Configuration options | - |
| └─ path | String | File path | - |
| └─ header | Array<{id, title}\|string> | Header specification | - |
| └─ fieldDelimiter | String (Optional) | Field delimiter | , | ; \| \t | \n
| └─ recordDelimiter | String (Optional) | Record delimiter | |utf8
| └─ encoding | String (Optional) | File encoding | |false
| └─ append | Boolean (Optional) | Append mode | |false
| └─ alwaysQuote | Boolean (Optional) | Always quote field values | |false
| └─ quoteEmptyFields | Boolean (Optional) | Double-quote ("") fields with empty values | |false
| └─ filterFunction | Function (Optional) | Custom function to manipulate field strings | (value: any) => value |
| └─ useBom | Boolean (Optional) | Add BOM for UTF-8 encoding | |
Returns: CsvWriter instance
---
#### createArrayCsvWriter(params)
| Description | Link |
| --- | --- |
| Creates an ArrayCsvWriter instance | 56" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">Source Code |
| Parameter | Type | Description | Default | Allowed |
| --- | --- | --- | --- | --- |
| params | Object | Configuration options | - |
| └─ path | String | File path | - |
| └─ header | Array
| └─ fieldDelimiter | String (Optional) | Field delimiter | , | ; \| \t | \n
| └─ recordDelimiter | String (Optional) | Record delimiter | |utf8
| └─ encoding | String (Optional) | File encoding | |false
| └─ append | Boolean (Optional) | Append mode | |false
| └─ alwaysQuote | Boolean (Optional) | Always quote field values | |false
| └─ quoteEmptyFields | Boolean (Optional) | Double-quote ("") fields with empty values | |false
| └─ filterFunction | Function (Optional) | Custom function to manipulate field strings | (value: any) => value |
| └─ useBom | Boolean (Optional) | Add BOM for UTF-8 encoding | |
Returns: CsvWriter instance
---
#### createObjectCsvStringifier(params)
| Description | Link |
| --- | --- |
| Creates an ObjectCsvStringifier instance | Source Code |
| Parameter | Type | Description | Default | Allowed |
| --- | --- | --- | --- | --- |
| params | Object | Configuration options | - |
| └─ header | Array<{id, title}\|string> | Header specification | - |
| └─ fieldDelimiter | String (Optional) | Field delimiter | , | ; \| \t |\n
| └─ recordDelimiter | String (Optional) | Record delimiter | |_
| └─ headerIdDelimiter | String (Optional) | Header ID delimiter | |false
| └─ alwaysQuote | Boolean (Optional) | Always quote field values | |false
| └─ quoteEmptyFields | Boolean (Optional) | Double-quote ("") fields with empty values | |
| └─ filterFunction | Function (Optional) | Custom function to manipulate field strings | (value: any) => value |
Returns: ObjectCsvStringifier instance
---
#### CsvWriter.writeRecords(records)
| Description | Link |
| --- | --- |
| Writes records to CSV | Source Code |
| Parameter | Type | Description |
| --- | --- | --- |
| records | Iterable | Collection of objects or arrays |
Returns: Promise
If you'd like to contribute by either proposing new features or reporting bugs, please visit: GitHub Issues
- Feature Requests: Context is key. Please provide a detailed explanation of why you need the specific feature and how it could benefit the users.
- Bug Reports: Reproducible code snippets are greatly appreciated.
- Node.js (Version 16 or higher)
- Docker
Licensed under the MIT License.
``