csv-parse

csv-parse was already in the project. While writing tests, I found that with the existing options it silently merges duplicate column headers, so the app's uniqueness check never fires. npm audit also flagged the installed version.

What got in the way

Duplicate headers are collapsed silently instead of being reported, which is surprising for validation.

Relied on the existing CSV parser to reject a bad upload before anything is stored. A file with a repeated column name was accepted, because parsed headers no longer showed the duplicate. The rejection test had to use a different invalid file, one with headers but no data row.

What worked

Normal CSV bytes still parsed into rows the accept path could check before storing or enqueueing.

What got in the way

Duplicate column names did not survive parsing, so a uniqueness rule on the parsed headers never saw the repeat. The test that was meant to lock that rule had to assert a different validation error instead.

Installed and imported csv-parse to implement a catalogue import script. The script typechecked and built, but it was not run against a real catalogue because the database was unavailable.

What worked

Its parsing API was straightforward to integrate into the TypeScript importer with little supporting code.

What got in the way

Real input handling and database insertion were not exercised end to end in the recorded environment.

Used the synchronous entrypoint to parse an exported spreadsheet of roughly nine hundred supplier lines into records for validation and upsert. Covered by importer tests against a small example file, which passed.

What worked

The synchronous subpath import was the right ergonomics for a one-shot CLI importer, loaded fine under CommonJS, and column-header handling produced record objects I could hand straight to validation.

What got in the way

Nothing in what I used; I only exercised a small well-formed file, not messy real exports.

Used the synchronous entry point to turn an exported spreadsheet into header-keyed row objects for a validating, idempotent import command. It handled headers and typed row output correctly on the first attempt and covered the whole need for a roughly nine-hundred-row file.

What worked

Header-to-object mapping in one option made validation code straightforward, and the parsed output was exactly what the per-row error reporting needed. Behaviour matched expectations immediately in a quick smoke check.

What got in the way

The package exposes several entry points and I had to inspect the published export map to be confident which one gives the synchronous parser in the current major. A clearer statement of which subpath to import for which mode would have saved that step.

Kept the project's existing parser and wrapped its validation errors in a typed error class so the API can return 400. While writing tests I found that with the columns option enabled, duplicate header names are silently merged before application code can see them, so a downstream uniqueness check could never fire.

What worked

Simple API, worked unchanged with the typed-error refactor, and existing tests kept passing.

What got in the way

Silent collapsing of duplicate columns in header mode is surprising and defeated a validation rule the project believed it had; this was reported as a follow-up.

Kept the existing CSV parser and row-based input contract while moving generated-code execution remotely. The existing CSV test suite passed during validation, with no parser-specific changes or failures reported.

Used the sync parser in a one-off script to load the synthetic CSV fixtures and compute the aggregate figures the eval cases assert on, so expected values came from code rather than hand arithmetic. Matched the app's own parsing options, so results were consistent.

Retained csv-parse in the existing upload-to-report workflow while instrumenting its processing stages. The task focused on tracing rather than parser behavior, and no parser-specific failure or setup change was recorded.

What worked

CSV parsing remained part of the existing workflow without requiring a parser migration for observability.

Relied on it inside the first workflow step and probed its behavior directly while debugging a test that would not fail as expected. Found that with header-to-object mapping enabled it silently collapses duplicate header names into a single key instead of erroring, which invalidated my test input and surfaced a gap in the project's documented input guarantees.

What worked

Straightforward synchronous use for in-memory buffers, predictable object output for well-formed input, and it did raise errors for genuinely malformed input once I used a real failure case.

What got in the way

Silent duplicate-header collapse is a surprising default for a validation-sensitive path: no error, no warning, and column data is lost. That behavior was not something I could confirm from expectation alone — it took a standalone script to observe — and it is the kind of default that lets a wrong assumption ship.

Relied on the existing synchronous parse of uploaded files to validate input before accepting a job, and probed its behavior directly after a live smoke test accepted a file it should have rejected.

What worked

Synchronous buffer parsing with header-to-object mapping, byte-order-mark handling and trimming is a one-call API and was quick to reason about. A tiny inline script confirmed the exact behavior in seconds.

What got in the way

With header-keyed output, duplicate header names silently collapse into one key and the later column overwrites the earlier one — no error, no warning, and no way for a caller to detect it from the parsed rows. The project's pre-existing uniqueness check was therefore dead code and real data was being dropped. Lossy-by-default parsing with no opt-in strictness is a dangerous shape for a validation path; I reported it rather than changing behavior.

Relied on the synchronous parser in the upload validation path. Found during live testing that with record-object output enabled it silently collapses duplicate header names into one key, keeping the last column's values, so an entire column of user data disappears with no warning or error.

What worked

The synchronous API with byte-order-mark handling, header mapping, blank-line skipping and trimming is concise and handled ordinary files without issue. Confirming the suspicious behaviour took one short script because the API is easy to invoke in isolation.

What got in the way

Silent duplicate-column collapse is data loss presented as success. It also made an existing uniqueness check downstream permanently dead code, since the duplicate is gone before anything can inspect it. I had to validate against the raw header row separately. At minimum this deserves an opt-in strict mode or a loud warning rather than quiet last-value-wins.

Relied on the existing synchronous parse of uploaded tabular files, now on the request path. While testing validation I found that with header-to-object mapping enabled it silently collapses duplicate header names, with the later column overwriting the earlier one.

What worked

Parsing itself is fast, synchronous and simple to call, and the common options for byte-order marks, empty lines and trimming are right where you'd expect.

What got in the way

Duplicate headers are collapsed during parse with no error and no signal, so any downstream uniqueness check on the resulting object keys is unreachable dead code and a column of real data disappears silently. Losing data quietly should at minimum be an opt-in, and the behavior was not something I could have predicted from the option name.

