# @chbrown/sv

> Any separated values.

Latest version **0.4.4** (published 2024-08-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install @chbrown/sv
pnpm add @chbrown/sv
yarn add @chbrown/sv
bun add @chbrown/sv
```

Provides the command `sv`.

## Health

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

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

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.4 |
| Published | 2024-08-04 |
| First published | 2024-08-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 32.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Christopher Brown |
| Maintainers | chbrown |
| Keywords | any, separated, values, csv, tsv, tabular, tables |

## Links

- npm: https://www.npmjs.com/package/@chbrown/sv
- Repository: https://github.com/chbrown/sv
- Issues: https://github.com/chbrown/sv/issues
- npm.io page: https://npm.io/package/@chbrown/sv

## Dependencies (3)

- [async](https://npm.io/package/async.md) ^1.5.2
- [optimist](https://npm.io/package/optimist.md) ^0.6.1
- [streaming](https://npm.io/package/streaming.md) ^1.1.1

## 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

- 0.4.4 (latest) — 2024-08-04

## README

# sv

[![npm version](https://badge.fury.io/js/@chbrown%2Fsv.svg)](https://www.npmjs.com/package/@chbrown/sv)
[![Travis CI Build Status](https://travis-ci.org/chbrown/sv.svg)](https://travis-ci.org/chbrown/sv)
[![Coverage Status](https://coveralls.io/repos/chbrown/sv/badge.svg)](https://coveralls.io/github/chbrown/sv)

For all your separated value needs.

* `sv.Stringifier` is a [Readable stream](http://nodejs.org/api/stream.html#stream_class_stream_readable).
* `sv.Parser` is a [Writable stream](http://nodejs.org/api/stream.html#stream_class_stream_writable).

## Install

    npm install @chbrown/sv

The `optimist` dependency is only required for command line use.

## API usage

All tabular data must / will have column names on the first row.

### Parsing

sprints.csv:

    index	name	time
    1	chris	1:18
    2	daniel	1:17
    3	lewis	1:30
    4	stephen	1:16
    5	larry	1:32

And in node:

    var sv = require('@chbrown/sv');
    var parser = new sv.Parser();
    parser.on('data', function(obj) {
      console.log('sprinter ->', obj);
    });

    var fs = require('fs');
    var sprints = fs.createReadStream('sprints.csv', {encoding: 'utf8'});
    sprints.pipe(parser);

### Stringifying

    var expenses = [
      {name: 'Tip'                },
      {name: 'Lunch', amount: 5.90},
      {name: 'Latte', amount: 3.15},
      {name: 'Paper', amount: 2.10},
      {name: 'Pens' , amount: 4.59},
      {               amount: 9.16}
    ];

    var sv = require('@chbrown/sv');
    var stringifier = new sv.Stringifier({peek: 2, missing: 'n/a'});
    stringifier.pipe(process.stdout);
    expenses.forEach(function(expense) {
      stringifier.write(expense);
    });

    // if you write set 'peek' to more rows than you have in your data,
    // you'll need to call stringifier end so that they get flushed.
    stringifier.end();

* N.b.: If you pipe a buffer or (i.e., with a stringifier) into a parser, the
  parser will not receive any encoding. You _must_ set the encoding on the
  parser in those cases.

### Stringifier features:

1. Infer column names from a list of objects.
2. Convert from objects to csv / tsv plaintext.
   * Also allows writing arrays / strings directly.
3. Write header automatically.

### Parser features:

1. Infer delimiter from input.
2. Infer column names from first line of input.
3. Handle universal newlines (`\r`, `\r\n`, or `\n`).

## CLI usage

    shopt -s globstar
    for csv in ~/corpora/testsheets/**/*.csv; do
      echo
      file "$csv"
      echo "Tunneling through multiple 'sv' calls should be transparent."
      cat "$csv" | sv -j | wc -l
      cat "$csv" | sv | sv -j | wc -l
    done

## TODO

* Decide how to encode a field like {id: 1, name: '"chris'},
  when the delimiter is `,` and quotechar is `"`.
  - This is weird because it doesn't *need* quoting, but without, the
    quotechar marker will trigger an `inside` state, but there's no end quote.)


# Development notes

## Characters codes

Line separators:

* `\n` = 10 (newline)
* `\r` = 13 (return)

Field separators:

* `\t` = 9 (tab)
* ` ` = 32 (space)
* `,` = 44 (comma)
* `;` = 59 (semicolon)

Field quotations:

* `"` = 34 (double quote)
* `'` = 39 (single quote)
* <code>`</code> = 96 (backtick)

Escapes:

* `\` = 92 (backslash)

## Debugging helper:

    function logEvents(emitter, prefix, names) {
      names.forEach(function(name) {
        emitter.on(name, function(/*...*/) {
          console.error(prefix + ':' + name, arguments);
        });
      });
    }


## License

Copyright 2013-2016 Christopher Brown. [MIT Licensed](http://chbrown.github.io/licenses/MIT/#2013-2016).

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