@justybase/spreadsheet-tasks 3.1.1 → 3.2.0

package/CHANGELOG.md

@@ -5,6 +5,84 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.0] - 2026-11-08
+
+### Added
+
+- Shared writer core (`src/writers/core`) used by the Node and browser XLSX/XLSB
+  writers. The unpacked package parts are byte-identical between Node and browsers.
+- `useSharedStrings: false` writer option for inline strings (four writers).
+- `ExcelError` cell value and round-trip support for Excel error cells.
+- `XlsxReader.openBuffer()` and `XlsbReader.openBuffer()` plus `readRow()`,
+  `readAll()` and `rows()` batch APIs.
+- Isolated-process I/O benchmark (`npm run benchmark:io`) with a 3% regression
+  gate, and a self-contained Microsoft Excel COM conformance suite
+  (`EXCEL_COM=1 npm run test:excel-com`).
+- Etap 2 cell formatting: `CellStyle`, `StyledCell`, `FormulaCell`, `RichText`
+  and style helpers. `FormattedCell` remains supported.
+- XLSX styling: fonts, fills, borders, alignment, protection, custom number
+  formats and differential styles for conditional formatting.
+- XLSX sheet features: formula cells with cached values, rich text, merged
+  cells, hyperlinks, data validation, conditional formatting and cell comments
+  (classic notes with VML).
+- XLSB styling and formulas: a BIFF12 style registry and a curated formula
+  compiler with cached values; merged cells, hyperlinks and data validation.
+- Conservative column autofit (header + up to 200 sample rows, capped at 200,
+  not narrower than xlspy/Excel AutoFit up to that cap) and explicit
+  `columnWidths` overrides in all four writers. Streaming writers delay the
+  sheet head until the first 200 data rows have been measured.
+- `XlsxReader.getStyle()`, `getFormula()` and `getRichText()`; `XlsbReader.getStyle()`.
+
+### Changed
+
+- `writeSheet` accepts a sheet-options object in place of the legacy
+  `doAutofilter` boolean while keeping the boolean overload backward compatible.
+- `updateColWidthsFromRows` understands styled, formula and rich-text cells.
+- Autofit is deliberately conservative so it is not narrower than
+  xlspy/Excel AutoFit up to the 200 cap: columns use the 8.43 minimum, calibrated
+  character costs (CJK/fullwidth, emoji, wide fonts, bold/italic and font
+  size), number/date-format display text, room for the autofilter button, the
+  5/7-character cell padding, and a 200-character cap on the stored width. The
+  default fallback width is 9.14.
+- Autofit also measures alignment indent, the longest line of wrapped text,
+  negative number-format sections, and Excel's 11-character General rendering
+  instead of the full JavaScript decimal expansion.
+- `options.autofitRows` controls how many rows are measured (default 200;
+  `0` disables row sampling).
+- XLSB column widths are written as full 1/256-character units instead of
+  floored integers.
+- Explicit `columnWidths` values are validated to 0.5-255 characters.
+
+### Fixed
+
+- XLSX reading no longer scans the rest of the sheet for every cell. The
+  formula lookup was unbounded, so a 20,000 x 10 sheet took minutes to read
+  instead of milliseconds; tag and value lookups are now bounded to the cell.
+- XLSX numeric cells are parsed without allocating an intermediate string
+  (`parseFloat` is still used for exponents and long mantissas), restoring
+  read throughput close to the pre-Etap-2 reader.
+- Dates with a time of day now use the datetime style (`numFmt` 22) in XLSX and
+  XLSB instead of the date-only style, so the time is no longer hidden.
+- Streaming `writeRow()` now feeds autofit instead of leaving columns sized only
+  from the header and `sampleRows`.
+- Long runs of accented Latin, Greek/Cyrillic and symbol characters are no
+  longer measured narrower than xlspy; a per-character exception table covers
+  the outliers.
+- XLSB `BrtWsDim` now contains the real last row and an inclusive last column;
+  previously rows were always 0 and the column was one past the data.
+- XLSB cells with an error value are read as `#DIV/0!`-style text instead of `null`.
+- XLSX reader resolves optional `r`/`t`/`s` cell attributes from raw bytes
+  (previously attribute-less and typed cells could be misread).
+- XLSB custom number formats no longer produce a corrupt styles part.
+
+### Limitations
+
+- XLSB rich text, comments and conditional formatting are not emitted yet; the
+  writers throw a clear error instead of silently dropping them.
+- XLSB formula support is a subset (literals, A1 references/ranges, operators
+  and common worksheet functions); unsupported syntax throws.
+- `XlsbReader` does not reconstruct formula text; it returns cached values.
+
 ## [3.1.1] - 2026-10-24
 
 ### Changed

