@justybase/spreadsheet-tasks 2.0.0 → 2.1.1

package/docs/API.md

@@ -6,6 +6,9 @@
 - [XlsxWriter](#xlsxwriter)
 - [XlsbReader](#xlsbreader)
 - [XlsxReader](#xlsxreader)
+- [XlsxUpdater](#xlsxupdater)
+- [XlsbUpdater](#xlsbupdater)
+- [Excel conversion](#excel-conversion)
 - [ReaderFactory](#readerfactory)
 - [Types](#types)
 
@@ -224,6 +227,212 @@ Gets value at the specified column index.
 
 ---
 
+## XlsxUpdater
+
+Updates the data of a worksheet inside an existing `.xlsx` file without rebuilding
+the workbook. Everything outside the target sheet's cell data — pivot tables and
+their caches, other sheets, styles, themes, defined names — is preserved, which
+makes it possible to refresh a data sheet that pivot tables / charts / formulas
+are wired to.
+
+### Constructor
+
+```typescript
+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).
+
+**Example:**
+```typescript
+const updater = new XlsxUpdater('report.xlsx');
+```
+
+### Methods
+
+#### `getSheetNames(): string[]`
+
+Returns the worksheet names in workbook order.
+
+#### `replaceSheetData(sheetName: string, rows: CellValue[][], options?: ReplaceSheetDataOptions): void`
+
+Clears the entire cell data of the target sheet and writes new rows in its place.
+
+**Parameters:**
+- `sheetName` - Name of the worksheet to replace. Throws if not found.
+- `rows` - 2D array of new data (`null` / `undefined` cells stay empty).
+  Trailing rows that contain no non-empty cells are trimmed so the written
+  range matches the actual data (pivot tables won't pick up "(blank)" items
+  from padding rows).
+- `options` - Optional object:
+  - `headers?: string[]` - Optional header row written into row 1
+  - `styleFallback?: 'inherit' | 'general'` - Style strategy for new cells
+    (default `'inherit'`)
+
+**Behavior:**
+- The sheet's `<dimension>` and `<autoFilter>` ranges are recalculated and end
+  exactly at the last data row.
+- When `headers` are omitted, the first data row lands in row 1 and becomes the
+  pivot's field names — always pass `headers` matching the original columns.
+- New strings are appended to `xl/sharedStrings.xml` (existing entries and their
+  indices are never modified); files without a shared string table use inline strings.
+- With `styleFallback: 'inherit'` (default), new cells reuse the dominant style
+  of their column from the existing data, and `Date` cells fall back to a date
+  style found in `styles.xml` when the column has none.
+- Pivot tables whose `worksheetSource` references the updated sheet get their
+  `ref` and `recordCount` adjusted, and `refreshOnLoad="1"` is added to the
+  pivot table definitions so Excel refreshes them on open.
+
+**Example:**
+```typescript
+const updater = new XlsxUpdater('report.xlsx');
+updater.replaceSheetData('data1', rows, { headers: ['ID', 'NAME'] });
+updater.save('report_new.xlsx');
+```
+
+#### `save(outputPath?: string): void`
+
+Writes the updated workbook to disk. When `outputPath` is omitted, the source
+file is overwritten in place.
+
+#### `toBuffer(): Buffer`
+
+Returns the updated workbook as an in-memory ZIP buffer.
+
+---
+
+## XlsbUpdater
+
+Updates the data of a worksheet inside an existing `.xlsb` file without
+rebuilding the workbook. Everything outside the target sheet's rows — pivot
+tables and their caches, other sheets, styles, column widths, views — is
+preserved byte-for-byte.
+
+The API is identical to [XlsxUpdater](#xlsxupdater); see that section for the
+behavior of `replaceSheetData` (inherited column styles, shared-strings
+appending, pivot cache range + `refreshOnLoad`).
+
+### Constructor
+
+```typescript
+new XlsbUpdater(filePath: string)
+```
+
+**Parameters:**
+- `filePath` - Path to an existing `.xlsb` file
+
+Throws if the file does not exist, is not a valid XLSB, or is an XLSX
+(XLSB-only updater).
+
+### Methods
+
+#### `getSheetNames(): string[]`
+
+Returns the worksheet names in workbook order.
+
+#### `replaceSheetData(sheetName: string, rows: CellValue[][], options?: ReplaceSheetDataOptions): void`
+
+Clears the entire cell data of the target sheet and writes new rows in its place.
+
+**Parameters:**
+- `sheetName` - Name of the worksheet to replace. Throws if not found.
+- `rows` - 2D array of new data (`null` / `undefined` cells stay empty).
+  Trailing rows that contain no non-empty cells are trimmed so the written
+  range matches the actual data (pivot tables won't pick up "(blank)" items
+  from padding rows).
+- `options` - Optional object:
+  - `headers?: string[]` - Optional header row written into row 1
+  - `styleFallback?: 'inherit' | 'general'` - Style strategy for new cells
+    (default `'inherit'`)
+
+**Behavior:**
+- Only the worksheet's row records are replaced; column widths, views, and all
+  other sheet records are preserved. Auto-filter ranges are recalculated.
+- The sheet's dimension record and the pivot cache source range end exactly at
+  the last data row.
+- When `headers` are omitted, the first data row lands in row 1 and becomes the
+  pivot's field names — always pass `headers` matching the original columns.
+- New strings are appended to `xl/sharedStrings.bin` (existing entries and their
+  indices are never modified).
+- With `styleFallback: 'inherit'` (default), new cells reuse the dominant cell
+  style (xf) of their column from the existing data, and `Date` cells fall back
+  to a date style found in `styles.bin` when the column has none.
+- Pivot caches whose `worksheetSource` references the updated sheet get their
+  range and record count adjusted, and the `refreshOnLoad` flag is set so Excel
+  refreshes them on open.
+
+**Example:**
+```typescript
+const updater = new XlsbUpdater('report.xlsb');
+updater.replaceSheetData('data1', rows, { headers: ['ID', 'NAME'] });
+updater.save('report_new.xlsb');
+```
+
+#### `save(outputPath?: string): void`
+
+Writes the updated workbook to disk. When `outputPath` is omitted, the source
+file is overwritten in place.
+
+#### `toBuffer(): Buffer`
+
+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.

package/examples/basic-read.ts

@@ -7,7 +7,7 @@
  * Run with: npx ts-node examples/basic-read.ts
  */
 
-import { XlsbReader, XlsxReader, ReaderFactory } from '../dist';
+import { XlsbReader, XlsxReader, ReaderFactory } from '../dist/cjs';
 import * as path from 'path';
 
 async function readXlsbExample() {

package/examples/basic-write.ts

@@ -7,7 +7,7 @@
  * Run with: npx ts-node examples/basic-write.ts
  */
 
-import { XlsbWriter, XlsxWriter } from '../dist';
+import { XlsbWriter, XlsxWriter } from '../dist/cjs';
 import * as path from 'path';
 import * as fs from 'fs';
 

package/examples/datetime-widths.ts

@@ -8,7 +8,7 @@
  * Run with: npx ts-node examples/datetime-widths.ts
  */
 
-import { XlsbWriter, XlsxWriter } from '../dist';
+import { XlsbWriter, XlsxWriter } from '../dist/cjs';
 import * as path from 'path';
 import * as fs from 'fs';
 

package/examples/large-dataset.ts

@@ -7,7 +7,7 @@
  * Run with: npx ts-node examples/large-dataset.ts
  */
 
-import { XlsbWriter, XlsxWriter, XlsbReader, XlsxReader } from '../dist';
+import { XlsbWriter, XlsxWriter, XlsbReader, XlsxReader } from '../dist/cjs';
 import * as path from 'path';
 import * as fs from 'fs';
 

package/examples/multiple-sheets.ts

@@ -7,7 +7,7 @@
  * Run with: npx ts-node examples/multiple-sheets.ts
  */
 
-import { XlsbWriter, XlsxWriter } from '../dist';
+import { XlsbWriter, XlsxWriter } from '../dist/cjs';
 import * as path from 'path';
 import * as fs from 'fs';
 

package/examples/streaming-example.ts

@@ -7,13 +7,15 @@
  * Run with: npx ts-node examples/streaming-example.ts
  */
 
-import { XlsbWriter } from '../dist/XlsbWriter';
+import { XlsbWriter } from '../dist/cjs';
 import * as path from 'path';
+import * as fs from 'fs';
 
 async function streamingExample() {
     console.log('=== XlsbWriter Streaming Example ===\n');
 
     const outputPath = path.join(__dirname, '..', 'output', 'streaming-example.xlsb');
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
     console.log(`Output file: ${outputPath}\n`);
 
     const writer = new XlsbWriter(outputPath);

package/examples/update-existing.ts

@@ -0,0 +1,53 @@
+/**
+ * Update Existing Workbook Example
+ *
+ * This example demonstrates how to replace the data of a worksheet inside an
+ * existing Excel file (e.g. a report whose pivot tables are wired to a "data1"
+ * sheet) without rebuilding the workbook. The same API works for XLSX and XLSB.
+ *
+ * Run with: npx ts-node examples/update-existing.ts
+ */
+
+import { XlsxUpdater, XlsbUpdater } from '../dist/cjs';
+import * as path from 'path';
+import * as fs from 'fs';
+
+const outputDir = path.join(__dirname, 'output');
+if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+}
+
+async function updateExistingWorkbook() {
+    // New data for the "data1" sheet (same columns as before)
+    const rows = [
+        [new Date('2026-01-01'), 'PL', 'Warsaw', 1200.5, true],
+        [new Date('2026-01-02'), 'DE', 'Berlin', 980.25, true],
+        [new Date('2026-01-03'), 'PL', 'Krakow', 1530.0, false],
+    ];
+    const headers = ['DATEKEY', 'COUNTRY', 'CITY', 'AMOUNT', 'ACTIVE'];
+
+    for (const ext of ['xlsx', 'xlsb']) {
+        const input = path.join(__dirname, '..', `report.${ext}`);
+        const output = path.join(outputDir, `report_updated.${ext}`);
+
+        if (!fs.existsSync(input)) {
+            console.log(`Template workbook not found: ${input} (skipping)`);
+            continue;
+        }
+
+        // Open the existing workbook (everything outside the replaced sheet
+        // — pivot tables, other sheets, styles — is preserved)
+        const updater = ext === 'xlsb' ? new XlsbUpdater(input) : new XlsxUpdater(input);
+        console.log(`[${ext}] Sheets:`, updater.getSheetNames());
+
+        updater.replaceSheetData('data1', rows, { headers });
+
+        // Write the updated workbook to a new file (or omit the path to
+        // overwrite the source in place)
+        updater.save(output);
+        console.log(`[${ext}] Workbook updated: ${output}`);
+    }
+}
+
+updateExistingWorkbook();
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justybase/spreadsheet-tasks",
-  "version": "2.0.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.1x faster to read than XLSX.",
+  "version": "2.1.1",
+  "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",
   "types": "./dist/cjs/index.d.ts",
@@ -29,10 +29,11 @@
     "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:integration": "npx ts-node tests/integration/xlsb-writer.test.ts && npx ts-node tests/integration/xlsx-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",
+    "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:xlsb": "npx ts-node tests/integration/xlsb-writer.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",
     "benchmark:comparison": "npm run build && npx ts-node benchmarks/comparison.bench.ts",