@justybase/spreadsheet-tasks 1.3.3 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+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).
+
+## [2.1.0] - 2026-08-07
+
+### Added
+
+- `XlsxUpdater` and `XlsbUpdater` — replace the data of a worksheet inside an
+  existing `.xlsx` / `.xlsb` file without rebuilding the workbook. Pivot tables,
+  other sheets, styles and defined names are preserved; shared strings are
+  appended (never reordered), column styles are inherited, and pivot cache
+  ranges + `refreshOnLoad` are updated automatically.
+- Shared helpers: `xmlUtils.ts` (XML escaping, column letters, shared strings
+  parsing) and `biff12Utils.ts` (BIFF12 record helpers for XLSB).
+- `examples/update-existing.ts` — end-to-end example for refreshing a data
+  sheet in an existing XLSX / XLSB report.
+
+### Fixed
+
+- `XlsbUpdater` pivot source range was one row too long when `headers` were not
+  provided, causing an empty trailing row (and a "(blank)" item in pivot
+  tables). The range now ends exactly at the last data row.
+- Both updaters now trim trailing rows that contain only empty cells (padding
+  rows from SQL exports), so they don't appear as "(blank)" in pivot tables.
+- `XlsbUpdater` no longer removes the worksheet's row-block terminator records
+  (0x92/0x217/0x1dd/0x1dc) and keeps the sheet dimension record (0x98) in sync
+  with the new row count — without these, Excel hid the last written row.
+
+## [2.0.0] - 2026-07-25
+
+### Breaking
+
+- `XlsbReader.read()` is now `async` and returns `Promise<boolean>` (same as `XlsxReader`).
+  Update loops from `while (reader.read())` to `while (await reader.read())`.
+- Package entry points moved under `dist/cjs` and `dist/esm` with an `exports` map.
+  Most consumers of `@justybase/spreadsheet-tasks` need no import path changes.
+
+### Added
+
+- `CellValue` / `PrimitiveCellValue` types for writer and reader cell APIs
+- Shared writer helpers: `sanitizeSheetName`, column-width helpers, `StreamingSheetState`
+- Dual package build (CJS + ESM) via `tsup`
+- Browser sources under `src/browser/` with `npm run build:browser`
+- `docs/PACKAGING.md` (ZIP library rationale + dual package notes)
+- Dist surface smoke test (`npm run test:dist`)
+
+### Changed
+
+- `XlsbWriter` / `XlsxWriter` share sanitization, autofit, and streaming state helpers
+- Tests import from `src/` (published surface still verified via `test:dist`)
+- ZIP type definitions use `@types/*` only (hand-written ambient modules removed)
+
+### Browser
+
+- Source of truth is TypeScript in `src/browser/`; `browser/*.js` writer sources are generated bundles
+
+## [1.3.2] - previous
+
+See git history for 1.x changes.

package/README.md

@@ -1,72 +1,112 @@
-# SpreadsheetTasks
+# @justybase/spreadsheet-tasks
 
-A high-performance TypeScript library for reading and writing Excel files in XLSB and XLSX formats.
+High-performance TypeScript library for reading and writing Excel files in XLSB and XLSX formats.
 