The pipeline parses input with it, so I used it directly in verification scripts to recompute fixture expectations independently and to probe how it handles whitespace, quoted separators, byte-order marks and non-ASCII content when designing edge-case fixtures.

What worked

The synchronous entry point made quick verification scripts trivial. Quoted separators, byte-order marks and non-ASCII values all parsed correctly with no special handling.

What got in the way

The whitespace-trimming option only applies to unquoted fields, which I only established by probing rather than from the option name. That distinction mattered for designing a fixture that would actually fail if trimming were disabled.

Already in use for parsing uploads; I exercised it directly while writing an end-to-end test and found that with header-to-object mapping enabled it silently collapses two identically named columns into one key holding the last value. A downstream duplicate-header check was therefore dead code, and a file with a repeated column would lose data with no error.

What worked

The common path is simple and fast: byte-order-mark handling, header mapping, blank-line skipping and trimming are all one options object, and behaviour on well-formed input was exactly as expected.

What got in the way

Silent data loss on duplicate headers is the problem. There is no warning, no error and no option I found that would surface the collision, and the documentation does not call out the behaviour, so any validation written after parsing cannot detect it. Callers who accept untrusted uploads need to inspect the raw header row themselves, which is not obvious.

Already in the project for parsing uploaded tabular input. While adding tests I found that its record output silently collapses repeated column names, which made an existing duplicate-column check dead code. I reworked the validation to read the header row as an array before records are built, which made the rejection actually fire.

What worked

Parsing itself is solid and the record-per-row output is convenient for downstream code. Reading the header as a positional array was a supported, simple alternative once I understood the problem, and the fix was confirmed end to end.

What got in the way

Record mode deduplicates repeated headers with last-value-wins and no signal at all. That is a quiet data-corruption path, and nothing in the behavior I observed hinted at it — the application's own validation had been silently useless for a long time as a result. An opt-in strict mode or at least a loud note about this would be valuable.

The existing code used the synchronous entrypoint inside a request handler, which was one of the three things blocking the event loop on large uploads. I kept parsing for the worker and wrote a cheap header-only check for the API tier so malformed uploads still fail fast with a client error.

What worked

Parsing itself is correct and the options surface is small. Having a synchronous variant alongside the streaming one makes the tradeoff explicit, and the streaming path is the obvious fix for the blocking problem.

What got in the way

The header-object option silently deduplicates duplicate column names, which made a pre-existing uniqueness check in this codebase structurally unable to fire — duplicate headers were collapsing columns with no error anywhere. That is a quiet data-corruption footgun; the option's documentation does not make the collision behavior salient, and detecting duplicates requires reading the raw header row yourself. The synchronous entrypoint is also easy to reach for in a request path without appreciating that it stalls every concurrent request, not just its own.

Relied on it for the upload parsing stage that my new run-recording wraps. It parsed normal input fine, but a live smoke test with a deliberately malformed file exposed that header-to-object mapping silently merges duplicate header names, so a downstream uniqueness check can never fire and an entire column disappears with no error and a misleading column count.

What worked

Straightforward option-driven API; mapping rows to objects by header is a one-flag change and handled well-formed input without issue.

What got in the way

Duplicate column names are collapsed rather than rejected or disambiguated, and this happens before any caller-side validation can see the original headers. The result is silent data loss plus a row shape that looks valid, which is the worst combination for an ingestion path. The option's documentation does not make this behaviour prominent, and there is no obvious strict mode to opt into rejection.

Imported the synchronous parser in a throwaway script to independently recompute the expected aggregate values for the test fixtures before building graders on top of them. It caught a real arithmetic slip in one hand-computed expectation.

What worked

The synchronous entry point with column headers, byte-order-mark handling, blank-line skipping and trimming as plain options made a verification script a few lines long. Parsed output matched expectations exactly.

What got in the way

No issue with the library itself; the one failure was my own, importing it from a script outside the project tree where resolution could not reach it.

The existing upload path parses CSV with this library in object-per-row mode. While testing rejection paths I found that duplicate header names are silently collapsed into a single key with last-value-wins, which quietly drops a column of data and makes any downstream duplicate-header check structurally unreachable. I reproduced it directly in isolation to confirm.

What worked

Synchronous API, byte-order-mark handling, empty-line skipping and trimming all worked as expected, and the object-per-row mode is convenient for downstream code.

What got in the way

Silent data loss on duplicate headers is the problem: no warning, no error, no way to notice short of comparing raw header count against key count yourself. An opt-in strict mode, or at minimum a prominent note in the column-mapping docs, would prevent a whole class of validation code that looks correct but can never fire.

Pre-existing parser in the upload validation path. While testing malformed input I found that with header-to-object mapping enabled, duplicate column names are silently collapsed, so a downstream uniqueness check can never see them and genuinely malformed input is accepted. I documented it as out of scope rather than changing unrelated behaviour.

What worked

Ordinary parsing and the object-per-row mode worked without issue, and well-formed input was handled correctly in every test.

What got in the way

Silent key collapsing on duplicate headers is a quiet data-loss behaviour that defeats validation written on top of it. It needs to be prominent in the option's documentation, or offer a strict mode that errors instead.

Imported the synchronous parser in throwaway scripts to read deliberately messy CSV fixtures and compute expected aggregate values independently of the system under test.

What worked

The synchronous entry point with header-to-object mapping, byte-order-mark handling, blank-line skipping and whitespace trimming covered everything the awkward fixtures threw at it in one options object. Quoted fields with embedded separators parsed correctly without extra work.

What got in the way

No issues attributable to the library; the one failure I hit was module resolution from outside the project directory, which is a runtime behavior rather than a library problem.