@js-ak/excel-toolbox 1.2.7 → 1.3.1

package/build/esm/lib/template/utils/write-rows-to-stream.js

@@ -0,0 +1,38 @@
+import { columnIndexToLetter } from "./column-index-to-letter.js";
+/**
+ * Writes an async iterable of rows to an Excel XML file.
+ *
+ * Each row is expected to be an array of values, where each value is
+ * converted to a string using the `String()` function. Empty values are
+ * replaced with an empty string.
+ *
+ * The `startRowNumber` parameter is used as the starting row number
+ * for the first row written to the file. Subsequent rows are written
+ * with incrementing row numbers.
+ *
+ * @param output - A file write stream to write the Excel XML to.
+ * @param rows - An async iterable of rows, where each row is an array
+ *               of values.
+ * @param startRowNumber - The starting row number to use for the first
+ *                         row written to the file.
+ *
+ * @returns An object with a single property `rowNumber`, which is the
+ *          last row number written to the file (i.e., the `startRowNumber`
+ *          plus the number of rows written).
+ */
+export async function writeRowsToStream(output, rows, startRowNumber) {
+    let rowNumber = startRowNumber;
+    for await (const row of rows) {
+        // Transform the row into XML
+        const cells = row.map((value, colIndex) => {
+            const colLetter = columnIndexToLetter(colIndex);
+            const cellRef = `${colLetter}${rowNumber}`;
+            const cellValue = String(value ?? "");
+            return `<c r="${cellRef}" t="inlineStr"><is><t>${cellValue}</t></is></c>`;
+        });
+        // Write the row to the file
+        output.write(`<row r="${rowNumber}">${cells.join("")}</row>`);
+        rowNumber++;
+    }
+    return { rowNumber };
+}

package/build/esm/lib/xml/build-merged-sheet.js

@@ -22,7 +22,7 @@ export function buildMergedSheet(originalXml, mergedRows, mergeCells = []) {
         // Construct a new <mergeCells> section with the provided merge references
         const mergeCellsXml = `<mergeCells count="${mergeCells.length}">${mergeCells.map(mc => `<mergeCell ref="${mc.ref}"/>`).join("")}</mergeCells>`;
         // Insert <mergeCells> after </sheetData> and before the next XML tag
-        xmlData = xmlData.replace(/(<\/sheetData>)(\s*<)/, `$1\n${mergeCellsXml}\n$2`);
+        xmlData = xmlData.replace(/(<\/sheetData>)(\s*<)/, `$1${mergeCellsXml}$2`);
     }
     return Buffer.from(xmlData);
 }

package/build/esm/lib/zip/constants.js

@@ -12,6 +12,21 @@ import { Buffer } from "node:buffer";
  * Found in the central directory that appears at the end of the ZIP file.
  */
 export const CENTRAL_DIR_HEADER_SIG = Buffer.from("504b0102", "hex");
