# csv-tr
> cli utility to manipulate (filter, search, sort and transform) long csv files lightning fast
Latest version **2.0.6** (published 2023-03-01) · MIT license · 0 weekly downloads
## Install
```sh
npm install csv-tr
pnpm add csv-tr
yarn add csv-tr
bun add csv-tr
```
Provides the command `csv-tr`.
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 2.0.6 |
| Published | 2023-03-01 |
| First published | 2021-12-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 15.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Martin Gonzalez |
| Maintainers | tin_r |
| Keywords | csv, transform, sort, filter |
## Links
- npm: https://www.npmjs.com/package/csv-tr
- Repository: https://github.com/devtin/csv-tr
- Homepage: https://github.com/devtin/csv-tr#readme
- Issues: https://github.com/devtin/csv-tr/issues
- npm.io page: https://npm.io/package/csv-tr
## Dependencies (3)
- [ramda](https://npm.io/package/ramda.md) ^0.27.1
- [commander](https://npm.io/package/commander.md) ^8.3.0
- [csv-parser](https://npm.io/package/csv-parser.md) ^3.0.0
## 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
- 2.0.6 (latest) — 2023-03-01
- 2.0.5 — 2022-12-21
- 2.0.4 — 2022-08-23
- 2.0.3 — 2022-01-08
- 2.0.2 — 2022-01-07
- 2.0.1 — 2021-12-22
- 2.0.0 — 2021-12-14
- 1.0.7 — 2021-12-05
- 1.0.6 — 2021-12-05
- 1.0.5 — 2021-12-05
- 1.0.4 — 2021-12-05
- 1.0.2 — 2021-12-04
- 1.0.1 — 2021-12-04
- 1.0.0 — 2021-12-04
## README
# csv-tr
Utility to manipulate long csv files
## Manifesto
Manipulating long csv files using graphic user interfaces might not be the most efficient at times. I want an utility that
helps me manipulate long csv files. This utility should:
- [Filter rows](#filtering-rows)
- [Transform rows](#transforming-rows)
- [Select specific columns](#selecting-specific-columns)
- [Exclude specific columns](#excluding-specific-columns)
- [Sort by columns](#sorting-by-column)
**Glossary of terms**
- **Column**: header column name of a csv file
- **Index**: line number of a csv file
- **Row**: line of a csv file
## Installation
```shell
npm install --global csv-tr
```
using `yarn`
```shell
yarn add global csv-tr
```
using `npx`
```shell
npx csv-tr --help
```
## CLI usage
```text
Usage: csv-tr [options] [source | input stream]
transforms given csv file or stream and outputs the result
Options:
-V, --version output the version number
-o, --only output only specified columns (comma separated). Not to be used with --exclude.
-e, --exclude exclude specified columns (comma separated). Not to be used with --only.
-t, --transform transform rows by given JavaScript expression. Ej: -t "row.email = row.email.toLowerCase()"
-f, --filter filter rows by given JavaScript file or expression. Ej: -f "row.state === 'FL'"
-s, --sort <[sort-column]:[sort-order: 1=ASC | -1=DESC]> sorts rows by column:order (comma separated) Ej: -s "firstName:1,lastName:-1"
-h, --help display help for command
```
### Input sample
Imagine a CSV file called `contacts.csv` with content
```csv
name,email,state
Juan,juan@gmail.com,FL
Miguel,miguel@hotmail.com,NY
Jesus,jesus@gmail.com,NY
```
### Filtering rows
Filtering values using the option `--filter` or `-f` followed by a JavaScript expression that will be evaluated
against a function that must return boolean, and looks like:
```js
(row, index) => { return /* your JavaScript expression */ }
```
Alternatively a file that exports a function with the same signature is also accepted:
```js
// my-filter-file
module.exports = (row/* , index */) => {
return /@gmail.com$/i.test(row.email)
}
```
Each `row` is nothing but a line of the csv file represented as a JSON object streamed by
csv-parser.
The `index` value is given row number starting at `0`. Meaning `index` of the first row (which is not the column names header)
equals `0`.
```shell
csv-tr contacts.csv -f '/@gmail.com$/i.test(row.email)' > gmail-contacts.csv
```
`gmail-contacts.csv` would look like:
```csv
name,email,state
Juan,juan@gmail.com,FL
Jesus,jesus@gmail.com,NY
```
**Slicing a given range of rows using the `index` value**
```shell
csv-tr contacts.csv -f 'index > 0 && index < 2'
```
Would output:
```csv
name,email,state
Miguel,miguel@hotmail.com,NY
```
### Transforming rows
Transforming values using the option `--transform` or `-t` followed by a JavaScript expression that will be evaluated
against a function that looks like.
```js
(row, index) => {
/* your js mutations go here */
}
```
Alternatively a file that exports a function with the same signature is also accepted:
```js
// my-transform-file
module.exports = (row/* , index */) => {
row.name = row.name.toUpperCase()
row.email = row.email.toUpperCase()
row.initial = row.name[0]
return row
}
```
Using the same `contacts.csv` [input sample](#input-sample).
```shell
csv-tr contacts.csv -t 'row.name = row.name.toUpperCase(); row.email = row.email.toUpperCase(); row.initial = row.name[0]' > contacts-uppercase.csv
```
`contacts-uppercase.csv` would look like:
```csv
name,email,state,initial
JUAN,JUAN@GMAIL.COM,FL,J
MIGUEL,MIGUEL@HOTMAIL.COM,NY,M
JESUS,JESUS@GMAIL.COM,NY,J
```
### Selecting specific columns
Using the same `contacts.csv` [input sample](#input-sample).
```shell
csv-tr contacts.csv -o email,state > contact-email-state.csv
```
`contact-email-state.csv` would look like:
```csv
email,state
juan@gmail.com,FL
miguel@hotmail.com,NY
jesus@gmail.com,NY
```
### Excluding specific columns
Using the same `contacts.csv` [input sample](#input-sample).
```shell
csv-tr contacts.csv -e email,state > contact-names.csv
```
`contact-names.csv` would look like:
```csv
name
Juan
Miguel
Jesus
```
### Sorting by column
Using the same `contacts.csv` [input sample](#input-sample), imagine sorting by `state` -> `DESC` and `name` -> `ASC`:
Sorting will guess numeric and date kind of values, and treat them accordingly.
```shell
csv-tr contacts.csv -s state:-1,name:1
```
Would output:
```csv
name,email,state
Jesus,jesus@gmail.com,NY
Miguel,miguel@hotmail.com,NY
Juan,juan@gmail.com,FL
```
## API Usage
Using all above's examples at once with the same `contacts.csv` [input sample](#input-sample)
```js
const fs = require('fs');
const { csvTr, sort, csvStringify } = require('csv-tr');
// un-comment any or multiple of the options below, run it and then take a look at result.csv
csvTr(fs.createReadStream('./tests/contacts.csv'), {
// filter: (row, index) => { return /@gmail.com$/i.test(row.email) },
// transform: (row, index) => { row.name = row.name.toUpperCase(); row.email = row.email.toUpperCase(); return row },
// only: ['email', 'state'],
// exclude: ['email', 'state'],
}).pipe(csvStringify()).pipe(fs.createWriteStream('result.csv'))
// SORTING
// mind sorting buffers all rows
const csvStreamToSort = csvTr(fs.createReadStream('contacts.csv'))
sort(csvStreamToSort, { state: -1, name: 1 }).then(sortedStream => {
sortedStream.pipe(csvStringify()).pipe(fs.createWriteStream('result-sorted.csv'))
})
```
`result-sorted.csv` would look like:
```csv
name,email,state
Jesus,jesus@gmail.com,NY
Miguel,miguel@hotmail.com,NY
Juan,juan@gmail.com,FL
```
* * *
## License
[MIT](https://opensource.org/licenses/MIT)
© 2021 Martin Rafael
---
_Source: https://npm.io/package/csv-tr · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._