@xlsxflow/core 1.1.6 → 1.1.7

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.1.7
+
+### Added
+
+- Migration guides from [ExcelJS](https://github.com/xlsxflow/xlsxflow/blob/main/docs/migrating-from-exceljs.md) and [SheetJS](https://github.com/xlsxflow/xlsxflow/blob/main/docs/migrating-from-sheetjs.md), and [recipes](https://github.com/xlsxflow/xlsxflow/blob/main/examples/README.md) for streaming downloads, uploads, database exports and browser downloads. CI runs the recipes on every push.
+
+### Changed
+
+- On a runtime without `CompressionStream` or `DecompressionStream` for `deflate-raw` (Chrome before 103, Firefox before 113, Safari before 16.4), reading and writing throw an error naming the minimum versions instead of a bare `ReferenceError` or `TypeError`.
+
 ## 1.1.6
 
 ### Changed

package/README.md

@@ -9,6 +9,7 @@
   [![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)
+  [![OpenSSF Best Practices](https://img.shields.io/cii/level/15329?label=OpenSSF%20Best%20Practices&style=flat-square)](https://www.bestpractices.dev/projects/15329)
 
   <p>
     <a href="#features">Features</a> •
@@ -16,6 +17,7 @@
     <a href="#quick-start">Quick Start</a> •
     <a href="#styles-formulas--conditional-formats">Styles &amp; Formulas</a> •
     <a href="#compared-with-sheetjs-and-exceljs">Comparison</a> •
+    <a href="#recipes-and-migration-guides">Recipes</a> •
     <a href="#benchmarks">Benchmarks</a> •
     <a href="#free-and-pro">Free and Pro</a>
   </p>
@@ -31,7 +33,7 @@ Rows are read and written one at a time instead of loading the whole workbook, s
 
 - **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 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`).
+- **Runs anywhere with Web APIs**: tested on Node 20.12 and later, Bun, Deno, Chrome, Firefox, Safari (WebKit) and Cloudflare Workers (without `nodejs_compat`). Browsers need `CompressionStream` with `deflate-raw`: Chrome 103+, Firefox 113+, Safari 16.4+; older ones get an error saying so.
 - **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`.
@@ -287,15 +289,21 @@ 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.
 
+## Recipes and migration guides
+
+- [Recipes](https://github.com/xlsxflow/xlsxflow/blob/main/examples/README.md): streaming downloads from Next.js, Cloudflare Workers, Bun, Deno and Express; reading uploads; exporting a database table; an "Export to Excel" button in the browser. Each runs in CI.
+- [Migrating from ExcelJS](https://github.com/xlsxflow/xlsxflow/blob/main/docs/migrating-from-exceljs.md) and [Migrating from SheetJS](https://github.com/xlsxflow/xlsxflow/blob/main/docs/migrating-from-sheetjs.md): each common task in both libraries, side by side, and what works differently.
+
 ## 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;
+- the test suite (nearly 400 tests, including fuzz and property-based tests with [fast-check](https://fast-check.dev) on 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, and the [recipes](https://github.com/xlsxflow/xlsxflow/blob/main/examples/README.md);
+- 10M cells written to disk and read back with Node's heap capped at 32 MB, smaller than the 34 MB file;
 - 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).
+The project holds the [OpenSSF Best Practices](https://www.bestpractices.dev/projects/15329) passing badge; [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
 

package/dist/index.cjs

@@ -13,6 +13,15 @@ const CRC_TABLE = (() => {
 function crc32(bytes) {
     return (crc32Update(0xffffffff, bytes) ^ 0xffffffff) >>> 0;
 }
+// Older runtimes lack CompressionStream or its 'deflate-raw' format; say what is needed instead of a bare ReferenceError
+function deflateRaw(kind) {
+    try {
+        return (kind === 'compress' ? new CompressionStream('deflate-raw') : new DecompressionStream('deflate-raw'));
+    }
+    catch {
+        throw new Error(`XlsxFlow needs ${kind === 'compress' ? 'CompressionStream' : 'DecompressionStream'} with 'deflate-raw': Chrome 103+, Firefox 113+, Safari 16.4+, Node 20.12+, Deno, Bun or Cloudflare Workers`);
+    }
+}
 // Running CRC-32 over chunks: start at 0xffffffff, finish with (crc ^ 0xffffffff) >>> 0
 function crc32Update(crc, bytes) {
     for (let i = 0; i < bytes.length; i++)
@@ -58,7 +67,7 @@ class ZipStreamWriter {
         // Stream data, tracking sizes and CRC32
         let uncompressedSize = 0;
         let crc = 0xffffffff;
-        const compressor = new CompressionStream('deflate-raw');
+        const compressor = deflateRaw('compress');
         const writer = compressor.writable.getWriter();
         const reader = compressor.readable.getReader();
         const input = inputStream.getReader();
@@ -505,7 +514,7 @@ class ZipRandomAccessParser {
         }
         const stream = await this.extractRawStream(filename);
         const data = record.compressionMethod === 0 ? stream
-            : stream.pipeThrough(new DecompressionStream('deflate-raw'));
+            : stream.pipeThrough(deflateRaw('decompress'));
         // Node reports bad deflate data as a bare TypeError; name the entry instead
         const inflated = data.getReader();
         let total = 0;