@justybase/spreadsheet-tasks 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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).
 
+## [Unreleased]
+
+### Added
+
+- `convertXlsbToXlsx` and `convertXlsxToXlsb` — Windows/Excel COM conversions
+  with protected destinations and optional explicit overwriting.
+- `replaceSheetDataStream()` and `saveStreaming()` for XLSX/XLSB updaters,
+  accepting synchronous or asynchronous row sources without collecting the
+  complete result set in memory.
+- `XlsmUpdater` as an explicit alias for `XlsxUpdater`; VBA package members are
+  preserved as opaque ZIP parts.
+
+### Fixed
+
+- Destination replacement during Excel conversion now preserves files created
+  concurrently and rolls back safely when the final rename fails.
+- Shared-string `count` values now reflect the replaced worksheet rather than
+  accumulating stale references across repeated updates. Pending strings are
+  committed only once.
+- Updater saves now install the destination atomically through a same-directory
+  temporary file.
+
 ## [2.1.0] - 2026-08-07
 
 ### Added

package/README.md

@@ -31,7 +31,8 @@ High-performance TypeScript library for reading and writing Excel files in XLSB
 - **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
+- **Excel COM Conversion** — Convert XLSB and XLSX through desktop Microsoft Excel on Windows
+- **In-place Updates** — Replace the data of a worksheet inside an existing XLSX, XLSM or XLSB while keeping pivot tables, other sheets and formatting untouched
 
 ## Benchmark Results
 
@@ -46,6 +47,7 @@ Measured with `npm run benchmark` (50K rows). Your results may vary by hardware
 ## Requirements
 
 - **Node.js** 16 or newer ([`engines`](./package.json) in `package.json`)
+- XLSB/XLSX conversion additionally requires Windows, PowerShell and desktop Microsoft Excel with COM automation
 
 ## Installation
 
@@ -211,7 +213,7 @@ 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';
+import { XlsxUpdater, XlsbUpdater, XlsmUpdater } from '@justybase/spreadsheet-tasks';
 
 // XLSX
 const xlsx = new XlsxUpdater('report.xlsx');
@@ -222,8 +224,26 @@ xlsx.save();                 // overwrite in place, or xlsx.save('report_new.xls
 const xlsb = new XlsbUpdater('report.xlsb');
 xlsb.replaceSheetData('data1', rows, { headers: ['ID', 'NAME', 'AMOUNT'] });
 xlsb.save('report_new.xlsb');