+/**
+ * Precomputed CRC-32 lookup table for optimized checksum calculation.
+ * The table is generated using the standard IEEE 802.3 (Ethernet) polynomial:
+ * 0xEDB88320 (reversed representation of 0x04C11DB7).
+ *
+ * The table is immediately invoked and cached as a constant for performance,
+ * following the common implementation pattern for CRC algorithms.
+ */
+export const CRC32_TABLE = new Uint32Array(256).map((_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+        c = c & 1 ? 0xEDB88320 ^ (c >>> 1) : c >>> 1;
+    }
+    return c >>> 0;
+});
 /**
  * End of Central Directory Record signature (0x504b0506).
  * Marks the end of the central directory and contains global information

package/build/esm/lib/zip/create-with-stream.js

@@ -0,0 +1,175 @@
+import * as path from "node:path";
+import { Transform } from "node:stream";
+import { createReadStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
+import zlib from "node:zlib";
+import { crc32Stream, dosTime, toBytes } from "./utils/index.js";
+import { CENTRAL_DIR_HEADER_SIG, END_OF_CENTRAL_DIR_SIG, LOCAL_FILE_HEADER_SIG, } from "./constants.js";
+/**
+ * Creates a ZIP archive from a collection of files, streaming the output to a provided writable stream.
+ *
+ * @param fileKeys - An array of file paths (relative to the destination) that will be used to create a new workbook.
+ * @param destination - The path where the template files are located.
+ * @param output - A Writable stream that the ZIP archive will be written to.
+ *
+ * @throws {Error} - If a file does not exist in the destination.
+ * @throws {Error} - If a file is not readable.
+ * @throws {Error} - If the writable stream emits an error.
+ */
+export async function createWithStream(fileKeys, destination, output) {
+    const centralDirectory = [];
+    let offset = 0;
+    for (const filename of fileKeys.sort((a, b) => a.localeCompare(b))) {
+        if (filename.includes("..")) {
+            throw new Error(`Invalid filename: ${filename}`);
+        }
+        const fullPath = path.join(destination, ...filename.split("/"));
+        const fileNameBuf = Buffer.from(filename, "utf8");
+        const modTime = dosTime(new Date());
+        const source = createReadStream(fullPath);
+        const crc32 = crc32Stream();
+        const deflater = zlib.createDeflateRaw();
+        let uncompSize = 0;
+        let compSize = 0;
+        const compressedChunks = [];
+        const sizeCounter = new Transform({
+            transform(chunk, _enc, cb) {
+                uncompSize += chunk.length;
+                cb(null, chunk);
+            },
+        });
+        const collectCompressed = new Transform({
+            transform(chunk, _enc, cb) {
+                compressedChunks.push(chunk);
+                compSize += chunk.length;
+                cb(null, chunk);
+            },
+        });
+        // deflater.on("data", (chunk) => { console.log("deflater data path:", fullPath, "length:", chunk.length); });
+        // deflater.on("finish", () => { console.log("deflater finished path:", fullPath, "uncompSize:", uncompSize, "compSize:", compSize); });
+        // deflater.on("error", (err) => { console.log("deflater error path:", fullPath, "error:", err); });
+        // deflater.on("close", () => { console.log("deflater closed path:", fullPath); });
+        // deflater.on("pipe", (src) => { console.log("deflater pipe path:", fullPath); });
+        // deflater.on("unpipe", (src) => { console.log("deflater unpipe path:", fullPath); });
+        // deflater.on("drain", () => { console.log("deflater drain path:", fullPath); });
+        // deflater.on("pause", () => { console.log("deflater pause path:", fullPath); });
+        // deflater.on("resume", () => { console.log("deflater resume path:", fullPath); });
+        // deflater.on("end", () => console.log("deflater ended, path:", fullPath));
+        // source.on("data", (chunk) => { console.log("source data path:", fullPath, "length:", chunk.length); });
+        // source.on("finish", () => { console.log("source finished path:", fullPath, "uncompSize:", uncompSize, "compSize:", compSize); });
+        // source.on("error", (err) => { console.log("source error path:", fullPath, "error:", err); });
+        // source.on("close", () => { console.log("source closed path:", fullPath); });
+        // source.on("pipe", (src) => { console.log("source pipe path:", fullPath); });
+        // source.on("unpipe", (src) => { console.log("source unpipe path:", fullPath); });
+        // source.on("drain", () => { console.log("source drain path:", fullPath); });
+        // source.on("pause", () => { console.log("source pause path:", fullPath); });
+        // source.on("resume", () => { console.log("source resume path:", fullPath); });
+        // source.on("end", () => console.log("source ended, path:", fullPath));
+        // sizeCounter.on("data", (chunk) => { console.log("sizeCounter data path:", fullPath, "length:", chunk.length); });
+        // sizeCounter.on("finish", () => { console.log("sizeCounter finished path:", fullPath, "uncompSize:", uncompSize, "compSize:", compSize); });
+        // sizeCounter.on("error", (err) => { console.log("sizeCounter error path:", fullPath, "error:", err); });
+        // sizeCounter.on("close", () => { console.log("sizeCounter closed path:", fullPath); });
+        // sizeCounter.on("pipe", (src) => { console.log("sizeCounter pipe path:", fullPath); });
+        // sizeCounter.on("unpipe", (src) => { console.log("sizeCounter unpipe path:", fullPath); });
+        // sizeCounter.on("drain", () => { console.log("sizeCounter drain path:", fullPath); });
+        // sizeCounter.on("pause", () => { console.log("sizeCounter pause path:", fullPath); });
+        // sizeCounter.on("resume", () => { console.log("sizeCounter resume path:", fullPath); });
+        // sizeCounter.on("end", () => console.log("sizeCounter ended, path:", fullPath));
+        // crc32.on("data", (chunk) => { console.log("crc32 data path:", fullPath, "length:", chunk.length); });
+        // crc32.on("finish", () => { console.log("crc32 finished path:", fullPath, "uncompSize:", uncompSize, "compSize:", compSize); });
+        // crc32.on("error", (err) => { console.log("crc32 error path:", fullPath, "error:", err); });
+        // crc32.on("close", () => { console.log("crc32 closed path:", fullPath); });
+        // crc32.on("pipe", (src) => { console.log("crc32 pipe path:", fullPath); });
+        // crc32.on("unpipe", (src) => { console.log("crc32 unpipe path:", fullPath); });
+        // crc32.on("drain", () => { console.log("crc32 drain path:", fullPath); });
+        // crc32.on("pause", () => { console.log("crc32 pause path:", fullPath); });
+        // crc32.on("resume", () => { console.log("crc32 resume path:", fullPath); });
+        // crc32.on("end", () => console.log("crc32 ended, path:", fullPath));
+        collectCompressed.on("data", ( /* chunk */) => { });
+        // collectCompressed.on("finish", () => { console.log("collectCompressed finished path:", fullPath, "uncompSize:", uncompSize, "compSize:", compSize); });
+        // collectCompressed.on("error", (err) => { console.log("collectCompressed error path:", fullPath, "error:", err); });
+        // collectCompressed.on("close", () => { console.log("collectCompressed closed path:", fullPath); });
+        // collectCompressed.on("pipe", (src) => { console.log("collectCompressed pipe path:", fullPath); });
+        // collectCompressed.on("unpipe", (src) => { console.log("collectCompressed unpipe path:", fullPath); });
+        // collectCompressed.on("drain", () => { console.log("collectCompressed drain path:", fullPath); });
+        // collectCompressed.on("pause", () => { console.log("collectCompressed pause path:", fullPath); });
+        // collectCompressed.on("resume", () => { console.log("collectCompressed resume path:", fullPath); });
+        // collectCompressed.on("end", () => console.log("collectCompressed ended, path:", fullPath));
+        // deflater.on("readable", () => {
+        // 	console.log("deflater readable path:", fullPath);
+        // });
+        await pipeline(source, sizeCounter, crc32, deflater, collectCompressed);
+        // await new Promise<void>((resolve, reject) => {
+        // 	source
+        // 		.pipe(sizeCounter)
+        // 		.pipe(crc32)
+        // 		.pipe(deflater)
+        // 		.pipe(collectCompressed)
+        // 		.on("finish", resolve)
+        // 		.on("error", reject);
+        // 	source.on("error", reject);
+        // 	deflater.on("error", reject);
+        // });
+        const crc = crc32.digest();
+        const compressed = Buffer.concat(compressedChunks);
+        const localHeader = Buffer.concat([
+            LOCAL_FILE_HEADER_SIG,
+            toBytes(20, 2),
+            toBytes(0, 2),
+            toBytes(8, 2),
+            modTime,
+            toBytes(crc, 4),
+            toBytes(compSize, 4),
+            toBytes(uncompSize, 4),
+            toBytes(fileNameBuf.length, 2),
+            toBytes(0, 2),
+            fileNameBuf,
+            compressed,
+        ]);
+        await new Promise((resolve, reject) => {
+            output.write(localHeader, err => err ? reject(err) : resolve());
+        });
+        const centralEntry = Buffer.concat([
+            CENTRAL_DIR_HEADER_SIG,
+            toBytes(20, 2),
+            toBytes(20, 2),
+            toBytes(0, 2),
+            toBytes(8, 2),
+            modTime,
+            toBytes(crc, 4),
+            toBytes(compSize, 4),
+            toBytes(uncompSize, 4),
+            toBytes(fileNameBuf.length, 2),
+            toBytes(0, 2),
+            toBytes(0, 2),
+            toBytes(0, 2),
+            toBytes(0, 2),
+            toBytes(0, 4),
+            toBytes(offset, 4),
+            fileNameBuf,
+        ]);
+        centralDirectory.push(centralEntry);
+        offset += localHeader.length;
+    }
+    const centralDirSize = centralDirectory.reduce((sum, entry) => sum + entry.length, 0);
+    const centralDirOffset = offset;
+    for (const entry of centralDirectory) {
+        await new Promise((resolve, reject) => {
+            output.write(entry, err => err ? reject(err) : resolve());
+        });
+    }
+    const endRecord = Buffer.concat([
+        END_OF_CENTRAL_DIR_SIG,
+        toBytes(0, 2),
+        toBytes(0, 2),
+        toBytes(centralDirectory.length, 2),
+        toBytes(centralDirectory.length, 2),
+        toBytes(centralDirSize, 4),
+        toBytes(centralDirOffset, 4),
+        toBytes(0, 2),
+    ]);
+    await new Promise((resolve, reject) => {
+        output.write(endRecord, err => err ? reject(err) : resolve());
+    });
+    output.end();
+}

