Add example of processing `.csv.gz` files

Delete unnecessary utility function

Add caching for dependencies

Clean up unused variables

Add git.ardis.lu mirror

Pin Node.js and npm versions in `devEngines`

`devEngines` is the standardized field for this purpose [0], with varying levels of tooling support. The duplicative and non-standard `.node-version` file will eventually be removed once tooling support for `devEngines` is more widespread.

[0] https://github.com/openjs-foundation/package-metadata-interoperability-collab-space

Broaden `value` type to `any`

Add note on long release notes

Add example for `stdin` and `stdout` usage

Rename `CSVNormalizerRow` to `CSVNormalizerField`

This type is not a row of data, it is a single field. So the name "row" never made sense.

Remove platform-specific data from test gzip file

This step is not required for real-world usage, but for testing purposes it is useful to share the same tests and test data across platforms.

Cut v0.1.5

Add `types:check` script mentioned in `CONTRIBUTING.md`

Upgrade dependencies

Add test case for raw strings passed to `TransformStream` CSVWriter

Add initial `TransformStream` CSVWriter implementation

This change enables users to create a `TransformStream` by doing `new CSVWriter()` instead of always creating an ultimate sink `WritableStream`. This behavior is useful when there is some transformation that must be performed on the CSV data before writing (e.g., compressing into a `.csv.gz` file using `CompressionStream`).

Delete unused import

Loosen `CSVNormalizerRow` type to match `CSVDenormalizer` usage

Add contribution checklist

Fix bug where it was not possible to read into an ArrayBuffer with offset

The code was originally correct because it was copied from the Streams specification [1], but turned incorrect after copying from Node.js's implementation [2], and now reverted back to the original correct implementation.

[1] https://streams.spec.whatwg.org/#example-rbs-pull
[2] https://github.com/nodejs/node/blob/134625d76139b4b3630d5baaf2efccae01ede564/lib/internal/fs/promises.js#L322

Delete unnecessary negative test

The row length check in `csvStreamEqualWritable` now covers the original testing edge case that necessitated the negative test. Now the test will correctly fail without requiring the negative test to trigger the failure.

Fix broken test

Fix `createProxy` type templates

Remove intermediate JSON serialization and `rawInput`/`rawOutput` options

Previously, each row was JSON serialized and deserialized on each `.pipeThrough`. The intent of this serialization was to normalize the data of each row, with an escape hatch in the `rawInput` and `rawOutput` options.

However, this approach is counterintuitive because most users would expect a CSV row to simply be an `Array<string>`, NOT a `string` that can be `JSON.parse`-ed into an `Array<string>`. Furthermore, this excessive serialization has a significant performance impact. Lastly, the `rawInput` and `rawOutput` options effectively made `CSVTransformer` an overly complex and difficult-to-use JSON parser on top of a CSV transformer.

So, simply removing the JSON serialization and directly enqueuing the actual object (i.e., the `Array<string>`) resolves all these issues with minimal impact to the user-facing API.

Fix words

Add npm script to create local dev packages

Add initial `TransformStream` CSVReader implementation

This change enables users to create a `TransformStream` by doing `new CSVReader()` instead of always creating an underlying source `ReadableStream`. This behavior is useful when there is some transformation that must be performed on the source file before parsing (e.g., decompressing a `.csv.gz` file using `DecompressionStream`).

Add tests for `instanceof` behavior

In preparation for possible future refactoring for these classes to return a `Proxy` object (this pattern is required to simulate dynamic superclasses, e.g., `CSVReader` returning either `ReadableStream` OR `TransformStream` depending on constructor argument). If such refactoring takes place, these tests will check that `Proxy` was implemented correctly and maintain backwards compatibility.

Add initial tests for memory leaks

Future tests should be dedicated for finding memory leaks only, but as an initial step it makes sense to add a simple sanity check to the large file tests.

Cut v0.1.4

Upgrade dependencies

Delete redundant BOM check

`TextDecoderStream` already handles it upstream, no need to check for it again.

Simplify implementation

Use consistent JSDoc typecasting formatting

Add initial documentation for `CSVNormalizer`

Re-export callback types

These types were initially missed because they are defined with the `callback` annotation and not `typedef`. For future completeness, search for `export type` in the generated declaration files.

Add `useLiteralNames` option to disable column name normalization

This behavior is useful to preserve data when an input CSV has multiple columns with the same normalized name. By default, `CSVNormalizer` will remove these duplicate columns (the data from the last column is used).

Note that columns with the same *literal* name are still removed even when `useLiteralNames` is `true`. If you need to preserve columns with the same literal name, use a lower-level transformation (e.g., `CSVTransformer`).

Add explicit test for `passthroughEmptyRows`

Re-export all types in `index.js`

Currently, the types are accessible internally in the library and within `index.js`, but NOT accessible from consumers importing from the `index.js` file. A re-export is required to make the types accessible to end-users.

Additionally, the JSDoc import will only work for types declared at the module scope, so `CSVWriterStatus` was moved to the outer scope.

Cut v0.1.3

Upgrade dependencies

Fix bug where `defaultValue` was not set if row is uneven

Add explicit test for sparse CSV

Delete debugging flag

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

Simplify type annotation

Ignore `handleHeaders` if the row has been normalized

This behavior is desirable when `CSVTransformer` interacts with `CSVNormalizer` or any other transformation which converts the row from `Array<string>` into `Array<Object>`, because it avoids the need to pass `handleHeaders: true` to `CSVTransformer` (which is counterintuitive). It is more accurate to say the header row has been deleted by the transformation and must by re-inserted into the write stream later.

The loosening of the type checking is not a breaking change. Since the row is passed directly to `JSON.parse()`, the fields could have always been type `Object` instead of `string`.

