@justybase/spreadsheet-tasks 2.1.1 → 2.2.0

package/CHANGELOG.md

@@ -11,11 +11,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `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
 

package/README.md

@@ -32,7 +32,7 @@ High-performance TypeScript library for reading and writing Excel files in XLSB
 - **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
-- **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
+- **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
 
@@ -213,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');
@@ -224,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.

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.
@@ -566,4 +624,4 @@ declare class StreamingSheetState {
     end(): void;
 }
 
-export { BiffReaderWriter, BigBuffer, type CellValue, type ExcelConversionOptions, 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, convertXlsbToXlsx, convertXlsxToXlsb, 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 };