package/build/esm/lib/zip/index.js

@@ -1,4 +1,5 @@
 export * from "./create-sync.js";
+export * from "./create-with-stream.js";
 export * from "./create.js";
 export * from "./read-sync.js";
 export * from "./read.js";

package/build/esm/lib/zip/utils/crc-32-stream.js

@@ -0,0 +1,39 @@
+import { Transform } from "node:stream";
+import { CRC32_TABLE } from "../constants.js";
+/**
+ * Computes the CRC-32 checksum for the given byte, using the standard IEEE 802.3 polynomial.
+ * This is a low-level function that is used by the crc32Stream() function.
+ *
+ * @param {number} byte - The byte (0-255) to add to the checksum.
+ * @param {number} crc - The current checksum value to update.
+ * @returns {number} - The new checksum value.
+ */
+function crc32(byte, crc = 0xffffffff) {
+    return CRC32_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+}
+/**
+ * Creates a Transform stream that computes the CRC-32 checksum of the input data.
+ *
+ * The `digest()` method can be called on the returned stream to get the final checksum value.
+ *
+ * @returns {Transform & { digest: () => number }} - The Transform stream.
+ */
+export function crc32Stream() {
+    let crc = 0xffffffff;
+    const transform = new Transform({
+        final(callback) {
+            callback();
+        },
+        flush(callback) {
+            callback();
+        },
+        transform(chunk, _encoding, callback) {
+            for (let i = 0; i < chunk.length; i++) {
+                crc = crc32(chunk[i], crc);
+            }
+            callback(null, chunk);
+        },
+    });
+    transform.digest = () => (crc ^ 0xffffffff) >>> 0;
+    return transform;
+}