-[![npm version](https://badge.fury.io/js/@justybase%2Fspreadsheet-tasks.svg)](https://www.npmjs.com/package/@justybase/spreadsheet-tasks)
+[![npm version](https://img.shields.io/npm/v/@justybase/spreadsheet-tasks.svg)](https://www.npmjs.com/package/@justybase/spreadsheet-tasks)
+[![CI](https://github.com/justybase/justybase_spreadsheet_tasks/actions/workflows/ci.yml/badge.svg)](https://github.com/justybase/justybase_spreadsheet_tasks/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## 🚀 Features
-
-- **High Performance** - XLSB format is 3.3x faster to write and 2.1x faster to read than XLSX
-- **Small File Size** - XLSB files are ~47% smaller than equivalent XLSX files
-- **TypeScript First** - Full TypeScript support with type definitions
-- **Dual Format Support** - Read and write both XLSB and XLSX formats
-- **Zero External Dependencies** - Uses only Node.js built-in modules and minimal zip libraries
-- **Streaming Support** - Efficient memory usage for large files
-- **Multiple Sheets** - Support for multiple worksheets per workbook
-- **Auto-filter** - Automatic filter headers support
-
-## 📊 Benchmark Results
+## Table of Contents
+
+- [Features](#features)
+- [Benchmark Results](#benchmark-results)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Browser Support](#browser-support)
+- [Quick Start](#quick-start)
+- [API Documentation](#api-documentation)
+- [Examples](#examples)
+- [When to Use XLSB vs XLSX](#when-to-use-xlsb-vs-xlsx)
+- [Contributing](#contributing)
+- [License](#license)
+- [Acknowledgments](#acknowledgments)
+
+## Features
+
+- **High Performance** — XLSB is about 3.3× faster to write and 2.3× faster to read than XLSX (see [benchmarks](#benchmark-results))
+- **Small File Size** — XLSB files are ~47% smaller than equivalent XLSX files
+- **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
+- **Multiple Sheets** — Support for multiple worksheets per workbook
+- **Auto-filter** — Automatic filter headers support
+- **In-place Updates** — Replace the data of a worksheet inside an existing XLSX or XLSB (e.g. `report.xlsx` / `report.xlsb`) while keeping pivot tables, other sheets and formatting untouched
+
+## Benchmark Results
+
+Measured with `npm run benchmark` (50K rows). Your results may vary by hardware and dataset.
 
 | Operation | XLSB | XLSX | Performance Gain |
 |-----------|------|------|------------------|
-| Write (50K rows) | 140 ms | 467 ms | **3.3x faster** |
-| Read (50K rows) | 118 ms | 276 ms | **2.3x faster** |
+| Write (50K rows) | 140 ms | 467 ms | **3.3× faster** |
+| Read (50K rows) | 118 ms | 276 ms | **2.3× faster** |
 | File Size | 1.49 MB | 2.83 MB | **47% smaller** |
 
-## 📦 Installation
+## Requirements
+
+- **Node.js** 16 or newer ([`engines`](./package.json) in `package.json`)
+
+## Installation
 
 ```bash
 npm install @justybase/spreadsheet-tasks
 ```
 
-## 🌐 Browser Support & CDN (Zero Dependencies)
+CommonJS:
+
+```js
+const { XlsbWriter } = require('@justybase/spreadsheet-tasks');
+```
+
+ES modules:
+
+```js
+import { XlsbWriter } from '@justybase/spreadsheet-tasks';
+```
 
-This library includes browser-compatible modules to generate XLSB and XLSX files directly on the client side without relying on Node.js APIs or external dependencies.
+## Browser Support
 
-To bundle the browser version into a single minified file (e.g. for deployment to a CDN), run the following command in the project root:
+Browser writers live in TypeScript under `src/browser/` and are bundled with:
 
 ```bash
-npx esbuild browser/browser-spreadsheet.js --bundle --minify --format=esm --outfile=browser/justybase-spreadsheet.min.js
+npm run build:browser
 ```
 
-You can then import this single file via a script tag in any web application:
+This produces:
+
+- `browser/justybase-spreadsheet.min.js` — IIFE (`JustybaseSpreadsheet` global)
+- `browser/browser-spreadsheet.js` — ESM for local demos (`demo.html`, `test.html`)
+
+The browser bundle has **no runtime npm dependencies** (ZIP logic is inlined).
 
 ```html
 <script type="module">
-  import { downloadXlsb, downloadXlsx } from 'https://your-cdn.com/justybase-spreadsheet.min.js';
-  
-  const headers = ["ID", "Name", "Score"];
+  import { downloadXlsb, downloadXlsx, F } from './browser-spreadsheet.js';
+
+  const headers = ['ID', 'Name', 'Score'];
   const rows = [
-    [1, "Alice", 99.5],
-    [2, "Bob", 88.0]
+    [1, 'Alice', 99.5],
+    [2, 'Bob', 88.0],
   ];
-  
-  // Generates the file and triggers the browser download automatically
+
   document.getElementById('downloadBtn').addEventListener('click', () => {
-    downloadXlsb('report.xlsb', rows, headers, { headerStyle: 'bold+fill' });
+    downloadXlsb('report.xlsb', rows, headers);
   });
 </script>
 ```
 
 **Features included in the browser build:**
-- Built-in Zip archiving (no external libraries needed)
+
+- Built-in ZIP archiving (no external libraries in the bundle)
 - Memory-efficient `Uint8Array` buffer handling
 - Auto-fitted column widths
 - Frozen and styled headers (styles: `bold`, `fill`, `bold+fill`)
 - Auto-filters enabled by default
 
-## 🔧 Quick Start
+See [CHANGELOG.md](./CHANGELOG.md) for v2 breaking changes (`await reader.read()`).
+
+## Quick Start
 
 ### Writing Excel Files
 
@@ -131,13 +171,13 @@ await writer.finalize();
 ```
 
 **Benefits of Streaming API:**
-- ✅ Constant memory usage regardless of dataset size
-- ✅ Write millions of rows without loading all data into RAM
-- ✅ Generate data on-the-fly from databases, APIs, or other sources
-- ✅ Same performance as batch mode
 
-### Reading Excel Files
+- Constant memory usage regardless of dataset size
+- Write millions of rows without loading all data into RAM
+- Generate data on-the-fly from databases, APIs, or other sources
+- Same performance as batch mode
 
+### Reading Excel Files
 
 ```typescript
 import { XlsbReader, XlsxReader, ReaderFactory } from '@justybase/spreadsheet-tasks';
@@ -148,7 +188,7 @@ await reader.open('data.xlsb');
 
 console.log('Sheet names:', reader.getSheetNames());
 
-while (reader.read()) {
+while (await reader.read()) {
     const row = [];
     for (let i = 0; i < reader.fieldCount; i++) {
         row.push(reader.getValue(i));
@@ -162,28 +202,69 @@ await xlsbReader.open('data.xlsb');
 // ... same API as above
 ```
 
-## 📖 API Documentation
+### Updating Data in an Existing Workbook
+
+`XlsxUpdater` and `XlsbUpdater` replace the cell data of a worksheet inside an
+existing workbook without rebuilding it. Everything else — pivot tables, charts,
+other sheets, styles, defined names — is preserved, so you can keep an advanced
+Excel file (like a report with pivot tables wired to a data sheet) and only
+refresh its data:
+
+```typescript
+import { XlsxUpdater, XlsbUpdater } from '@justybase/spreadsheet-tasks';
+
+// XLSX
+const xlsx = new XlsxUpdater('report.xlsx');
+xlsx.replaceSheetData('data1', rows, { headers: ['ID', 'NAME', 'AMOUNT'] });
+xlsx.save();                 // overwrite in place, or xlsx.save('report_new.xlsx')
+
+// XLSB — the same API
+const xlsb = new XlsbUpdater('report.xlsb');
+xlsb.replaceSheetData('data1', rows, { headers: ['ID', 'NAME', 'AMOUNT'] });
+xlsb.save('report_new.xlsb');
+```
+
+**What happens under the hood:**
+
+- The target sheet's cell data is cleared and replaced with the new rows.
+- New strings are appended to the shared strings table (existing entries and
+  their indices are never moved, so other sheets stay valid).
+- New cells reuse the dominant style of their column from the original data
+  (dates stay dates, numbers stay numbers). Pass `styleFallback: 'general'`
+  to write everything as General.
+- Pivot tables whose cache source is the updated sheet get their source range
+  and record count adjusted, and `refreshOnLoad` is enabled so Excel refreshes
+  them automatically on open.
+
+> **Tip:** always pass the `headers` matching the original columns. When
+> `headers` are omitted, the first data row lands in row 1 and becomes the
+> pivot's field names (Excel reads the first row of the source range as
+> headers), so the pivot's columns would be replaced by the first record's
+> values.
+
+## API Documentation
 
 See [API Documentation](./docs/API.md) for detailed API reference.
 
-## 💡 Examples
+## Examples
 
 Check out the [examples](./examples) folder for more usage examples:
 
-- [Basic Write](./examples/basic-write.ts) - Writing data to Excel files
-- [Basic Read](./examples/basic-read.ts) - Reading data from Excel files
-- [Multiple Sheets](./examples/multiple-sheets.ts) - Working with multiple worksheets
-- [Large Dataset](./examples/large-dataset.ts) - Handling large datasets efficiently
-- [Streaming Example](./examples/streaming-example.ts) - Write millions of rows without loading all data in memory
+- [Basic Write](./examples/basic-write.ts) — Writing data to Excel files
+- [Basic Read](./examples/basic-read.ts) — Reading data from Excel files
+- [Multiple Sheets](./examples/multiple-sheets.ts) — Working with multiple worksheets
+- [Update Existing Workbook](./examples/update-existing.ts) — Replacing the data of a sheet in an existing XLSX/XLSB with pivot tables
+- [Large Dataset](./examples/large-dataset.ts) — Handling large datasets efficiently
+- [Streaming Example](./examples/streaming-example.ts) — Write millions of rows without loading all data in memory
 
 Run examples with:
+
 ```bash
 npm run build
 npx ts-node examples/basic-write.ts
 ```
 
-
-## 🔍 When to Use XLSB vs XLSX
+## When to Use XLSB vs XLSX
 
 | Use XLSB When | Use XLSX When |
 |---------------|---------------|
@@ -192,14 +273,30 @@ npx ts-node examples/basic-write.ts
 | Internal/backend processing | Human-readable XML is needed |
 | Storage space is limited | Third-party integrations require it |
 
-## 🤝 Contributing
+## Contributing
+
+Contributions are welcome. To work on the project locally:
+
+```bash
+git clone https://github.com/justybase/justybase_spreadsheet_tasks.git
+cd justybase_spreadsheet_tasks
+npm install
+npm run build
+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.
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Please open an issue or pull request on [GitHub](https://github.com/justybase/justybase_spreadsheet_tasks).
 
-## 📄 License
+## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
 
-## 🙏 Acknowledgments
+## Acknowledgments
 
-- Inspired by and reimplemented from [SpreadSheetTasks](https://github.com/KrzysztofDusko/SpreadSheetTasks)
+- Inspired by and reimplemented from [SpreadSheetTasks](https://github.com/justybae/SpreadSheetTasks)