+
+// XLSM uses the XLSX updater and keeps opaque VBA parts intact.
+const xlsm = new XlsmUpdater('report.xlsm');
+xlsm.replaceSheetData('data1', rows, { headers: ['ID', 'NAME', 'AMOUNT'] });
+xlsm.save('report_new.xlsm');
 ```
 
+For a result set that should not be collected into a 2D array, use the additive
+streaming API. It accepts either a synchronous iterable or an async iterable and
+writes the final ZIP through a temporary file before installing it atomically:
+
+```typescript
+const updater = new XlsxUpdater('large-report.xlsx');
+await updater.replaceSheetDataStream('data1', databaseRows(), { headers });
+await updater.saveStreaming('large-report-updated.xlsx');
+```
+
+`save()` remains available for the existing synchronous API. Both save methods
+replace their destination atomically after a successful write.
+
 **What happens under the hood:**
 
 - The target sheet's cell data is cleared and replaced with the new rows.
@@ -242,6 +262,30 @@ xlsb.save('report_new.xlsb');
 > headers), so the pivot's columns would be replaced by the first record's
 > values.
 
+### Converting XLSB and XLSX with Excel
+
+On Windows, existing workbooks can be converted by asking the installed desktop
+Microsoft Excel to perform `SaveAs` through COM. The source file is opened
+read-only and the destination is written separately:
+
+```typescript
+import {
+    convertXlsbToXlsx,
+    convertXlsxToXlsb,
+} from '@justybase/spreadsheet-tasks';
+
+await convertXlsbToXlsx('report.xlsb', 'report.xlsx');
+await convertXlsxToXlsb('report.xlsx', 'report.xlsb');
+
+// Existing destinations are protected by default.
+await convertXlsbToXlsx('report.xlsb', 'report.xlsx', { overwrite: true });
+```
+
+Conversion is a Node.js-only API and requires Windows plus desktop Microsoft
+Excel. Unsupported files, unavailable COM automation, and Excel conversion
+errors are reported as rejected promises. VBA/macros are not guaranteed when
+the target format does not support them.
+
 ## API Documentation
 
 See [API Documentation](./docs/API.md) for detailed API reference.

package/dist/cjs/index.d.ts

@@ -367,6 +367,8 @@ interface ReplaceSheetDataOptions$1 {
      */
     styleFallback?: 'inherit' | 'general';
 }
+/** A one-pass synchronous or asynchronous source of worksheet rows. */
+type RowSource$1 = Iterable<ReadonlyArray<CellValue>> | AsyncIterable<ReadonlyArray<CellValue>>;
 /**
  * Update the data of a worksheet inside an existing XLSX file without rebuilding
  * the workbook. Everything outside the target sheet's cell data — pivot tables
@@ -383,6 +385,8 @@ interface ReplaceSheetDataOptions$1 {
 declare class XlsxUpdater {
     private readonly zip;
     private readonly sourcePath;
+    private temporaryDirectory;
+    private readonly stagedParts;
     private sheetNameToPath;
     private pivotCacheDefs;
     private pivotTableDefPaths;
@@ -390,12 +394,14 @@ declare class XlsxUpdater {
     private sharedStringsValues;
     private sharedStringsOriginalLength;
     private sharedStringsCount;
+    private sharedStringsPending;
+    private sharedStringsDirty;
     private stringIndexMap;
     private readonly _oaEpoch;
     /**
      * @param path Path to an existing `.xlsx` file.
      */
-    constructor(path: string);
+    constructor(filePath: string);
     /** Worksheet names in workbook order. */
     getSheetNames(): string[];
     /**
@@ -407,13 +413,36 @@ declare class XlsxUpdater {
      * @param options See {@link ReplaceSheetDataOptions}.
      */
     replaceSheetData(sheetName: string, rows: CellValue[][], options?: ReplaceSheetDataOptions$1): void;
+    /**
+     * Replace worksheet rows from a one-pass source without materialising the
+     * complete result set. Use {@link saveStreaming} to keep the final ZIP
+     * write streaming as well.
+     */
+    replaceSheetDataStream(sheetName: string, rows: RowSource$1, options?: ReplaceSheetDataOptions$1): Promise<void>;
     /**
      * Write the updated workbook to disk.
      * @param outputPath Destination path; defaults to the source file (overwrites in place).
      */
     save(outputPath?: string): void;
+    /** Save staged streaming replacements without materialising the ZIP. */
+    saveStreaming(outputPath?: string): Promise<void>;
     /** The updated workbook as an in-memory ZIP buffer. */
     toBuffer(): Buffer;
+    /**
+     * Release the staging directory and any unsaved staged parts.
+     * The updater remains usable; a new staging directory is created lazily
+     * on the next streaming replacement.
+     */
+    dispose(): void;
+    /** Support `using` declarations for automatic staging cleanup. */
+    [Symbol.dispose](): void;
+    private _ensureTemporaryDirectory;
+    private _temporaryPath;
+    private _removeTemporaryFile;
+    private _entryData;
+    private _stagePart;
+    private _discardStagedPart;
+    private _materializeStagedParts;
     private _loadWorkbookStructure;
     private _ensureSharedStringsLoaded;
     private _commitSharedStrings;
@@ -422,7 +451,10 @@ declare class XlsxUpdater {
     private _buildSheetData;
     private _valueCell;
     private _stringCell;
+    private static _replaceOrAddXmlAttribute;
+    private _sharedStringRefCount;
     private _patchSheetXml;
+    private _patchSheetFile;
     private _updatePivotCaches;
     private _addRefreshOnLoadToPivotTables;
 }
@@ -445,6 +477,8 @@ interface ReplaceSheetDataOptions {
      */
     styleFallback?: 'inherit' | 'general';
 }
+/** A one-pass synchronous or asynchronous source of worksheet rows. */
+type RowSource = Iterable<ReadonlyArray<CellValue>> | AsyncIterable<ReadonlyArray<CellValue>>;
 /**
  * Update the data of a worksheet inside an existing XLSB file without rebuilding
  * the workbook. Everything outside the target sheet's rows — pivot tables and
@@ -460,6 +494,8 @@ interface ReplaceSheetDataOptions {
 declare class XlsbUpdater {
     private readonly zip;
     private readonly sourcePath;
+    private temporaryDirectory;
+    private readonly stagedParts;
     private sheetNameToPath;
     private pivotCacheDefPaths;
     private sharedStringsBuf;
@@ -468,11 +504,12 @@ declare class XlsbUpdater {
     private sharedStringsUnique;
     private sharedStringsEndSst;
     private stringIndexMap;
+    private sharedStringsDirty;
     private readonly _oaEpoch;
     /**
      * @param path Path to an existing `.xlsb` file.
      */
-    constructor(path: string);
+    constructor(filePath: string);
     /** Worksheet names in workbook order. */
     getSheetNames(): string[];
     /**
@@ -484,13 +521,32 @@ declare class XlsbUpdater {
      * @param options See {@link ReplaceSheetDataOptions}.
      */
     replaceSheetData(sheetName: string, rows: CellValue[][], options?: ReplaceSheetDataOptions): void;
+    /** Replace worksheet rows from a one-pass source. */
+    replaceSheetDataStream(sheetName: string, rows: RowSource, options?: ReplaceSheetDataOptions): Promise<void>;
     /**
      * Write the updated workbook to disk.
      * @param outputPath Destination path; defaults to the source file (overwrites in place).
      */
     save(outputPath?: string): void;
+    /** Save staged streaming replacements without materialising the ZIP. */
+    saveStreaming(outputPath?: string): Promise<void>;
     /** The updated workbook as an in-memory ZIP buffer. */
     toBuffer(): Buffer;
+    /**
+     * Release the staging directory and any unsaved staged parts.
+     * The updater remains usable; a new staging directory is created lazily
+     * on the next streaming replacement.
+     */
+    dispose(): void;
+    /** Support `using` declarations for automatic staging cleanup. */
+    [Symbol.dispose](): void;
+    private _ensureTemporaryDirectory;
+    private _temporaryPath;
+    private _removeTemporaryFile;
+    private _entryData;
+    private _stagePart;
+    private _discardStagedPart;
+    private _materializeStagedParts;
     private _loadWorkbookStructure;
     private _appendCount;
     private _ensureSharedStringsLoaded;
@@ -500,6 +556,8 @@ declare class XlsbUpdater {
     private _buildRows;
     private _valueCellBytes;
     private _stringCellBytes;
+    private _sharedStringRefCount;
+    private _patchSheetMetadataFile;
     private _findRowsRegion;
     /**
      * Keep the sheet dimension record (0x98) in sync with the new data.
@@ -511,6 +569,16 @@ declare class XlsbUpdater {
     private _patchPivotCaches;
 }
 
+/** Options for an Excel format conversion. */
+interface ExcelConversionOptions {
+    /** Allow replacing an existing destination file. Defaults to false. */
+    overwrite?: boolean;
+}
+/** Convert an Excel Binary Workbook (.xlsb) to an Open XML Workbook (.xlsx). */
+declare function convertXlsbToXlsx(inputPath: string, outputPath: string, options?: ExcelConversionOptions): Promise<void>;
+/** Convert an Open XML Workbook (.xlsx) to an Excel Binary Workbook (.xlsb). */
+declare function convertXlsxToXlsb(inputPath: string, outputPath: string, options?: ExcelConversionOptions): Promise<void>;
+
 /** Excel sheet name characters that must be replaced. */
 declare const INVALID_SHEET_NAME_CHARS: RegExp;
 /**
@@ -556,4 +624,4 @@ declare class StreamingSheetState {
     end(): void;
 }
 
-export { BiffReaderWriter, BigBuffer, type CellValue, ExcelReaderAbstract, F, type FormattedCell, INVALID_SHEET_NAME_CHARS, type PrimitiveCellValue, ReaderFactory, type ReplaceSheetDataOptions$1 as ReplaceSheetDataOptions, StreamingSheetState, XlsbReader, type ReplaceSheetDataOptions as XlsbReplaceSheetDataOptions, XlsbUpdater, XlsbWriter, XlsxReader, XlsxUpdater, XlsxWriter, applyHeaderWidths, defaultColWidth, getFormat, initColWidths, isFormattedCell, sanitizeSheetName, unwrapCell, updateColWidthsFromRows };
+export { BiffReaderWriter, BigBuffer, type CellValue, type ExcelConversionOptions, ExcelReaderAbstract, F, type FormattedCell, INVALID_SHEET_NAME_CHARS, type PrimitiveCellValue, ReaderFactory, type ReplaceSheetDataOptions$1 as ReplaceSheetDataOptions, type RowSource$1 as RowSource, StreamingSheetState, XlsbReader, type ReplaceSheetDataOptions as XlsbReplaceSheetDataOptions, XlsbUpdater, XlsbWriter, XlsxUpdater as XlsmUpdater, XlsxReader, XlsxUpdater, XlsxWriter, applyHeaderWidths, convertXlsbToXlsx, convertXlsxToXlsb, defaultColWidth, getFormat, initColWidths, isFormattedCell, sanitizeSheetName, unwrapCell, updateColWidthsFromRows };