@justybase/spreadsheet-tasks 2.1.0 → 2.2.0

package/dist/esm/index.js

@@ -402,8 +402,8 @@ var XlsbReader = class extends ExcelReaderAbstract {
     this.xfIdToNumFmtId = [];
     this.customDateFormats = null;
   }
-  async open(path2, readSharedStrings = true) {
-    this.zip = new AdmZip(path2);
+  async open(path7, readSharedStrings = true) {
+    this.zip = new AdmZip(path7);
     const wbEntry = this.zip.getEntry("xl/workbook.bin");
     if (wbEntry) {
       const buf = wbEntry.getData();
@@ -448,8 +448,8 @@ var XlsbReader = class extends ExcelReaderAbstract {
     this.resultsCount = this.sheets.length;
     this._currentSheetIndex = -1;
   }
-  _readSharedStrings(path2) {
-    const entry = this.zip.getEntry(path2);
+  _readSharedStrings(path7) {
+    const entry = this.zip.getEntry(path7);
     if (!entry) return;
     const reader = new BiffReaderWriter(entry.getData());
     while (reader.readSharedStrings()) {
@@ -458,8 +458,8 @@ var XlsbReader = class extends ExcelReaderAbstract {
       }
     }
   }
-  _readStyles(path2) {
-    const entry = this.zip.getEntry(path2);
+  _readStyles(path7) {
+    const entry = this.zip.getEntry(path7);
     if (!entry) return;
     const reader = new BiffReaderWriter(entry.getData());
     while (reader.readStyles()) {
@@ -582,7 +582,7 @@ function escapeXmlText(str) {
 }
 function unescapeXml(str) {
   if (!str || str.indexOf("&") === -1) return str;
-  return str.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'");
+  return str.replace(/&#x([0-9a-f]+);/gi, (_match, hex) => String.fromCodePoint(parseInt(hex, 16))).replace(/&#(\d+);/g, (_match, decimal) => String.fromCodePoint(parseInt(decimal, 10))).replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'");
 }
 function columnIndexToLetter(colIndex) {
   let n = colIndex + 1;
@@ -611,26 +611,17 @@ function trimTrailingEmptyRows(rows) {
 }
 function parseSharedStringsXml(xml) {
   const result = [];
-  let pos = 0;
-  while (true) {
-    const siStart = xml.indexOf("<si>", pos);
-    if (siStart === -1) break;
-    const siEnd = xml.indexOf("</si>", siStart);
-    if (siEnd === -1) break;
-    const content = xml.substring(siStart, siEnd);
-    let val = "";
-    let tPos = 0;
-    while (true) {
-      const tStart = content.indexOf("<t", tPos);
-      if (tStart === -1) break;
-      const tagEnd = content.indexOf(">", tStart);
-      const tEnd = content.indexOf("</t>", tagEnd);
-      if (tEnd === -1) break;
-      val += content.substring(tagEnd + 1, tEnd);
-      tPos = tEnd + 4;
-    }
-    result.push(unescapeXml(val));
-    pos = siEnd + 5;
+  const itemRegex = /<(?:(?:[A-Za-z_][\w.-]*):)?si\b[^>]*>([\s\S]*?)<\/(?:(?:[A-Za-z_][\w.-]*):)?si\s*>/gi;
+  let itemMatch;
+  while ((itemMatch = itemRegex.exec(xml)) !== null) {
+    const content = itemMatch[1];
+    const textRegex = /<(?:(?:[A-Za-z_][\w.-]*):)?t\b[^>]*>([\s\S]*?)<\/(?:(?:[A-Za-z_][\w.-]*):)?t\s*>/gi;
+    let value = "";
+    let textMatch;
+    while ((textMatch = textRegex.exec(content)) !== null) {
+      value += textMatch[1];
+    }
+    result.push(unescapeXml(value));
   }
   return result;
 }
@@ -651,9 +642,9 @@ var XlsxReader = class extends ExcelReaderAbstract {
     this.xfIdToNumFmtId = [];
     this.customDateFormats = /* @__PURE__ */ new Set();
   }
-  async open(path2, readSharedStrings = true) {
-    return new Promise((resolve, reject) => {
-      yauzl.open(path2, { lazyEntries: true, autoClose: false }, async (err, zipfile) => {
+  async open(path7, readSharedStrings = true) {
+    return new Promise((resolve4, reject) => {
+      yauzl.open(path7, { lazyEntries: true, autoClose: false }, async (err, zipfile) => {
         if (err) return reject(err);
         this.zipfile = zipfile;
         this.entries = /* @__PURE__ */ new Map();
@@ -701,7 +692,7 @@ var XlsxReader = class extends ExcelReaderAbstract {
             }
             this.resultsCount = this.sheets.length;
             this._currentSheetIndex = -1;
-            resolve();
+            resolve4();
           } catch (e) {
             reject(e);
           }
@@ -715,16 +706,16 @@ var XlsxReader = class extends ExcelReaderAbstract {
       this.zipfile.close();
     }
   }
-  async _readZipEntryContent(path2) {
-    const entry = this.entries.get(path2);
+  async _readZipEntryContent(path7) {
+    const entry = this.entries.get(path7);
     if (!entry) return null;
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve4, 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"));
+          resolve4(Buffer.concat(chunks).toString("utf8"));
         });
         readStream.on("error", reject);
       });
@@ -3330,7 +3321,7 @@ var XlsbWriter = class _XlsbWriter {
    * Must be awaited before the file is fully written.
    */
   finalize() {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve4, reject) => {
       try {
         this.saveSst();
         this.archive.append(this._buildStylesBin(), { name: "xl/styles.bin" });
@@ -3428,7 +3419,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", () => resolve4());
         this.archive.on("error", (err) => reject(err));
         this.archive.finalize();
       } catch (err) {
@@ -3776,7 +3767,7 @@ var XlsxWriter = class {
   }
   /** Finalize the ZIP package and close the output stream. */
   finalize() {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve4, reject) => {
       try {
         this._writeSharedStrings();
         this._writeStyles();
@@ -3784,7 +3775,7 @@ var XlsxWriter = class {
         this._writeContentTypes();
         this._writeRels();
         this.output.on("close", () => {
-          resolve();
+          resolve4();
         });
         this.archive.on("error", (err) => {
           reject(err);
@@ -3921,13 +3912,237 @@ ${xfEntries.join("\n")}
 };
 
 // src/XlsxUpdater.ts
-import * as fs3 from "fs";
+import * as fs5 from "fs";
+import * as os from "os";
+import * as path4 from "path";
 import AdmZip2 from "adm-zip";
-var XlsxUpdater = class {
+
+// src/atomicFile.ts
+import * as fs3 from "fs";
+import * as path2 from "path";
+import { randomUUID } from "crypto";
+var realFileOperations = {
+  exists: (filePath) => fs3.existsSync(filePath),
+  rename: (sourcePath, destinationPath) => fs3.renameSync(sourcePath, destinationPath),
+  remove: (filePath) => fs3.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 readDestinationMode(target) {
+  try {
+    if (!fs3.existsSync(target)) return void 0;
+    return fs3.statSync(target).mode & 511;
+  } catch {
+    return void 0;
+  }
+}
+function installTemporaryOutput(temporaryPath, destinationPath, overwrite, operations = realFileOperations) {
+  const backupPath = `${destinationPath}.${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;
+  }
+}
+function writeBufferAtomically(buffer, destinationPath) {
+  const target = path2.resolve(destinationPath);
+  fs3.mkdirSync(path2.dirname(target), { recursive: true });
+  const temporaryPath = path2.join(
+    path2.dirname(target),
+    `.${path2.basename(target)}.${randomUUID()}.tmp`
+  );
+  const destinationMode = readDestinationMode(target);
+  try {
+    const fd = fs3.openSync(temporaryPath, "w", destinationMode ?? 438);
+    try {
+      if (destinationMode !== void 0) {
+        try {
+          fs3.fchmodSync(fd, destinationMode);
+        } catch {
+        }
+      }
+      fs3.writeFileSync(fd, buffer);
+      fs3.fsyncSync(fd);
+    } finally {
+      fs3.closeSync(fd);
+    }
+    if (destinationMode !== void 0) {
+      try {
+        fs3.chmodSync(temporaryPath, destinationMode);
+      } catch {
+      }
+    }
+    fs3.renameSync(temporaryPath, target);
+  } finally {
+    if (fs3.existsSync(temporaryPath)) {
+      try {
+        fs3.rmSync(temporaryPath);
+      } catch {
+      }
+    }
+  }
+}
+
+// src/streamingZip.ts
+import * as fs4 from "fs";
+import * as path3 from "path";
+import { randomUUID as randomUUID2 } from "crypto";
+import { finished } from "stream/promises";
+import { Readable as Readable3 } from "stream";
+import archiver3 from "archiver";
+function readDestinationMode2(target) {
+  try {
+    if (!fs4.existsSync(target)) return void 0;
+    return fs4.statSync(target).mode & 511;
+  } catch {
+    return void 0;
+  }
+}
+function appendAndWait(archive, source, name) {
+  return new Promise((resolve4, reject) => {
+    const cleanup = () => {
+      archive.off("entry", onEntry);
+      archive.off("error", onError);
+      const maybeEmitter2 = source;
+      if (typeof maybeEmitter2.off === "function") {
+        maybeEmitter2.off("error", onError);
+      }
+    };
+    const onEntry = () => {
+      cleanup();
+      resolve4();
+    };
+    const onError = (error) => {
+      cleanup();
+      reject(error);
+    };
+    archive.once("entry", onEntry);
+    archive.once("error", onError);
+    const maybeEmitter = source;
+    if (typeof maybeEmitter.once === "function") {
+      maybeEmitter.once("error", onError);
+    }
+    try {
+      archive.append(source, { name });
+    } catch (error) {
+      cleanup();
+      reject(error);
+    }
+  });
+}
+async function writeAdmZipStreaming(zip, stagedParts, destinationPath) {
+  const target = path3.resolve(destinationPath);
+  fs4.mkdirSync(path3.dirname(target), { recursive: true });
+  const temporaryPath = path3.join(
+    path3.dirname(target),
+    `.${path3.basename(target)}.${randomUUID2()}.tmp`
+  );
+  const destinationMode = readDestinationMode2(target);
+  let output = null;
+  let archive = null;
+  try {
+    output = fs4.createWriteStream(
+      temporaryPath,
+      destinationMode !== void 0 ? { mode: destinationMode } : {}
+    );
+    archive = archiver3("zip");
+    archive.pipe(output);
+    for (const entry of zip.getEntries()) {
+      const stagedPath = stagedParts.get(entry.entryName);
+      if (stagedPath) {
+        await appendAndWait(archive, fs4.createReadStream(stagedPath), entry.entryName);
+      } else {
+        await appendAndWait(archive, Readable3.from([entry.getData()]), entry.entryName);
+      }
+    }
+    await archive.finalize();
+    await finished(output);
+    if (destinationMode !== void 0) {
+      try {
+        fs4.chmodSync(temporaryPath, destinationMode);
+      } catch {
+      }
+    }
+    const fd = fs4.openSync(temporaryPath, "r+");
+    try {
+      fs4.fsyncSync(fd);
+    } finally {
+      fs4.closeSync(fd);
+    }
+    fs4.renameSync(temporaryPath, target);
+  } catch (error) {
+    try {
+      archive == null ? void 0 : archive.abort();
+    } catch {
+    }
+    throw error;
+  } finally {
+    if (output && !output.closed) {
+      output.destroy();
+    }
+    if (fs4.existsSync(temporaryPath)) {
+      try {
+        fs4.rmSync(temporaryPath);
+      } catch {
+      }
+    }
+  }
+}
+
+// src/XlsxUpdater.ts
+var XlsxUpdater = class _XlsxUpdater {
   /**
    * @param path Path to an existing `.xlsx` file.
    */
-  constructor(path2) {
+  constructor(filePath) {
+    this.temporaryDirectory = null;
+    this.stagedParts = /* @__PURE__ */ new Map();
     this.sheetNameToPath = /* @__PURE__ */ new Map();
     this.pivotCacheDefs = [];
     this.pivotTableDefPaths = [];
@@ -3935,13 +4150,15 @@ var XlsxUpdater = class {
     this.sharedStringsValues = [];
     this.sharedStringsOriginalLength = 0;
     this.sharedStringsCount = 0;
+    this.sharedStringsPending = [];
+    this.sharedStringsDirty = false;
     this.stringIndexMap = /* @__PURE__ */ new Map();
-    this.sourcePath = path2;
+    this.sourcePath = filePath;
     this._oaEpoch = Date.UTC(1899, 11, 30);
-    if (!fs3.existsSync(path2)) {
-      throw new Error(`XlsxUpdater: file not found: ${path2}`);
+    if (!fs5.existsSync(filePath)) {
+      throw new Error(`XlsxUpdater: file not found: ${filePath}`);
     }
-    this.zip = new AdmZip2(path2);
+    this.zip = new AdmZip2(filePath);
     if (this.zip.getEntry("xl/workbook.bin")) {
       throw new Error(
         "XlsxUpdater: XLSB files are not supported yet. Convert the workbook to XLSX first."
@@ -3975,8 +4192,15 @@ var XlsxUpdater = class {
     if (!entry) {
       throw new Error(`XlsxUpdater: worksheet part missing for sheet "${sheetName}".`);
     }
-    const sheetXml = entry.getData().toString("utf8");
+    const sheetXml = this._entryData(sheetPath).toString("utf8");
     this._ensureSharedStringsLoaded();
+    if (this.sharedStringsXml !== null) {
+      this.sharedStringsCount = Math.max(
+        0,
+        this.sharedStringsCount - this._sharedStringRefCount(sheetXml)
+      );
+      this.sharedStringsDirty = true;
+    }
     let colStyles = /* @__PURE__ */ new Map();
     let headerStyles = /* @__PURE__ */ new Map();
     let dateStyle = null;
@@ -3991,6 +4215,7 @@ var XlsxUpdater = class {
     const newSheetData = this._buildSheetData(rows, headers, colStyles, headerStyles, dateStyle);
     const newXml = this._patchSheetXml(sheetXml, newSheetData, totalRows, lastCol);
     this.zip.updateFile(sheetPath, Buffer.from(newXml, "utf8"));
+    this._discardStagedPart(sheetPath);
     if (this.sharedStringsXml !== null) {
       this._commitSharedStrings();
     }
@@ -3998,18 +4223,255 @@ var XlsxUpdater = class {
     this._updatePivotCaches(sheetName, dimRef, rows.length);
     this._addRefreshOnLoadToPivotTables();
   }
+  /**
+   * 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.
+   */
+  async replaceSheetDataStream(sheetName, rows, options = {}) {
+    const { headers, styleFallback = "inherit" } = options;
+    if (styleFallback !== "inherit" && styleFallback !== "general") {
+      throw new Error("XlsxUpdater: styleFallback must be 'inherit' or 'general'.");
+    }
+    const sheetPath = this.sheetNameToPath.get(sheetName);
+    if (!sheetPath) {
+      throw new Error(`XlsxUpdater: sheet "${sheetName}" not found in the workbook.`);
+    }
+    const entry = this.zip.getEntry(sheetPath);
+    if (!entry) {
+      throw new Error(`XlsxUpdater: worksheet part missing for sheet "${sheetName}".`);
+    }
+    const oldStage = this.stagedParts.get(sheetPath);
+    const beforeValuesLength = this.sharedStringsValues.length;
+    const beforePendingLength = this.sharedStringsPending.length;
+    const beforeSharedStringsCount = this.sharedStringsCount;
+    const beforeSharedStringsDirty = this.sharedStringsDirty;
+    const beforeSharedStringsXml = this.sharedStringsXml;
+    const beforeSharedStringsOriginalLength = this.sharedStringsOriginalLength;
+    const beforeStringIndexMap = new Map(this.stringIndexMap);
+    const sharedStringsEntry = this.zip.getEntry("xl/sharedStrings.xml");
+    const beforeSharedStringsBytes = sharedStringsEntry || this.stagedParts.has("xl/sharedStrings.xml") ? Buffer.from(this._entryData("xl/sharedStrings.xml")) : null;
+    const createdParts = [];
+    const oldSheetXml = this._entryData(sheetPath).toString("utf8");
+    const rowsPath = this._temporaryPath(".rows");
+    const outputPath = this._temporaryPath(".xml");
+    createdParts.push(rowsPath, outputPath);
+    let output = null;
+    try {
+      this._ensureSharedStringsLoaded();
+      if (this.sharedStringsXml !== null) {
+        this.sharedStringsCount = Math.max(
+          0,
+          this.sharedStringsCount - this._sharedStringRefCount(oldSheetXml)
+        );
+        this.sharedStringsDirty = true;
+      }
+      let colStyles = /* @__PURE__ */ new Map();
+      let headerStyles = /* @__PURE__ */ new Map();
+      let dateStyle = null;
+      if (styleFallback !== "general") {
+        const collected = this._collectExistingStyles(oldSheetXml);
+        colStyles = collected.dataStyles;
+        headerStyles = collected.headerStyles;
+        dateStyle = this._findDateStyleIndex();
+      }
+      const prefixMatch = /<([A-Za-z_][\w.-]*:)?sheetData\b/.exec(oldSheetXml);
+      const prefix = (prefixMatch == null ? void 0 : prefixMatch[1]) ?? "";
+      const rowOutput = fs5.createWriteStream(rowsPath);
+      output = rowOutput;
+      let outputError = null;
+      rowOutput.on("error", (error) => {
+        outputError = error;
+      });
+      let nextRow = 1;
+      let width = (headers == null ? void 0 : headers.length) ?? 0;
+      let dataRowsSeen = 0;
+      let keptDataRows = 0;
+      let lastKeptEnd = 0;
+      let pendingEmptyWidth = 0;
+      let writtenBytes = 0;
+      const write = async (data) => {
+        if (outputError) throw outputError;
+        writtenBytes += data.length;
+        if (rowOutput.write(data)) return;
+        await new Promise((resolve4, reject) => {
+          const onDrain = () => {
+            cleanup();
+            resolve4();
+          };
+          const onError = (error) => {
+            cleanup();
+            reject(error);
+          };
+          const cleanup = () => {
+            rowOutput.off("drain", onDrain);
+            rowOutput.off("error", onError);
+          };
+          rowOutput.once("drain", onDrain);
+          rowOutput.once("error", onError);
+        });
+      };
+      if (headers !== void 0) {
+        const cells = headers.map((value, column) => this._valueCell(value, column, nextRow, headerStyles, dateStyle));
+        const header = `<${prefix}row r="${nextRow}">${cells.join("")}</${prefix}row>`;
+        await write(Buffer.from(header, "utf8"));
+        lastKeptEnd = writtenBytes;
+        nextRow++;
+      }
+      for await (const sourceRow of rows) {
+        if (typeof sourceRow === "string" || sourceRow instanceof Uint8Array) {
+          throw new TypeError("Each row must be an iterable of cells, not text");
+        }
+        const row = Array.from(sourceRow);
+        const cells = row.map((value, column) => value === null || value === void 0 ? "" : this._valueCell(value, column, nextRow, colStyles, dateStyle));
+        const rowXml = `<${prefix}row r="${nextRow}">${cells.join("")}</${prefix}row>`;
+        await write(Buffer.from(rowXml, "utf8"));
+        dataRowsSeen++;
+        nextRow++;
+        if (row.every((value) => value === null || value === void 0)) {
+          pendingEmptyWidth = Math.max(pendingEmptyWidth, row.length);
+        } else {
+          width = Math.max(width, pendingEmptyWidth, row.length);
+          pendingEmptyWidth = 0;
+          keptDataRows = dataRowsSeen;
+          lastKeptEnd = writtenBytes;
+        }
+      }
+      await new Promise((resolve4, reject) => {
+        rowOutput.once("close", resolve4);
+        rowOutput.once("error", reject);
+        rowOutput.end();
+      });
+      if (outputError) throw outputError;
+      const rowsFd = fs5.openSync(rowsPath, "r+");
+      try {
+        fs5.ftruncateSync(rowsFd, lastKeptEnd);
+      } finally {
+        fs5.closeSync(rowsFd);
+      }
+      const totalRows = keptDataRows + (headers !== void 0 ? 1 : 0);
+      const lastCol = width - 1;
+      const dimRef = totalRows > 0 && lastCol >= 0 ? `A1:${columnIndexToLetter(lastCol)}${totalRows}` : "A1";
+      this._patchSheetFile(oldSheetXml, rowsPath, outputPath, dimRef);
+      this._stagePart(sheetPath, outputPath);
+      this._commitSharedStrings();
+      this._updatePivotCaches(sheetName, dimRef, keptDataRows);
+      this._addRefreshOnLoadToPivotTables();
+      if (oldStage && oldStage !== outputPath) {
+        this._removeTemporaryFile(oldStage);
+      }
+      createdParts.splice(createdParts.indexOf(outputPath), 1);
+    } catch (error) {
+      this.sharedStringsValues.length = beforeValuesLength;
+      this.sharedStringsPending.length = beforePendingLength;
+      this.sharedStringsCount = beforeSharedStringsCount;
+      this.sharedStringsDirty = beforeSharedStringsDirty;
+      this.sharedStringsXml = beforeSharedStringsXml;
+      this.sharedStringsOriginalLength = beforeSharedStringsOriginalLength;
+      this.stringIndexMap.clear();
+      for (const [value, index] of beforeStringIndexMap) this.stringIndexMap.set(value, index);
+      if (beforeSharedStringsBytes) {
+        this.zip.updateFile("xl/sharedStrings.xml", beforeSharedStringsBytes);
+      }
+      if (oldStage) this.stagedParts.set(sheetPath, oldStage);
+      else this.stagedParts.delete(sheetPath);
+      throw error;
+    } finally {
+      if (output && !output.closed) output.destroy();
+      for (const temporaryPath of createdParts) {
+        this._removeTemporaryFile(temporaryPath);
+      }
+    }
+  }
   /**
    * Write the updated workbook to disk.
    * @param outputPath Destination path; defaults to the source file (overwrites in place).
    */
   save(outputPath) {
     const target = outputPath ?? this.sourcePath;
-    fs3.writeFileSync(target, this.zip.toBuffer());
+    this._materializeStagedParts();
+    writeBufferAtomically(this.zip.toBuffer(), target);
+  }
+  /** Save staged streaming replacements without materialising the ZIP. */
+  async saveStreaming(outputPath) {
+    const target = outputPath ?? this.sourcePath;
+    await writeAdmZipStreaming(this.zip, this.stagedParts, target);
+    this._materializeStagedParts();
   }
   /** The updated workbook as an in-memory ZIP buffer. */
   toBuffer() {
+    this._materializeStagedParts();
     return this.zip.toBuffer();
   }
+  /**
+   * 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() {
+    for (const stagedPath of this.stagedParts.values()) {
+      try {
+        fs5.rmSync(stagedPath, { force: true });
+      } catch {
+      }
+    }
+    this.stagedParts.clear();
+    if (this.temporaryDirectory !== null) {
+      try {
+        fs5.rmSync(this.temporaryDirectory, { recursive: true, force: true });
+      } catch {
+      }
+      this.temporaryDirectory = null;
+    }
+  }
+  /** Support `using` declarations for automatic staging cleanup. */
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+  _ensureTemporaryDirectory() {
+    if (this.temporaryDirectory === null) {
+      this.temporaryDirectory = fs5.mkdtempSync(path4.join(os.tmpdir(), "spreadsheet-updater-"));
+    } else {
+      try {
+        fs5.mkdirSync(this.temporaryDirectory, { recursive: true });
+      } catch {
+      }
+    }
+    return this.temporaryDirectory;
+  }
+  _temporaryPath(suffix) {
+    return path4.join(this._ensureTemporaryDirectory(), `part-${Date.now()}-${Math.random().toString(16).slice(2)}${suffix}`);
+  }
+  _removeTemporaryFile(filePath) {
+    try {
+      fs5.rmSync(filePath);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  _entryData(name) {
+    const stagedPath = this.stagedParts.get(name);
+    if (stagedPath) return fs5.readFileSync(stagedPath);
+    const entry = this.zip.getEntry(name);
+    if (!entry) throw new Error(`XlsxUpdater: ZIP member missing: ${name}`);
+    return entry.getData();
+  }
+  _stagePart(name, filePath) {
+    this.stagedParts.set(name, filePath);
+  }
+  _discardStagedPart(name) {
+    const stagedPath = this.stagedParts.get(name);
+    if (!stagedPath) return;
+    this._removeTemporaryFile(stagedPath);
+    this.stagedParts.delete(name);
+  }
+  _materializeStagedParts() {
+    for (const [name, stagedPath] of this.stagedParts) {
+      this.zip.updateFile(name, fs5.readFileSync(stagedPath));
+      this._removeTemporaryFile(stagedPath);
+    }
+    this.stagedParts.clear();
+  }
   // ------------------------------------------------------------------
   // Workbook structure
   // ------------------------------------------------------------------
@@ -4062,47 +4524,59 @@ var XlsxUpdater = class {
       return;
     }
     const entry = this.zip.getEntry("xl/sharedStrings.xml");
-    if (!entry) {
+    if (!entry && !this.stagedParts.has("xl/sharedStrings.xml")) {
       this.sharedStringsXml = null;
       return;
     }
-    this.sharedStringsXml = entry.getData().toString("utf8");
+    this.sharedStringsXml = this._entryData("xl/sharedStrings.xml").toString("utf8");
     this.sharedStringsValues = parseSharedStringsXml(this.sharedStringsXml);
-    const countMatch = /<sst\b[^>]*>/.exec(this.sharedStringsXml);
-    const countAttr = countMatch ? /count="(\d+)"/.exec(countMatch[0]) : null;
-    this.sharedStringsCount = countAttr ? parseInt(countAttr[1], 10) : 0;
+    const countMatch = /<(?:[A-Za-z_][\w.-]*:)?sst\b[^>]*>/i.exec(this.sharedStringsXml);
+    const countAttr = countMatch ? /(?:^|\s)count\s*=\s*["'](\d+)["']/.exec(countMatch[0]) : null;
+    this.sharedStringsCount = countAttr ? parseInt(countAttr[1], 10) : this.sharedStringsValues.length;
     this.sharedStringsValues.forEach((value, index) => {
       if (!this.stringIndexMap.has(value)) {
         this.stringIndexMap.set(value, index);
       }
     });
     this.sharedStringsOriginalLength = this.sharedStringsValues.length;
+    this.sharedStringsPending = [];
+    this.sharedStringsDirty = false;
   }
   _commitSharedStrings() {
-    if (this.sharedStringsXml === null || this.sharedStringsValues.length === this.sharedStringsOriginalLength) {
+    var _a;
+    if (this.sharedStringsXml === null || !this.sharedStringsDirty) {
       return;
     }
     let xml = this.sharedStringsXml;
-    const sstStart = xml.indexOf("<sst");
-    const sstTagEnd = xml.indexOf(">", sstStart);
-    if (sstStart !== -1 && sstTagEnd !== -1) {
-      const tag = xml.substring(sstStart, sstTagEnd + 1);
-      const newTag = tag.replace(/count="\d+"/, `count="${this.sharedStringsCount}"`).replace(/uniqueCount="\d+"/, `uniqueCount="${this.sharedStringsValues.length}"`);
-      xml = xml.substring(0, sstStart) + newTag + xml.substring(sstTagEnd + 1);
-    }
-    const sstEnd = xml.lastIndexOf("</sst>");
-    if (sstEnd === -1) {
-      return;
-    }
-    let appended = "";
-    for (let i = this.sharedStringsOriginalLength; i < this.sharedStringsValues.length; i++) {
-      const txt = this.sharedStringsValues[i];
+    const sstMatch = /<(?<prefix>[A-Za-z_][\w.-]*:)?sst\b[^>]*>/i.exec(xml);
+    if (!sstMatch || sstMatch.index === void 0) {
+      throw new Error("XlsxUpdater: sharedStrings.xml has no sst element.");
+    }
+    const tag = sstMatch[0];
+    const prefix = ((_a = sstMatch.groups) == null ? void 0 : _a.prefix) ?? "";
+    const newTag = _XlsxUpdater._replaceOrAddXmlAttribute(
+      _XlsxUpdater._replaceOrAddXmlAttribute(tag, "count", String(this.sharedStringsCount)),
+      "uniqueCount",
+      String(this.sharedStringsValues.length)
+    );
+    xml = xml.substring(0, sstMatch.index) + newTag + xml.substring(sstMatch.index + tag.length);
+    const closingRe = new RegExp(`</${prefix}sst\\s*>\\s*$`, "i");
+    const closingMatch = closingRe.exec(xml);
+    if (!closingMatch || closingMatch.index === void 0) {
+      throw new Error("XlsxUpdater: sharedStrings.xml has no closing sst element.");
+    }
+    const appended = this.sharedStringsPending.map((txt) => {
       const clean = escapeXmlText(txt);
       const preserve = clean.length > 0 && (clean[0] === " " || clean[clean.length - 1] === " " || /[\t\n\r]/.test(clean));
-      appended += preserve ? `<si><t xml:space="preserve">${clean}</t></si>` : `<si><t>${clean}</t></si>`;
-    }
-    xml = xml.substring(0, sstEnd) + appended + xml.substring(sstEnd);
+      const tAttr = preserve ? ' xml:space="preserve"' : "";
+      return `<${prefix}si><${prefix}t${tAttr}>${clean}</${prefix}t></${prefix}si>`;
+    }).join("");
+    xml = xml.substring(0, closingMatch.index) + appended + xml.substring(closingMatch.index);
     this.zip.updateFile("xl/sharedStrings.xml", Buffer.from(xml, "utf8"));
+    this.sharedStringsXml = xml;
+    this.sharedStringsOriginalLength = this.sharedStringsValues.length;
+    this.sharedStringsPending = [];
+    this.sharedStringsDirty = false;
   }
   // ------------------------------------------------------------------
   // Styles
@@ -4253,10 +4727,25 @@ var XlsxUpdater = class {
       index = this.sharedStringsValues.length;
       this.sharedStringsValues.push(text);
       this.stringIndexMap.set(text, index);
+      this.sharedStringsPending.push(text);
     }
     this.sharedStringsCount++;
+    this.sharedStringsDirty = true;
     return `<c r="${colRef}${rowNum}" t="s"${styleAttr}><v>${index}</v></c>`;
   }
+  static _replaceOrAddXmlAttribute(tag, name, value) {
+    const escaped = escapeXmlText(value);
+    const attribute = new RegExp(`(\\s${name}\\s*=\\s*["'])[^"']*(["'])`, "i");
+    if (attribute.test(tag)) {
+      return tag.replace(attribute, `$1${escaped}$2`);
+    }
+    const insertion = ` ${name}="${escaped}"`;
+    return tag.endsWith("/>") ? `${tag.slice(0, -2)}${insertion}/>` : `${tag.slice(0, -1)}${insertion}>`;
+  }
+  _sharedStringRefCount(sheetXml) {
+    const cellTags = sheetXml.match(/<(?:(?:[A-Za-z_][\w.-]*):)?c\b[^>]*>/gi) ?? [];
+    return cellTags.filter((tag) => /(?:^|\s)t\s*=\s*["']s["']/i.test(tag)).length;
+  }
   // ------------------------------------------------------------------
   // Worksheet XML patching
   // ------------------------------------------------------------------
@@ -4298,6 +4787,109 @@ var XlsxUpdater = class {
     }
     return xml;
   }
+  _patchSheetFile(sheetXml, rowsPath, outputPath, dimensionRef) {
+    var _a, _b, _c, _d;
+    const source = Buffer.from(sheetXml, "utf8");
+    const text = sheetXml;
+    const replacements = [];
+    const emptySheetData = /<(?<prefix>[A-Za-z_][\w.-]*:)?sheetData\b(?<attrs>[^>]*)\/>/i.exec(text);
+    if (emptySheetData && emptySheetData.index !== void 0) {
+      const prefix = ((_a = emptySheetData.groups) == null ? void 0 : _a.prefix) ?? "";
+      replacements.push({
+        start: emptySheetData.index,
+        end: emptySheetData.index + emptySheetData[0].length,
+        data: Buffer.from(`<${prefix}sheetData${((_b = emptySheetData.groups) == null ? void 0 : _b.attrs) ?? ""}>`, "utf8"),
+        rows: true,
+        suffix: Buffer.from(`</${prefix}sheetData>`, "utf8")
+      });
+    } else {
+      const opening = /<(?<prefix>[A-Za-z_][\w.-]*:)?sheetData\b[^>]*>/i.exec(text);
+      if (!opening || opening.index === void 0) {
+        throw new Error("XlsxUpdater: <sheetData> element not found in worksheet XML.");
+      }
+      const prefix = ((_c = opening.groups) == null ? void 0 : _c.prefix) ?? "";
+      const closeRe = new RegExp(`</${prefix}sheetData\\s*>`, "i");
+      const closing = closeRe.exec(text.slice(opening.index + opening[0].length));
+      if (!closing || closing.index === void 0) {
+        throw new Error("XlsxUpdater: <sheetData> element not closed in worksheet XML.");
+      }
+      const closingStart = opening.index + opening[0].length + closing.index;
+      replacements.push({
+        start: opening.index + opening[0].length,
+        end: closingStart,
+        rows: true
+      });
+    }
+    const dimension = /<(?<prefix>[A-Za-z_][\w.-]*:)?dimension\b[^>]*>/i.exec(text);
+    if (dimension && dimension.index !== void 0) {
+      replacements.push({
+        start: dimension.index,
+        end: dimension.index + dimension[0].length,
+        data: Buffer.from(
+          _XlsxUpdater._replaceOrAddXmlAttribute(dimension[0], "ref", dimensionRef)
+        )
+      });
+    } else {
+      const root = /<(?<prefix>[A-Za-z_][\w.-]*:)?worksheet\b[^>]*>/i.exec(text);
+      if (root && root.index !== void 0) {
+        const prefix = ((_d = root.groups) == null ? void 0 : _d.prefix) ?? "";
+        const insertAt = root.index + root[0].length;
+        replacements.push({
+          start: insertAt,
+          end: insertAt,
+          data: Buffer.from(`<${prefix}dimension ref="${dimensionRef}"/>`, "utf8")
+        });
+      }
+    }
+    const autoFilter = /<(?<prefix>[A-Za-z_][\w.-]*:)?autoFilter\b[^>]*>/i.exec(text);
+    if (autoFilter && autoFilter.index !== void 0) {
+      replacements.push({
+        start: autoFilter.index,
+        end: autoFilter.index + autoFilter[0].length,
+        data: Buffer.from(
+          _XlsxUpdater._replaceOrAddXmlAttribute(autoFilter[0], "ref", dimensionRef),
+          "utf8"
+        )
+      });
+    }
+    replacements.sort((a, b) => a.start - b.start || a.end - b.end);
+    const fd = fs5.openSync(outputPath, "w");
+    let cursor = 0;
+    const writeBuffer = (data) => {
+      fs5.writeSync(fd, data);
+    };
+    const copyRows = () => {
+      const rowsFd = fs5.openSync(rowsPath, "r");
+      try {
+        const chunk = Buffer.alloc(1024 * 1024);
+        const length = fs5.statSync(rowsPath).size;
+        let position = 0;
+        while (position < length) {
+          const count = fs5.readSync(rowsFd, chunk, 0, Math.min(chunk.length, length - position), position);
+          if (count <= 0) throw new Error("XlsxUpdater: failed to read staged rows.");
+          fs5.writeSync(fd, chunk, 0, count);
+          position += count;
+        }
+      } finally {
+        fs5.closeSync(rowsFd);
+      }
+    };
+    try {
+      for (const replacement of replacements) {
+        const startByte = Buffer.byteLength(text.slice(0, replacement.start), "utf8");
+        const endByte = Buffer.byteLength(text.slice(0, replacement.end), "utf8");
+        if (startByte < cursor) throw new Error("XlsxUpdater: overlapping worksheet replacements.");
+        writeBuffer(source.subarray(cursor, startByte));
+        if (replacement.data) writeBuffer(replacement.data);
+        if (replacement.rows) copyRows();
+        if (replacement.suffix) writeBuffer(replacement.suffix);
+        cursor = endByte;
+      }
+      writeBuffer(source.subarray(cursor));
+    } finally {
+      fs5.closeSync(fd);
+    }
+  }
   // ------------------------------------------------------------------
   // Pivot table integration
   // ------------------------------------------------------------------
@@ -4326,8 +4918,8 @@ var XlsxUpdater = class {
     }
   }
   _addRefreshOnLoadToPivotTables() {
-    for (const path2 of this.pivotTableDefPaths) {
-      const entry = this.zip.getEntry(path2);
+    for (const path7 of this.pivotTableDefPaths) {
+      const entry = this.zip.getEntry(path7);
       if (!entry) continue;
       let xml = entry.getData().toString("utf8");
       const rootRe = /<pivotTableDefinition\b[^>]*>/;
@@ -4335,13 +4927,15 @@ 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(path7, Buffer.from(xml, "utf8"));
     }
   }
 };
 
 // src/XlsbUpdater.ts
-import * as fs4 from "fs";
+import * as fs6 from "fs";
+import * as os2 from "os";
+import * as path5 from "path";
 import AdmZip3 from "adm-zip";
 
 // src/biff12Utils.ts
@@ -4420,7 +5014,9 @@ var XlsbUpdater = class {
   /**
    * @param path Path to an existing `.xlsb` file.
    */
-  constructor(path2) {
+  constructor(filePath) {
+    this.temporaryDirectory = null;
+    this.stagedParts = /* @__PURE__ */ new Map();
     this.sheetNameToPath = /* @__PURE__ */ new Map();
     this.pivotCacheDefPaths = [];
     this.sharedStringsBuf = null;
@@ -4429,16 +5025,17 @@ var XlsbUpdater = class {
     this.sharedStringsUnique = 0;
     this.sharedStringsEndSst = 0;
     this.stringIndexMap = /* @__PURE__ */ new Map();
+    this.sharedStringsDirty = false;
     // ------------------------------------------------------------------
     // Shared strings
     // ------------------------------------------------------------------
     this._appendCount = 0;
-    this.sourcePath = path2;
+    this.sourcePath = filePath;
     this._oaEpoch = Date.UTC(1899, 11, 30);
-    if (!fs4.existsSync(path2)) {
-      throw new Error(`XlsbUpdater: file not found: ${path2}`);
+    if (!fs6.existsSync(filePath)) {
+      throw new Error(`XlsbUpdater: file not found: ${filePath}`);
     }
-    this.zip = new AdmZip3(path2);
+    this.zip = new AdmZip3(filePath);
     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."
@@ -4469,8 +5066,15 @@ var XlsbUpdater = class {
     if (!entry) {
       throw new Error(`XlsbUpdater: worksheet part missing for sheet "${sheetName}".`);
     }
-    const sheetBuf = entry.getData();
+    const sheetBuf = this._entryData(sheetPath);
     this._ensureSharedStringsLoaded();
+    if (this.sharedStringsBuf !== null) {
+      this.sharedStringsTotal = Math.max(
+        0,
+        this.sharedStringsTotal - this._sharedStringRefCount(sheetBuf)
+      );
+      this.sharedStringsDirty = true;
+    }
     let dataStyles = /* @__PURE__ */ new Map();
     let headerStyles = /* @__PURE__ */ new Map();
     let dateXf = null;
@@ -4499,25 +5103,310 @@ var XlsbUpdater = class {
     }
     this._patchDimension(newSheet, lastRowIdx, lastCol);
     this.zip.updateFile(sheetPath, newSheet);
-    if (this.sharedStringsBuf !== null && this._appendCount > 0) {
+    this._discardStagedPart(sheetPath);
+    if (this.sharedStringsBuf !== null) {
       this._commitSharedStrings();
     }
     const rwLast = Math.max(0, rows.length + (headers ? 1 : 0) - 1);
     const colLast = lastCol;
     this._patchPivotCaches(sheetName, rwLast, colLast);
   }
+  /** Replace worksheet rows from a one-pass source. */
+  async replaceSheetDataStream(sheetName, rows, options = {}) {
+    const { headers, styleFallback = "inherit" } = options;
+    if (styleFallback !== "inherit" && styleFallback !== "general") {
+      throw new Error("XlsbUpdater: styleFallback must be 'inherit' or 'general'.");
+    }
+    const sheetPath = this.sheetNameToPath.get(sheetName);
+    if (!sheetPath) {
+      throw new Error(`XlsbUpdater: sheet "${sheetName}" not found in the workbook.`);
+    }
+    const entry = this.zip.getEntry(sheetPath);
+    if (!entry) {
+      throw new Error(`XlsbUpdater: worksheet part missing for sheet "${sheetName}".`);
+    }
+    const oldStage = this.stagedParts.get(sheetPath);
+    const beforeValuesLength = this.sharedStringsValues.length;
+    const beforeAppendCount = this._appendCount;
+    const beforeSharedStringsTotal = this.sharedStringsTotal;
+    const beforeSharedStringsUnique = this.sharedStringsUnique;
+    const beforeSharedStringsEndSst = this.sharedStringsEndSst;
+    const beforeSharedStringsDirty = this.sharedStringsDirty;
+    const beforeStringIndexMap = new Map(this.stringIndexMap);
+    const sharedStringsEntry = this.zip.getEntry("xl/sharedStrings.bin");
+    const beforeSharedStringsBytes = sharedStringsEntry || this.stagedParts.has("xl/sharedStrings.bin") ? Buffer.from(this._entryData("xl/sharedStrings.bin")) : null;
+    const beforeSharedStringsBuf = this.sharedStringsBuf ? Buffer.from(this.sharedStringsBuf) : null;
+    const oldSheet = this._entryData(sheetPath);
+    const rowsPath = this._temporaryPath(".rows");
+    const outputPath = this._temporaryPath(".bin");
+    const createdParts = [rowsPath, outputPath];
+    let output = null;
+    try {
+      this._ensureSharedStringsLoaded();
+      if (this.sharedStringsBuf !== null) {
+        this.sharedStringsTotal = Math.max(
+          0,
+          this.sharedStringsTotal - this._sharedStringRefCount(oldSheet)
+        );
+        this.sharedStringsDirty = true;
+      }
+      let dataStyles = /* @__PURE__ */ new Map();
+      let headerStyles = /* @__PURE__ */ new Map();
+      let dateXf = null;
+      if (styleFallback !== "general") {
+        const collected = this._collectStyles(oldSheet);
+        dataStyles = collected.dataStyles;
+        headerStyles = collected.headerStyles;
+        dateXf = this._findDateXf();
+      }
+      const rowOutput = fs6.createWriteStream(rowsPath);
+      output = rowOutput;
+      let outputError = null;
+      rowOutput.on("error", (error) => {
+        outputError = error;
+      });
+      let writtenBytes = 0;
+      let lastKeptEnd = 0;
+      let width = (headers == null ? void 0 : headers.length) ?? 0;
+      let dataRowsSeen = 0;
+      let keptDataRows = 0;
+      let pendingEmptyWidth = 0;
+      let nextRow = 0;
+      const rowHeaderOffsets = [];
+      const write = async (data) => {
+        if (outputError) throw outputError;
+        writtenBytes += data.length;
+        if (rowOutput.write(data)) return;
+        await new Promise((resolve4, reject) => {
+          const onDrain = () => {
+            cleanup();
+            resolve4();
+          };
+          const onError = (error) => {
+            cleanup();
+            reject(error);
+          };
+          const cleanup = () => {
+            rowOutput.off("drain", onDrain);
+            rowOutput.off("error", onError);
+          };
+          rowOutput.once("drain", onDrain);
+          rowOutput.once("error", onError);
+        });
+      };
+      const writeRow = async (rowNumber, cells) => {
+        rowHeaderOffsets.push(writtenBytes);
+        const header = Buffer.alloc(27);
+        header[0] = 0;
+        header[1] = 25;
+        header.writeInt32LE(rowNumber, 2);
+        header[10] = 44;
+        header[11] = 1;
+        header[15] = 1;
+        header.writeInt32LE(0, 19);
+        header.writeInt32LE(0, 23);
+        await write(header);
+        for (const cell of cells) await write(cell);
+      };
+      if (headers !== void 0) {
+        await writeRow(0, headers.map((value, column) => this._stringCellBytes(column, styleFallback === "general" ? 0 : headerStyles.get(column) ?? 0, value)));
+        lastKeptEnd = writtenBytes;
+        nextRow = 1;
+      }
+      for await (const sourceRow of rows) {
+        if (typeof sourceRow === "string" || sourceRow instanceof Uint8Array) {
+          throw new TypeError("Each row must be an iterable of cells, not text");
+        }
+        const row = Array.from(sourceRow);
+        const cells = row.map((value, column) => value === null || value === void 0 ? null : this._valueCellBytes(value, column, dataStyles, dateXf)).filter((cell) => cell !== null);
+        await writeRow(nextRow, cells);
+        dataRowsSeen++;
+        nextRow++;
+        if (row.every((value) => value === null || value === void 0)) {
+          pendingEmptyWidth = Math.max(pendingEmptyWidth, row.length);
+        } else {
+          width = Math.max(width, pendingEmptyWidth, row.length);
+          pendingEmptyWidth = 0;
+          keptDataRows = dataRowsSeen;
+          lastKeptEnd = writtenBytes;
+        }
+      }
+      await new Promise((resolve4, reject) => {
+        rowOutput.once("close", resolve4);
+        rowOutput.once("error", reject);
+        rowOutput.end();
+      });
+      if (outputError) throw outputError;
+      const rowsFd = fs6.openSync(rowsPath, "r+");
+      try {
+        fs6.ftruncateSync(rowsFd, lastKeptEnd);
+      } finally {
+        fs6.closeSync(rowsFd);
+      }
+      const lastCol = Math.max(0, width - 1);
+      const rowPatchFd = fs6.openSync(rowsPath, "r+");
+      try {
+        const lastColBuffer = Buffer.alloc(4);
+        lastColBuffer.writeInt32LE(lastCol, 0);
+        for (const offset of rowHeaderOffsets) {
+          if (offset >= lastKeptEnd) continue;
+          fs6.writeSync(rowPatchFd, lastColBuffer, 0, lastColBuffer.length, offset + 23);
+        }
+      } finally {
+        fs6.closeSync(rowPatchFd);
+      }
+      const { rowsStart, rowsEnd, autoFilterRanges } = this._findRowsRegion(oldSheet);
+      const oldLength = oldSheet.length;
+      const newRowsLength = fs6.statSync(rowsPath).size;
+      const delta = newRowsLength - (rowsEnd - rowsStart);
+      const outputFd = fs6.openSync(outputPath, "w");
+      try {
+        fs6.writeSync(outputFd, oldSheet, 0, rowsStart, null);
+        const rowsFdRead = fs6.openSync(rowsPath, "r");
+        try {
+          const chunk = Buffer.alloc(1024 * 1024);
+          let position = 0;
+          while (position < newRowsLength) {
+            const count = fs6.readSync(rowsFdRead, chunk, 0, Math.min(chunk.length, newRowsLength - position), position);
+            if (count <= 0) throw new Error("XlsbUpdater: failed to read staged rows.");
+            fs6.writeSync(outputFd, chunk, 0, count);
+            position += count;
+          }
+        } finally {
+          fs6.closeSync(rowsFdRead);
+        }
+        fs6.writeSync(outputFd, oldSheet, rowsEnd, oldLength - rowsEnd, rowsStart + newRowsLength);
+      } finally {
+        fs6.closeSync(outputFd);
+      }
+      this._patchSheetMetadataFile(
+        outputPath,
+        oldSheet,
+        rowsEnd,
+        delta,
+        autoFilterRanges,
+        Math.max(0, keptDataRows + (headers !== void 0 ? 1 : 0) - 1),
+        lastCol
+      );
+      this._stagePart(sheetPath, outputPath);
+      this._commitSharedStrings();
+      this._patchPivotCaches(
+        sheetName,
+        Math.max(0, keptDataRows + (headers !== void 0 ? 1 : 0) - 1),
+        lastCol
+      );
+      if (oldStage && oldStage !== outputPath) this._removeTemporaryFile(oldStage);
+      createdParts.splice(createdParts.indexOf(outputPath), 1);
+    } catch (error) {
+      this.sharedStringsValues.length = beforeValuesLength;
+      this._appendCount = beforeAppendCount;
+      this.sharedStringsTotal = beforeSharedStringsTotal;
+      this.sharedStringsUnique = beforeSharedStringsUnique;
+      this.sharedStringsEndSst = beforeSharedStringsEndSst;
+      this.sharedStringsDirty = beforeSharedStringsDirty;
+      this.sharedStringsBuf = beforeSharedStringsBuf;
+      this.stringIndexMap.clear();
+      for (const [value, index] of beforeStringIndexMap) this.stringIndexMap.set(value, index);
+      if (beforeSharedStringsBytes) {
+        this.zip.updateFile("xl/sharedStrings.bin", beforeSharedStringsBytes);
+      }
+      if (oldStage) this.stagedParts.set(sheetPath, oldStage);
+      else this.stagedParts.delete(sheetPath);
+      throw error;
+    } finally {
+      if (output && !output.closed) output.destroy();
+      for (const temporaryPath of createdParts) this._removeTemporaryFile(temporaryPath);
+    }
+  }
   /**
    * Write the updated workbook to disk.
    * @param outputPath Destination path; defaults to the source file (overwrites in place).
    */
   save(outputPath) {
     const target = outputPath ?? this.sourcePath;
-    fs4.writeFileSync(target, this.zip.toBuffer());
+    this._materializeStagedParts();
+    writeBufferAtomically(this.zip.toBuffer(), target);
+  }
+  /** Save staged streaming replacements without materialising the ZIP. */
+  async saveStreaming(outputPath) {
+    const target = outputPath ?? this.sourcePath;
+    await writeAdmZipStreaming(this.zip, this.stagedParts, target);
+    this._materializeStagedParts();
   }
   /** The updated workbook as an in-memory ZIP buffer. */
   toBuffer() {
+    this._materializeStagedParts();
     return this.zip.toBuffer();
   }
+  /**
+   * 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() {
+    for (const stagedPath of this.stagedParts.values()) {
+      try {
+        fs6.rmSync(stagedPath, { force: true });
+      } catch {
+      }
+    }
+    this.stagedParts.clear();
+    if (this.temporaryDirectory !== null) {
+      try {
+        fs6.rmSync(this.temporaryDirectory, { recursive: true, force: true });
+      } catch {
+      }
+      this.temporaryDirectory = null;
+    }
+  }
+  /** Support `using` declarations for automatic staging cleanup. */
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+  _ensureTemporaryDirectory() {
+    if (this.temporaryDirectory === null) {
+      this.temporaryDirectory = fs6.mkdtempSync(path5.join(os2.tmpdir(), "spreadsheet-updater-"));
+    } else {
+      try {
+        fs6.mkdirSync(this.temporaryDirectory, { recursive: true });
+      } catch {
+      }
+    }
+    return this.temporaryDirectory;
+  }
+  _temporaryPath(suffix) {
+    return path5.join(this._ensureTemporaryDirectory(), `part-${Date.now()}-${Math.random().toString(16).slice(2)}${suffix}`);
+  }
+  _removeTemporaryFile(filePath) {
+    try {
+      fs6.rmSync(filePath);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  _entryData(name) {
+    const stagedPath = this.stagedParts.get(name);
+    if (stagedPath) return fs6.readFileSync(stagedPath);
+    const entry = this.zip.getEntry(name);
+    if (!entry) throw new Error(`XlsbUpdater: ZIP member missing: ${name}`);
+    return entry.getData();
+  }
+  _stagePart(name, filePath) {
+    this.stagedParts.set(name, filePath);
+  }
+  _discardStagedPart(name) {
+    const stagedPath = this.stagedParts.get(name);
+    if (!stagedPath) return;
+    this._removeTemporaryFile(stagedPath);
+    this.stagedParts.delete(name);
+  }
+  _materializeStagedParts() {
+    for (const [name, stagedPath] of this.stagedParts) {
+      this.zip.updateFile(name, fs6.readFileSync(stagedPath));
+      this._removeTemporaryFile(stagedPath);
+    }
+    this.stagedParts.clear();
+  }
   // ------------------------------------------------------------------
   // Workbook structure
   // ------------------------------------------------------------------
@@ -4567,11 +5456,11 @@ var XlsbUpdater = class {
       return;
     }
     const entry = this.zip.getEntry("xl/sharedStrings.bin");
-    if (!entry) {
+    if (!entry && !this.stagedParts.has("xl/sharedStrings.bin")) {
       this.sharedStringsBuf = null;
       return;
     }
-    this.sharedStringsBuf = entry.getData();
+    this.sharedStringsBuf = this._entryData("xl/sharedStrings.bin");
     const parsed = parseSharedStringsBin(this.sharedStringsBuf);
     this.sharedStringsValues = parsed.values;
     this.sharedStringsTotal = parsed.total;
@@ -4583,9 +5472,10 @@ var XlsbUpdater = class {
       }
     });
     this._appendCount = 0;
+    this.sharedStringsDirty = false;
   }
   _commitSharedStrings() {
-    if (this.sharedStringsBuf === null || this._appendCount === 0) return;
+    if (this.sharedStringsBuf === null || !this.sharedStringsDirty) return;
     const originalValuesLength = this.sharedStringsValues.length - this._appendCount;
     let newItems = Buffer.alloc(0);
     for (let i = originalValuesLength; i < this.sharedStringsValues.length; i++) {
@@ -4611,6 +5501,9 @@ var XlsbUpdater = class {
       pos = rec.dataEnd;
     }
     this.zip.updateFile("xl/sharedStrings.bin", out);
+    this.sharedStringsBuf = out;
+    this._appendCount = 0;
+    this.sharedStringsDirty = false;
   }
   // ------------------------------------------------------------------
   // Styles
@@ -4793,12 +5686,51 @@ var XlsbUpdater = class {
       this._appendCount++;
     }
     this.sharedStringsTotal++;
+    this.sharedStringsDirty = true;
     const payload = Buffer.alloc(12);
     payload.writeUInt32LE(col, 0);
     payload.writeUInt32LE(style, 4);
     payload.writeUInt32LE(index, 8);
     return buildRecord(7, payload);
   }
+  _sharedStringRefCount(sheetBuf) {
+    const rec = { headerStart: 0, dataStart: 0, dataEnd: 0, id: 0, len: 0 };
+    let pos = 0;
+    let count = 0;
+    while (readRecord(sheetBuf, pos, rec)) {
+      if (rec.id === 7) count++;
+      pos = rec.dataEnd;
+    }
+    return count;
+  }
+  _patchSheetMetadataFile(filePath, originalSheet, rowsEnd, delta, autoFilterRanges, lastRowIdx, lastCol) {
+    const fd = fs6.openSync(filePath, "r+");
+    try {
+      const patchInt32 = (offset, value) => {
+        const bytes = Buffer.alloc(4);
+        bytes.writeInt32LE(value, 0);
+        fs6.writeSync(fd, bytes, 0, bytes.length, offset);
+      };
+      for (const filterOffset of autoFilterRanges) {
+        const newOffset = filterOffset >= rowsEnd ? filterOffset + delta : filterOffset;
+        patchInt32(newOffset + 4, lastRowIdx);
+        patchInt32(newOffset + 12, lastCol);
+      }
+      const rec = { headerStart: 0, dataStart: 0, dataEnd: 0, id: 0, len: 0 };
+      let pos = 0;
+      while (readRecord(originalSheet, pos, rec)) {
+        if (rec.id === 152 && rec.len >= 36) {
+          const shift = rec.dataStart >= rowsEnd ? delta : 0;
+          patchInt32(rec.dataStart + shift + 24, lastRowIdx);
+          patchInt32(rec.dataStart + shift + 32, lastCol);
+          break;
+        }
+        pos = rec.dataEnd;
+      }
+    } finally {
+      fs6.closeSync(fd);
+    }
+  }
   // ------------------------------------------------------------------
   // Rows region detection
   // ------------------------------------------------------------------
@@ -4850,8 +5782,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 path7 of this.pivotCacheDefPaths) {
+      const entry = this.zip.getEntry(path7);
       if (!entry) continue;
       const buf = Buffer.from(entry.getData());
       const rec = { headerStart: 0, dataStart: 0, dataEnd: 0, id: 0, len: 0 };
@@ -4883,11 +5815,188 @@ var XlsbUpdater = class {
         }
       }
       if (patched) {
-        this.zip.updateFile(path2, buf);
+        this.zip.updateFile(path7, buf);
       }
     }
   }
 };
+
+// src/ExcelConverter.ts
+import * as fs7 from "fs";
+import * as path6 from "path";
+import { randomUUID as randomUUID3 } from "crypto";
+import { spawn } from "child_process";
+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 = path6.resolve(inputPath);
+  const output = path6.resolve(outputPath);
+  if (path6.extname(input).toLowerCase() !== inputExtension) {
+    throw new Error(
+      `Excel conversion: source must have the ${inputExtension} extension: ${inputPath}`
+    );
+  }
+  if (path6.extname(output).toLowerCase() !== outputExtension) {
+    throw new Error(
+      `Excel conversion: destination must have the ${outputExtension} extension: ${outputPath}`
+    );
+  }
+  if (!fs7.existsSync(input)) {
+    throw new Error(`Excel conversion: source file not found: ${inputPath}`);
+  }
+  if (!fs7.statSync(input).isFile()) {
+    throw new Error(`Excel conversion: source path is not a file: ${inputPath}`);
+  }
+  if (!fs7.existsSync(path6.dirname(output))) {
+    throw new Error(`Excel conversion: destination directory not found: ${path6.dirname(output)}`);
+  }
+  if (fs7.existsSync(output)) {
+    if (fs7.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((resolve4, reject) => {
+    var _a, _b, _c, _d;
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const child = 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) {
+        resolve4();
+        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 = path6.join(
+    path6.dirname(output),
+    `.${path6.basename(output, outputExtension)}.${randomUUID3()}.conversion${outputExtension}`
+  );
+  try {
+    await runPowerShellConversion(input, temporaryOutput, fileFormat);
+    if (!fs7.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 (fs7.existsSync(temporaryOutput)) {
+      try {
+        fs7.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);
+}
 export {
   BiffReaderWriter,
   BigBuffer,
@@ -4899,10 +6008,13 @@ export {
   XlsbReader,
   XlsbUpdater,
   XlsbWriter,
+  XlsxUpdater as XlsmUpdater,
   XlsxReader,
   XlsxUpdater,
   XlsxWriter,
   applyHeaderWidths,
+  convertXlsbToXlsx,
+  convertXlsxToXlsb,
   defaultColWidth,
   getFormat,
   initColWidths,