SheetJS Cell Type Verdict

Decides what a SheetJS read will SILENTLY MISREAD, from the options you pass and what you know about the sheet. Pure function: no I/O, no workbook parsing, no dependency on xlsx.

Built for xlsx (SheetJS Community Edition) 0.18.5 (Apache-2.0). Not affiliated with or endorsed by SheetJS. SheetJS Pro is a separate commercial product; this concerns the community edition only.

THE SILENT FAILURE. Excel does not store a date -- it stores a NUMBER with a date format on it, and every SheetJS read has to decide what to hand you. There is no setting that is right for every cell, and each wrong answer is a perfectly valid value of some OTHER type, so nothing throws anywhere.

DATES ARRIVE AS INTEGERS. 2026-03-04 reads back as 46085. It is a good number, so it is stored, compared, summed and rendered as one -- and the mistake surfaces later as a date in 1970 or a nonsense total, never as a parse failure.

FIXING THAT BUYS YOU A TIMEZONE SHIFT. cellDates:true gives real Dates, at LOCAL midnight expressed as an instant. Read the UTC calendar day back and an invoice dated the 4th is filed on the 3rd on any machine AHEAD of UTC. Still a valid Date; still nothing reported. MEASURED across five zones on the same cell: UTC getters return the right day in America/Los_Angeles and UTC, and the WRONG one in Asia/Tokyo, Pacific/Auckland and Pacific/Kiritimati -- while LOCAL getters are right in all five. So the remedy is to take the LOCAL year/month/day components, never the UTC ones. An earlier version of this listing advised the opposite; it was captured on a Pacific-timezone machine and generalised, and it is corrected here rather than quietly restated.

BOTH SETTINGS ARE WRONG FOR A CALENDAR DATE, in different ways. That is the finding, and it is why this reports a problem under cellDates true and false alike rather than telling you to flip a flag.

AND SHEETJS'S OWN OPTIONS CONTRADICT EACH OTHER. Excel serial 60 is 29 February 1900 -- a day that never existed, retained for Lotus 1-2-3 compatibility. Measured: raw:false formats it "1900-02-29" and cellDates:true yields 1900-02-28. Same cell, two answers, both silent. Only reported when your data can actually reach 1900, because historic records and birth dates do and a sales report does not.

raw:false ALSO TURNS MONEY INTO TEXT. 0.075 becomes "7.50%" and 1234.5 becomes "$1,234.50". Arithmetic on those concatenates or coerces instead of adding, and a total quietly becomes a string or a NaN.

IT STAYS QUIET WHERE THERE IS NOTHING TO SAY. A sheet with no dates and no currency or percentage formatting cannot be affected by either option, and it says so specifically -- you can stop thinking about cellDates entirely, rather than being told your options happen to match.

VERIFIED: 18 tests, measured by running the suite, every mutation observed FAILING before restore -- including one that caught a gap in the TESTS: the nothing-to-say branch could be deleted and the status stayed SAFE, because only the status was asserted and not the explanation.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function evaluateSheetJsRead(path: ReadPath): Verdict;

  export type CellDates = boolean | "unknown";
  export type RawOption = boolean | "unknown";
  export type Verdict = | { status: "SAFE";