@xlsxflow/core 1.1.4 → 1.1.6

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 1.1.6
+
+### Changed
+
+- `SheetWriter`, `SheetEditor` and `OdsWriter` keep up to four chunks queued for compression instead of one, so building the next chunk overlaps compressing the last. Writing 10M cells takes about 10% less time; the files are the same, and the writer still waits while nobody reads its output.
+
+### Testing
+
+- Public CI on every push and pull request: the tests on Node 20, 22 and 24 with coverage; the README's claims in Node, Bun, Deno, Chromium, Firefox, WebKit and Cloudflare Workers; and written and edited files validated with Microsoft's Open XML SDK and opened in LibreOffice. OpenSSF Scorecard and CodeQL check the repository.
+
+## 1.1.5
+
+Fixes found while testing every claim in the README on Node 20.12 and 25, Bun, Deno, Chrome and Cloudflare Workers.
+
+### Fixed
+
+- `SheetWriter`, `SheetEditor` and `OdsWriter` wait while nobody reads their output on Node and Bun too. Their `CompressionStream` takes thousands of chunks without pushing back, so a slow consumer let the writer pull the whole row source into memory.
+- On Bun, `.ods` files and other ZIP entries stored without compression read correctly. Bun's `Blob.slice().stream()` runs past the end of the slice, which 1.1.4's size check rejected.
+- `SheetWriter` refuses a merge that overlaps a table. Excel tables cannot hold merged cells, and Excel repaired such files by removing the table.
+
+### Docs
+
+- The README says to close a `createFileReader` reader (Node 25 stops the process when an open file is garbage-collected), lists Deno as tested, fixes the sheet-options example that merged cells inside a table, and corrects the comparison table: ExcelJS 4.4 has no pivot tables.
+
 ## 1.1.4
 
 Fixes from the third round of end-user tests (700 cases).

package/README.md