Fall back on `name` if `displayName` is undefined

This behavior is useful when passing rows to `CSVDenormalizer` after a transformation *other* than `CSVNormalizer` (which automatically creates `displayName`).

Set default normalization type to `'string'`

This behavior is helpful to perform minimal normalization tasks but otherwise preserve the default CSV transformation behavior (i.e., have all input values be a string).

This is not a breaking change. Previously, `type` would also default to `'string'` after logging a warning in console.

Fix bug where extra normalization headers were not dropped

This bug was not caught due to a separate bug in the test logic, which is also fixed in this commit.

Add explicit test to remove extra headers

Sort keys to match default order in 5.9

Reference: https://devblogs.microsoft.com/typescript/announcing-typescript-5-9-beta/

Delete unnecessary constructor annotation

This tag has no impact on the generated `.d.ts` file so it can be removed.

Cut v0.1.2

Upgrade dependencies

Support ArrayLike outputs

Could be useful for chained transformations using DOM APIs, e.g. passing through the NodeList object.

Improve internal type documentation

Increase `highWaterMark` for `CSVWriter`'s queuing strategy

This change improves the 100MB Write benchmark from ~9s to ~7s.

Bumping `highWaterMark` to >1 also changes the stream's interaction with `AbortController`, so now the chunk processed during an abort is included in the write.

I believe this behavior has to do with the task queue order of the callback for the `AbortSignal`'s `abort` event - so now with multiple chunks in the queue, the last chunk is written before the `abort` event is processed. I was unable to force this writing code to occur after the `abort` event in a deterministic way.

This situation is a rare edge case so letting it through.

Simplify and harden tick indicator

Relying on physical timing is flaky (e.g., it will fail if executing on a slow machine).  Sending a simple `tick` increment into the task queue is more reliable.

Tweak wording

Add test to remove empty columns

Handle whitespace strings

Support path of type `SharedArrayBuffer`

Increase default chunk size from 1 KiB to 64 KiB

Benchmarks showed improvements or no change across all tests. Notably, 100MB Read improved from ~13s to ~3s.

The magic value of 64 KiB was selected based on Node.js's default of 16 KiB in similar code [1] and manually testing some multiples over that (Node.js tends to be conservative).

[1] https://github.com/nodejs/node/blob/f69f90d97a30cf9a5f7cbe0260e487ae4d457ed5/lib/internal/fs/promises.js#L317

Remove `scripts` and `devDependencies` from packed `package.json`

These keys are used for development purposes only, so it is wasting bandwidth to ship them with the final package.

Move prepack script to a JS file

To facilitate future more complex transformations that would be easier to manage in a code file.

Use consistent casing

Upgrade dependencies

Add code repository mirrors

Clarify type to allow raw `ArrayBuffer`, not just `TypedArray`

Upgrade dependencies

Simplify release notes to be auto generated

Reasons in favor of minimal release notes: (1) Releases is a GitHub functionality, it's better not to invest too much time into vendor-specific configurations. (2) There is no binary associated with this library so Releases has reduced significance. (3) Meaningful release notes are still contained in git tag annotations, which can be carried across hosts.

One downside is losing meaningful messages in email notifications if people subscribe to follow releases on GitHub.

Cut v0.1.1

Release and publish on new version tags

Add keywords

Update for new scoped package name

Publish as scoped package

Add prepack script

Upgrade dependencies

Normalize repository value

Even though the shorthand is valid,  `npm publish` will show a warning every time about running `npm pkg fix` unless it is normalized.

Use `outDir` instead of `outFile`

`outFile` is not compatible with ES6 modules.

Tweak types

Upgrade dependencies

Strictly count the number of batches

Update `maxBatchSize` behavior to match type documentation

**Any** value should start batching, instead of any value > 1.

Add overloads for raw and batch transformation variants based on options provided to the constructor

If `rawInput` is `true`, then `TransformationFunctionRaw` is required.

If `maxBatchSize` is set to any number (including `1`), then `TransformationFunctionBatch` is required.

Otherwise, `TransformationFunction` is required.

This change resolves all remaining type problems in `core.test.js`.

Refactor `DECIMAL_SEPARATOR` to a function

This change enables easier testing and also allows future improvements for dynamically changing the locale during runtime.

Refine types

Refactor to pass options through to private fields

This change makes the code consistent with previous refactoring on the core code, and also prevents unexpected behavior from mutating the options object after instantiation.

Fix docs

The retry is not necessarily immediate if `interval` is specified in options.

Refine types

Explicitly import `ReadableStream` to make TS understand `ReadableStream.from`

This change does not affect the code execution, but it makes the TS language server understand the `ReadableStream.from` static function. Without the explicit import, it is not possible using only JSDoc to merge the `ReadableStream` instance interface with the `ReadableStream` constructor because they share the same name.

Pin node types

Refactor `expandScientificNotation` to throw errors instead of using sentinel `null` value

Migrate from CLI options to explicit `tsconfig.json`

This change makes it easier to use an explicit `lib` configuration and types, which resolves type issues resulting from subtle mismatches between implied type imports (e.g., some files importing `ReadableStream` from TS's built-in Web API types and others importing from Node.js's `streams/web`).

Fix typechecking for `parsePathLike`

`PathLike` only includes Node.js's `Buffer` type, need to explicitly add the web API `TypedArray` (e.g., `Uint8Array`).

Bump Node.js version for dev

Check in package-lock

Explicitly assert that `byobRequest` and `view` are not null

Add TypeScript declaration file (`.d.ts`) generation

This is the cleanest way to make a JS library importable to a TS project. This approach is similar to Svelte's approach.

Note the dev dependency on TS is only used for `.d.ts` generation. The source code itself still does not use TS (or any dependencies other than Node.js) at all.