package/build/esm/lib/zip/utils/crc-32.js

@@ -1,37 +1,4 @@
-/**
- * Precomputed CRC-32 lookup table for optimized checksum calculation.
- * The table is generated using the standard IEEE 802.3 (Ethernet) polynomial:
- * 0xEDB88320 (reversed representation of 0x04C11DB7).
- *
- * The table is immediately invoked and cached as a constant for performance,
- * following the common implementation pattern for CRC algorithms.
- */
-const crcTable = (() => {
-    // Create a typed array for better performance with 256 32-bit unsigned integers
-    const table = new Uint32Array(256);
-    // Generate table entries for all possible byte values (0-255)
-    for (let i = 0; i < 256; i++) {
-        let crc = i; // Initialize with current byte value
-        // Process each bit (8 times)
-        for (let j = 0; j < 8; j++) {
-            /*
-             * CRC division algorithm:
-             * 1. If LSB is set (crc & 1), XOR with polynomial
-             * 2. Right-shift by 1 (unsigned)
-             *
-             * The polynomial 0xEDB88320 is:
-             * - Bit-reversed version of 0x04C11DB7
-             * - Uses reflected input/output algorithm
-             */
-            crc = crc & 1
-                ? 0xedb88320 ^ (crc >>> 1) // XOR with polynomial if LSB is set
-                : crc >>> 1; // Just shift right if LSB is not set
-        }
-        // Store final 32-bit value (>>> 0 ensures unsigned 32-bit representation)
-        table[i] = crc >>> 0;
-    }
-    return table;
-})();
+import { CRC32_TABLE } from "../constants.js";
 /**
  * Computes a CRC-32 checksum for the given Buffer using the standard IEEE 802.3 polynomial.
  * This implementation uses a precomputed lookup table for optimal performance.
@@ -62,7 +29,7 @@ export function crc32(buf) {
          * - crc >>> 8 - Shift CRC right by 8 bits (unsigned)
          * - ^ crcTable[...] - XOR with precomputed table value
          */
