@js-ak/excel-toolbox 1.3.1 → 1.4.0

package/build/esm/lib/template/utils/apply-replacements.js

@@ -0,0 +1,22 @@
+import { getByPath } from "./get-by-path.js";
+/**
+ * Replaces placeholders in the given content string with values from the replacements map.
+ *
+ * The function searches for placeholders in the format `${key}` within the content
+ * string, where `key` corresponds to a path in the replacements object.
+ * If a value is found for the key, it replaces the placeholder with the value.
+ * If no value is found, the original placeholder remains unchanged.
+ *
+ * @param content - The string containing placeholders to be replaced.
+ * @param replacements - An object where keys represent placeholder paths and values are the replacements.
+ * @returns A new string with placeholders replaced by corresponding values from the replacements object.
+ */
+export const applyReplacements = (content, replacements) => {
+    if (!content) {
+        return "";
+    }
+    return content.replace(/\$\{([^}]+)\}/g, (match, path) => {
+        const value = getByPath(replacements, path);
+        return value !== undefined ? String(value) : match;
+    });
+};

package/build/esm/lib/template/utils/check-row.js

@@ -1,19 +1,14 @@
 /**
- * Validates that each key in the given row object is a valid cell reference.
+ * Validates an object representing a single row of data to ensure that its keys
+ * are valid Excel column references. Throws an error if any of the keys are
+ * invalid.
  *
- * 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.
+ * @param row An object with string keys that represent the cell references and
+ * string values that represent the values of those cells.
  */
 export function checkRow(row) {
     for (const key of Object.keys(row)) {
-        if (!/^[A-Z]+$/i.test(key)) {
+        if (!/^[A-Z]+$/i.test(key) || !/^[A-Z]$|^[A-Z][A-Z]$|^[A-Z][A-Z][A-Z]$/i.test(key)) {
             throw new Error(`Invalid cell reference "${key}" in row. Only column letters (like "A", "B", "C") are allowed.`);
         }
     }

package/build/esm/lib/template/utils/column-index-to-letter.js

@@ -1,10 +1,21 @@
 /**
- * Converts a 0-based column index to an Excel-style letter (A, B, ..., Z, AA, AB, ...).
+ * Converts a zero-based column index to its corresponding Excel column letter.
  *
- * @param index - The 0-based column index.
- * @returns The Excel-style letter for the given column index.
+ * @throws Will throw an error if the input is not a positive integer.
+ * @param {number} index - The zero-based index of the column to convert.
+ * @returns {string} The corresponding Excel column letter.
+ *
+ * @example
+ * columnIndexToLetter(0); // returns "A"
+ * columnIndexToLetter(25); // returns "Z"
+ * columnIndexToLetter(26); // returns "AA"
+ * columnIndexToLetter(51); // returns "AZ"
+ * columnIndexToLetter(52); // returns "BA"
  */
 export function columnIndexToLetter(index) {
+    if (!Number.isInteger(index) || index < 0) {
+        throw new Error(`Invalid column index: ${index}. Must be a positive integer.`);
+    }
     let letters = "";
     while (index >= 0) {
         letters = String.fromCharCode((index % 26) + 65) + letters;

package/build/esm/lib/template/utils/extract-xml-declaration.js

@@ -0,0 +1,19 @@
+/**
+ * Extracts the XML declaration from a given XML string.
+ *
+ * The XML declaration is a string that looks like `<?xml ...?>` and is usually
+ * present at the beginning of an XML file. It contains information about the
+ * XML version, encoding, and standalone status.
+ *
+ * This function returns `null` if the input string does not have a valid XML
+ * declaration.
+ *
+ * @param xmlString - The XML string to extract the declaration from.
+ * @returns The extracted XML declaration string, or `null`.
+ */
+export function extractXmlDeclaration(xmlString) {
+    // const declarationRegex = /^<\?xml\s+[^?]+\?>/;
+    const declarationRegex = /^<\?xml\s+version\s*=\s*["'][^"']+["'](\s+(encoding|standalone)\s*=\s*["'][^"']+["'])*\s*\?>/;
+    const match = xmlString.match(declarationRegex);
+    return match ? match[0] : null;
+}

package/build/esm/lib/template/utils/get-by-path.js

@@ -0,0 +1,15 @@
+/**
+ * Gets a value from an object by a given path.
+ *
+ * @param obj - The object to search.
+ * @param path - The path to the value, separated by dots.
+ * @returns The value at the given path, or undefined if not found.
+ */
+export function getByPath(obj, path) {
+    return path.split(".").reduce((acc, key) => {
+        if (acc && typeof acc === "object" && key in acc) {
+            return acc[key];
+        }
+        return undefined;
+    }, obj);
+}

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

@@ -1,11 +1,16 @@
+export * from "./apply-replacements.js";
 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 "./extract-xml-declaration.js";
+export * from "./get-by-path.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 "./update-dimension.js";
+export * from "./validate-worksheet-xml.js";
 export * from "./write-rows-to-stream.js";

package/build/esm/lib/template/utils/update-dimension.js

@@ -0,0 +1,37 @@
+export function updateDimension(xml) {
+    const cellRefs = [...xml.matchAll(/<c r="([A-Z]+)(\d+)"/g)];
+    if (cellRefs.length === 0)
+        return xml;
+    let minCol = Infinity, maxCol = -Infinity;
+    let minRow = Infinity, maxRow = -Infinity;
+    for (const [, colStr, rowStr] of cellRefs) {
+        const col = columnLetterToNumber(colStr);
+        const row = parseInt(rowStr, 10);
+        if (col < minCol)
+            minCol = col;
+        if (col > maxCol)
+            maxCol = col;
+        if (row < minRow)
+            minRow = row;
+        if (row > maxRow)
+            maxRow = row;
+    }
+    const newRef = `${columnNumberToLetter(minCol)}${minRow}:${columnNumberToLetter(maxCol)}${maxRow}`;
+    return xml.replace(/<dimension ref="[^"]*"/, `<dimension ref="${newRef}"`);
+}
+function columnLetterToNumber(letters) {
+    let num = 0;
+    for (let i = 0; i < letters.length; i++) {
+        num = num * 26 + (letters.charCodeAt(i) - 64);
+    }
+    return num;
+}
+function columnNumberToLetter(num) {
+    let letters = "";
+    while (num > 0) {
+        const rem = (num - 1) % 26;
+        letters = String.fromCharCode(65 + rem) + letters;
+        num = Math.floor((num - 1) / 26);
+    }
+    return letters;
+}

package/build/esm/lib/template/utils/validate-worksheet-xml.js

@@ -0,0 +1,214 @@
+export function validateWorksheetXml(xml) {
+    const createError = (message, details) => ({
+        error: {
+            details,
+            message,
+        },
+        isValid: false,
+    });
+    // 1. Проверка базовой структуры XML
+    if (!xml.startsWith("<?xml")) {
+        return createError("XML должен начинаться с декларации <?xml>");
+    }
+    if (!xml.includes("<worksheet") || !xml.includes("</worksheet>")) {
+        return createError("Не найден корневой элемент worksheet");
+    }
+    // 2. Проверка наличия обязательных элементов
+    const requiredElements = [
+        { name: "sheetViews", tag: "<sheetViews>" },
+        { name: "sheetFormatPr", tag: "<sheetFormatPr" },
+        { name: "cols", tag: "<cols>" },
+        { name: "sheetData", tag: "<sheetData>" },
+        { name: "mergeCells", tag: "<mergeCells" },
+    ];
+    for (const { name, tag } of requiredElements) {
+        if (!xml.includes(tag)) {
+            return createError(`Отсутствует обязательный элемент ${name}`);
+        }
+    }
+    // 3. Извлечение и проверка sheetData
+    const sheetDataStart = xml.indexOf("<sheetData>");
+    const sheetDataEnd = xml.indexOf("</sheetData>");
+    if (sheetDataStart === -1 || sheetDataEnd === -1) {
+        return createError("Некорректная структура sheetData");
+    }
+    const sheetDataContent = xml.substring(sheetDataStart + 10, sheetDataEnd);
+    const rows = sheetDataContent.split("</row>");
+    if (rows.length < 2) {
+        return createError("SheetData должен содержать хотя бы одну строку");
+    }
+    // Собираем информацию о всех строках и ячейках
+    const allRows = [];
+    const allCells = [];
+    let prevRowNum = 0;
+    for (const row of rows.slice(0, -1)) {
+        if (!row.includes("<row ")) {
+            return createError("Не найден тег row", `Фрагмент: ${row.substring(0, 50)}...`);
+        }
+        if (!row.includes("<c ")) {
+            return createError("Строка не содержит ячеек", `Строка: ${row.substring(0, 50)}...`);
+        }
+        // Извлекаем номер строки
+        const rowNumMatch = row.match(/<row\s+r="(\d+)"/);
+        if (!rowNumMatch) {
+            return createError("Не указан номер строки (атрибут r)", `Строка: ${row.substring(0, 50)}...`);
+        }
+        const rowNum = parseInt(rowNumMatch[1]);
+        // Проверка уникальности строк
+        if (allRows.includes(rowNum)) {
+            return createError("Найден дубликат номера строки", `Номер строки: ${rowNum}`);
+        }
+        allRows.push(rowNum);
+        // Проверка порядка строк (должны идти по возрастанию)
+        if (rowNum <= prevRowNum) {
+            return createError("Нарушен порядок следования строк", `Текущая строка: ${rowNum}, предыдущая: ${prevRowNum}`);
+        }
+        prevRowNum = rowNum;
+        // Извлекаем все ячейки в строке
+        const cells = row.match(/<c\s+r="([A-Z]+)(\d+)"/g) || [];
+        for (const cell of cells) {
+            const match = cell.match(/<c\s+r="([A-Z]+)(\d+)"/);
+            if (!match) {
+                return createError("Некорректный формат ячейки", `Ячейка: ${cell}`);
+            }
+            const col = match[1];
+            const cellRowNum = parseInt(match[2]);
+            // Проверяем соответствие номера строки
+            if (cellRowNum !== rowNum) {
+                return createError("Несоответствие номера строки в ячейке", `Ожидалось: ${rowNum}, найдено: ${cellRowNum} в ячейке ${col}${cellRowNum}`);
+            }
+            allCells.push({
+                col,
+                row: rowNum,
+            });
+        }
+    }
+    // 4. Проверка mergeCells
+    const mergeCellsStart = xml.indexOf("<mergeCells");
+    const mergeCellsEnd = xml.indexOf("</mergeCells>");
+    if (mergeCellsStart === -1 || mergeCellsEnd === -1) {
+        return createError("Некорректная структура mergeCells");
+    }
+    const mergeCellsContent = xml.substring(mergeCellsStart, mergeCellsEnd);
+    const countMatch = mergeCellsContent.match(/count="(\d+)"/);
+    if (!countMatch) {
+        return createError("Не указано количество объединенных ячеек (атрибут count)");
+    }
+    const mergeCellTags = mergeCellsContent.match(/<mergeCell\s+ref="([A-Z]+\d+:[A-Z]+\d+)"\s*\/>/g);
+    if (!mergeCellTags) {
+        return createError("Не найдены объединенные ячейки");
+    }
+    // Проверка соответствия заявленного количества и фактического
+    if (mergeCellTags.length !== parseInt(countMatch[1])) {
+        return createError("Несоответствие количества объединенных ячеек", `Ожидалось: ${countMatch[1]}, найдено: ${mergeCellTags.length}`);
+    }
+    // Проверка на дублирующиеся mergeCell
+    const mergeRefs = new Set();
+    const duplicates = new Set();
+    for (const mergeTag of mergeCellTags) {
+        const refMatch = mergeTag.match(/ref="([A-Z]+\d+:[A-Z]+\d+)"/);
+        if (!refMatch) {
+            return createError("Некорректный формат объединения ячеек", `Тег: ${mergeTag}`);
+        }
+        const ref = refMatch[1];
+        if (mergeRefs.has(ref)) {
+            duplicates.add(ref);
+        }
+        else {
+            mergeRefs.add(ref);
+        }
+    }
+    if (duplicates.size > 0) {
+        return createError("Найдены дублирующиеся объединения ячеек", `Дубликаты: ${Array.from(duplicates).join(", ")}`);
+    }
+    // Проверка пересекающихся объединений
+    const mergedRanges = Array.from(mergeRefs).map(ref => {
+        const [start, end] = ref.split(":");
+        return {
+            endCol: end.match(/[A-Z]+/)?.[0] || "",
+            endRow: parseInt(end.match(/\d+/)?.[0] || "0"),
+            startCol: start.match(/[A-Z]+/)?.[0] || "",
+            startRow: parseInt(start.match(/\d+/)?.[0] || "0"),
+        };
+    });
+    for (let i = 0; i < mergedRanges.length; i++) {
+        for (let j = i + 1; j < mergedRanges.length; j++) {
+            const a = mergedRanges[i];
+            const b = mergedRanges[j];
+            if (rangesIntersect(a, b)) {
+                return createError("Найдены пересекающиеся объединения ячеек", `Пересекаются: ${getRangeString(a)} и ${getRangeString(b)}`);
+            }
+        }
+    }
+    // 5. Проверка dimension и соответствия с реальными данными
+    const dimensionMatch = xml.match(/<dimension\s+ref="([A-Z]+\d+:[A-Z]+\d+)"\s*\/>/);
+    if (!dimensionMatch) {
+        return createError("Не указана область данных (dimension)");
+    }
+    const [startCell, endCell] = dimensionMatch[1].split(":");
+    const startCol = startCell.match(/[A-Z]+/)?.[0];
+    const startRow = parseInt(startCell.match(/\d+/)?.[0] || "0");
+    const endCol = endCell.match(/[A-Z]+/)?.[0];
+    const endRow = parseInt(endCell.match(/\d+/)?.[0] || "0");
+    if (!startCol || !endCol || isNaN(startRow) || isNaN(endRow)) {
+        return createError("Некорректный формат dimension", `Dimension: ${dimensionMatch[1]}`);
+    }
+    const startColNum = colToNumber(startCol);
+    const endColNum = colToNumber(endCol);
+    // Проверяем все ячейки на вхождение в dimension
+    for (const cell of allCells) {
+        const colNum = colToNumber(cell.col);
+        if (cell.row < startRow || cell.row > endRow) {
+            return createError("Ячейка находится вне указанной области (по строке)", `Ячейка: ${cell.col}${cell.row}, dimension: ${dimensionMatch[1]}`);
+        }
+        if (colNum < startColNum || colNum > endColNum) {
+            return createError("Ячейка находится вне указанной области (по столбцу)", `Ячейка: ${cell.col}${cell.row}, dimension: ${dimensionMatch[1]}`);
+        }
+    }
+    // 6. Дополнительная проверка: все mergeCell ссылаются на существующие ячейки
+    for (const mergeTag of mergeCellTags) {
+        const refMatch = mergeTag.match(/ref="([A-Z]+\d+:[A-Z]+\d+)"/);
+        if (!refMatch) {
+            return createError("Некорректный формат объединения ячеек", `Тег: ${mergeTag}`);
+        }
+        const [cell1, cell2] = refMatch[1].split(":");
+        const cell1Col = cell1.match(/[A-Z]+/)?.[0];
+        const cell1Row = parseInt(cell1.match(/\d+/)?.[0] || "0");
+        const cell2Col = cell2.match(/[A-Z]+/)?.[0];
+        const cell2Row = parseInt(cell2.match(/\d+/)?.[0] || "0");
+        if (!cell1Col || !cell2Col || isNaN(cell1Row) || isNaN(cell2Row)) {
+            return createError("Некорректные координаты объединения ячеек", `Объединение: ${refMatch[1]}`);
+        }
+        // Проверяем что объединяемые ячейки существуют
+        const cell1Exists = allCells.some(c => c.row === cell1Row && c.col === cell1Col);
+        const cell2Exists = allCells.some(c => c.row === cell2Row && c.col === cell2Col);
+        if (!cell1Exists || !cell2Exists) {
+            return createError("Объединение ссылается на несуществующие ячейки", `Объединение: ${refMatch[1]}, отсутствует: ${!cell1Exists ? `${cell1Col}${cell1Row}` : `${cell2Col}${cell2Row}`}`);
+        }
+    }
+    return { isValid: true };
+}
+// Вспомогательные функции для проверки пересечений
+function rangesIntersect(a, b) {
+    const aStartColNum = colToNumber(a.startCol);
+    const aEndColNum = colToNumber(a.endCol);
+    const bStartColNum = colToNumber(b.startCol);
+    const bEndColNum = colToNumber(b.endCol);
+    // Проверяем пересечение по строкам
+    const rowsIntersect = !(a.endRow < b.startRow || a.startRow > b.endRow);
+    // Проверяем пересечение по колонкам
+    const colsIntersect = !(aEndColNum < bStartColNum || aStartColNum > bEndColNum);
+    return rowsIntersect && colsIntersect;
+}
+function getRangeString(range) {
+    return `${range.startCol}${range.startRow}:${range.endCol}${range.endRow}`;
+}
+// Функция для преобразования букв колонки в число
+function colToNumber(col) {
+    let num = 0;
+    for (let i = 0; i < col.length; i++) {
+        num = num * 26 + (col.charCodeAt(i) - 64);
+    }
+    return num;
+}
+;

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

@@ -1,5 +1,5 @@
 import * as path from "node:path";
-import { Transform } from "node:stream";
+import { PassThrough, Transform } from "node:stream";
 import { createReadStream } from "node:fs";
 import { pipeline } from "node:stream/promises";
 import zlib from "node:zlib";
@@ -17,20 +17,32 @@ import { CENTRAL_DIR_HEADER_SIG, END_OF_CENTRAL_DIR_SIG, LOCAL_FILE_HEADER_SIG,
  * @throws {Error} - If the writable stream emits an error.
  */
 export async function createWithStream(fileKeys, destination, output) {
+    // Stores central directory records
     const centralDirectory = [];
+    // Tracks the current offset in the output stream
     let offset = 0;
     for (const filename of fileKeys.sort((a, b) => a.localeCompare(b))) {
+        // Prevent directory traversal
         if (filename.includes("..")) {
             throw new Error(`Invalid filename: ${filename}`);
         }
+        // Construct absolute path to the file
         const fullPath = path.join(destination, ...filename.split("/"));
+        // Convert filename to UTF-8 buffer
         const fileNameBuf = Buffer.from(filename, "utf8");
+        // Get modification time in DOS format
         const modTime = dosTime(new Date());
+        // Read file as stream
         const source = createReadStream(fullPath);
+        // Create CRC32 transform stream
         const crc32 = crc32Stream();
+        // Create raw deflate stream (no zlib headers)
         const deflater = zlib.createDeflateRaw();
+        // Uncompressed size counter
         let uncompSize = 0;
+        // Compressed size counter
         let compSize = 0;
+        // Store compressed output data
         const compressedChunks = [];
         const sizeCounter = new Transform({
             transform(chunk, _enc, cb) {
@@ -38,135 +50,83 @@ export async function createWithStream(fileKeys, destination, output) {
                 cb(null, chunk);
             },
         });
-        const collectCompressed = new Transform({
-            transform(chunk, _enc, cb) {
-                compressedChunks.push(chunk);
-                compSize += chunk.length;
-                cb(null, chunk);
-            },
+        const collectCompressed = new PassThrough();
+        collectCompressed.on("data", chunk => {
+            // Count compressed bytes
+            compSize += chunk.length;
+            // Save compressed chunk
+            compressedChunks.push(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);
-        // });
+        // Run all transforms in pipeline: read -> count size -> CRC -> deflate -> collect compressed
         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);
-        // });
+        // Get final CRC32 value
         const crc = crc32.digest();
+        // Concatenate all compressed chunks into a single buffer
         const compressed = Buffer.concat(compressedChunks);
+        // Create local file header followed by compressed content
         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,
+            LOCAL_FILE_HEADER_SIG, // Local file header signature
+            toBytes(20, 2), // Version needed to extract
+            toBytes(0, 2), // General purpose bit flag
+            toBytes(8, 2), // Compression method (deflate)
+            modTime, // File modification time and date
+            toBytes(crc, 4), // CRC-32 checksum
+            toBytes(compSize, 4), // Compressed size
+            toBytes(uncompSize, 4), // Uncompressed size
+            toBytes(fileNameBuf.length, 2), // Filename length
+            toBytes(0, 2), // Extra field length
+            fileNameBuf, // Filename
+            compressed, // Compressed file data
         ]);
+        // Write local file header and data to output
         await new Promise((resolve, reject) => {
             output.write(localHeader, err => err ? reject(err) : resolve());
         });
+        // Create central directory entry for this file
         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,
+            CENTRAL_DIR_HEADER_SIG, // Central directory file header signature
+            toBytes(20, 2), // Version made by
+            toBytes(20, 2), // Version needed to extract
+            toBytes(0, 2), // General purpose bit flag
+            toBytes(8, 2), // Compression method
+            modTime, // File modification time and date
+            toBytes(crc, 4), // CRC-32 checksum
+            toBytes(compSize, 4), // Compressed size
+            toBytes(uncompSize, 4), // Uncompressed size
+            toBytes(fileNameBuf.length, 2), // Filename length
+            toBytes(0, 2), // Extra field length
+            toBytes(0, 2), // File comment length
+            toBytes(0, 2), // Disk number start
+            toBytes(0, 2), // Internal file attributes
+            toBytes(0, 4), // External file attributes
+            toBytes(offset, 4), // Offset of local header
+            fileNameBuf, // Filename
         ]);
+        // Store for later
         centralDirectory.push(centralEntry);
+        // Update offset after writing this entry
         offset += localHeader.length;
     }
+    // Total size of central directory
     const centralDirSize = centralDirectory.reduce((sum, entry) => sum + entry.length, 0);
+    // Start of central directory
     const centralDirOffset = offset;
+    // Write each central directory entry to output
     for (const entry of centralDirectory) {
         await new Promise((resolve, reject) => {
             output.write(entry, err => err ? reject(err) : resolve());
         });
     }
+    // Create and write end of central directory record
     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),
+        END_OF_CENTRAL_DIR_SIG, // End of central directory signature
+        toBytes(0, 2), // Number of this disk
+        toBytes(0, 2), // Disk with start of central directory
+        toBytes(centralDirectory.length, 2), // Total entries on this disk
+        toBytes(centralDirectory.length, 2), // Total entries overall
+        toBytes(centralDirSize, 4), // Size of central directory
+        toBytes(centralDirOffset, 4), // Offset of start of central directory
+        toBytes(0, 2), // ZIP file comment length
     ]);
     await new Promise((resolve, reject) => {
         output.write(endRecord, err => err ? reject(err) : resolve());

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

@@ -29,6 +29,30 @@ export declare class TemplateFs {
      * @experimental This API is experimental and might change in future versions.
      */
     constructor(fileKeys: Set<string>, destination: string);
+    /**
+     * Copies a sheet from the template to a new name.
+     *
+     * @param {string} sourceName - The name of the sheet to copy.
+     * @param {string} newName - The new name for the sheet.
+     * @returns {Promise<void>}
+     * @throws {Error} If the sheet with the source name does not exist.
+     * @throws {Error} If a sheet with the new name already exists.
+     * @experimental This API is experimental and might change in future versions.
+     */
+    copySheet(sourceName: string, newName: string): Promise<void>;
+    /**
+     * Replaces placeholders in the given sheet with values from the replacements map.
+     *
+     * The function searches for placeholders in the format `${key}` within the sheet
+     * content, where `key` corresponds to a path in the replacements object.
+     * If a value is found for the key, it replaces the placeholder with the value.
+     * If no value is found, the original placeholder remains unchanged.
+     *
+     * @param sheetName - The name of the sheet to be replaced.
+     * @param replacements - An object where keys represent placeholder paths and values are the replacements.
+     * @returns A promise that resolves when the substitution is complete.
+     */
+    substitute(sheetName: string, replacements: Record<string, unknown>): Promise<void>;
     /**
      * Inserts rows into a specific sheet in the template.
      *