@xlsxflow/core 1.1.2 → 1.1.4

package/CHANGELOG.md

@@ -1,108 +1,146 @@
-# Changelog
-
-## 1.1.2
-
-### Fixed
-
-- `SheetWriter` throws an error for a row longer than 16,384 cells or past row 1,048,576, instead of writing a file Excel reports as damaged.
-- `SheetEditor.setCells`: a date in a cell without a date format gets `yyyy-mm-dd` (or `yyyy-mm-dd hh:mm:ss` with a time), as in `SheetWriter`, instead of showing as a serial number.
-- `OdsWriter` stores formula results, so readers that don't recalculate show them.
-- `sheetToJson` keeps every column when headers repeat: the second `Name` becomes `Name_2`.
-- `parseCsv` returns `null` for empty unquoted fields with `{ convert: false }` too.
-
-### Added
-
-- `StylePatcher` is exported, for `@xlsxflow/pro`.
-
-## 1.1.1
-
-- README: the XlsxFlow website address, and Pro at a flat $5.
-- More npm keywords: `xls` and `ods`.
-
-## 1.1.0
-
-### Added
-
-- `SheetWriter`: workbook properties (title, author, company and so on), defined names, hidden and very hidden sheets, and sheet views (zoom, gridlines, headings, right-to-left). `SheetReader.readWorkbook` reads them back.
-- `{ formatted: true }` reports each cell's text as Excel shows it, from its number format.
-- `SheetEditor.insertRows`, `deleteRows`, `insertColumns` and `deleteColumns`. Everything that points at the moved cells moves with them: formulas on all sheets, defined names, merges, conditional formats, validations, hyperlinks, filters, page breaks, column widths, tables, pictures, notes, sparklines, data tables, chart series and pivot sources.
-- `SheetEditor.setCells` edits and restyles cells of existing files; `addSheet` and `deleteSheet` add and remove sheets.
-- `parseCsv` streams CSV rows, which `SheetWriter.addSheet` turns into a sheet.
-- `SheetReader` reads Excel 97-2003 `.xls` files and OpenDocument `.ods` files: values, dates, formula results, merges, hidden rows, columns and sheets, frozen panes, defined names and document properties. `.ods` also gives formulas, hyperlinks and notes.
-- `OdsWriter` writes `.ods` files: values, dates, formulas, merges, column widths, frozen panes and hidden sheets.
-- Password-protected `.xlsx` files are rejected with an error that points to `decryptWorkbook` in `@xlsxflow/pro`, instead of a ZIP error.
-- Cell notes on write (plain or formatted text) and `getComments()` on read.
-- Conditional formats `cellIs`, `expression`, `top10`, `aboveAverage`, text rules, `duplicateValues`/`uniqueValues` and `iconSet`.
-- Excel tables, sheet protection, page setup (margins, header and footer, print area and titles), row heights, hidden rows and columns, outline grouping, tab colour, and validation operators and messages.
-- `Date` cell values, hyperlinks (URLs and locations in the workbook), `autoFilter`, and an optional shared string table on write.
-- Reading returns formulas (`formulas: true`, shared formulas expanded), styles (`styles: true`) and rich text (`richText: true`). Theme and indexed colours are resolved to ARGB.
-- PNG, JPEG and GIF images (`images` sheet option), anchored to a cell or stretched over a range. `getImages()` reads them back.
-- Low-level parts are exported for add-ons: the ZIP reader and writer, `resolveWorkbookParts`, `readSharedStrings`, and `mapFormulaRefs`/`shiftFormula`.
-- Tested: `.xlsm` files keep their macros through `SheetEditor`; the library runs in Cloudflare Workers without `nodejs_compat` (`scripts/workers` checks it).
-
-### Security
-
-Fixed crashes, hangs and memory blowups caused by crafted files:
-
-- A ZIP directory pointing outside the file crashed Node.
-- Unclosed tags and elements made the parser quadratic. The XML tokenizer is now linear on giant tags, text nodes and CDATA.
-- Repeated hidden columns, far-right cells, fraction formats with long denominators and large style tables were slow or used unbounded memory.
-- One deflated entry could be read many times under different names.
-
-Also:
-
-- `SheetEditor.edit` takes `maxUncompressedBytes`.
-- Option values typed as enums are escaped, and appended rows encode control characters.
-- `sheetToJson` keeps a `__proto__` header as an ordinary key.
-- In-memory parts are capped at 1 GiB uncompressed by default.
-
-### Fixed
-
-- Sheets with frozen panes were all marked as selected, so Excel opened them grouped.
-- The reader dropped or corrupted cells at stream chunk boundaries.
-- Styles pointed at the wrong font, fill or border, and styles used only by `AsyncIterable` rows were missing from `styles.xml`.
-- Number formats with quoted text, escapes or colours (`#,##0.00 "USD"`, `[Red]0.0`) were taken for date formats.
-- Reading a corrupt file without calling `getMetadata()` caused an unhandled promise rejection, which is fatal in Node.
-- `addSheet` accepted sheet names Excel refuses to open. It now throws.
-- Files Excel would repair:
-  - gradient stops were written as `<gradientStop>`;
-  - `vertical: 'middle'` was written as is instead of `center`;
-  - conditional formats came after validations.
-- Data bar `minValue`/`maxValue` were ignored, every conditional format had priority 1, and colours and ranges were not XML-escaped.
-- Strings with `_xHHHH_`, control characters, CR, or leading and trailing spaces now survive a round trip. `NaN` and `Infinity` are written as `#NUM!`.
-- Reader:
-  - Strict OOXML and non-standard part names work;
-  - empty `<v/>` reads as empty and `-0` as `0`;
-  - out-of-order cells land in the right column;
-  - time-only values are no longer a day off, and datetimes keep milliseconds.
-  - frozen panes saved by Excel as `frozenSplit` (frozen after a split) are reported.
-- `sheetToJson` ignored its `headerRowIndex` argument.
-
-### Changed
-
-- The package ships compiled ESM and CommonJS builds with type declarations.
-- Browser bundles no longer try to resolve Node's `fs`.
-- `[Content_Types].xml` is written last in the ZIP.
-- Real backpressure in the ZIP writer and worksheet stream. Producer errors now error the output stream instead of hanging it.
-- About 2.5× faster reads, and a table-driven CRC-32 for faster writes.
-- Styles, formulas and conditional formats are part of the MIT core. Paid add-ons are in the separate `@xlsxflow/pro` package.
-- Benchmarks corrected: the earlier ExcelJS write time came from a cold first run, and write-excel-file was run with an old API.
-
-## 1.0.0
-
-- `SheetWriter` and `SheetEditor` stream the ZIP with data descriptors instead of buffering the file in memory.
-- Dates are returned as ISO-8601 strings, detected from each cell's number format.
-
-## 0.3.0-beta
-
-- Workbooks with several sheets.
-- Fixed a buffer bug that made parsing quadratic.
-
-## 0.2.0-beta
-
-- Deflate compression with `CompressionStream`: a 1M-cell file went from 30 MB to 2.9 MB.
-- Inline and rich text strings are read.
-
-## 0.1.0-beta
-
-- First release: streaming reader, writer, and shared strings.
+# Changelog
+
+## 1.1.4
+
+Fixes from the third round of end-user tests (700 cases).
+
+### Fixed
+
+- `XlsxFlow.readFile` reads `.ods` files, and `getComments()` / `getImages()` work after reading an `.xlsx` with it.
+- Control characters and U+FFFE/U+FFFF never reach the XML: cell text keeps them as `_xHHHH_` escapes, other text (document properties, notes' authors, validations, headers and footers, table columns, alt text, formulas) drops them, and sheet names with them are refused.
+- `SheetWriter` stores formula text that starts with `#` as text, not as an error cell Excel repairs.
+- `SheetWriter` waits while nobody reads its output, instead of pulling rows from the source without limit, and cancelling the output ends the row source (its `finally` runs).
+- Cached formula results: formulas over other formula cells, scientific literals (`1E3`), reversed ranges, case-insensitive text comparison, values typed into `SUM`, 15-digit number text, `TRUE`/`FALSE` text, errors (`#DIV/0!`, `#VALUE!`) and circular references follow Excel. Streamed rows get no made-up cached values (in `OdsWriter` too).
+- `SheetWriter` refuses overlapping or malformed merges, overlapping tables, table names that look like cell references, defined names over 255 characters, row options outside rows 1 to 1,048,576, list validations over 255 characters, truncated images, and picture sizes that are not positive numbers. Validation formulas lose a leading `=`, and every range of a multi-range print area names its sheet.
+- `SheetEditor.appendSheet` writes dates, formulas, styles and NaN as `setCells` does, keeps both batches when called twice, writes rows in the sheet's namespace, and refuses rows past 1,048,576.
+- `SheetEditor`: `setCells` edits the right row on sheets whose rows have no `r` attribute; a date and a style on one cell keep both; repeating a restyle reuses the formats it added; `insertRows` keeps ranges ending at the last row (`SUM(B1:B1048576)`), leaves references to other workbooks (`[1]S!A5`) alone, moves every cell of a shared formula on another sheet, and moves pivot tables on the sheet.
+- `SheetReader`: entries whose data does not match their CRC-32, and worksheets cut off mid-row, are errors instead of silently different data. A zip comment holding the end-record signature, part names in another case, UTF-16 parts, rows with an unusable `r`, `t="d"` cells (now UTC ISO strings, formatted with their date format), sheet names with `&amp;`, and a chart sheet as the first tab are read correctly.
+- `sheetToJson` keeps values right of the header row (`Column3`); `streamToCsv` keeps blank rows between rows.
+- `parseCsv` keeps numbers that overflow a double (`1e400`) as text.
+- `OdsWriter` keeps the milliseconds of dates and converts whole-column references (`SUM(C:C)`); the `.ods` reader reads the created date as UTC.
+- ZIP: UTF-8 entry names set the UTF-8 flag, 65,535 entries are refused (readers take 0xFFFF as ZIP64), and an encrypted or `.xls` file given where a ZIP is expected says so.
+
+### Added
+
+- The `errors` parse option: `row.errors` marks cells holding error values.
+
+## 1.1.3
+
+### Fixed
+
+- `SheetEditor.setCells` refuses addresses past column XFD or row 1,048,576, instead of writing a file Excel reports as damaged.
+- `SheetWriter` and `SheetEditor` refuse text longer than Excel's 32,767 characters per cell.
+- Colours are checked: ARGB (`FFFF0000`) and RGB (`FF0000`, `#FF0000`) hex are accepted, anything else (`'red'`) throws instead of making Excel repair the file.
+- Picture anchors past the last column or row throw; a range given the wrong way round (`F20:A2`) is turned round.
+- `SheetReader`: a shared string index past the end of the table reads as an empty cell, not as the index.
+
+### Added
+
+- `checkCellText` is exported, for `@xlsxflow/pro`.
+
+## 1.1.2
+
+### Fixed
+
+- `SheetWriter` throws an error for a row longer than 16,384 cells or past row 1,048,576, instead of writing a file Excel reports as damaged.
+- `SheetEditor.setCells`: a date in a cell without a date format gets `yyyy-mm-dd` (or `yyyy-mm-dd hh:mm:ss` with a time), as in `SheetWriter`, instead of showing as a serial number.
+- `OdsWriter` stores formula results, so readers that don't recalculate show them.
+- `sheetToJson` keeps every column when headers repeat: the second `Name` becomes `Name_2`.
+- `parseCsv` returns `null` for empty unquoted fields with `{ convert: false }` too.
+
+### Added
+
+- `StylePatcher` is exported, for `@xlsxflow/pro`.
+
+## 1.1.1
+
+- README: the XlsxFlow website address, and Pro at a flat $5.
+- More npm keywords: `xls` and `ods`.
+
+## 1.1.0
+
+### Added
+
+- `SheetWriter`: workbook properties (title, author, company and so on), defined names, hidden and very hidden sheets, and sheet views (zoom, gridlines, headings, right-to-left). `SheetReader.readWorkbook` reads them back.
+- `{ formatted: true }` reports each cell's text as Excel shows it, from its number format.
+- `SheetEditor.insertRows`, `deleteRows`, `insertColumns` and `deleteColumns`. Everything that points at the moved cells moves with them: formulas on all sheets, defined names, merges, conditional formats, validations, hyperlinks, filters, page breaks, column widths, tables, pictures, notes, sparklines, data tables, chart series and pivot sources.
+- `SheetEditor.setCells` edits and restyles cells of existing files; `addSheet` and `deleteSheet` add and remove sheets.
+- `parseCsv` streams CSV rows, which `SheetWriter.addSheet` turns into a sheet.
+- `SheetReader` reads Excel 97-2003 `.xls` files and OpenDocument `.ods` files: values, dates, formula results, merges, hidden rows, columns and sheets, frozen panes, defined names and document properties. `.ods` also gives formulas, hyperlinks and notes.
+- `OdsWriter` writes `.ods` files: values, dates, formulas, merges, column widths, frozen panes and hidden sheets.
+- Password-protected `.xlsx` files are rejected with an error that points to `decryptWorkbook` in `@xlsxflow/pro`, instead of a ZIP error.
+- Cell notes on write (plain or formatted text) and `getComments()` on read.
+- Conditional formats `cellIs`, `expression`, `top10`, `aboveAverage`, text rules, `duplicateValues`/`uniqueValues` and `iconSet`.
+- Excel tables, sheet protection, page setup (margins, header and footer, print area and titles), row heights, hidden rows and columns, outline grouping, tab colour, and validation operators and messages.
+- `Date` cell values, hyperlinks (URLs and locations in the workbook), `autoFilter`, and an optional shared string table on write.
+- Reading returns formulas (`formulas: true`, shared formulas expanded), styles (`styles: true`) and rich text (`richText: true`). Theme and indexed colours are resolved to ARGB.
+- PNG, JPEG and GIF images (`images` sheet option), anchored to a cell or stretched over a range. `getImages()` reads them back.
+- Low-level parts are exported for add-ons: the ZIP reader and writer, `resolveWorkbookParts`, `readSharedStrings`, and `mapFormulaRefs`/`shiftFormula`.
+- Tested: `.xlsm` files keep their macros through `SheetEditor`; the library runs in Cloudflare Workers without `nodejs_compat` (`scripts/workers` checks it).
+
+### Security
+
+Fixed crashes, hangs and memory blowups caused by crafted files:
+
+- A ZIP directory pointing outside the file crashed Node.
+- Unclosed tags and elements made the parser quadratic. The XML tokenizer is now linear on giant tags, text nodes and CDATA.
+- Repeated hidden columns, far-right cells, fraction formats with long denominators and large style tables were slow or used unbounded memory.
+- One deflated entry could be read many times under different names.
+
+Also:
+
+- `SheetEditor.edit` takes `maxUncompressedBytes`.
+- Option values typed as enums are escaped, and appended rows encode control characters.
+- `sheetToJson` keeps a `__proto__` header as an ordinary key.
+- In-memory parts are capped at 1 GiB uncompressed by default.
+
+### Fixed
+
+- Sheets with frozen panes were all marked as selected, so Excel opened them grouped.
+- The reader dropped or corrupted cells at stream chunk boundaries.
+- Styles pointed at the wrong font, fill or border, and styles used only by `AsyncIterable` rows were missing from `styles.xml`.
+- Number formats with quoted text, escapes or colours (`#,##0.00 "USD"`, `[Red]0.0`) were taken for date formats.
+- Reading a corrupt file without calling `getMetadata()` caused an unhandled promise rejection, which is fatal in Node.
+- `addSheet` accepted sheet names Excel refuses to open. It now throws.
+- Files Excel would repair:
+  - gradient stops were written as `<gradientStop>`;
+  - `vertical: 'middle'` was written as is instead of `center`;
+  - conditional formats came after validations.
+- Data bar `minValue`/`maxValue` were ignored, every conditional format had priority 1, and colours and ranges were not XML-escaped.
+- Strings with `_xHHHH_`, control characters, CR, or leading and trailing spaces now survive a round trip. `NaN` and `Infinity` are written as `#NUM!`.
+- Reader:
+  - Strict OOXML and non-standard part names work;
+  - empty `<v/>` reads as empty and `-0` as `0`;
+  - out-of-order cells land in the right column;
+  - time-only values are no longer a day off, and datetimes keep milliseconds.
+  - frozen panes saved by Excel as `frozenSplit` (frozen after a split) are reported.
+- `sheetToJson` ignored its `headerRowIndex` argument.
+
+### Changed
+
+- The package ships compiled ESM and CommonJS builds with type declarations.
+- Browser bundles no longer try to resolve Node's `fs`.
+- `[Content_Types].xml` is written last in the ZIP.
+- Real backpressure in the ZIP writer and worksheet stream. Producer errors now error the output stream instead of hanging it.
+- About 2.5× faster reads, and a table-driven CRC-32 for faster writes.
+- Styles, formulas and conditional formats are part of the MIT core. Paid add-ons are in the separate `@xlsxflow/pro` package.
+- Benchmarks corrected: the earlier ExcelJS write time came from a cold first run, and write-excel-file was run with an old API.
+
+## 1.0.0
+
+- `SheetWriter` and `SheetEditor` stream the ZIP with data descriptors instead of buffering the file in memory.
+- Dates are returned as ISO-8601 strings, detected from each cell's number format.
+
+## 0.3.0-beta
+
+- Workbooks with several sheets.
+- Fixed a buffer bug that made parsing quadratic.
+
+## 0.2.0-beta
+
+- Deflate compression with `CompressionStream`: a 1M-cell file went from 30 MB to 2.9 MB.
+- Inline and rich text strings are read.
+
+## 0.1.0-beta
+
+- First release: streaming reader, writer, and shared strings.

package/README.md

@@ -73,6 +73,7 @@ Dates come back as ISO-8601 strings. Opt in to more detail, each indexed like `r
 - `{ formulas: true }` gives `row.formulas`, with shared formulas expanded per cell.
 - `{ styles: true }` gives `row.styles`, as `CellStyle` objects (the same shape the writer takes). Theme and palette colours are resolved to ARGB.
 - `{ richText: true }` gives `row.richText`, the formatted runs of cells that have them. `row.cells` still holds the plain text.
+- `{ errors: true }` gives `row.errors`, `true` for the cells that hold an error value such as `#N/A`. `row.cells` gives errors as text, so this tells them from text that reads `#N/A` (`.xlsx` only).
 - `{ formatted: true }` gives `row.formatted`, each cell's text as Excel (en-US) shows it: `1,234.50`, `25.6%`, `(42)`, `08-Oct-2026 2:05 PM`. It covers sections, conditions, dates and elapsed times, fractions, scientific notation, currency and text formats. Repeat fills (`*`) and colours are left out, and other locales are shown as en-US.
 
 `await reader.readWorkbook(createBlobReader(blob))` lists the sheets with their visibility, the defined names and the document properties, without reading any sheet.
@@ -180,7 +181,7 @@ editor.setCells('Sheet1', {
   A1: { style: { font: { bold: true }, fill: { type: 'solid', fgColor: 'FFFFFF00' } } }, // restyle, keep content
   B3: { value: 7, style: { numFmt: '0.00' } },
 });
-editor.appendSheet('Sheet1', [['new', 'row']]); // appended after the last existing row
+editor.appendSheet('Sheet1', [['new', 'row']]); // after the last existing row (values, formulas, styles)
 editor.insertRows('Sheet1', 5, 3);  // 3 empty rows before row 5
 editor.deleteRows('Sheet1', 20, 2); // rows 20-21
 editor.insertColumns('Sheet1', 'C');  // or deleteColumns('Sheet1', 'C', 2)
@@ -193,10 +194,10 @@ Edited cells keep their style. A style change is merged into the cell's current
 
 Macro-enabled workbooks (`.xlsm`) keep their VBA project and content type through every edit.
 
-`addSheet` takes an array of rows with values, formulas and styles; for hyperlinks, notes and sheet options, write the workbook with `SheetWriter`. `deleteSheet` removes names scoped to the sheet and turns other defined names that point at it into `#REF!`; formulas in other sheets that point at it are not rewritten. `insertRows`, `deleteRows`, `insertColumns` and `deleteColumns` move everything that points at the cells, as Excel does:
+`addSheet` and `appendSheet` take arrays of rows with values, formulas and styles; for hyperlinks, notes and sheet options, write the workbook with `SheetWriter`. Calling `appendSheet` again for a sheet adds the rows after the earlier ones. `deleteSheet` removes names scoped to the sheet and turns other defined names that point at it into `#REF!`; formulas in other sheets that point at it are not rewritten. `insertRows`, `deleteRows`, `insertColumns` and `deleteColumns` move everything that points at the cells, as Excel does:
 - formulas on every sheet and the workbook's defined names (print areas, named ranges);
 - merged cells, conditional formats, validations, hyperlinks, the filter and its column filters, page breaks and column widths;
-- tables, pictures, notes, sparklines, What-If data tables, chart series and pivot-table sources.
+- tables, pictures, notes, sparklines, What-If data tables, chart series, and pivot tables and their sources.
 
 Ranges that span inserted rows or columns grow, and ranges over deleted ones shrink. References to deleted cells become `#REF!`. Columns inserted inside a table become table columns named Column1, Column2 and so on. Deleting a table's header row, all its data rows or all its columns is refused. Operations run in the order given, and `setCells` addresses count after the cells have moved. Inserted rows and columns are empty: they don't copy the formatting of their neighbours. Every sheet streams through the editor, because any of its formulas might point at the moved cells.
 
@@ -224,6 +225,8 @@ writer.addSheet('Sales', [
 });
 ```
 
+Colours are ARGB hex (`FFC00000`); RGB hex (`C00000` or `#C00000`) is opaque. A cell holds at most 32,767 characters, as in Excel.
+
 Other sheet options:
 
 ```typescript
@@ -248,7 +251,7 @@ writer.addSheet('Report', rows, {
 // Formatted notes: comment: { text: [{ text: 'Ana:', font: { bold: true } }, { text: ' restated' }] }
 ```
 
-Formulas are stored for Excel to calculate when it opens the file. For array rows, the writer also stores a cached result for simple formulas (`SUM`, `AVERAGE`, `COUNT`, `MIN`, `MAX`, `IF`, `CONCATENATE` and arithmetic), so other readers see a value.
+Formulas are stored for Excel to calculate when it opens the file. For array rows, the writer also stores a cached result for simple formulas (`SUM`, `AVERAGE`, `COUNT`, `MIN`, `MAX`, `IF`, `CONCATENATE`, `&`, comparisons and arithmetic, including over other formula cells), so other readers see a value. Errors are stored as error values (`#DIV/0!`). Rows from an AsyncIterable get no cached results, since the writer cannot look back at them.
 
 Strings are written inline, which keeps memory flat. `new SheetWriter({ sharedStrings: true })` stores each distinct string once instead. Files are smaller when values repeat, but the distinct strings stay in memory until the file is finished.