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.