docs: update titles, links, feature and samples

adaltas · Nov 13, 2021 · 722f1eb · 722f1eb
1 parent 187a4ef
commit 722f1eb
Show file tree

Hide file tree

Showing 6 changed files with 242 additions and 91 deletions.
diff --git a/README.md b/README.md
@@ -9,6 +9,8 @@
 
 </pre>
 
+# CSV packages for Node.js and the web
+
 This project provides CSV generation, parsing, transformation and serialization for Node.js.
 
 It has been tested and used by a large community over the years and should be considered reliable. It provides every option you would expect from an advanced CSV parser and stringifier.
@@ -17,21 +19,42 @@ It has been tested and used by a large community over the years and should be co
 
 This repository is a monorepo managed using [Lerna](https://github.com/lerna/lerna). There are 5 packages managed in this codebase, even though we publish them to NPM as separate packages:
 
-*   [`csv`](packages/csv/),
-    an umbrella which is itself split into 4 packages.
-*   [`csv-generate`](packages/csv-generate/),
-    a flexible generator of CSV string and Javascript objects.
-*   [`csv-parse`](packages/csv-parse/),
-    a parser converting CSV text into arrays or objects.
-*   [`csv-stringify`](packages/csv-stringify/),
-    a stringifier converting records into a CSV text.
-*   [`stream-transform`](packages/stream-transform/),
-    a transformation framework.
+* [`csv`](packages/csv/),
+  an umbrella which is itself split into 4 packages.
+* [`csv-generate`](packages/csv-generate/),
+  a flexible generator of CSV string and Javascript objects.
+* [`csv-parse`](packages/csv-parse/),
+  a parser converting CSV text into arrays or objects.
+* [`csv-stringify`](packages/csv-stringify/),
+  a stringifier converting records into a CSV text.
+* [`stream-transform`](packages/stream-transform/),
+  a transformation framework.
 
 ## Documentation
 
 The full documentation for the current version is available [here](https://csv.js.org).
 
+* [Getting Started](https://csv.js.org/project/getting-started/)
+* [Examples](https://csv.js.org/project/examples/)
+* [License](https://csv.js.org/project/license/)
+* [Community](https://csv.js.org/project/contribute/)
+
+## Features
+
+* Extends the native Node.js [transform stream API](http://nodejs.org/api/stream.html#stream_class_stream_transform)
+* Simplicity with the optional callback and sync API
+* Support for ECMAScript modules and CommonJS
+* Large documentation, numerous examples and full unit test coverage
+* Few dependencies, in many cases zero dependencies
+* Node.js support from version 8 to latest
+* Mature project with more than 10 years of history
+
 ## License
 
 Licensed under the [MIT License](LICENSE).
+
+## Contributors
+
+The project is sponsored by [Adaltas](https://www.adaltas.com), an Big Data consulting firm based in Paris, France.
+
+*   David Worms: <https://github.com/wdavidw>
diff --git a/packages/csv-generate/README.md b/packages/csv-generate/README.md
@@ -1,21 +1,20 @@
 
+# CSV generator for Node.js and the web - `csv-generate` package
+
 [![Build Status](https://img.shields.io/github/workflow/status/adaltas/node-csv/Node.js)](https://github.com/adaltas/node-csv/actions)
 [![NPM](https://img.shields.io/npm/dm/csv-generate)](https://www.npmjs.com/package/csv-generate)
 [![NPM](https://img.shields.io/npm/v/csv-generate)](https://www.npmjs.com/package/csv-generate)
 
-# CSV and object generation
-
-This package provides a flexible generator of CSV strings and Javascript objects
-implementing the Node.js `stream.Readable` API.
+This package provides a flexible generator of random CSV strings and Javascript objects implementing the Node.js `stream.Readable` API.
 
 [Documentation for the "csv-generate" package is available here](https://csv.js.org/generate/).
 
 ## Documentation
 
-* [Project homepage](http://csv.js.org/generate/)
-* [API](http://csv.js.org/generate/api/)
-* [Options](http://csv.js.org/generate/options/)
-* [Examples](http://csv.js.org/generate/examples/)
+* [Project homepage](https://csv.js.org/generate/)
+* [API](https://csv.js.org/generate/api/)
+* [Options](https://csv.js.org/generate/options/)
+* [Examples](https://csv.js.org/generate/examples/)
 
 ## Main features
 
@@ -30,7 +29,42 @@ implementing the Node.js `stream.Readable` API.
 
 Run `npm install csv` to install the full csv module or run `npm install csv-generate` if you are only interested by the CSV generator.
 
-Use the callback style API for simplicity or the stream based API for scalability.
+Use the callback and sync APIs for simplicity or the stream based API for scalability.
+
+## Example
+
+The [API](https://csv.js.org/generate/api/) is available in multiple flavors. This example illustrates the stream API.
+
+```js
+import { generate } from 'csv-generate';
+import assert from 'assert';
+
+const records = [];
+// Initialize the generator
+generate({
+  seed: 1,
+  objectMode: true,
+  columns: 2,
+  length: 2
+})
+// Use the readable stream api to consume generated records
+  .on('readable', function(){
+    let record; while((record = this.read()) !== null){
+      records.push(record);
+    }
+  })
+// Catch any error
+  .on('error', function(err){
+    console.error(err);
+  })
+// Test that the generated records matched the expected records
+  .on('end', function(){
+    assert.deepEqual(records, [
+      [ 'OMH', 'ONKCHhJmjadoA' ],
+      [ 'D', 'GeACHiN' ]
+    ]);
+  });
+```
 
 ## Development
 

diff --git a/packages/csv-parse/README.md b/packages/csv-parse/README.md
@@ -1,5 +1,5 @@
 
-# CSV Parser for Node.js
+# CSV parser for Node.js and the web - `csv-parse` package
 
 [![Build Status](https://img.shields.io/github/workflow/status/adaltas/node-csv/Node.js)](https://github.com/adaltas/node-csv/actions)
 [![NPM](https://img.shields.io/npm/dm/csv-parse)](https://www.npmjs.com/package/csv-parse)
@@ -9,25 +9,74 @@ Part of the [CSV module](https://csv.js.org/), this project is a parser converti
 
 ## Documentation
 
-* [Project homepage](http://csv.js.org/parse/)
-* [API](http://csv.js.org/parse/api/)
-* [Options](http://csv.js.org/parse/options/)
-* [Info properties](http://csv.js.org/parse/info/)
-* [Common errors](http://csv.js.org/parse/errors/)
-* [Examples](http://csv.js.org/project/examples/)
+* [Project homepage](https://csv.js.org/parse/)
+* [API](https://csv.js.org/parse/api/)
+* [Options](https://csv.js.org/parse/options/)
+* [Info properties](https://csv.js.org/parse/info/)
+* [Common errors](https://csv.js.org/parse/errors/)
+* [Examples](https://csv.js.org/project/examples/)
 
-## Features
+## Main features
 
+*   Flexible with lot of [options](https://csv.js.org/parse/options/)
+*   Multiple [distributions](https://csv.js.org/parse/distributions/): Node.js, Web, ECMAScript modules and CommonJS
 *   Follow the Node.js streaming API
 *   Simplicity with the optional callback API
 *   Support delimiters, quotes, escape characters and comments
 *   Line breaks discovery
 *   Support big datasets
-*   Complete test coverage and samples for inspiration
+*   Complete test coverage and lot of samples for inspiration
 *   No external dependencies
 *   Work nicely with the [csv-generate](https://csv.js.org/generate/), [stream-transform](https://csv.js.org/transform/) and [csv-stringify](https://csv.js.org/stringify/) packages
 *   MIT License
 
+## Usage
+
+Run `npm install csv` to install the full csv module or run `npm install csv-parse` if you are only interested by the CSV parser.
+
+Use the callback and sync APIs for simplicity or the stream based API for scalability.
+
+## Example
+
+The [API](https://csv.js.org/parse/api/) is available in multiple flavors. This example illustrates the stream API.
+
+```js
+import assert from 'assert';
+import { parse } from 'csv-parse';
+
+const records = [];
+// Initialize the parser
+const parser = parse({
+  delimiter: ':'
+});
+// Use the readable stream api to consume records
+parser.on('readable', function(){
+  let record;
+  while ((record = parser.read()) !== null) {
+    records.push(record);
+  }
+});
+// Catch any error
+parser.on('error', function(err){
+  console.error(err.message);
+});
+// Test that the parsed records matched the expected records
+parser.on('end', function(){
+  assert.deepStrictEqual(
+    records,
+    [
+      [ 'root','x','0','0','root','/root','/bin/bash' ],
+      [ 'someone','x','1022','1022','','/home/someone','/bin/bash' ]
+    ]
+  );
+});
+// Write data to the stream
+parser.write("root:x:0:0:root:/root:/bin/bash\n");
+parser.write("someone:x:1022:1022::/home/someone:/bin/bash\n");
+// Close the readable stream
+parser.end();
+```
+
 ## Contributors
 
 The project is sponsored by [Adaltas](https://www.adaltas.com), an Big Data consulting firm based in Paris, France.

diff --git a/packages/csv-stringify/README.md b/packages/csv-stringify/README.md
@@ -1,4 +1,6 @@
 
+# CSV stringifier for Node.js and the web - `csv-stringify` package
+
 [![Build Status](https://img.shields.io/github/workflow/status/adaltas/node-csv/Node.js)](https://github.com/adaltas/node-csv/actions)
 [![NPM](https://img.shields.io/npm/dm/csv-stringify)](https://www.npmjs.com/package/csv-stringify)
 [![NPM](https://img.shields.io/npm/v/csv-stringify)](https://www.npmjs.com/package/csv-stringify)
@@ -12,10 +14,10 @@ data sets by a large community.
 
 ## Documentation
 
-* [Project homepage](http://csv.js.org/stringify/)
-* [API](http://csv.js.org/stringify/api/)
-* [Options](http://csv.js.org/stringify/options/)
-* [Examples](http://csv.js.org/stringify/examples/)
+* [Project homepage](https://csv.js.org/stringify/)
+* [API](https://csv.js.org/stringify/api/)
+* [Options](https://csv.js.org/stringify/options/)
+* [Examples](https://csv.js.org/stringify/examples/)
 
 ## Main features
 
@@ -30,22 +32,24 @@ data sets by a large community.
 
 ## Usage
 
-The module is built on the Node.js Stream API. For the sake of simplicity, a
-simple callback API is also provided. To give you a quick look, here's an
-example of the callback API:
-
-```javascript
-const stringify = require('csv-stringify')
-const assert = require('assert')
-// import stringify from 'csv-stringify'
-// import assert from 'assert/strict'
-
-const input = [ [ '1', '2', '3', '4' ], [ 'a', 'b', 'c', 'd' ] ]
-stringify(input, function(err, output) {
-  const expected = '1,2,3,4\na,b,c,d\n'
-  assert.strictEqual(output, expected, `output.should.eql ${expected}`)
-  console.log("Passed.", output)
-})
+Run `npm install csv` to install the full csv module or run `npm install csv-stringify` if you are only interested by the CSV stringifier.
+
+The module is built on the Node.js Stream API. Use the callback and sync APIs for simplicity or the stream based API for scalability.
+
+## Example
+
+The [API](https://csv.js.org/stringify/api/) is available in multiple flavors. This example illustrates the sync API.
+
+```js
+import { stringify } from 'csv-stringify/sync';
+import assert from 'assert';
+
+const output = stringify([
+  [ '1', '2', '3', '4' ],
+  [ 'a', 'b', 'c', 'd' ]
+]);
+
+assert.equal(output, '1,2,3,4\na,b,c,d\n');
 ```
 
 ## Development
@@ -71,5 +75,5 @@ The project is sponsored by [Adaltas](https://www.adaltas.com), an Big Data cons
 
 [csv_home]: https://github.com/adaltas/node-csv
 [stream_transform]: http://nodejs.org/api/stream.html#stream_class_stream_transform
-[examples]: http://csv.js.org/stringify/examples/
+[examples]: https://csv.js.org/stringify/examples/
 [csv]: https://github.com/adaltas/node-csv
diff --git a/packages/csv/README.md b/packages/csv/README.md
@@ -1,13 +1,8 @@
 
-<pre>
-     _   _           _        _____  _______      __
-    | \ | |         | |      / ____|/ ____\ \    / /
-    |  \| | ___   __| | ___ | |    | (___  \ \  / /
-    | . ` |/ _ \ / _` |/ _ \| |     \___ \  \ \/ /
-    | |\  | (_) | (_| |  __/| |____ ____) |  \  /
-    |_| \_|\___/ \__,_|\___| \_____|_____/    \/     MIT License
+# CSV for Node.js and the web - `csv` package
 
-</pre>
+[![Build Status](https://img.shields.io/github/workflow/status/adaltas/node-csv/Node.js)](https://github.com/adaltas/node-csv/actions)
+[![NPM](https://img.shields.io/npm/dm/csv)](https://www.npmjs.com/package/csv) [![NPM](https://img.shields.io/npm/v/csv)](https://www.npmjs.com/package/csv)
 
 This project provides CSV generation, parsing, transformation and serialization
 for Node.js.
@@ -16,23 +11,24 @@ It has been tested and used by a large community over the years and should be
 considered reliable. It provides every option you would expect from an advanced
 CSV parser and stringifier.
 
-[![Build Status](https://img.shields.io/github/workflow/status/adaltas/node-csv/Node.js)](https://github.com/adaltas/node-csv/actions)
-[![NPM](https://img.shields.io/npm/dm/csv)](https://www.npmjs.com/package/csv) [![NPM](https://img.shields.io/npm/v/csv)](https://www.npmjs.com/package/csv)
-
-The `csv` package is itself split into 4 packages:
-
-*   [`csv-generate`](https://csv.js.org/generate/),
-    a flexible generator of CSV string and Javascript objects. 
-    [![Build Status](https://secure.travis-ci.org/adaltas/node-csv-generate.svg?branch=master)][travis-csv-generate]
-*   [`csv-parse`](https://csv.js.org/parse/),
-    a parser converting CSV text into arrays or objects. 
-    [![Build Status](https://secure.travis-ci.org/adaltas/node-csv-parse.svg?branch=master)][travis-csv-parse]
-*   [`stream-transform`](https://csv.js.org/transform/),
-    a transformation framework.
-    [![Build Status](https://secure.travis-ci.org/adaltas/node-stream-transform.svg?branch=master)][travis-stream-transform]
-*   [`csv-stringify`](https://csv.js.org/stringify/), 
-    a stringifier converting records into a CSV text. 
-    [![Build Status](https://secure.travis-ci.org/adaltas/node-csv-stringify.svg?branch=master)][travis-csv-stringify]
+The `csv` package exposes 4 packages:
+
+*   [`csv-generate`](https://csv.js.org/generate/)   
+    A flexible generator of CSV string and Javascript objects.   
+    [![NPM](https://img.shields.io/npm/dm/csv-generate)](https://www.npmjs.com/package/csv-generate) 
+    [![NPM](https://img.shields.io/npm/v/csv-generate)](https://www.npmjs.com/package/csv-generate)
+*   [`csv-parse`](https://csv.js.org/parse/)   
+    A parser converting CSV text into arrays or objects.   
+    [![NPM](https://img.shields.io/npm/dm/csv-parse)](https://www.npmjs.com/package/csv-parse)
+    [![NPM](https://img.shields.io/npm/v/csv-parse)](https://www.npmjs.com/package/csv-parse)
+*   [`stream-transform`](https://csv.js.org/transform/)   
+    A transformation framework.   
+    [![NPM](https://img.shields.io/npm/dm/stream-transform)](https://www.npmjs.com/package/stream-transform) 
+    [![NPM](https://img.shields.io/npm/v/stream-transform)](https://www.npmjs.com/package/stream-transform)
+*   [`csv-stringify`](https://csv.js.org/stringify/)   
+    A stringifier converting records into a CSV text.   
+    [![NPM](https://img.shields.io/npm/dm/csv-stringify)](https://www.npmjs.com/package/csv-stringify)
+    [![NPM](https://img.shields.io/npm/v/csv-stringify)](https://www.npmjs.com/package/csv-stringify)
 
 ## Documentation
 
@@ -45,6 +41,39 @@ Installation command is `npm install csv`.
 Each package is fully compatible with the stream 2 and 3 specifications.
 Also, a simple callback-based API is always provided for convenience.
 
+## Sample
+
+This example uses the Stream API to create a processing pipeline.
+
+```js
+// Import the package
+import * as csv from '../lib/index.js';
+
+// Run the pipeline
+csv
+// Generate 20 records
+  .generate({
+    delimiter: '|',
+    length: 20
+  })
+// Transform CSV data into records
+  .pipe(csv.parse({
+    delimiter: '|'
+  }))
+// Transform each value into uppercase
+  .pipe(csv.transform((record) => {
+    return record.map((value) => {
+      return value.toUpperCase();
+    });
+  }))
+// Convert objects into a stream
+  .pipe(csv.stringify({
+    quoted: true
+  }))
+// Print the CSV stream to stdout
+  .pipe(process.stdout);
+```
+
 ## Development
 
 This parent project doesn't have tests itself but instead delegates the