@js-ak/excel-toolbox 1.8.3 → 1.9.0

package/build/esm/lib/workbook-builder/utils/write-worksheet-xml.js

@@ -0,0 +1,203 @@
+import fs from "node:fs";
+import fsPromises from "node:fs/promises";
+import path from "node:path";
+import readline from "node:readline";
+import { XML_DECLARATION, XML_NAMESPACES } from "./constants.js";
+import { columnIndexToLetter } from "../../template/utils/column-index-to-letter.js";
+import { columnLetterToIndex } from "../../template/utils/column-letter-to-index.js";
+/**
+ * Writes a worksheet XML file to the given destination using a streaming approach.
+ *
+ * - Streams rows and cells to minimize memory usage
+ * - Tracks the worksheet dimension (min/max rows/cols) while streaming
+ * - Updates the <dimension> ref at the end by rewriting the file in a buffered pass
+ *
+ * @param destination - Absolute or relative file path for the worksheet XML
+ * @param rows - Map of rowIndex -> RowData with cells
+ * @param merges - Merge ranges to append after <sheetData>
+ * @returns Promise that resolves when the file is fully written and dimension updated
+ */
+export async function writeWorksheetXml(destination, rows = new Map(), merges = []) {
+    // ensure folder exists
+    await fsPromises.mkdir(path.dirname(destination), { recursive: true });
+    const stream = fs.createWriteStream(destination, { encoding: "utf-8" });
+    // Track dimension incrementally while streaming
+    let minRow = Number.POSITIVE_INFINITY;
+    let maxRow = 0;
+    let minCol = Number.POSITIVE_INFINITY;
+    let maxCol = 0;
+    try {
+        // header
+        stream.write(XML_DECLARATION + "\n");
+        stream.write(`<worksheet xmlns="${XML_NAMESPACES.SPREADSHEET_ML}" xmlns:r="${XML_NAMESPACES.OFFICE_DOCUMENT}">\n`);
+        // dimension
+        stream.write("  <dimension ref=\"A1:A1\"/>\n");
+        // sheetViews
+        stream.write("  <sheetViews>\n");
+        stream.write("    <sheetView workbookViewId=\"0\"/>\n");
+        stream.write("  </sheetViews>\n");
+        // sheetFormatPr
+        stream.write("  <sheetFormatPr defaultRowHeight=\"15\"/>\n");
+        // sheetData start
+        stream.write("  <sheetData>\n");
+        // rows (stream, without accumulation)
+        const typeSetSkipping = new Set(["n"]);
+        let processedRows = 0;
+        for (const [rowNumber, row] of rows) {
+            if (row.cells.size > 0) {
+                if (rowNumber < minRow)
+                    minRow = rowNumber;
+                if (rowNumber > maxRow)
+                    maxRow = rowNumber;
+            }
+            // Build the row string
+            const rowStart = `    <row r="${rowNumber}">\n`;
+            const rowEnd = "    </row>\n";
+            // write to stream with backpressure control
+            if (!stream.write(rowStart)) {
+                await new Promise(resolve => stream.once("drain", () => resolve()));
+            }
+            // if you need to stream cells, you can do so as well:
+            for (const [colNumber, cellData] of row.cells) {
+                const colIndex = columnLetterToIndex(colNumber) - 1;
+                if (colIndex < minCol)
+                    minCol = colIndex;
+                if (colIndex > maxCol)
+                    maxCol = colIndex;
+                const attrT = cellData.type && typeSetSkipping.has(cellData.type)
+                    ? ""
+                    : ` t="${cellData.type}"`;
+                const attrS = cellData.style?.index
+                    ? ` s="${cellData.style?.index}"`
+                    : "";
+                let cellXml = "";
+                if (cellData.isFormula) {
+                    cellXml = `      <c r="${colNumber}${rowNumber}"${attrS}${attrT}><f>${cellData.value}</f></c>\n`;
+                }
+                else {
+                    switch (cellData.type) {
+                        case "b": {
+                            cellXml = `      <c r="${colNumber}${rowNumber}"${attrS}${attrT}><v>${cellData.value ? "1" : "0"}</v></c>\n`;
+                            break;
+                        }
+                        case "inlineStr": {
+                            cellXml = `      <c r="${colNumber}${rowNumber}"${attrS}${attrT}><is><t>${cellData.value}</t></is></c>\n`;
+                            break;
+                        }
+                        default: {
+                            cellXml = `      <c r="${colNumber}${rowNumber}"${attrS}${attrT}><v>${cellData.value}</v></c>\n`;
+                            break;
+                        }
+                    }
+                }
+                stream.write(cellXml);
+                // if (!stream.write(cellXml)) {
+                // 	await new Promise<void>(resolve => stream.once("drain", () => resolve()));
+                // }
+            }
+            if (!stream.write(rowEnd)) {
+                await new Promise(resolve => stream.once("drain", () => resolve()));
+            }
+            // Unload the event loop every 100 rows
+            processedRows++;
+            if (processedRows % 100 === 0) {
+                await new Promise(resolve => setImmediate(resolve));
+            }
+            // Unload the event loop every 100 rows
+            // rows.delete(rowNumber);
+        }
+        // sheetData end
+        stream.write("  </sheetData>\n");
+        // mergeCells
+        if (merges.length > 0) {
+            stream.write(`  <mergeCells count="${merges.length}">\n`);
+            for (const merge of merges) {
+                if (merge.startCol < minCol)
+                    minCol = merge.startCol;
+                if (merge.endCol > maxCol)
+                    maxCol = merge.endCol;
+                if (merge.startRow < minRow)
+                    minRow = merge.startRow;
+                if (merge.endRow > maxRow)
+                    maxRow = merge.endRow;
+                const ref = `${columnIndexToLetter(merge.startCol)}${merge.startRow}:${columnIndexToLetter(merge.endCol)}${merge.endRow}`;
+                stream.write(`    <mergeCell ref="${ref}"/>\n`);
+            }
+            stream.write("  </mergeCells>\n");
+        }
+        // close worksheet
+        stream.write("</worksheet>\n");
+    }
+    finally {
+        stream.end();
+    }
+    let finalDimensionRef = "A1:A1";
+    if (Number.isFinite(minCol) && Number.isFinite(minRow) && maxCol >= 0 && maxRow > 0) {
+        finalDimensionRef = `${columnIndexToLetter(minCol)}${minRow}:${columnIndexToLetter(maxCol)}${maxRow}`;
+    }
+    await new Promise((resolve, reject) => {
+        stream.on("error", reject);
+        stream.on("finish", resolve);
+    });
+    await updateWorksheetDimensionInFile(destination, finalDimensionRef);
+    return;
+}
+// async function updateWorksheetDimensionInFile(destination: string, dimensionRef: string): Promise<void> {
+// 	const tempPath = `${destination}.tmp`;
+// 	const readStream = fs.createReadStream(destination, { encoding: "utf-8" });
+// 	const rl = readline.createInterface({ crlfDelay: Infinity, input: readStream });
+// 	const writeStream = fs.createWriteStream(tempPath, { encoding: "utf-8" });
+// 	let updated = false;
+// 	const rlClosed = new Promise<void>(resolve => rl.once("close", resolve));
+// 	for await (const line of rl) {
+// 		let outLine = line;
+// 		if (!updated && line.includes("<dimension")) {
+// 			outLine = line.replace(/(<dimension[^>]*ref=")[^"]*("[^>]*\/>)/, `$1${dimensionRef}$2`);
+// 			updated = true;
+// 		}
+// 		if (!writeStream.write(outLine + "\n")) {
+// 			await new Promise<void>(resolve => writeStream.once("drain", resolve));
+// 		}
+// 	}
+// 	await rlClosed;
+// 	writeStream.end();
+// 	await new Promise<void>(resolve => writeStream.once("finish", resolve));
+// 	await fsPromises.rename(tempPath, destination);
+// }
+/**
+ * Updates the <dimension> ref attribute in an existing worksheet XML file.
+ * Performs a buffered line-by-line rewrite to a temporary file, then renames it in place.
+ *
+ * @param destination - Path to the worksheet XML file to update
+ * @param dimensionRef - Final dimension reference, e.g., "A1:C25"
+ */
+async function updateWorksheetDimensionInFile(destination, dimensionRef) {
+    const tempPath = `${destination}.tmp`;
+    const readStream = fs.createReadStream(destination, { encoding: "utf-8" });
+    const rl = readline.createInterface({ crlfDelay: Infinity, input: readStream });
+    const writeStream = fs.createWriteStream(tempPath, { encoding: "utf-8" });
+    let updated = false;
+    let buffer = "";
+    const BUFFER_SIZE = 64 * 1024; // 64 KB
+    for await (const line of rl) {
+        let outLine = line;
+        if (!updated && line.includes("<dimension")) {
+            outLine = line.replace(/(<dimension[^>]*ref=")[^"]*("[^>]*\/>)/, `$1${dimensionRef}$2`);
+            updated = true;
+        }
+        buffer += outLine + "\n";
+        if (buffer.length >= BUFFER_SIZE) {
+            if (!writeStream.write(buffer)) {
+                await new Promise(resolve => writeStream.once("drain", resolve));
+            }
+            buffer = "";
+        }
+    }
+    // Write remaining buffer
+    if (buffer)
+        writeStream.write(buffer);
+    // Close streams
+    await new Promise(resolve => writeStream.end(resolve));
+    // Replace original file
+    await fsPromises.rename(tempPath, destination);
+}

package/build/esm/lib/workbook-builder/utils/write-xml.js

@@ -0,0 +1,34 @@
+export async function writeXml(node, stream, level = 0, chunkSize = 100) {
+    const { attrs = {}, children = [], tag } = node;
+    const attrStr = Object.entries(attrs)
+        .filter(([, v]) => v !== undefined && v !== null)
+        .map(([k, v]) => ` ${k}="${v}"`)
+        .join("");
+    const gap = "  ".repeat(level);
+    // No children → self-closing tag
+    if (!children.length) {
+        stream.write(`${gap}<${tag}${attrStr}/>\n`);
+        return;
+    }
+    // Single text child → inline formatting
+    if (children.length === 1 && typeof children[0] === "string" && !children[0].includes("<")) {
+        stream.write(`${gap}<${tag}${attrStr}>${children[0]}</${tag}>\n`);
+        return;
+    }
+    // Has children → recursive streaming
+    stream.write(`${gap}<${tag}${attrStr}>\n`);
+    let processed = 0;
+    for (const c of children) {
+        if (typeof c === "string") {
+            stream.write(`${"  ".repeat(level + 1)}${c}\n`);
+        }
+        else {
+            await writeXml(c, stream, level + 1, chunkSize);
+        }
+        processed++;
+        if (processed % chunkSize === 0) {
+            await new Promise(resolve => setImmediate(resolve));
+        }
+    }
+    stream.write(`${gap}</${tag}>\n`);
+}

package/build/esm/lib/workbook-builder/workbook-builder.js

@@ -0,0 +1,374 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import * as Zip from "../zip/index.js";
+import { columnIndexToLetter, updateDimension } from "../template/utils/index.js";
+import * as Utils from "./utils/index.js";
+import * as Default from "./default/index.js";
+import * as MergeCells from "./merge-cells/index.js";
+import * as SharedStringRef from "./shared-string-ref/index.js";
+import * as StyleRef from "./style-ref/index.js";
+/**
+ * Builds Excel workbooks by composing sheets, styles, shared strings and merges,
+ * and provides methods to save to file or stream.
+ *
+ * @experimental This API is experimental and might change in future versions.
+ */
+export class WorkbookBuilder {
+    /** In-memory representation of workbook files to be zipped. */
+    #files;
+    /** Collection of sheets keyed by sheet name. */
+    #sheets = new Map();
+    /** Shared strings storage used by cells of type "s". */
+    #sharedStrings = [];
+    /** Map for lookup of shared string indices (key = string, value = index). */
+    #sharedStringMap = new Map();
+    /** Workbook style collections. */
+    #borders;
+    #cellXfs;
+    #fills;
+    #fonts;
+    #numFmts;
+    /** Map of serialized style JSON to style index (xf). */
+    #styleMap = new Map();
+    /** Map caches for fast de-duplication of style components. */
+    #fontMap = new Map();
+    #fillMap = new Map();
+    #borderMap = new Map();
+    /** Merge cell ranges grouped by sheet name. */
+    #mergeCells = new Map();
+    /**
+     * Creates a new workbook with a default sheet and initial style collections.
+     *
+     * @param options.defaultSheetName - The name for the initial sheet
+     */
+    constructor({ defaultSheetName = Default.sheetName(), } = {}) {
+        this.#files = Utils.initializeFiles(defaultSheetName);
+        // Initialize base style collections
+        this.#borders = [Default.border()];
+        this.#fills = [Default.fill()];
+        this.#fonts = [Default.font()];
+        this.#numFmts = [];
+        this.#cellXfs = [Default.cellXf()];
+        // Seed component maps with defaults at index 0
+        this.#fontMap.set(JSON.stringify(this.#fonts[0]), 0);
+        this.#fillMap.set(JSON.stringify(this.#fills[0]), 0);
+        this.#borderMap.set(JSON.stringify(this.#borders[0]), 0);
+        const sheet = Utils.createSheet(defaultSheetName, {
+            addMerge: this.#addMerge.bind(this),
+            addOrGetStyle: this.#addOrGetStyle.bind(this),
+            addSharedString: this.#addSharedString.bind(this),
+            removeMerge: this.#removeMerge.bind(this),
+        });
+        this.#sheets.set(Default.sheetName(), sheet);
+    }
+    /** Returns the internal sheets map. */
+    get sheets() {
+        return this.#sheets;
+    }
+    /** Returns the shared strings array. */
+    get sharedStrings() {
+        return this.#sharedStrings;
+    }
+    /** Replaces the shared strings array. */
+    set sharedStrings(sharedStrings) {
+        this.#sharedStrings = sharedStrings;
+    }
+    /** Returns the shared string index map. */
+    get sharedStringMap() {
+        return this.#sharedStringMap;
+    }
+    /** Returns the borders collection. */
+    get borders() {
+        return this.#borders;
+    }
+    /** Returns the border cache map (serialized xml -> index). */
+    get bordersMap() {
+        return this.#borderMap;
+    }
+    /** Returns the cellXfs (style records). */
+    get cellXfs() {
+        return this.#cellXfs;
+    }
+    /** Returns the fills collection. */
+    get fills() {
+        return this.#fills;
+    }
+    /** Returns the fill cache map (serialized xml -> index). */
+    get fillsMap() {
+        return this.#fillMap;
+    }
+    /** Returns the fonts collection. */
+    get fonts() {
+        return this.#fonts;
+    }
+    /** Returns the font cache map (serialized xml -> index). */
+    get fontsMap() {
+        return this.#fontMap;
+    }
+    /** Returns the number formats collection. */
+    get numFmts() {
+        return this.#numFmts;
+    }
+    /** Returns the mapping from serialized style JSON to style index. */
+    get styleMap() {
+        return this.#styleMap;
+    }
+    /** Returns the merge ranges, grouped by sheet name. */
+    get mergeCells() {
+        return this.#mergeCells;
+    }
+    /** Shared strings */
+    /** Adds a shared string (or returns existing index) and tracks its usage by sheet. */
+    #addSharedString(str, sheetName) {
+        return SharedStringRef.add.bind(this)({ sheetName, str });
+    }
+    /** -------------- */
+    /** Style refs */
+    /** Adds a style or returns an existing style index. */
+    #addOrGetStyle(style) {
+        return StyleRef.addOrGet.bind(this)({ style });
+    }
+    ;
+    /** ---------- */
+    /** Merge cells */
+    /** Adds a merge range to a sheet. */
+    #addMerge(payload) {
+        return MergeCells.add.bind(this)(payload);
+    }
+    /** Removes a merge range from a sheet. */
+    #removeMerge(payload) {
+        return MergeCells.remove.bind(this)(payload);
+    }
+    /** Removes all merge ranges for a sheet. */
+    #removeSheetMerges(sheetName) {
+        this.mergeCells.delete(sheetName);
+    }
+    /** ----------- */
+    /** Adds or replaces a logical file content in the in-memory file map. */
+    #addFile(key, value) {
+        this.#files[key] = value;
+    }
+    /** Updates the docProps/app.xml content based on current sheet names. */
+    #updateAppXml() {
+        this.#addFile(Utils.FILE_PATHS.APP, Utils.buildAppXml({ sheetNames: Array.from(this.#sheets.keys()) }));
+    }
+    /** Updates the xl/workbook.xml content based on current sheets. */
+    #updateWorkbookXml() {
+        this.#addFile(Utils.FILE_PATHS.WORKBOOK, Utils.buildWorkbookXml(Array.from(this.#sheets.values())));
+    }
+    /** Updates the xl/_rels/workbook.xml.rels relationships for sheets. */
+    #updateWorkbookRels() {
+        this.#addFile(Utils.FILE_PATHS.WORKBOOK_RELS, Utils.buildWorkbookRels(this.#sheets.size));
+    }
+    /** Updates [Content_Types].xml with sheet overrides. */
+    #updateContentTypes() {
+        this.#addFile(Utils.FILE_PATHS.CONTENT_TYPES, Utils.buildContentTypesXml(this.#sheets.size));
+    }
+    /** Public methods */
+    /**
+     * Adds a new sheet to the workbook.
+     *
+     * @throws Error if a sheet with the same name already exists
+     * @param sheetName - Sheet name to add
+     * @returns The created sheet data
+     */
+    addSheet(sheetName) {
+        if (this.getSheet(sheetName)) {
+            throw new Error("Sheet with this name already exists");
+        }
+        const sheet = Utils.createSheet(sheetName, {
+            addMerge: this.#addMerge.bind(this),
+            addOrGetStyle: this.#addOrGetStyle.bind(this),
+            addSharedString: this.#addSharedString.bind(this),
+            removeMerge: this.#removeMerge.bind(this),
+        });
+        this.#sheets.set(sheetName, sheet);
+        // Add entry to app.xml
+        this.#updateAppXml();
+        // Add entry to workbook.xml
+        this.#updateWorkbookXml();
+        // Add relationship in workbook.xml.rels
+        this.#updateWorkbookRels();
+        // Add Override in [Content_Types].xml
+        this.#updateContentTypes();
+        return sheet;
+    }
+    /** Returns a sheet by name if it exists. */
+    getSheet(sheetName) {
+        return this.#sheets.get(sheetName);
+    }
+    /**
+     * Removes a sheet by name.
+     * If cleanup is enabled, also removes associated shared strings and styles.
+     *
+     * @param sheetName - Sheet name to remove
+     * @returns True if the sheet existed and was removed
+     */
+    removeSheet(sheetName) {
+        const sheet = this.#sheets.get(sheetName);
+        if (!sheet) {
+            throw new Error("Sheet not found: " + sheetName);
+        }
+        // Remove its merges
+        this.#removeSheetMerges(sheetName);
+        // Remove from collection
+        this.#sheets.delete(sheetName);
+        this.#updateAppXml();
+        this.#updateWorkbookXml();
+        this.#updateWorkbookRels();
+        this.#updateContentTypes();
+        return true;
+    }
+    /**
+     * Returns a snapshot of the workbook internals for inspection and tests.
+     * The returned structure is deeply frozen to avoid accidental mutations.
+     */
+    getInfo() {
+        function deepFreeze(obj) {
+            if (obj === null || obj === undefined) {
+                return obj;
+            }
+            if (typeof obj !== "object") {
+                // string | number | boolean | symbol
+                return obj;
+            }
+            if (Array.isArray(obj)) {
+                return Object.freeze(obj.map(item => deepFreeze(item)));
+            }
+            if (obj instanceof Map) {
+                const frozenMap = new Map(Array.from(obj.entries()).map(([k, v]) => [k, deepFreeze(v)]));
+                return Object.freeze(frozenMap);
+            }
+            if (obj instanceof Set) {
+                const frozenSet = new Set(Array.from(obj.values()).map(v => deepFreeze(v)));
+                return Object.freeze(frozenSet);
+            }
+            // XmlNode or generic object
+            const frozenObj = {};
+            for (const [k, v] of Object.entries(obj)) {
+                frozenObj[k] = deepFreeze(v);
+            }
+            return Object.freeze(frozenObj);
+        }
+        return deepFreeze({
+            mergeCells: new Map(this.#mergeCells),
+            sheetsNames: Array.from(this.#sheets.values()).map((sheet) => sheet.name),
+            sharedStringMap: new Map(this.#sharedStringMap),
+            sharedStrings: [...this.#sharedStrings],
+            styles: {
+                borders: [...this.#borders],
+                cellXfs: [...this.#cellXfs],
+                fills: [...this.#fills],
+                fonts: [...this.#fonts],
+                numFmts: [...this.#numFmts],
+                styleMap: new Map(this.#styleMap),
+            },
+        });
+    }
+    /**
+     * Generates workbook XML parts in-memory and writes a .xlsx zip to disk.
+     *
+     * @param path - Absolute or relative file path to write
+     */
+    async saveToFile(path) {
+        let index = 0;
+        for (const sheet of this.#sheets.values()) {
+            const merges = this.#mergeCells.get(sheet.name) || [];
+            const preparedMerges = merges.map(merge => `${columnIndexToLetter(merge.startCol)}${merge.startRow}:${columnIndexToLetter(merge.endCol)}${merge.endRow}`);
+            const xml = Utils.buildWorksheetXml(sheet.rows, preparedMerges);
+            const filePath = `xl/worksheets/sheet${++index}.xml`;
+            this.#addFile(filePath, updateDimension(xml));
+        }
+        if (this.#sharedStrings.length) {
+            const xml = Utils.buildSharedStringsXml(this.#sharedStrings);
+            this.#addFile(Utils.FILE_PATHS.SHARED_STRINGS, xml);
+        }
+        // Styles
+        this.#addFile(Utils.FILE_PATHS.STYLES, Utils.buildStylesXml({
+            borders: this.#borders,
+            cellXfs: this.#cellXfs,
+            fills: this.#fills,
+            fonts: this.#fonts,
+            numFmts: this.#numFmts,
+        }));
+        const zipBuffer = await Zip.create(this.#files);
+        await fs.writeFile(path, zipBuffer);
+    }
+    /**
+     * Saves the workbook to a writable stream using temporary files.
+     * This method creates temporary files from the in-memory data and streams them
+     * to the output stream, avoiding loading the entire file into memory.
+     *
+     * @param output - Writable stream to receive the Excel file
+     * @param options.destination - Optional existing directory to use instead of a system temp directory
+     * @param options.cleanup - Optional flag to cleanup the temporary directory after saving (default: true)
+     * @returns Promise that resolves when the file has been fully written
+     */
+    async saveToStream(output, options) {
+        const { cleanup = true, destination } = options ?? {};
+        // Determine a temp directory to assemble ZIP contents
+        let tempDir = "";
+        if (destination) {
+            // Create a random subdirectory inside provided destination
+            tempDir = path.join(destination, crypto.randomUUID());
+            await fs.mkdir(tempDir, { recursive: true });
+        }
+        else {
+            // Create a temp directory in OS temp
+            tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "excel-toolbox-", crypto.randomUUID()));
+        }
+        let index = 0;
+        const usedFileKeys = [];
+        // Write "xl/worksheets/sheet*.xml"
+        for (const sheet of this.#sheets.values()) {
+            const merges = this.#mergeCells.get(sheet.name) || [];
+            const filePath = `xl/worksheets/sheet${++index}.xml`;
+            usedFileKeys.push(filePath);
+            const fullPath = path.join(tempDir, ...filePath.split("/"));
+            await Utils.writeWorksheetXml(fullPath, sheet.rows, merges);
+            this.#addFile(filePath, "");
+        }
+        // Write "xl/sharedStrings.xml"
+        if (this.#sharedStrings.length) {
+            usedFileKeys.push(Utils.FILE_PATHS.SHARED_STRINGS);
+            const fullPath = path.join(tempDir, ...Utils.FILE_PATHS.SHARED_STRINGS.split("/"));
+            await Utils.writeSharedStringsXml(fullPath, this.#sharedStrings);
+        }
+        // Write "xl/styles.xml"
+        {
+            usedFileKeys.push(Utils.FILE_PATHS.STYLES);
+            const fullPath = path.join(tempDir, ...Utils.FILE_PATHS.STYLES.split("/"));
+            await Utils.writeStylesXml(fullPath, {
+                borders: this.#borders,
+                cellXfs: this.#cellXfs,
+                fills: this.#fills,
+                fonts: this.#fonts,
+                numFmts: this.#numFmts,
+            });
+        }
+        try {
+            // Write all files from memory to temporary files
+            const fileKeys = [];
+            for (const [key, value] of Object.entries(this.#files)) {
+                if (usedFileKeys.includes(key)) {
+                    fileKeys.push(key);
+                    continue;
+                }
+                const fullPath = path.join(tempDir, ...key.split("/"));
+                await fs.mkdir(path.dirname(fullPath), { recursive: true });
+                await fs.writeFile(fullPath, value);
+                fileKeys.push(key);
+            }
+            // Create ZIP archive and stream to output
+            await Zip.createWithStream(fileKeys, tempDir, output);
+        }
+        finally {
+            // Clean up temporary files
+            if (cleanup) {
+                await fs.rm(tempDir, { force: true, recursive: true });
+            }
+        }
+    }
+}

package/build/types/lib/template/utils/column-letter-to-index.d.ts

@@ -0,0 +1 @@
+export declare function columnLetterToIndex(col: string): number;

package/build/types/lib/template/utils/index.d.ts

@@ -4,8 +4,8 @@ export * from "./check-row.js";
 export * from "./check-rows.js";
 export * from "./check-start-row.js";
 export * from "./column-index-to-letter.js";
+export * from "./column-letter-to-index.js";
 export * from "./compare-columns.js";
-export * from "./escape-xml.js";
 export * from "./extract-xml-declaration.js";
 export * from "./found-arrays-in-replacements.js";
 export * from "./get-by-path.js";

package/build/types/lib/utils/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./escape-xml.js";
 export * from "./get-max-row-number.js";
 export * from "./is-same-buffer.js";
 export * from "./remove-sheet-by-name.js";
@@ -5,3 +6,4 @@ export * from "./remove-sheet-from-content-types.js";
 export * from "./remove-sheet-from-rels.js";
 export * from "./remove-sheet-from-workbook.js";
 export * from "./shift-cell-ref.js";
+export * from "./trim-and-join-multiline.js";

package/build/types/lib/utils/trim-and-join-multiline.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Trims whitespace from multiline strings and joins them with a specified separator.
+ *
+ * This function processes multiline text by:
+ * - Splitting the input string by line breaks (handles both \n and \r\n)
+ * - Trimming whitespace from each line
+ * - Optionally normalizing multiple spaces to single spaces
+ * - Optionally filtering out empty lines
+ * - Joining the processed lines with a custom separator
+ *
+ * @param options - Configuration object for processing the multiline string
+ * @param options.inputString - The multiline string to process
+ * @param options.keepEmptyLines - Whether to preserve empty lines in the output (default: false)
+ * @param options.normalizeSpaces - Whether to normalize multiple consecutive spaces to single spaces (default: true)
+ * @param options.separator - The string to use when joining lines (default: " ")
+ * @returns The processed string with lines joined by the separator
+ */
+export declare function trimAndJoinMultiline(options: {
+    inputString: string;
+    keepEmptyLines?: boolean;
+    normalizeSpaces?: boolean;
+    separator?: string;
+}): string;

package/build/types/lib/workbook-builder/default/border.d.ts

@@ -0,0 +1,7 @@
+import { XmlNode } from "../types/index.js";
+/**
+ * Creates a basic empty border XML node.
+ *
+ * @returns XML node representing an empty border with left, right, top, and bottom elements
+ */
+export declare const border: () => XmlNode;

package/build/types/lib/workbook-builder/default/cell-xf.d.ts

@@ -0,0 +1,7 @@
+import { CellXf } from "../types/index.js";
+/**
+ * Creates a default cell formatting object.
+ *
+ * @returns Cell formatting object with default IDs
+ */
+export declare const cellXf: () => CellXf;