From: Ardis Lu Date: Sun, 13 Jul 2025 04:47:52 +0000 (-0700) Subject: Add initial documentation for `CSVNormalizer` X-Git-Tag: v0.1.4~5 X-Git-Url: https://git.ardis.lu/?a=commitdiff_plain;h=e03ad7c291b6f0ddd3b0917ff3d48084c62e9947;p=csvio Add initial documentation for `CSVNormalizer` --- diff --git a/README.md b/README.md index dd4f674..bbe4878 100644 --- a/README.md +++ b/README.md @@ -158,9 +158,14 @@ In addition to the core API, optional utilities are provided to address common C ### `CSVNormalizer` and `CSVDenormalizer` -`CSVNormalizer` is a `TransformStream` that attempts to fix CSVs that have been mangled by spreadsheet programs such as Excel. - -`CSVDenormalizer` is a `TransformStream` that will convert objects normalized by `CSVNormalizer` back into a plain array. +`CSVNormalizer` is a `TransformStream` that applies opinionated transformations to correct data mangling caused by spreadsheet programs and manual user manipulation: +- **Remove empty or extra data**: Spreadsheet programs may append empty rows or columns at the ends of a CSV file, or users may insert empty rows or columns for formatting purposes. These empty rows are removed. Additionally, columns which are not explicitly listed in the `CSVNormalizerHeader` array are also removed. +- **Fix date and number mangling**: Spreadsheet programs may [automatically cast data types in unexpected ways](https://www.theverge.com/2020/8/6/21355674/human-genes-rename-microsoft-excel-misreading-dates). `CSVNormalizer` will perform various transformations to reverse data type casting that was unlikely to be intentional. +- **Flexible column naming**: Column names are normalized to camelCase to prevent issues with subtly inconsistent names (e.g., `Column A`, `column A`, and `ColumnA` are all considered to be the same name). +- **Column ordering**: Columns may appear in any order on the input CSV. The columns in the output are re-ordered to match the order in the `CSVNormalizerHeader` array. +- **Stream of objects**: The stream is transformed from an `Array` to an `Array` to provide a better developer experience for subsequent transformations. + +`CSVDenormalizer` is a `TransformStream` that will convert an `Array` created by `CSVNormalizer` back into an `Array`, ready for writing to a file. ```javascript import { CSVNormalizer, CSVDenormalizer } from './src/index.js';