From b2646ba910e0edf52a0d877cced37fc9ff70b8fd Mon Sep 17 00:00:00 2001
From: Ardis Lu <ardisglu@gmail.com>
Date: Wed, 9 Jul 2025 22:35:32 -0700
Subject: [PATCH] Add an example for `CSVTransformer` interaction with
 `CSVNormalizer`

---
 examples/README.md          |  2 ++
 examples/data/ex4_2-in.csv  |  7 +++++++
 examples/data/ex4_2-out.csv |  4 ++++
 examples/ex4_2.js           | 36 ++++++++++++++++++++++++++++++++++++
 4 files changed, 49 insertions(+)
 create mode 100644 examples/data/ex4_2-in.csv
 create mode 100644 examples/data/ex4_2-out.csv
 create mode 100644 examples/ex4_2.js

diff --git a/examples/README.md b/examples/README.md
index 0a1a0be..a78fd6f 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -51,3 +51,5 @@ These examples demonstrate using the `maxBatchSize` and `maxConcurrent` options
 These examples demonstrate the extended API.
 
 [Example 4.1: Using `CSVNormalizer` and `CSVDenormalizer`](./ex4_1.js) ([input](./data/ex4_1-in.csv), [output](./data/ex4_1-out.csv))
+
+[Example 4.2: Using `CSVNormalizer` and `CSVDenormalizer` with `CSVTransformer`](./ex4_2.js) ([input](./data/ex4_2-in.csv), [output](./data/ex4_2-out.csv))
diff --git a/examples/data/ex4_2-in.csv b/examples/data/ex4_2-in.csv
new file mode 100644
index 0000000..a19d662
--- /dev/null
+++ b/examples/data/ex4_2-in.csv
@@ -0,0 +1,7 @@
+columnA,columnB,columnC,sparse1,sparse2,sparse3,extra1,extra2,extra3,,,
+a1,b1,c1,s1,,,e,e,e,,,
+a2,b2,c2,,s2,,e,e,e,,,
+a3,b3,c3,,,s3,e,e,e,,,
+,,,,,,,,,,,
+,,,,,,,,,,,
+,,,,,,,,,,,
diff --git a/examples/data/ex4_2-out.csv b/examples/data/ex4_2-out.csv
new file mode 100644
index 0000000..4e1dfbf
--- /dev/null
+++ b/examples/data/ex4_2-out.csv
@@ -0,0 +1,4 @@
+columnA_new,columnB_new,columnC_new,sparse1_new,sparse2_new,sparse3_new,count
+A1,B1,C1,S1,,,4
+A2,B2,C2,,S2,,4
+A3,B3,C3,,,S3,4
diff --git a/examples/ex4_2.js b/examples/ex4_2.js
new file mode 100644
index 0000000..cfbe256
--- /dev/null
+++ b/examples/ex4_2.js
@@ -0,0 +1,36 @@
+// ## Example 4.2: Using `CSVNormalizer` and `CSVDenormalizer` with `CSVTransformer`
+// 
+// Sometimes it is easier to work with an array of objects than an array of strings in a transformation function.
+// `CSVNormalizer` is useful for preparing CSV row data into such an array of objects, in addition to handling
+// common CSV mangling by spreadsheet programs.
+
+import { CSVReader, CSVWriter, CSVNormalizer, CSVDenormalizer, CSVTransformer } from '../src/index.js';
+/** @import { CSVNormalizerHeader } from '../src/normalization.js'; */
+
+// A minimal declaration to tell `CSVNormalizer` to trim empty rows and columns but otherwise don't touch the data
+/** @type { Array<CSVNormalizerHeader> } */
+const headers = [
+  { name: 'columnA' },
+  { name: 'columnB' },
+  { name: 'columnC' },
+  { name: 'sparse1' },
+  { name: 'sparse2' },
+  { name: 'sparse3' }
+];
+
+function transform(row) {
+  let c = 0
+  for (const field of row) {
+    field.displayName = `${field.displayName}_new`; // To modify column names
+    field.value = field.value.toUpperCase(); // To modify field values
+    if (!field.emptyField) { c++; } // The `emptyField` property is useful for managing sparse or uneven CSV data
+  }
+  row.push({ name: 'count', value: c }); // You can also insert new columns in a transformation
+  return row;
+}
+
+await new CSVReader(new URL('./data/ex4_2-in.csv', import.meta.url))
+  .pipeThrough(new CSVNormalizer(headers))
+  .pipeThrough(new CSVTransformer(transform))
+  .pipeThrough(new CSVDenormalizer())
+  .pipeTo(new CSVWriter(new URL('./data/ex4_2-out.csv', import.meta.url)));
\ No newline at end of file
-- 
2.47.3