CSV to JSON

CSV looks trivial to parse — split each line on commas, treat the first line as headers — until a value in the actual data contains a comma of its own, which happens constantly with real spreadsheet exports: an address like "123 Main St, Apt 4", a company name like "Smith, Jones & Co", or a product description containing a list. The CSV specification, formalised as RFC 4180, handles this by allowing a field to be wrapped in double quotes, inside which commas, line breaks and even literal quote characters (escaped by doubling them) are all just data rather than structure. A parser that naively splits on every comma, ignoring quoting entirely, corrupts exactly these rows — splitting "Smith, Jones & Co" into two separate columns — and it usually does so silently, with no error to flag that anything went wrong, which is what makes the bug dangerous rather than just annoying.

Properly quote-aware parsing tracks whether the reader is currently inside a quoted field and ignores delimiter and newline characters until the closing quote is reached, which is the only way to correctly reconstruct fields that legitimately contain the characters that would otherwise be mistaken for structure.

Every value in a raw CSV file is text, since CSV has no native concept of a number, a boolean or a null — a cell containing `42` and a cell containing `hello` are stored identically as characters. Type inference is the process of guessing which strings were "really" meant to be numbers, true/false values or nulls, and converting them accordingly so the resulting JSON has actual typed values rather than everything wrapped in quotes as a string.

The guessing has to be conservative, though, because plenty of values that look numeric are not meant to be treated as numbers at all. A leading zero — `007`, `042` — usually signals an identifier or a padded code where the leading zero is meaningful and would be silently destroyed by conversion to a number, since `7` and `007` are the same number but very different identifiers. A phone number like `+44 20 7946 0958` looks partially numeric but is not arithmetic data. Values beyond JavaScript's safe integer range lose precision if converted to a number at all. This tool leaves all of those as strings specifically because guessing wrong here means silently corrupting data in a way that is easy to miss until much later.

A JSON object cannot have two keys with the same name — the second one encountered simply overwrites the first, silently discarding a whole column's worth of data with no error raised anywhere. Spreadsheet exports produce duplicate headers more often than seems likely: a report with two differently-scoped "Total" columns, or a merged export from two sources that both happened to use "Name." Detecting duplicates and renaming the second occurrence to `name_2` preserves every column's data rather than silently losing whichever one happened to come first in the row object. Blank headers get the same treatment for the same reason, since JSON has no way to represent a key that is simply an empty string as a meaningful, addressable field.