package/README.md

@@ -28,7 +28,16 @@ High-performance TypeScript library for reading and writing Excel files in XLSB
 - **TypeScript First** — Full TypeScript support with type definitions
 - **Dual Format Support** — Read and write both XLSB and XLSX formats
 - **Lightweight Node Dependencies** — Small ZIP-focused runtime deps (`adm-zip`, `archiver`, `yauzl`); no heavy Excel framework
-- **Streaming Support** — Efficient memory usage for large files
+- **Streaming Support** - Efficient memory usage for large files
+- **Shared Writer Core** - Node and browser writers emit byte-identical package parts
+- **Inline or Shared Strings** - Opt into inline strings for high-cardinality text
+- **Buffer I/O** - `openBuffer()` reads a workbook from memory; `readAll()`/`rows()` batch APIs
+- **Styles and Formats** - Fonts, fills, borders, alignment, protection and number formats (`CellStyle`)
+- **Formulas** - Write formula cells with cached values (`FormulaCell`); XLSX and a curated XLSB formula subset
+- **Sheet Features** - Merged cells, hyperlinks, data validation, comments and conditional formatting in XLSX; merges, hyperlinks and validation in XLSB
+- **Rich Text** - Formatted text runs in XLSX shared and inline strings
+- **Conservative Column Autofit** - Not narrower than xlspy/Excel AutoFit up to the 200 cap; explicit `columnWidths` override it
+- **Excel Error Values** - Read and write `#DIV/0!`, `#N/A` and the other Excel errors
 - **Multiple Sheets** — Support for multiple worksheets per workbook
 - **Auto-filter** — Automatic filter headers support
 - **Excel COM Conversion** — Convert XLSB and XLSX through desktop Microsoft Excel on Windows
@@ -190,6 +199,19 @@ const writer = new XlsxWriter('fast.xlsx', { compressionLevel: 1 });
 
 Out-of-range values throw a `RangeError`.
 
+### Inline Strings
+
+Writers use a shared-string table by default, which is fastest when text repeats.
+For high-cardinality text (IDs, messages) inline strings can reduce peak memory:
+
+```typescript
+const xlsx = new XlsxWriter('inline.xlsx', { useSharedStrings: false });
+const xlsb = new XlsbWriter('inline.xlsb', { useSharedStrings: false });
+```
+
+The browser writers accept the same option:
+`new BrowserXlsxWriter({ useSharedStrings: false })`.
+
 ### Reading Excel Files
 
 ```typescript
@@ -215,6 +237,101 @@ await xlsbReader.open('data.xlsb');
 // ... same API as above
 ```
 
