docs: comment stream samples

Author: wdavidw

packages/csv-generate/samples/api.stream.js

@@ -3,21 +3,25 @@ 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()){
     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' ],

packages/csv-parse/samples/api.stream.js

@@ -3,11 +3,11 @@ import assert from 'assert';
 import { parse } from 'csv-parse';
 
 const records = [];
-// Create the parser
+// Initialize the parser
 const parser = parse({
   delimiter: ':'
 });
-// Use the readable stream api
+// Use the readable stream api to consume records
 parser.on('readable', function(){
   let record;
   while ((record = parser.read()) !== null) {
@@ -18,7 +18,7 @@ parser.on('readable', function(){
 parser.on('error', function(err){
   console.error(err.message);
 });
-// When we are done, test that the parsed records matched what expected
+// Test that the parsed records matched the expected records
 parser.on('end', function(){
   assert.deepStrictEqual(
     records,

packages/csv-stringify/samples/api.stream.js

@@ -3,25 +3,31 @@ import { stringify } from 'csv-stringify';
 import assert from 'assert';
 
 const data = [];
+// Initialize the stringifier
 const stringifier = stringify({
   delimiter: ':'
 });
+// Use the readable stream api to consume CSV data
 stringifier.on('readable', function(){
   let row;
   while((row = stringifier.read()) !== null){
     data.push(row);
   }
 });
+// Catch any error
 stringifier.on('error', function(err){
   console.error(err.message);
 });
+// When finished, validate the CSV output with the expected value
 stringifier.on('finish', function(){
   assert.equal(
     data.join(''),
     "root:x:0:0:root:/root:/bin/bash\n" +
     "someone:x:1022:1022::/home/someone:/bin/bash\n"
   );
 });
+// Write records to the stream
 stringifier.write([ 'root','x','0','0','root','/root','/bin/bash' ]);
 stringifier.write([ 'someone','x','1022','1022','','/home/someone','/bin/bash' ]);
+// Close the writable stream
 stringifier.end();

packages/csv/samples/stream.js

@@ -11,38 +11,46 @@ const transformer = csv.transform(function(data){
 });
 const stringifier = csv.stringify();
 
+// Read generated CSV data and send it to the parser
 generator.on('readable', function(){
   let data; while(data = generator.read()){
     parser.write(data);
   }
 });
+// When generation is over, close the parser
 generator.on('end', function(){
   parser.end()
 });
 
+// Read parsed records and send them to the transformer
 parser.on('readable', function(){
   let data; while(data = parser.read()){
     transformer.write(data);
   }
 });
+// When parsing is over, close the transformer
 parser.on('end', function(){
   transformer.end()
 });
 
+// Read transformed records and send them to the stringifier
 transformer.on('readable', function(){
   let data; while(data = transformer.read()){
     stringifier.write(data);
   }
 });
+// When transformation is over, close the stringifier
 transformer.on('end', function(){
   stringifier.end();
 });
 
+// Read CSV data and print it to stdout
 stringifier.on('readable', function(){
   let data; while(data = stringifier.read()){
     process.stdout.write(data);
   }
 });
+// When stringifying is over, print a summary to stderr
 generator.on('end', function(){
-  process.stdout.write('=> ' + i + ' records\n');
+  process.stderr.write('=> ' + i + ' records\n');
 });

packages/stream-transform/samples/api.stream.js

@@ -3,24 +3,30 @@ import { transform } from 'stream-transform';
 import assert from 'assert';
 
 const output = [];
+// Initialize the transformer
 const transformer = transform(function(data){
   data.push(data.shift());
   return data;
 });
+// Use the readable stream api to consume transformed records
 transformer.on('readable', function(){
   let row; while((row = transformer.read()) !== null){
     output.push(row);
   }
 });
+// Catch any error
 transformer.on('error', function(err){
   console.error(err.message);
 });
+// When finished, validate the records with the expected value
 transformer.on('finish', function(){
   assert.deepEqual(output, [
     [ '2', '3', '4', '1' ],
     [ 'b', 'c', 'd', 'a' ]
   ]);
 });
+// Write records to the stream
 transformer.write(['1','2','3','4']);
 transformer.write(['a','b','c','d']);
+// Close the writable stream
 transformer.end();