csv-writer-portable

CSV Writer Portable

Introduction

This repository serves as an enhanced version of an existing project, ryu1kn/csv-writer.

Rationale

The original project appeared to be unmaintained, leaving issues such as TypeScript compilation errors unresolved.

Features

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.

Prerequisites

Node.js (Version 16 or higher)

Webpack

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.

How to Test

To bundle and serve the application, run the following commands in sequence:
```
npm run bundle:dev
npm run serve
```
Then, navigate to http://localhost:8080.
To compile TypeScript and bundle in one go:
```
npm run compile-and-bundle
npm run serve
```

Quick Start

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.

const createCsvWriter = require('csv-writer').createObjectCsvWriter;
const csvWriter = createCsvWriter({
    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:

NAME,LANGUAGE
Bob,"French, English"
Mary,English

Multiple Writes to the Same File

To append more records, simply call writeRecords again after the promise from the previous call is fulfilled.

// 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.

const csvWriter = createCsvWriter({
    path: 'path/to/file.csv',
    header: ['name', 'lang']
});

If each record is defined as an array, use createArrayCsvWriter to get an csvWriter instance.

const createCsvWriter = require('csv-writer').createArrayCsvWriter;
const csvWriter = createCsvWriter({
    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:

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 an csvStringifier.

const createCsvStringifier = require('csv-writer').createObjectCsvStringifier;
const csvStringifier = createCsvStringifier({
    header: [
        {id: 'name', title: 'NAME'},
        {id: 'lang', title: 'LANGUAGE'}
    ]
});

const records = [
    {name: 'Bob',  lang: 'French, English'},
    {name: 'Mary', lang: 'English'}
];

console.log(csvStringifier.getHeaderString());
// => 'NAME,LANGUAGE\n'

console.log(csvStringifier.stringifyRecords(records));
// => 'Bob,"French, English"\nMary,English\n'

API Documentation

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
params	Object	Configuration options	-
└─ path	String	File path	-
└─ header	Array<{id, title}\|string>	Header specification	-
└─ fieldDelimiter	String (Optional)	Field delimiter	`,`
└─ recordDelimiter	String (Optional)	Record delimiter	`\n`
└─ encoding	String (Optional)	File encoding	`utf8`
└─ append	Boolean (Optional)	Append mode	`false`

Returns: CsvWriter instance

CsvWriter.writeRecords(records)

Description	Link
Writes records to CSV	Source Code

Parameter	Type	Description
records	Iterable	Collection of objects or arrays

Returns: Promise

createObjectCsvStringifier(params)

Description	Link
Creates an ObjectCsvStringifier instance	Source Code

Parameter	Type	Description	Default
params	Object	Configuration options	-
└─ header	Array<{id, title}\|string>	Header specification	-
└─ fieldDelimiter	String (Optional)	Field delimiter	`,`
└─ recordDelimiter	String (Optional)	Record delimiter	`\n`

Returns: ObjectCsvStringifier instance

Contribute

If you'd like to contribute by either proposing new features or reporting bugs, please visit: GitHub Issues

Guidelines

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.

csv-writer-portable