@justybase/spreadsheet-tasks 2.1.0 → 2.2.0

package/docs/API.md

@@ -7,7 +7,9 @@
 - [XlsbReader](#xlsbreader)
 - [XlsxReader](#xlsxreader)
 - [XlsxUpdater](#xlsxupdater)
+- [XlsmUpdater](#xlsmupdater)
 - [XlsbUpdater](#xlsbupdater)
+- [Excel conversion](#excel-conversion)
 - [ReaderFactory](#readerfactory)
 - [Types](#types)
 
@@ -243,8 +245,9 @@ new XlsxUpdater(filePath: string)
 **Parameters:**
 - `filePath` - Path to an existing `.xlsx` file
 
-Throws if the file does not exist, is not a valid XLSX, or is an XLSB
-(XLSB updates are not supported yet).
+Throws if the file does not exist, is not a valid XLSX package, or is an XLSB.
+Macro-enabled `.xlsm` packages can use the explicit [XlsmUpdater](#xlsmupdater)
+alias; unknown VBA members are preserved.
 
 **Example:**
 ```typescript
@@ -298,10 +301,28 @@ updater.save('report_new.xlsx');
 Writes the updated workbook to disk. When `outputPath` is omitted, the source
 file is overwritten in place.
 
+#### `replaceSheetDataStream(sheetName: string, rows: RowSource, options?: ReplaceSheetDataOptions): Promise<void>`
+
+Replaces worksheet rows from a synchronous or asynchronous one-pass row source.
+The row source is processed incrementally and is not collected into a complete
+2D array. Use `saveStreaming()` to also avoid materialising the final ZIP buffer.
+
+#### `saveStreaming(outputPath?: string): Promise<void>`
+
+Writes the updated package through a temporary file and installs it atomically.
+Staged worksheet parts are streamed; `save()` remains the simpler synchronous
+buffering path.
+
 #### `toBuffer(): Buffer`
 
 Returns the updated workbook as an in-memory ZIP buffer.
 
+## XlsmUpdater
+
+`XlsmUpdater` is an explicit alias of `XlsxUpdater` for macro-enabled `.xlsm`
+packages. It has the same API as `XlsxUpdater` and preserves VBA parts without
+parsing or modifying them.
+
 ---
 
 ## XlsbUpdater
@@ -382,6 +403,56 @@ Returns the updated workbook as an in-memory ZIP buffer.
 
 ---
 
+## Excel conversion
+
+Excel conversion uses the installed desktop Microsoft Excel through COM. It is
+available in the Node.js build on Windows only; the browser build does not
+expose these functions.
+
+### `ExcelConversionOptions`
+
+```typescript
+interface ExcelConversionOptions {
+    overwrite?: boolean;
+}
+```
+
+`overwrite` defaults to `false`. Existing destination files are rejected unless
+it is explicitly set to `true`.
+
+### `convertXlsbToXlsx`
+
+```typescript
+convertXlsbToXlsx(
+    inputPath: string,
+    outputPath: string,
+    options?: ExcelConversionOptions
+): Promise<void>
+```
+
+Converts an existing `.xlsb` file to `.xlsx` using Excel `SaveAs` format 51.
+
+### `convertXlsxToXlsb`
+
+```typescript
+convertXlsxToXlsb(
+    inputPath: string,
+    outputPath: string,
+    options?: ExcelConversionOptions
+): Promise<void>
+```
+
+Converts an existing `.xlsx` file to `.xlsb` using Excel `SaveAs` format 50.
+
+Both functions reject invalid extensions, missing files, protected
+destinations, unavailable COM automation, and Excel errors. The source is
+opened read-only and the destination is first written to a temporary file.
+
+```typescript
+await convertXlsbToXlsx('report.xlsb', 'report.xlsx');
+await convertXlsxToXlsb('report.xlsx', 'report.xlsb', { overwrite: true });
+```
+
 ## ReaderFactory
 
 Factory class for creating appropriate reader based on file extension.
@@ -418,6 +489,16 @@ await reader.open('data.xlsb');
 | `Date` | Date Serial Number |
 | `null` / `undefined` | Empty Cell |
 
+### `RowSource`
+
+```typescript
+type RowSource =
+  | Iterable<ReadonlyArray<CellValue>>
+  | AsyncIterable<ReadonlyArray<CellValue>>;
+```
+
+Used by `replaceSheetDataStream()` in both updater classes.
+
 ### Sheet Name Restrictions
 
 Sheet names have the following restrictions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justybase/spreadsheet-tasks",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "High-performance TypeScript library for reading and writing Excel files in XLSB and XLSX formats. XLSB is 3.3x faster to write and 2.3x faster to read than XLSX.",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -29,9 +29,10 @@
     "typecheck": "tsc --noEmit",
     "test": "npm run typecheck && npm run test:smoke && npm run test:unit && npm run test:integration && npm run test:dist",
     "test:smoke": "npx ts-node tests/smoke.test.ts",
-    "test:unit": "npx ts-node tests/unit/bigbuffer.test.ts && npx ts-node tests/unit/biff-reader-writer.test.ts && npx ts-node tests/unit/xlsb-writer.test.ts",
+    "test:unit": "npx ts-node tests/unit/bigbuffer.test.ts && npx ts-node tests/unit/biff-reader-writer.test.ts && npx ts-node tests/unit/xlsb-writer.test.ts && npx ts-node tests/unit/excel-converter.test.ts && npx ts-node tests/unit/updater-streaming.test.ts",
     "test:integration": "npx ts-node tests/integration/xlsb-writer.test.ts && npx ts-node tests/integration/xlsx-writer.test.ts && npx ts-node tests/integration/xlsx-updater.test.ts && npx ts-node tests/integration/xlsb-updater.test.ts",
     "test:dist": "npm run build && npx ts-node tests/dist-surface.test.ts",
+    "test:excel-conversion": "npm run build && npx ts-node tests/excel-compat/conversion.ts",
     "test:xlsb": "npx ts-node tests/integration/xlsb-writer.test.ts && npx ts-node tests/integration/xlsb-updater.test.ts",
     "test:xlsx": "npx ts-node tests/integration/xlsx-writer.test.ts",
     "benchmark": "npm run build && npx ts-node benchmarks/performance.bench.ts",