+Batch and in-memory APIs avoid the per-row `await`/`getValue` loop:
+
+```typescript
+const reader = new XlsxReader();
+await reader.openBuffer(buffer);          // ZIP bytes, e.g. from fetch() or fs.readFileSync()
+await reader.selectSheet(0);              // or a sheet name
+const rows = await reader.readAll();       // CellValue[][] (header row included)
+
+for await (const row of reader.rows()) {   // streaming without holding the sheet
+    consume(row);
+}
+
+// Synchronous fast path after selectSheet(): the returned array is reused until the next call.
+let row: CellValue[] | null;
+while ((row = reader.readRow()) !== null) {
+    consume(row.slice());                  // copy if you keep it
+}
+```
+
+Excel error cells are returned as their display text (`'#DIV/0!'`). To write an error,
+wrap it in `ExcelError`:
+
+```typescript
+import { ExcelError } from '@justybase/spreadsheet-tasks';
+writer.writeSheet([[new ExcelError('#N/A'), 1, 2]]);
+```
+
+### Styles, Formulas and Sheet Features
+
+Cells can carry a full style, a formula with a cached value, or rich text:
+
+```typescript
+import { XlsxWriter, RichText } from '@justybase/spreadsheet-tasks';
+
+const writer = new XlsxWriter('report.xlsx');
+writer.addSheet('Report');
+writer.writeSheet(
+    [
+        [
+            { value: 1234.5, style: { numFmt: '#,##0.00', font: { bold: true, color: 'FF0000' }, fill: { fgColor: 'FFFF00' } } },
+            { formula: 'SUM(A2:A3)', value: 1234.5 },
+            new RichText([
+                { text: 'red', style: { font: { color: 'FF0000' } } },
+                { text: ' plain' },
+            ]),
+        ],
+        [200, { formula: 'A2*2', value: 400 }, 'x'],
+    ],
+    ['Amount', 'Total', 'Note'],
+    {
+        merges: ['A4:B4'],
+        hyperlinks: [{ ref: 'C1', target: 'https://example.com', tooltip: 'Example' }],
+        dataValidations: [{ sqref: 'C2:C5', type: 'list', values: ['x', 'y'] }],
+        conditionalFormats: [{
+            sqref: 'A2:A3',
+            rules: [{ type: 'cellIs', operator: 'greaterThan', formula: ['1000'], style: { font: { bold: true } } }],
+        }],
+        comments: [{ ref: 'A2', text: 'Reviewed', author: 'Analyst' }],
+        columnWidths: [18, 14], // optional; otherwise conservative autofit is used
+    },
+);
+await writer.finalize();
+```
+
+`columnWidths` wins over autofit. Autofit itself is deliberately conservative:
+it looks at the header plus up to 200 sample rows (xlspy measures up to 1000) and
+estimates widths from character costs calibrated against xlspy's widest font
+metrics. The estimate includes CJK/fullwidth characters, emoji, bold/italic
+text, font size, wide font families, common number/date formats, alignment
+indent, the longest line of wrapped text and negative number-format sections.
+It enforces Excel's 8.43 minimum, reserves room for the autofilter button, adds
+the 5/7-character cell padding when writing, and caps the stored width at 200.
+The estimate errs on the wide side so columns are not narrower than
+xlspy/Excel AutoFit up to that cap. In streaming mode the sheet head is delayed
+until the first 200 data rows have been measured. Explicit
+`columnWidths` must be 0.5-255 characters and are written unchanged.
+
+XLSB supports `CellStyle`, `FormulaCell` (a formula subset with cached values),
+`merges`, `hyperlinks`, `dataValidations` and `columnWidths`. Rich text,
+comments and conditional formatting are XLSX-only and throw a clear error when
+passed to an XLSB writer.
+
+XlsxReader exposes the style, formula and rich-text runs of the last read row:
+
+```typescript
+const reader = new XlsxReader();
+await reader.open('report.xlsx');
+await reader.selectSheet('Report');
+while (reader.readRow() !== null) {
+    const style = reader.getStyle(0);     // CellStyle | null
+    const formula = reader.getFormula(1); // string | null (no leading '=')
+    const rich = reader.getRichText(2);   // RichText | null
+}
+```
+
 ### Updating Data in an Existing Workbook
 
 `XlsxUpdater` and `XlsbUpdater` replace the cell data of a worksheet inside an
@@ -343,8 +460,12 @@ npm test
 Before opening a pull request:
 
 1. Run `npm run lint` and `npm test`.
-2. Add or update tests if you change behavior.
-3. Update [CHANGELOG.md](./CHANGELOG.md) for user-visible changes.
+2. Run `npm run benchmark:io:baseline` once, then `npm run benchmark:io:check` to
+   catch I/O regressions (the quick gate defaults to 5% on a quiet machine; pass
+   `-- --max-regression 3` for the strict full-run gate).
+3. On Windows with desktop Excel, run `EXCEL_COM=1 npm run test:excel-com`.
+4. Add or update tests if you change behavior.
+5. Update [CHANGELOG.md](./CHANGELOG.md) for user-visible changes.
 
 Please open an issue or pull request on [GitHub](https://github.com/justybase/justybase_spreadsheet_tasks).