From 0755bb98adb05a81a36aace4eb1f52ff7f9ea512 Mon Sep 17 00:00:00 2001
From: Ardis Lu <ardisglu@gmail.com>
Date: Thu, 23 Jan 2025 20:23:21 -0800
Subject: [PATCH] Clarify handleHeaders intended usage

Setting it to an Array<any> is preferred for simple scenarios.
---
 examples/README.md          |  2 +-
 examples/data/ex1_2-out.csv |  2 +-
 examples/ex1_2.js           | 14 ++++----------
 examples/ex1_3.js           |  3 +++
 examples/ex3_2.js           |  7 +------
 5 files changed, 10 insertions(+), 18 deletions(-)

diff --git a/examples/README.md b/examples/README.md
index 6386a4c..dc9abea 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -16,7 +16,7 @@ These examples demonstrate the most common, expected usage.
 
 [Example 1.1: Basic usage](./ex1_1.js)
 
-[Example 1.2: Updating headers in the output](./ex1_2.js)
+[Example 1.2: Replace headers in the output](./ex1_2.js)
 
 [Example 1.3: Chaining multiple transformations](./ex1_3.js)
 
diff --git a/examples/data/ex1_2-out.csv b/examples/data/ex1_2-out.csv
index 69e4d65..61b0374 100644
--- a/examples/data/ex1_2-out.csv
+++ b/examples/data/ex1_2-out.csv
@@ -1,4 +1,4 @@
-columnA,columnB,sum
+Column A,Column B,Sum
 1,1,2
 100,100,200
 223423,455947,679370
diff --git a/examples/ex1_2.js b/examples/ex1_2.js
index cf8a892..68ac864 100644
--- a/examples/ex1_2.js
+++ b/examples/ex1_2.js
@@ -1,23 +1,17 @@
-// ## Example 1.2: Updating headers in the output
+// ## Example 1.2: Replace headers in the output
 // 
-// Set `handleHeaders: true` to manually handle the header row (first row).
+// Set `handleHeaders` to an `Array<any>` to replace the header row (first row) in the output.
 // 
 // Notes:
 // - The header row is assumed to be the first row in the input CSV, and by default it goes directly to the output (skipping the user-provided transformation function).
-// - If your input CSV does not have a header row, set `handleHeaders: true` and process the header row (first row) normally.
-// - Otherwise, you will need distinct logic to handle the header row vs. data rows. A simple boolean variable is a good way to switch between this logic. 
+// - Setting `handleHeaders` to an array is the simplest way to rename headers, delete headers, or add new headers.
 
 import { CSVReader, CSVTransformer, CSVWriter } from '../src/index.js';
 
-let firstRow = true;
 function sum(row) {
-  if (firstRow) {
-    firstRow = false;
-    return [...row, 'sum'];
-  }
   return [...row, Number(row[0]) + Number(row[1])];
 }
 
 await new CSVReader(new URL('./data/ex1_2-in.csv', import.meta.url))
-  .pipeThrough(new CSVTransformer(sum, { handleHeaders: true }))
+  .pipeThrough(new CSVTransformer(sum, { handleHeaders: ['Column A', 'Column B', 'Sum'] }))
   .pipeTo(new CSVWriter(new URL('./data/ex1_2-out.csv', import.meta.url)));
\ No newline at end of file
diff --git a/examples/ex1_3.js b/examples/ex1_3.js
index 7fdc65b..c19486f 100644
--- a/examples/ex1_3.js
+++ b/examples/ex1_3.js
@@ -4,6 +4,9 @@
 // (`rawOutput`) when handling the transformation function input/output. These options are intended for advanced
 // transformations (e.g., transformations spread across multiple functions or lower-level transformations directly
 // on byte arrays).
+// 
+// Set `handleHeaders` to `true` to pass the header row to the transformation function as a normal row and manually
+// handle the header output processing. This setting is required if the input CSV does not have a header row.
 
 import { CSVReader, CSVTransformer, CSVWriter } from '../src/index.js';
 
diff --git a/examples/ex3_2.js b/examples/ex3_2.js
index caeadca..bf341b6 100644
--- a/examples/ex3_2.js
+++ b/examples/ex3_2.js
@@ -17,16 +17,11 @@ function tick() {
   return Math.floor(ms / 100);
 }
 
-let firstChunk = true;
 async function concurrent(row) {
-  if (firstChunk) {
-    firstChunk = false;
-    return ['tick number', ...row];
-  }
   await setTimeout(100); // Simulate some slow task, e.g. a network request
   return [tick(), ...row];
 }
 
 await new CSVReader(new URL('./data/ex3_2-in.csv', import.meta.url))
-  .pipeThrough(new CSVTransformer(concurrent, { handleHeaders: true, maxConcurrent: 5 }))
+  .pipeThrough(new CSVTransformer(concurrent, { handleHeaders: h => ['tick number', ...h], maxConcurrent: 5 }))
   .pipeTo(new CSVWriter(new URL('./data/ex3_2-out.csv', import.meta.url)));
\ No newline at end of file
-- 
2.47.3