@justybase/spreadsheet-tasks 2.1.0 → 2.1.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.
+
+### Fixed
+
+- Destination replacement during Excel conversion now preserves files created
+  concurrently and rolls back safely when the final rename fails.
+
 ## [2.1.0] - 2026-08-07
 
 ### Added

package/README.md

@@ -31,6 +31,7 @@ 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
+- **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
 
 ## 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
 
@@ -242,6 +244,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

@@ -511,6 +511,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 +566,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, StreamingSheetState, XlsbReader, type ReplaceSheetDataOptions as XlsbReplaceSheetDataOptions, XlsbUpdater, XlsbWriter, XlsxReader, XlsxUpdater, XlsxWriter, applyHeaderWidths, convertXlsbToXlsx, convertXlsxToXlsb, defaultColWidth, getFormat, initColWidths, isFormattedCell, sanitizeSheetName, unwrapCell, updateColWidthsFromRows };

package/dist/cjs/index.js

@@ -44,6 +44,8 @@ __export(index_exports, {
   XlsxUpdater: () => XlsxUpdater,
   XlsxWriter: () => XlsxWriter,
   applyHeaderWidths: () => applyHeaderWidths,
+  convertXlsbToXlsx: () => convertXlsbToXlsx,
+  convertXlsxToXlsb: () => convertXlsxToXlsb,
   defaultColWidth: () => defaultColWidth,
   getFormat: () => getFormat,
   initColWidths: () => initColWidths,
@@ -458,8 +460,8 @@ var XlsbReader = class extends ExcelReaderAbstract {
     this.xfIdToNumFmtId = [];
     this.customDateFormats = null;
   }
-  async open(path2, readSharedStrings = true) {
-    this.zip = new import_adm_zip.default(path2);
+  async open(path3, readSharedStrings = true) {
+    this.zip = new import_adm_zip.default(path3);
     const wbEntry = this.zip.getEntry("xl/workbook.bin");
     if (wbEntry) {
       const buf = wbEntry.getData();
@@ -504,8 +506,8 @@ var XlsbReader = class extends ExcelReaderAbstract {
     this.resultsCount = this.sheets.length;
     this._currentSheetIndex = -1;
   }
-  _readSharedStrings(path2) {
-    const entry = this.zip.getEntry(path2);
+  _readSharedStrings(path3) {
+    const entry = this.zip.getEntry(path3);
     if (!entry) return;
     const reader = new BiffReaderWriter(entry.getData());
     while (reader.readSharedStrings()) {
@@ -514,8 +516,8 @@ var XlsbReader = class extends ExcelReaderAbstract {
       }
     }
   }
-  _readStyles(path2) {
-    const entry = this.zip.getEntry(path2);
+  _readStyles(path3) {
+    const entry = this.zip.getEntry(path3);
     if (!entry) return;
     const reader = new BiffReaderWriter(entry.getData());
     while (reader.readStyles()) {
@@ -707,9 +709,9 @@ var XlsxReader = class extends ExcelReaderAbstract {
     this.xfIdToNumFmtId = [];
     this.customDateFormats = /* @__PURE__ */ new Set();
   }
-  async open(path2, readSharedStrings = true) {
-    return new Promise((resolve, reject) => {
-      import_yauzl.default.open(path2, { lazyEntries: true, autoClose: false }, async (err, zipfile) => {
+  async open(path3, readSharedStrings = true) {
+    return new Promise((resolve2, reject) => {
+      import_yauzl.default.open(path3, { lazyEntries: true, autoClose: false }, async (err, zipfile) => {
         if (err) return reject(err);
         this.zipfile = zipfile;
         this.entries = /* @__PURE__ */ new Map();
@@ -757,7 +759,7 @@ var XlsxReader = class extends ExcelReaderAbstract {
             }
             this.resultsCount = this.sheets.length;
             this._currentSheetIndex = -1;
-            resolve();
+            resolve2();
           } catch (e) {
             reject(e);
           }
@@ -771,16 +773,16 @@ var XlsxReader = class extends ExcelReaderAbstract {
       this.zipfile.close();
     }
   }
-  async _readZipEntryContent(path2) {
-    const entry = this.entries.get(path2);
+  async _readZipEntryContent(path3) {
+    const entry = this.entries.get(path3);
     if (!entry) return null;
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       this.zipfile.openReadStream(entry, (err, readStream) => {
         if (err) return reject(err);
         const chunks = [];
         readStream.on("data", (chunk) => chunks.push(chunk));
         readStream.on("end", () => {
-          resolve(Buffer.concat(chunks).toString("utf8"));
+          resolve2(Buffer.concat(chunks).toString("utf8"));
         });
         readStream.on("error", reject);
       });
@@ -3386,7 +3388,7 @@ var XlsbWriter = class _XlsbWriter {
    * Must be awaited before the file is fully written.
    */
   finalize() {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       try {
         this.saveSst();
         this.archive.append(this._buildStylesBin(), { name: "xl/styles.bin" });
@@ -3484,7 +3486,7 @@ var XlsbWriter = class _XlsbWriter {
 </Relationships>`;
           this.archive.append(wsRels, { name: `xl/worksheets/_rels/${sheet.nameInArchive}.rels` });
         }
-        this.output.on("close", () => resolve());
+        this.output.on("close", () => resolve2());
         this.archive.on("error", (err) => reject(err));
         this.archive.finalize();
       } catch (err) {
@@ -3832,7 +3834,7 @@ var XlsxWriter = class {
   }
   /** Finalize the ZIP package and close the output stream. */
   finalize() {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       try {
         this._writeSharedStrings();
         this._writeStyles();
@@ -3840,7 +3842,7 @@ var XlsxWriter = class {
         this._writeContentTypes();
         this._writeRels();
         this.output.on("close", () => {
-          resolve();
+          resolve2();
         });
         this.archive.on("error", (err) => {
           reject(err);
@@ -3983,7 +3985,7 @@ var XlsxUpdater = class {
   /**
    * @param path Path to an existing `.xlsx` file.
    */
-  constructor(path2) {
+  constructor(path3) {
     this.sheetNameToPath = /* @__PURE__ */ new Map();
     this.pivotCacheDefs = [];
     this.pivotTableDefPaths = [];
@@ -3992,12 +3994,12 @@ var XlsxUpdater = class {
     this.sharedStringsOriginalLength = 0;
     this.sharedStringsCount = 0;
     this.stringIndexMap = /* @__PURE__ */ new Map();
-    this.sourcePath = path2;
+    this.sourcePath = path3;
     this._oaEpoch = Date.UTC(1899, 11, 30);
-    if (!fs3.existsSync(path2)) {
-      throw new Error(`XlsxUpdater: file not found: ${path2}`);
+    if (!fs3.existsSync(path3)) {
+      throw new Error(`XlsxUpdater: file not found: ${path3}`);
     }
-    this.zip = new import_adm_zip2.default(path2);
+    this.zip = new import_adm_zip2.default(path3);
     if (this.zip.getEntry("xl/workbook.bin")) {
       throw new Error(
         "XlsxUpdater: XLSB files are not supported yet. Convert the workbook to XLSX first."
@@ -4382,8 +4384,8 @@ var XlsxUpdater = class {
     }
   }
   _addRefreshOnLoadToPivotTables() {
-    for (const path2 of this.pivotTableDefPaths) {
-      const entry = this.zip.getEntry(path2);
+    for (const path3 of this.pivotTableDefPaths) {
+      const entry = this.zip.getEntry(path3);
       if (!entry) continue;
       let xml = entry.getData().toString("utf8");
       const rootRe = /<pivotTableDefinition\b[^>]*>/;
@@ -4391,7 +4393,7 @@ var XlsxUpdater = class {
       if (!rootMatch || rootMatch[0].includes("refreshOnLoad")) continue;
       const newTag = rootMatch[0].replace(/(\/?>)$/, ' refreshOnLoad="1"$1');
       xml = xml.substring(0, rootMatch.index) + newTag + xml.substring(rootMatch.index + rootMatch[0].length);
-      this.zip.updateFile(path2, Buffer.from(xml, "utf8"));
+      this.zip.updateFile(path3, Buffer.from(xml, "utf8"));
     }
   }
 };
@@ -4476,7 +4478,7 @@ var XlsbUpdater = class {
   /**
    * @param path Path to an existing `.xlsb` file.
    */
-  constructor(path2) {
+  constructor(path3) {
     this.sheetNameToPath = /* @__PURE__ */ new Map();
     this.pivotCacheDefPaths = [];
     this.sharedStringsBuf = null;
@@ -4489,12 +4491,12 @@ var XlsbUpdater = class {
     // Shared strings
     // ------------------------------------------------------------------
     this._appendCount = 0;
-    this.sourcePath = path2;
+    this.sourcePath = path3;
     this._oaEpoch = Date.UTC(1899, 11, 30);
-    if (!fs4.existsSync(path2)) {
-      throw new Error(`XlsbUpdater: file not found: ${path2}`);
+    if (!fs4.existsSync(path3)) {
+      throw new Error(`XlsbUpdater: file not found: ${path3}`);
     }
-    this.zip = new import_adm_zip3.default(path2);
+    this.zip = new import_adm_zip3.default(path3);
     if (!this.zip.getEntry("xl/workbook.bin")) {
       throw new Error(
         "XlsbUpdater: not an XLSB workbook (xl/workbook.bin missing). Convert the file to XLSB first."
@@ -4906,8 +4908,8 @@ var XlsbUpdater = class {
   // Pivot cache integration
   // ------------------------------------------------------------------
   _patchPivotCaches(sheetName, rwLast, colLast) {
-    for (const path2 of this.pivotCacheDefPaths) {
-      const entry = this.zip.getEntry(path2);
+    for (const path3 of this.pivotCacheDefPaths) {
+      const entry = this.zip.getEntry(path3);
       if (!entry) continue;
       const buf = Buffer.from(entry.getData());
       const rec = { headerStart: 0, dataStart: 0, dataEnd: 0, id: 0, len: 0 };
@@ -4939,11 +4941,255 @@ var XlsbUpdater = class {
         }
       }
       if (patched) {
-        this.zip.updateFile(path2, buf);
+        this.zip.updateFile(path3, buf);
       }
     }
   }
 };
+
+// src/ExcelConverter.ts
+var fs6 = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+var import_crypto2 = require("crypto");
+var import_child_process = require("child_process");
+
+// src/atomicFile.ts
+var fs5 = __toESM(require("fs"));
+var import_crypto = require("crypto");
+var realFileOperations = {
+  exists: (filePath) => fs5.existsSync(filePath),
+  rename: (sourcePath, destinationPath) => fs5.renameSync(sourcePath, destinationPath),
+  remove: (filePath) => fs5.rmSync(filePath)
+};
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function destinationExistsError(destinationPath) {
+  return new Error(
+    `Excel conversion: destination already exists (pass { overwrite: true } to replace it): ${destinationPath}`
+  );
+}
+function installTemporaryOutput(temporaryPath, destinationPath, overwrite, operations = realFileOperations) {
+  const backupPath = `${destinationPath}.${(0, import_crypto.randomUUID)()}.replacement-backup`;
+  let backupCreated = false;
+  let installed = false;
+  if (operations.exists(destinationPath)) {
+    if (!overwrite) {
+      throw destinationExistsError(destinationPath);
+    }
+    operations.rename(destinationPath, backupPath);
+    backupCreated = true;
+  }
+  try {
+    try {
+      operations.rename(temporaryPath, destinationPath);
+      installed = true;
+    } catch (error) {
+      if (overwrite && !backupCreated && operations.exists(destinationPath)) {
+        operations.rename(destinationPath, backupPath);
+        backupCreated = true;
+        operations.rename(temporaryPath, destinationPath);
+        installed = true;
+      } else {
+        throw error;
+      }
+    }
+    if (backupCreated) {
+      operations.remove(backupPath);
+    }
+  } catch (error) {
+    if (backupCreated && !installed) {
+      if (!operations.exists(destinationPath)) {
+        try {
+          operations.rename(backupPath, destinationPath);
+          backupCreated = false;
+        } catch (rollbackError) {
+          throw new Error(
+            `Excel conversion: final destination install failed (${errorMessage(error)}), and restoring the original destination also failed (${errorMessage(rollbackError)}). Original file remains at ${backupPath}.`
+          );
+        }
+      } else {
+        throw new Error(
+          `Excel conversion: final destination install failed (${errorMessage(error)}). A concurrent destination was preserved; the original file remains at ${backupPath}.`
+        );
+      }
+    }
+    throw error;
+  }
+}
+
+// src/ExcelConverter.ts
+var POWERSHELL_CONVERSION_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+$inputPath = [Environment]::GetEnvironmentVariable('JUSTYBASE_EXCEL_INPUT')
+$outputPath = [Environment]::GetEnvironmentVariable('JUSTYBASE_EXCEL_OUTPUT')
+$fileFormat = [int][Environment]::GetEnvironmentVariable('JUSTYBASE_EXCEL_FORMAT')
+$excel = $null
+$workbook = $null
+$exitCode = 0
+
+try {
+    $excel = New-Object -ComObject Excel.Application
+    $excel.Visible = $false
+    $excel.DisplayAlerts = $false
+    $excel.ScreenUpdating = $false
+
+    # Open read-only so the source workbook is never changed by the conversion.
+    $workbook = $excel.Workbooks.Open($inputPath, 0, $true)
+    if ($null -eq $workbook) {
+        throw 'Excel did not return a workbook when opening the source file.'
+    }
+
+    $workbook.SaveAs($outputPath, $fileFormat)
+} catch {
+    $exitCode = 1
+    [Console]::Error.WriteLine($_.Exception.ToString())
+} finally {
+    if ($null -ne $workbook) {
+        try { $workbook.Close($false) } catch { }
+        try { [System.Runtime.InteropServices.Marshal]::ReleaseComObject($workbook) | Out-Null } catch { }
+    }
+    if ($null -ne $excel) {
+        try { $excel.Quit() } catch { }
+        try { [System.Runtime.InteropServices.Marshal]::ReleaseComObject($excel) | Out-Null } catch { }
+    }
+    [GC]::Collect()
+    [GC]::WaitForPendingFinalizers()
+}
+
+exit $exitCode
+`;
+function errorMessage2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function validateConversionPaths(inputPath, outputPath, inputExtension, outputExtension, overwrite) {
+  const input = path2.resolve(inputPath);
+  const output = path2.resolve(outputPath);
+  if (path2.extname(input).toLowerCase() !== inputExtension) {
+    throw new Error(
+      `Excel conversion: source must have the ${inputExtension} extension: ${inputPath}`
+    );
+  }
+  if (path2.extname(output).toLowerCase() !== outputExtension) {
+    throw new Error(
+      `Excel conversion: destination must have the ${outputExtension} extension: ${outputPath}`
+    );
+  }
+  if (!fs6.existsSync(input)) {
+    throw new Error(`Excel conversion: source file not found: ${inputPath}`);
+  }
+  if (!fs6.statSync(input).isFile()) {
+    throw new Error(`Excel conversion: source path is not a file: ${inputPath}`);
+  }
+  if (!fs6.existsSync(path2.dirname(output))) {
+    throw new Error(`Excel conversion: destination directory not found: ${path2.dirname(output)}`);
+  }
+  if (fs6.existsSync(output)) {
+    if (fs6.statSync(output).isDirectory()) {
+      throw new Error(`Excel conversion: destination path is a directory: ${outputPath}`);
+    }
+    if (!overwrite) {
+      throw new Error(
+        `Excel conversion: destination already exists (pass { overwrite: true } to replace it): ${outputPath}`
+      );
+    }
+  }
+  if (process.platform === "win32" && input.toLowerCase() === output.toLowerCase()) {
+    throw new Error("Excel conversion: source and destination must be different files.");
+  }
+  return { input, output };
+}
+function runPowerShellConversion(inputPath, outputPath, fileFormat) {
+  const encodedCommand = Buffer.from(POWERSHELL_CONVERSION_SCRIPT, "utf16le").toString("base64");
+  const environment = {
+    ...process.env,
+    JUSTYBASE_EXCEL_INPUT: inputPath,
+    JUSTYBASE_EXCEL_OUTPUT: outputPath,
+    JUSTYBASE_EXCEL_FORMAT: String(fileFormat)
+  };
+  return new Promise((resolve2, reject) => {
+    var _a, _b, _c, _d;
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const child = (0, import_child_process.spawn)(
+      "powershell.exe",
+      [
+        "-NoLogo",
+        "-NoProfile",
+        "-NonInteractive",
+        "-ExecutionPolicy",
+        "Bypass",
+        "-EncodedCommand",
+        encodedCommand
+      ],
+      { env: environment, windowsHide: true }
+    );
+    (_a = child.stdout) == null ? void 0 : _a.setEncoding("utf8");
+    (_b = child.stderr) == null ? void 0 : _b.setEncoding("utf8");
+    (_c = child.stdout) == null ? void 0 : _c.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    (_d = child.stderr) == null ? void 0 : _d.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      reject(new Error(`Excel conversion: unable to start PowerShell/COM: ${error.message}`));
+    });
+    child.once("close", (code) => {
+      if (settled) return;
+      settled = true;
+      if (code === 0) {
+        resolve2();
+        return;
+      }
+      const details = (stderr || stdout).replace(/\s+/g, " ").trim();
+      reject(new Error(
+        `Excel conversion failed (PowerShell exit code ${code ?? "unknown"})${details ? `: ${details}` : "."}`
+      ));
+    });
+  });
+}
+async function convertExcelFile(inputPath, outputPath, inputExtension, outputExtension, fileFormat, options = {}) {
+  const { input, output } = validateConversionPaths(
+    inputPath,
+    outputPath,
+    inputExtension,
+    outputExtension,
+    options.overwrite === true
+  );
+  if (process.platform !== "win32") {
+    throw new Error("Excel conversion requires Windows with desktop Microsoft Excel and COM automation.");
+  }
+  const temporaryOutput = path2.join(
+    path2.dirname(output),
+    `.${path2.basename(output, outputExtension)}.${(0, import_crypto2.randomUUID)()}.conversion${outputExtension}`
+  );
+  try {
+    await runPowerShellConversion(input, temporaryOutput, fileFormat);
+    if (!fs6.existsSync(temporaryOutput)) {
+      throw new Error("Excel conversion completed without creating the destination file.");
+    }
+    installTemporaryOutput(temporaryOutput, output, options.overwrite === true);
+  } catch (error) {
+    throw new Error(`Excel conversion ${inputExtension} -> ${outputExtension}: ${errorMessage2(error)}`);
+  } finally {
+    if (fs6.existsSync(temporaryOutput)) {
+      try {
+        fs6.rmSync(temporaryOutput);
+      } catch {
+      }
+    }
+  }
+}
+function convertXlsbToXlsx(inputPath, outputPath, options) {
+  return convertExcelFile(inputPath, outputPath, ".xlsb", ".xlsx", 51, options);
+}
+function convertXlsxToXlsb(inputPath, outputPath, options) {
+  return convertExcelFile(inputPath, outputPath, ".xlsx", ".xlsb", 50, options);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BiffReaderWriter,
@@ -4960,6 +5206,8 @@ var XlsbUpdater = class {
   XlsxUpdater,
   XlsxWriter,
   applyHeaderWidths,
+  convertXlsbToXlsx,
+  convertXlsxToXlsb,
   defaultColWidth,
   getFormat,
   initColWidths,