Add an example for `CSVTransformer` interaction with `CSVNormalizer`

diff --git a/examples/README.md b/examples/README.md
index 0a1a0becae26eb6358da4910881ffcaa17e8c171..a78fd6f92d29f49d61c29c4ecd465fe121c99a93 100644 (file)
--- 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 (file)
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,,,\r
+a1,b1,c1,s1,,,e,e,e,,,\r
+a2,b2,c2,,s2,,e,e,e,,,\r
+a3,b3,c3,,,s3,e,e,e,,,\r
+,,,,,,,,,,,\r
+,,,,,,,,,,,\r
+,,,,,,,,,,,\r

diff --git a/examples/data/ex4_2-out.csv b/examples/data/ex4_2-out.csv
new file mode 100644 (file)
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\r
+A1,B1,C1,S1,,,4\r
+A2,B2,C2,,S2,,4\r
+A3,B3,C3,,,S3,4\r

diff --git a/examples/ex4_2.js b/examples/ex4_2.js
new file mode 100644 (file)
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