@justybase/spreadsheet-tasks 2.1.0 → 2.1.1

package/docs/API.md

@@ -8,6 +8,7 @@
 - [XlsxReader](#xlsxreader)
 - [XlsxUpdater](#xlsxupdater)
 - [XlsbUpdater](#xlsbupdater)
+- [Excel conversion](#excel-conversion)
 - [ReaderFactory](#readerfactory)
 - [Types](#types)
 
@@ -382,6 +383,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justybase/spreadsheet-tasks",
-  "version": "2.1.0",
+  "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",
@@ -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",
     "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",