-        crc = (crc >>> 8) ^ crcTable[(crc ^ buf[i]) & 0xff];
+        crc = (crc >>> 8) ^ CRC32_TABLE[(crc ^ buf[i]) & 0xff];
     }
     /*
      * Final processing:

package/build/esm/lib/zip/utils/index.js

@@ -1,3 +1,4 @@
+export * from "./crc-32-stream.js";
 export * from "./crc-32.js";
 export * from "./dos-time.js";
 export * from "./find-data-descriptor.js";

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

@@ -1,2 +1,3 @@
 export * from "./merge-sheets-to-base-file-sync.js";
 export * from "./merge-sheets-to-base-file.js";
+export * from "./template/index.js";

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

@@ -0,0 +1 @@
+export * from "./template-fs.js";

package/build/types/lib/template/template-fs.d.ts

@@ -0,0 +1,122 @@
+import { Writable } from "node:stream";
+/**
+ * A class for manipulating Excel templates by extracting, modifying, and repacking Excel files.
+ *
+ * @experimental This API is experimental and might change in future versions.
+ */
+export declare class TemplateFs {
+    #private;
+    /**
+     * Set of file paths (relative to the template) that will be used to create a new workbook.
+     * @type {Set<string>}
+     */
+    fileKeys: Set<string>;
+    /**
+     * The path where the template will be expanded.
+     * @type {string}
+     */
+    destination: string;
+    /**
+     * Flag indicating whether this template instance has been destroyed.
+     * @type {boolean}
+     */
+    destroyed: boolean;
+    /**
+     * Creates a Template instance.
+     *
+     * @param {Set<string>} fileKeys - Set of file paths (relative to the template) that will be used to create a new workbook.
+     * @param {string} destination - The path where the template will be expanded.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    constructor(fileKeys: Set<string>, destination: string);
+    /**
+     * Inserts rows into a specific sheet in the template.
+     *
+     * @param {Object} data - The data for row insertion.
+     * @param {string} data.sheetName - The name of the sheet to insert rows into.
+     * @param {number} [data.startRowNumber] - The row number to start inserting from.
+     * @param {unknown[][]} data.rows - The rows to insert.
+     * @returns {Promise<void>}
+     * @throws {Error} If the template instance has been destroyed.
+     * @throws {Error} If the sheet does not exist.
+     * @throws {Error} If the row number is out of range.
+     * @throws {Error} If a column is out of range.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    insertRows(data: {
+        sheetName: string;
+        startRowNumber?: number;
+        rows: unknown[][];
+    }): Promise<void>;
+    /**
+     * Inserts rows into a specific sheet in the template using an async stream.
+     *
+     * @param {Object} data - The data for row insertion.
+     * @param {string} data.sheetName - The name of the sheet to insert rows into.
+     * @param {number} [data.startRowNumber] - The row number to start inserting from.
+     * @param {AsyncIterable<unknown[]>} data.rows - Async iterable of rows to insert.
+     * @returns {Promise<void>}
+     * @throws {Error} If the template instance has been destroyed.
+     * @throws {Error} If the sheet does not exist.
+     * @throws {Error} If the row number is out of range.
+     * @throws {Error} If a column is out of range.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    insertRowsStream(data: {
+        sheetName: string;
+        startRowNumber?: number;
+        rows: AsyncIterable<unknown[]>;
+    }): Promise<void>;
+    /**
+     * Saves the modified Excel template to a buffer.
+     *
+     * @returns {Promise<Buffer>} The modified Excel template as a buffer.
+     * @throws {Error} If the template instance has been destroyed.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    save(): Promise<Buffer>;
+    /**
+     * Writes the modified Excel template to a writable stream.
+     *
+     * @param {Writable} output - The writable stream to write to.
+     * @returns {Promise<void>}
+     * @throws {Error} If the template instance has been destroyed.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    saveStream(output: Writable): Promise<void>;
+    /**
+     * Replaces the contents of a file in the template.
+     *
+     * @param {string} key - The Excel path of the file to replace.
+     * @param {Buffer|string} content - The new content.
+     * @returns {Promise<void>}
+     * @throws {Error} If the template instance has been destroyed.
+     * @throws {Error} If the file does not exist in the template.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    set(key: string, content: Buffer | string): Promise<void>;
+    /**
+     * Validates the template by checking all required files exist.
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If the template instance has been destroyed.
+     * @throws {Error} If any required files are missing.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    validate(): Promise<void>;
+    /**
+     * Creates a Template instance from an Excel file source.
+     * Removes any existing files in the destination directory.
+     *
+     * @param {Object} data - The data to create the template from.
+     * @param {string} data.source - The path or buffer of the Excel file.
+     * @param {string} data.destination - The path to save the template to.
+     * @returns {Promise<Template>} A new Template instance.
+     * @throws {Error} If reading or writing files fails.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    static from(data: {
+        destination: string;
+        source: string | Buffer;
+    }): Promise<TemplateFs>;
+}

package/build/types/lib/template/utils/check-row.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Validates that each key in the given row object is a valid cell reference.
+ *
+ * This function checks that all keys in the provided row object are composed
+ * only of column letters (A-Z, case insensitive). If a key is found that does
+ * not match this pattern, an error is thrown with a message indicating the
+ * invalid cell reference.
+ *
+ * @param row - An object representing a row of data, where keys are cell
+ *              references and values are strings.
+ *
+ * @throws {Error} If any key in the row is not a valid column letter.
+ */
+export declare function checkRow(row: Record<string, string>): void;

package/build/types/lib/template/utils/check-rows.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Validates an array of row objects to ensure each cell reference is valid.
+ * Each row object is checked to ensure that its keys (cell references) are
+ * composed of valid column letters (e.g., "A", "B", "C").
+ *
+ * @param rows An array of row objects, where each object represents a row
+ * of data with cell references as keys and cell values as strings.
+ *
+ * @throws {Error} If any cell reference in the rows is invalid.
+ */
+export declare function checkRows(rows: Record<string, string>[]): void;

package/build/types/lib/template/utils/check-start-row.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Checks if startRow is a positive integer.
+ *
+ * @param startRow The start row to check.
+ *
+ * @throws {Error} If startRow is not a positive integer.
+ */
+export declare function checkStartRow(startRow?: number): void;

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

@@ -0,0 +1,7 @@
+/**
+ * Converts a 0-based column index to an Excel-style letter (A, B, ..., Z, AA, AB, ...).
+ *
+ * @param index - The 0-based column index.
+ * @returns The Excel-style letter for the given column index.
+ */
+export declare function columnIndexToLetter(index: number): string;

package/build/types/lib/template/utils/escape-xml.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Escapes special characters in a string for use in an XML document.
+ *
+ * Replaces:
+ * - `&` with `&`
+ * - `<` with `&lt;`
+ * - `>` with `&gt;`
+ * - `"` with `&quot;`
+ * - `'` with `&apos;`
+ *
+ * @param str - The string to escape.
+ * @returns The escaped string.
+ */
+export declare function escapeXml(str: string): string;

package/build/types/lib/template/utils/get-max-row-number.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Finds the maximum row number in a list of <row> elements
+ * and returns the maximum row number + 1.
+ * @param {string} line - The line of XML to parse.
+ * @returns {number} - The maximum row number found + 1.
+ */
+export declare function getMaxRowNumber(line: string): number;

package/build/types/lib/template/utils/get-rows-above.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Filters out all rows in the given map that have a row number
+ * lower than or equal to the given minRow, and returns the
+ * filtered rows as a single string. Useful for removing rows
+ * from a template that are positioned above a certain row
+ * number.
+ *
+ * @param {Map<number, string>} map - The map of row numbers to row content
+ * @param {number} minRow - The minimum row number to include in the output
+ * @returns {string} The filtered rows, concatenated into a single string
+ */
+export declare function getRowsAbove(map: Map<number, string>, minRow: number): string;

package/build/types/lib/template/utils/get-rows-below.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Filters out all rows in the given map that have a row number
+ * greater than or equal to the given maxRow, and returns the
+ * filtered rows as a single string. Useful for removing rows
+ * from a template that are positioned below a certain row
+ * number.
+ *
+ * @param {Map<number, string>} map - The map of row numbers to row content
+ * @param {number} maxRow - The maximum row number to include in the output
+ * @returns {string} The filtered rows, concatenated into a single string
+ */
+export declare function getRowsBelow(map: Map<number, string>, maxRow: number): string;

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

@@ -0,0 +1,11 @@
+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 "./escape-xml.js";
+export * from "./get-max-row-number.js";
+export * from "./get-rows-above.js";
+export * from "./get-rows-below.js";
+export * from "./parse-rows.js";
+export * from "./to-excel-column-object.js";
+export * from "./write-rows-to-stream.js";

package/build/types/lib/template/utils/parse-rows.d.ts

@@ -0,0 +1 @@
+export declare function parseRows(innerRows: string): Map<number, string>;

package/build/types/lib/template/utils/to-excel-column-object.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Converts an array of values into a Record<string, string> with Excel column names as keys.
+ *
+ * The column names are generated in the standard Excel column naming convention (A, B, ..., Z, AA, AB, ...).
+ * The corresponding values are converted to strings using the String() function.
+ *
+ * @param values - The array of values to convert
+ * @returns The resulting Record<string, string>
+ */
+export declare function toExcelColumnObject(values: unknown[]): Record<string, string>;

package/build/types/lib/template/utils/write-rows-to-stream.d.ts

@@ -0,0 +1,25 @@
+import * as fs from "node:fs";
+/**
+ * Writes an async iterable of rows to an Excel XML file.
+ *
+ * Each row is expected to be an array of values, where each value is
+ * converted to a string using the `String()` function. Empty values are
+ * replaced with an empty string.
+ *
+ * The `startRowNumber` parameter is used as the starting row number
+ * for the first row written to the file. Subsequent rows are written
+ * with incrementing row numbers.
+ *
+ * @param output - A file write stream to write the Excel XML to.
+ * @param rows - An async iterable of rows, where each row is an array
+ *               of values.
+ * @param startRowNumber - The starting row number to use for the first
+ *                         row written to the file.
+ *
+ * @returns An object with a single property `rowNumber`, which is the
+ *          last row number written to the file (i.e., the `startRowNumber`
+ *          plus the number of rows written).
+ */
+export declare function writeRowsToStream(output: fs.WriteStream, rows: AsyncIterable<unknown[]>, startRowNumber: number): Promise<{
+    rowNumber: number;
+}>;

package/build/types/lib/zip/constants.d.ts

@@ -12,6 +12,15 @@ import { Buffer } from "node:buffer";
  * Found in the central directory that appears at the end of the ZIP file.
  */
 export declare const CENTRAL_DIR_HEADER_SIG: Buffer<ArrayBuffer>;
+/**
+ * Precomputed CRC-32 lookup table for optimized checksum calculation.
+ * The table is generated using the standard IEEE 802.3 (Ethernet) polynomial:
+ * 0xEDB88320 (reversed representation of 0x04C11DB7).
+ *
+ * The table is immediately invoked and cached as a constant for performance,
+ * following the common implementation pattern for CRC algorithms.
+ */
+export declare const CRC32_TABLE: Uint32Array<ArrayBuffer>;
 /**
  * End of Central Directory Record signature (0x504b0506).
  * Marks the end of the central directory and contains global information