# objects-to-csv

> Converts an array of objects into a CSV file. Saves CSV to disk or returns as string.

Latest version **1.3.6** (published 2020-01-04) · Unlicense license · 0 weekly downloads

## Install

```sh
npm install objects-to-csv
pnpm add objects-to-csv
yarn add objects-to-csv
bun add objects-to-csv
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.6 |
| Published | 2020-01-04 |
| First published | 2018-02-27 |
| Weekly downloads | 0 |
| License | Unlicense |
| TypeScript types | separate (@types/objects-to-csv) |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 13.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 100 |
| Author | Anton Ivanov |
| Maintainers | anton-ivanov |
| Keywords | csv, object-to-csv, async-csv, converters, conversion, utilities, utils, json-to-csv, json2csv, array-to-csv |

## Links

- npm: https://www.npmjs.com/package/objects-to-csv
- Repository: https://github.com/anton-bot/objects-to-csv
- Homepage: https://github.com/anton-bot/objects-to-csv#readme
- Issues: https://github.com/anton-bot/objects-to-csv/issues
- npm.io page: https://npm.io/package/objects-to-csv

## Dependencies (1)

- [async-csv](https://npm.io/package/async-csv.md) ^2.1.3

## Alternatives

- [csv-to-markdown-table](https://npm.io/package/csv-to-markdown-table.md) — 47.0K weekly downloads
- [@sapphire/ratelimits](https://npm.io/package/@sapphire/ratelimits.md) — 4.4K weekly downloads
- [js-csvparser](https://npm.io/package/js-csvparser.md) — 2.0K weekly downloads
- [@adadapted/js-sdk](https://npm.io/package/@adadapted/js-sdk.md) — 251 weekly downloads
- [@grapecity/spread-sheets-sparklines](https://npm.io/package/@grapecity/spread-sheets-sparklines.md) — 103 weekly downloads

## Recent versions

- 1.3.6 (latest) — 2020-01-04
- 2.0.0 (next) — 2019-07-23
- 1.3.5 — 2019-10-16
- 1.3.4 — 2019-08-29
- 2.0.0-pre — 2019-07-23
- 1.3.3 — 2019-07-12
- 1.3.2 — 2019-07-12
- 1.3.1 — 2019-07-06
- 1.3.0 — 2019-07-06
- 1.2.2 — 2019-06-05
- 1.2.1 — 2018-10-19
- 1.2.0 — 2018-10-19
- 1.1.0 — 2018-10-08
- 1.0.1 — 2018-02-27
- 1.0.0 — 2018-02-27
- … 1 more at https://npm.io/package/objects-to-csv/versions

## README

# Convert array of objects into a CSV file #

Converts an array of JavaScript objects into the CSV format. You can
save the CSV to file or return it as a string.

The keys in the first object of the array will be used as column names.

Any special characters in the values (such as commas) will be properly escaped.

## Usage ##

```js
const ObjectsToCsv = require('objects-to-csv');

// Sample data - two columns, three rows:
const data = [
  {code: 'CA', name: 'California'},
  {code: 'TX', name: 'Texas'},
  {code: 'NY', name: 'New York'},
];

// If you use "await", code must be inside an asynchronous function:
(async () => {
  const csv = new ObjectsToCsv(data);

  // Save to file:
  await csv.toDisk('./test.csv');

  // Return the CSV file as string:
  console.log(await csv.toString());
})();
```

## Methods ##

There are two methods, `toDisk(filename)` and `toString()`.

### async toDisk(filename, options) ###

Converts the data and saves the CSV file to disk. The `filename` must include the
path as well.

The `options` is an optional parameter which is an object that contains the 
settings. Supported options:

- `append` - whether to append to the file. Default is `false` (overwrite the file).
Set to `true` to append. Column names will be added only once at the beginning
of the file. If the file does not exist, it will be created.
- `bom` - whether to add the Unicode Byte Order Mark at the beginning of the
file. Default is `false`; set to `true` to be able to view Unicode in Excel
properly. Otherwise Excel will display Unicode incorrectly.
- `allColumns` - whether to check all array items for keys to convert to columns rather 
than only the first. This will sort the columns alphabetically. Default is `false`;
set to `true` to check all items for potential column names.

```js
const ObjectsToCsv = require('objects-to-csv');
const sampleData = [{ id: 1, text: 'this is a test' }];

// Run asynchronously, without awaiting:
new ObjectsToCsv(sampleData).toDisk('./test.csv');

// Alternatively, you can append to the existing file:
new ObjectsToCsv(sampleData).toDisk('./test.csv', { append: true });

// `allColumns: true` collects column names from all objects in the array,
// instead of only using the first one. In this case the CSV file will
// contain three columns:
const mixedData = [
  { id: 1, name: 'California' },
  { id: 2, description: 'A long description.' },
];
new ObjectsToCsv(mixedData).toDisk('./test.csv', { allColumns: true });
```

### async toString(header = true, allColumns = false) ###

Returns the CSV file as a string.

Two optional parameters are available:

- `header` controls whether the column names will be
returned as the first row of the file. Default is `true`. Set it to `false` to
get only the data rows, without the column names.
- `allColumns` controls whether to check every item for potential keys to process,
rather than only the first item; this will sort the columns alphabetically by key name.
Default is `false`. Set it to `true` to process keys that may not be present
in the first object of the array.

```js
const ObjectsToCsv = require('objects-to-csv');
const sampleData = [{ id: 1, text: 'this is a test' }];

async function printCsv(data) {
  console.log(
    await new ObjectsToCsv(data).toString()
  );
}

printCsv(sampleData);
```

## Requirements ##

Use Node.js version 8 or above.

---
_Source: https://npm.io/package/objects-to-csv · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._