@@ -7,6 +7,8 @@
   
   [![npm version](https://img.shields.io/npm/v/@xlsxflow/core.svg?style=flat-square)](https://www.npmjs.com/package/@xlsxflow/core)
   [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+  [![CI](https://img.shields.io/github/actions/workflow/status/xlsxflow/xlsxflow/ci.yml?branch=main&label=CI&style=flat-square)](https://github.com/xlsxflow/xlsxflow/actions/workflows/ci.yml)
+  [![OpenSSF Scorecard](https://img.shields.io/ossf-scorecard/github.com/xlsxflow/xlsxflow?label=OpenSSF%20Scorecard&style=flat-square)](https://scorecard.dev/viewer/?uri=github.com/xlsxflow/xlsxflow)
 
   <p>
     <a href="#features">Features</a> •
@@ -28,8 +30,8 @@ Rows are read and written one at a time instead of loading the whole workbook, s
 ## Features
 
 - **No dependencies**: TypeScript on Web APIs (`ReadableStream`, `CompressionStream`, `Blob`).
-- **Streaming**: rows are read and written one at a time, so memory stays flat as files grow (10M cells written with about 1 MB of extra heap; see [Benchmarks](#benchmarks)).
-- **Runs anywhere with Web APIs**: tested on Node 20.12+, Bun, browsers and Cloudflare Workers (without `nodejs_compat`). Deno provides the same APIs but is not tested yet.
+- **Streaming**: rows are read and written one at a time, so memory stays flat as files grow (10M cells written with about 2 MB of extra heap; see [Benchmarks](#benchmarks)).
+- **Runs anywhere with Web APIs**: tested on Node 20.12 and later, Bun, Deno, Chrome, Firefox, Safari (WebKit) and Cloudflare Workers (without `nodejs_compat`).
 - **Read, write and edit**: stream rows out of a file, generate one on the fly, or change cells, rows, columns and sheets of an existing file while keeping everything else in it.
 - **Styles and formulas**: fonts, fills, borders, alignment, number formats, conditional formats, validations, tables, notes, hyperlinks, autofilters, images, protection and page setup. Formulas and styles read back too.
 - **Older and open formats**: the same reader opens Excel 97-2003 `.xls` files and OpenDocument `.ods` files, and `OdsWriter` writes `.ods`.
@@ -89,11 +91,20 @@ Parts held in memory (workbook, shared strings, styles) are capped at 1 GiB unco
 In Node.js, read straight from disk with `XlsxFlow.readFile`, or pass `await createFileReader(path)` to any function that takes a reader:
 
 ```typescript
-import { XlsxFlow } from '@xlsxflow/core';
+import { XlsxFlow, SheetReader, createFileReader } from '@xlsxflow/core';
 
 for await (const row of await XlsxFlow.readFile('./data.xlsx')) {
   console.log(row.cells);
 }
+
+// createFileReader keeps the file open until you close it, after you are done with
+// everything read through it (Node 25 stops the process when an open file is garbage-collected)
+const file = await createFileReader('./data.xlsx');
+try {
+  console.log((await new SheetReader().readWorkbook(file)).sheets);
+} finally {
+  await file.close();
+}
 ```
 
 ### Writing an Excel File
@@ -243,7 +254,7 @@ writer.addSheet('Report', rows, {
   protection: { password: 'secret', sort: true },  // Excel's legacy hash: deters edits, is not encryption
   pageSetup: { orientation: 'landscape', paperSize: 9, fitToWidth: 1, fitToHeight: 0, printArea: 'A1:C100', printTitleRows: '1', footer: '&CPage &P of &N' },
   tabColor: 'FF00B050',
-  mergeCells: ['A1:C1'],
+  mergeCells: ['E1:G1'],   // not inside a table: Excel tables cannot hold merged cells
   columnWidths: [30, 12],  // in characters; `columns[i].width` wins where both are set
   autoFitColumns: true,    // widths from the longest value (array rows only)
 });
@@ -253,11 +264,11 @@ writer.addSheet('Report', rows, {
 
 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.
+Strings are written inline, which keeps memory flat. `new SheetWriter({ sharedStrings: true })` stores each distinct string once instead. Files are smaller when many different strings repeat (with only a handful of distinct values, inline strings compress as well or better), but the distinct strings stay in memory until the file is finished.
 
 ## Compared with SheetJS and ExcelJS
 
-Checked against each project's own documentation on 8 October 2026. "Pro" means a paid add-on.
+Checked against each project's own documentation, and ExcelJS 4.4.0's published code, on 9 October 2026. "Pro" means a paid add-on.
 
 | | XlsxFlow | SheetJS Community Edition | ExcelJS 4.4 |
 |---|---|---|---|
@@ -268,7 +279,7 @@ Checked against each project's own documentation on 8 October 2026. "Pro" means
 | `.ods` | Read and write | Read and write | No |
 | `.xlsb`, `.numbers` and other formats | No | Yes | No |
 | Charts | Add (Pro) | No (SheetJS Pro) | No |
-| Pivot tables | Add (Pro) | No (SheetJS Pro) | Partial, undocumented |
+| Pivot tables | Add (Pro) | No (SheetJS Pro) | No |
 | Password-protected files | Open and save (Pro) | Old `.xls` obfuscation only (SheetJS Pro opens AES files) | No |
 | Licence | MIT, Pro is paid | Apache 2.0 | MIT |
 
@@ -276,16 +287,26 @@ SheetJS reads and writes far more formats, and ExcelJS has a longer track record
 October 2023). XlsxFlow focuses on `.xlsx`: streaming in flat memory, keeping everything in a file it edits,
 and running on Web APIs alone.
 
+## Testing
+
+Every push and pull request runs, [in public CI](https://github.com/xlsxflow/xlsxflow/actions/workflows/ci.yml):
+
+- the test suite (nearly 400 tests, including fuzzing with malformed ZIP and XML input and files saved by Excel, LibreOffice, SheetJS, ExcelJS, openpyxl and xlsx-populate) on Node 20, 22 and 24, with 96% line coverage;
+- the README's claims, checked in Node, Bun, Deno, Chromium, Firefox, WebKit and Cloudflare Workers;
+- written and edited workbooks validated against the Office Open XML schema with Microsoft's [Open XML SDK](https://github.com/dotnet/Open-XML-SDK), then opened and recalculated in LibreOffice.
+
+[OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/xlsxflow/xlsxflow) and CodeQL check the repository, and npm releases are published from CI with [provenance](https://docs.npmjs.com/generating-provenance-statements).
+
 ## Benchmarks
 
-Write benchmark: 10 numeric columns, at 100,000 rows (1M cells) and 1,000,000 rows (10M cells). Each library ran in its own process on Node v25.8.2 with a 4 GB heap limit, and "Heap" is the growth in heap usage. Times are from one run on a laptop with other apps open; runs on that machine varied by up to 2×, so treat differences under about 20% as a tie. Reproduce with `npx tsx scripts/benchmark-competitors.ts` (inside `packages/core`, after `pnpm build`). `BENCH_ROWS=1000000` runs 10M cells, `BENCH_LIBS=xlsxflow,exceljs` runs a subset, and a library still writing after `BENCH_TIMEOUT_MIN` minutes (default 10) is stopped. The 10M runs for SheetJS and excel4node used a 30-minute limit.
+Write benchmark: 10 numeric columns, at 100,000 rows (1M cells) and 1,000,000 rows (10M cells). Each library ran in its own process on Node v25.8.2 with a 4 GB heap limit, and "Heap" is the growth in heap usage. XlsxFlow and ExcelJS times are medians of five alternating runs (XlsxFlow 1.1.6 was faster in all five at both sizes); the other libraries' times are from one run. The laptop had other apps open and single runs varied by up to 2×, so treat differences under about 20% as a tie. Reproduce with `npx tsx scripts/benchmark-competitors.ts` (inside `packages/core`, after `pnpm build`). `BENCH_ROWS=1000000` runs 10M cells, `BENCH_LIBS=xlsxflow,exceljs` runs a subset, and a library still writing after `BENCH_TIMEOUT_MIN` minutes (default 10) is stopped. The 10M runs for SheetJS and excel4node used a 30-minute limit.
 
 1M cells:
 
 | Library | Write Time | File Size | Heap |
 |---|---|---|---|
-| **XlsxFlow** | **2,899 ms** | **2.9 MB** | **+2 MB** |
-| ExcelJS 4.4 (streaming writer) | 3,397 ms | 3.0 MB | +9 MB |
+| **XlsxFlow** | **1,723 ms** | **2.9 MB** | **+2 MB** |
+| ExcelJS 4.4 (streaming writer) | 2,290 ms | 3.0 MB | +9 MB |
 | SheetJS 0.20.3, `compression: true` | 4,370 ms | 8.4 MB | +140 MB |
 | SheetJS 0.20.3, default options | 5,379 ms | 31.4 MB | +140 MB |
 | write-excel-file | 7,681 ms | 2.8 MB | +2 MB |
@@ -297,8 +318,8 @@ Write benchmark: 10 numeric columns, at 100,000 rows (1M cells) and 1,000,000 ro
 
 | Library | Write Time | File Size | Heap |
 |---|---|---|---|
-| **XlsxFlow** | **19.5 s** | **29.9 MB** | **+1 MB** |
-| ExcelJS 4.4 (streaming writer) | 22.0 s | 31.2 MB | +7 MB |
+| **XlsxFlow** | **19.1 s** | **29.9 MB** | **+2 MB** |
+| ExcelJS 4.4 (streaming writer) | 20.5 s | 31.2 MB | +7 MB |
 | write-excel-file | 68.1 s | 29.3 MB | +1 MB |
 | xlsx-populate | 75.3 s | 30.0 MB | +1,118 MB |
 | SheetJS 0.20.3 (with and without compression) | not finished after 30 min | | |

package/dist/index.cjs

@@ -58,21 +58,41 @@ class ZipStreamWriter {
         // Stream data, tracking sizes and CRC32
         let uncompressedSize = 0;
         let crc = 0xffffffff;
-        const crcStream = new TransformStream({
-            // CompressionStream takes every write at once, so the input is held back here instead,
-            // while nobody reads the output
-            transform: async (chunk, controller) => {
-                await this.roomInQueue();
-                uncompressedSize += chunk.length;
-                crc = crc32Update(crc, chunk);
-                controller.enqueue(chunk);
+        const compressor = new CompressionStream('deflate-raw');
+        const writer = compressor.writable.getWriter();
+        const reader = compressor.readable.getReader();
+        const input = inputStream.getReader();
+        // Node's and Bun's CompressionStream accept thousands of writes without backpressure, so only a few
+        // chunks are fed ahead: a write resolves once the chunk is compressed, which waits while nobody reads
+        // the output. Rows are then only pulled as fast as the ZIP is consumed.
+        // A few writes in flight keep the compressor busy while the next chunk is built
+        const inFlight = [];
+        const feed = (async () => {
+            try {
+                while (true) {
+                    const { done, value } = await input.read();
+                    if (done)
+                        break;
+                    await this.roomInQueue();
+                    uncompressedSize += value.length;
+                    crc = crc32Update(crc, value);
+                    const written = writer.write(value);
+                    written.catch(() => { }); // after a failure, writes nobody awaits any more must not go unhandled
+                    inFlight.push(written);
+                    if (inFlight.length >= 4)
+                        await inFlight.shift();
+                }
+                await Promise.all(inFlight);
+                await writer.close();
             }
-        });
+            catch (err) {
+                // Stop the source too (a row generator's finally runs, a database cursor closes)
+                await input.cancel(err).catch(() => { });
+                await writer.abort(err).catch(() => { });
+                throw err;
+            }
+        })();
         let compressedSize = 0;
-        const reader = inputStream
-            .pipeThrough(crcStream)
-            .pipeThrough(new CompressionStream('deflate-raw'))
-            .getReader();
         try {
             while (true) {
                 const { done, value } = await reader.read();
@@ -81,10 +101,12 @@ class ZipStreamWriter {
                 compressedSize += value.length;
                 await this.pushChunk(value);
             }
+            await feed;
         }
         catch (err) {
-            // Stop the source too (a row generator's finally runs, a database cursor closes)
             await reader.cancel(err).catch(() => { });
+            await input.cancel(err).catch(() => { });
+            await feed.catch(() => { });
             throw err;
         }
         crc = (crc ^ 0xffffffff) >>> 0;
@@ -3858,6 +3880,10 @@ class SheetWriter {
                 const box = parseRange$1(table.ref, 'table range');
                 if (boxes.some(b => overlaps(b, box)))
                     throw new Error(`Table "${table.name}" overlaps another table on sheet "${sheet.name}".`);
+                // Excel tables cannot hold merged cells: it repairs the file by removing the table
+                const merge = sheet.options.mergeCells?.find(ref => overlaps(parseRange$1(ref, 'merge range'), box));
+                if (merge)
+                    throw new Error(`Merge "${merge}" overlaps table "${table.name}" on sheet "${sheet.name}"; Excel tables cannot contain merged cells.`);
                 boxes.push(box);
                 const first = colIndex(m[1]);
                 const width = colIndex(m[3]) - first + 1;
@@ -4359,8 +4385,18 @@ function createBlobReader(blob) {
             return new Uint8Array(await slice.arrayBuffer());
         },
         stream(offset, length) {
-            const slice = blob.slice(offset, offset + length);
-            return slice.stream();
+            // Bun's Blob.slice(start, end).stream() runs on to the end of the original blob, so stop at length
+            let left = length;
+            return blob.slice(offset, offset + length).stream().pipeThrough(new TransformStream({
+                start(controller) { if (left <= 0)
+                    controller.terminate(); },
+                transform(chunk, controller) {
+                    controller.enqueue(chunk.length > left ? chunk.subarray(0, left) : chunk);
+                    left -= chunk.length;
+                    if (left <= 0)
+                        controller.terminate();
+                }
+            }));
         },
         async close() { }
     };