ADR 0279 — A workbook is written without a dependency

Serves I8, I9, I13.

Context

A consuming project found that none of the four reference applications exports Excel, while client admin panels almost always ask for it, and each project picks a library again. The failures are the same each time: user text that runs as a formula, an amount that changes in the double a cell stores, and a date a time zone away from the one written.

Decision

stitchkit/xlsx starts evolving and writes the format itself: a deflated ZIP of XML through the platform’s CompressionStream, about 500 lines. The package has one runtime dependency, and a write-only workbook with six column types does not justify a second.

Cells are typed by their column. Text is an inline string, so the file has no formula element whatever the text says, and a leading =, +, - or @ also gets Excel’s quote prefix. Anything Excel would store differently from what was written refuses with the cell’s address: a number past 15 significant digits, a date before 1900-03-01, a value of the wrong type. An instant is written as the wall clock of the column’s declared zone, because a cell stores none; the repeated hour of a daylight-saving change is the one loss that cannot be refused, and the guide names it.

Alternatives

  • A library such as exceljs: rejected for the shipped code. It brings about 170 packages for features this does not use. It stays as a development dependency, because a reader this package did not write is what proves the bytes.
  • A CSV export: rejected, it has no types, and leading = needs a mangling that changes the data.
  • Accepting doubles for money and rounding silently: rejected, that is the defect exact money exists to prevent.

Consequences

Reading, charts, merged cells and streaming are out of scope; an application that needs them takes a library. A workbook is built in memory, so its size is the caller’s to bound. Proven in packages/core/tests/xlsx.test.ts through exceljs.