@js-ak/excel-toolbox 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anton K.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1 @@
+# excel-toolbox

package/build/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/index.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -0,0 +1 @@
+export * from './lib/index.js';

package/build/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './merge-sheets-to-base-file.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC"}

package/build/lib/index.js

@@ -0,0 +1 @@
+export * from './merge-sheets-to-base-file.js';

package/build/lib/merge-sheets-to-base-file.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="node" />
+/// <reference types="node" />
+export declare function mergeSheetsToBaseFile(data: {
+    baseFile: Buffer;
+    baseSheetIndex?: number;
+    additions: {
+        file: Buffer;
+        sheetIndex: number;
+    }[];
+    gap?: number;
+}): Promise<Buffer>;
+//# sourceMappingURL=merge-sheets-to-base-file.d.ts.map

package/build/lib/merge-sheets-to-base-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-sheets-to-base-file.d.ts","sourceRoot":"","sources":["../../src/lib/merge-sheets-to-base-file.ts"],"names":[],"mappings":";;AAMA,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;KAAE,EAAE,CAAC;IACnD,GAAG,CAAC,EAAE,MAAM,CAAA;CACZ,mBAgEA"}

package/build/lib/merge-sheets-to-base-file.js

@@ -0,0 +1,91 @@
+import { extractRowsFromSheet } from './xml/extract-rows-from-sheet.js';
+import { shiftRowIndices } from './xml/shift-row-indices.js';
+import { buildMergedSheet } from './xml/build-merged-sheet.js';
+import * as Zip from './zip/index.js';
+export async function mergeSheetsToBaseFile(data) {
+    const { additions = [], baseFile, baseSheetIndex = 1, gap = 1, } = data;
+    const baseFiles = Zip.read(baseFile);
+    const basePath = `xl/worksheets/sheet${baseSheetIndex}.xml`;
+    if (!baseFiles[basePath]) {
+        throw new Error(`Base file does not contain ${basePath}`);
+    }
+    const { lastRowNumber, mergeCells: baseMergeCells, rows: baseRows, } = extractRowsFromSheet(baseFiles[basePath]);
+    const allRows = [...baseRows];
+    const allMergeCells = [...(baseMergeCells || [])];
+    let currentRowOffset = lastRowNumber + gap;
+    for (const { file, sheetIndex } of additions) {
+        const files = isSameBuffer(file, baseFile) ? baseFiles : Zip.read(file);
+        const sheetPath = `xl/worksheets/sheet${sheetIndex}.xml`;
+        if (!files[sheetPath]) {
+            throw new Error(`File does not contain ${sheetPath}`);
+        }
+        const { mergeCells, rows } = extractRowsFromSheet(files[sheetPath]);
+        const shiftedRows = shiftRowIndices(rows, currentRowOffset);
+        const shiftedMergeCells = (mergeCells || []).map(cell => {
+            const [start, end] = cell.ref.split(':');
+            if (!start || !end) {
+                return cell;
+            }
+            const shiftedStart = shiftCellRef(start, currentRowOffset);
+            const shiftedEnd = shiftCellRef(end, currentRowOffset);
+            return { ...cell, ref: `${shiftedStart}:${shiftedEnd}` };
+        });
+        allRows.push(...shiftedRows);
+        allMergeCells.push(...shiftedMergeCells);
+        currentRowOffset += getMaxRowNumber(rows) + gap;
+    }
+    const mergedXml = buildMergedSheet(baseFiles[basePath], allRows, allMergeCells);
+    baseFiles[basePath] = mergedXml;
+    const zip = Zip.create(baseFiles);
+    return zip;
+}
+/**
+ * Shifts the row number in a cell reference by the specified number of rows.
+ * The function takes a cell reference string in the format "A1" and a row shift value.
+ * It returns the shifted cell reference string.
+ *
+ * @example
+ * // Shifts the cell reference "A1" down by 2 rows, resulting in "A3"
+ * shiftCellRef('A1', 2);
+ * @param {string} cellRef - The cell reference string to be shifted
+ * @param {number} rowShift - The number of rows to shift the reference by
+ * @returns {string} - The shifted cell reference string
+ */
+function shiftCellRef(cellRef, rowShift) {
+    const match = cellRef.match(/^([A-Z]+)(\d+)$/);
+    if (!match)
+        return cellRef;
+    const col = match[1];
+    if (!match[2])
+        return cellRef;
+    const row = parseInt(match[2], 10);
+    return `${col}${row + rowShift}`;
+}
+/**
+ * Checks if two Buffers are the same
+ * @param {Buffer} buf1 - the first Buffer
+ * @param {Buffer} buf2 - the second Buffer
+ * @returns {boolean} - true if the Buffers are the same, false otherwise
+ */
+function isSameBuffer(buf1, buf2) {
+    return buf1.equals(buf2);
+}
+/**
+ * Finds the maximum row number in a list of <row> elements.
+ * @param {string[]} rows - An array of strings, each representing a <row> element.
+ * @returns {number} - The maximum row number.
+ */
+function getMaxRowNumber(rows) {
+    let max = 0;
+    for (const row of rows) {
+        const match = row.match(/<row[^>]* r="(\d+)"/);
+        if (match) {
+            if (!match[1])
+                continue;
+            const num = parseInt(match[1], 10);
+            if (num > max)
+                max = num;
+        }
+    }
+    return max;
+}

package/build/lib/xml/build-merged-sheet.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Builds a new XML string for a merged Excel sheet by combining the original XML
+ * with merged rows and optional cell merge information.
+ *
+ * This function replaces the sheet data content in the original XML with the merged rows
+ * and optionally adds merge cell definitions at the end of the sheet data.
+ *
+ * @param {string} originalXml - The original XML string of the Excel worksheet
+ * @param {string[]} mergedRows - Array of XML strings representing each row in the merged sheet
+ * @param {Object[]} [mergeCells] - Optional array of merge cell definitions
+ *        Each object should have a 'ref' property specifying the merge range (e.g., "A1:B2")
+ * @returns {string} - The reconstructed XML string with merged content
+ */
+export declare function buildMergedSheet(originalXml: string, mergedRows: string[], mergeCells?: {
+    ref: string;
+}[]): string;
+//# sourceMappingURL=build-merged-sheet.d.ts.map

package/build/lib/xml/build-merged-sheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-merged-sheet.d.ts","sourceRoot":"","sources":["../../../src/lib/xml/build-merged-sheet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC/B,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAAE,EACpB,UAAU,GAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,EAAO,GAChC,MAAM,CAwBR"}

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

@@ -0,0 +1,32 @@
+/**
+ * Builds a new XML string for a merged Excel sheet by combining the original XML
+ * with merged rows and optional cell merge information.
+ *
+ * This function replaces the sheet data content in the original XML with the merged rows
+ * and optionally adds merge cell definitions at the end of the sheet data.
+ *
+ * @param {string} originalXml - The original XML string of the Excel worksheet
+ * @param {string[]} mergedRows - Array of XML strings representing each row in the merged sheet
+ * @param {Object[]} [mergeCells] - Optional array of merge cell definitions
+ *        Each object should have a 'ref' property specifying the merge range (e.g., "A1:B2")
+ * @returns {string} - The reconstructed XML string with merged content
+ */
+export function buildMergedSheet(originalXml, mergedRows, mergeCells = []) {
+    // Replace the entire sheetData section in the original XML with our merged rows
+    // The regex matches:
+    // - Opening <sheetData> tag with any attributes
+    // - Any content between opening and closing tags (including line breaks)
+    // - Closing </sheetData> tag
+    let xmlData = originalXml.replace(/<sheetData[^>]*>[\s\S]*?<\/sheetData>/, `<sheetData>\n${mergedRows.join('\n')}\n</sheetData>`);
+    // If merge cells were specified, add them after the sheetData section
+    if (mergeCells.length > 0) {
+        // Create mergeCells XML section:
+        // - Includes count attribute with total number of merges
+        // - Contains one mergeCell element for each merge definition
+        const mergeCellsXml = `<mergeCells count="${mergeCells.length}">${mergeCells.map(mc => `<mergeCell ref="${mc.ref}"/>`).join('')}</mergeCells>`;
+        // Insert the mergeCells section immediately after the sheetData closing tag
+        xmlData = xmlData.replace('</sheetData>', `</sheetData>${mergeCellsXml}`);
+    }
+    // Return the fully reconstructed XML
+    return xmlData;
+}

package/build/lib/xml/extract-rows-from-sheet.d.ts

@@ -0,0 +1,30 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/**
+ * Parses a worksheet (either as Buffer or string) to extract row data,
+ * last row number, and merge cell information from Excel XML format.
+ *
+ * This function is particularly useful for processing Excel files in
+ * Open XML Spreadsheet format (.xlsx).
+ *
+ * @param {Buffer|string} sheet - The worksheet content to parse, either as:
+ *                               - Buffer (binary Excel sheet)
+ *                               - string (raw XML content)
+ * @returns {{
+ *   rows: string[],
+ *   lastRowNumber: number,
+ *   mergeCells: {ref: string}[]
+ * }} An object containing:
+ *   - rows: Array of raw XML strings for each <row> element
+ *   - lastRowNumber: Highest row number found in the sheet (1-based)
+ *   - mergeCells: Array of merged cell ranges (e.g., [{ref: "A1:B2"}])
+ * @throws {Error} If the sheetData section is not found in the XML
+ */
+export declare function extractRowsFromSheet(sheet: Buffer | string): {
+    rows: string[];
+    lastRowNumber: number;
+    mergeCells: {
+        ref: string;
+    }[];
+};
+//# sourceMappingURL=extract-rows-from-sheet.d.ts.map

package/build/lib/xml/extract-rows-from-sheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-rows-from-sheet.d.ts","sourceRoot":"","sources":["../../../src/lib/xml/extract-rows-from-sheet.ts"],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG;IAC7D,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC9B,CA+CA"}

package/build/lib/xml/extract-rows-from-sheet.js

@@ -0,0 +1,61 @@
+import { extractXmlFromSheet } from './extract-xml-from-sheet.js';
+/**
+ * Parses a worksheet (either as Buffer or string) to extract row data,
+ * last row number, and merge cell information from Excel XML format.
+ *
+ * This function is particularly useful for processing Excel files in
+ * Open XML Spreadsheet format (.xlsx).
+ *
+ * @param {Buffer|string} sheet - The worksheet content to parse, either as:
+ *                               - Buffer (binary Excel sheet)
+ *                               - string (raw XML content)
+ * @returns {{
+ *   rows: string[],
+ *   lastRowNumber: number,
+ *   mergeCells: {ref: string}[]
+ * }} An object containing:
+ *   - rows: Array of raw XML strings for each <row> element
+ *   - lastRowNumber: Highest row number found in the sheet (1-based)
+ *   - mergeCells: Array of merged cell ranges (e.g., [{ref: "A1:B2"}])
+ * @throws {Error} If the sheetData section is not found in the XML
+ */
+export function extractRowsFromSheet(sheet) {
+    // Convert Buffer input to XML string if needed
+    const xml = typeof sheet === 'string' ? sheet : extractXmlFromSheet(sheet);
+    // Extract the sheetData section containing all rows
+    const sheetDataMatch = xml.match(/<sheetData[^>]*>([\s\S]*?)<\/sheetData>/);
+    if (!sheetDataMatch) {
+        throw new Error('sheetData not found in worksheet XML');
+    }
+    const sheetDataContent = sheetDataMatch[1] || '';
+    // Extract all <row> elements using regex
+    const rowMatches = [...sheetDataContent.matchAll(/<row[\s\S]*?<\/row>/g)];
+    const rows = rowMatches.map(match => match[0]);
+    // Calculate the highest row number present in the sheet
+    const lastRowNumber = rowMatches
+        .map(match => {
+        // Extract row number from r="..." attribute (1-based)
+        const rowNumMatch = match[0].match(/r="(\d+)"/);
+        return rowNumMatch?.[1] ? parseInt(rowNumMatch[1], 10) : null;
+    })
+        .filter((row) => row !== null) // Type guard to filter out nulls
+        .reduce((max, current) => Math.max(max, current), 0); // Find maximum row number
+    // Extract all merged cell ranges from the worksheet
+    const mergeCells = [];
+    const mergeCellsMatch = xml.match(/<mergeCells[^>]*>([\s\S]*?)<\/mergeCells>/);
+    if (mergeCellsMatch) {
+        // Find all mergeCell entries with ref attributes
+        const mergeCellMatches = mergeCellsMatch[1]?.match(/<mergeCell[^>]+ref="([^"]+)"[^>]*>/g) || [];
+        mergeCellMatches.forEach(match => {
+            const refMatch = match.match(/ref="([^"]+)"/);
+            if (refMatch?.[1]) {
+                mergeCells.push({ ref: refMatch[1] }); // Store the cell range (e.g., "A1:B2")
+            }
+        });
+    }
+    return {
+        rows,
+        lastRowNumber,
+        mergeCells,
+    };
+}

package/build/lib/xml/extract-xml-from-sheet.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/**
+ * Extracts and parses XML content from an Excel worksheet file (e.g., xl/worksheets/sheet1.xml).
+ * Handles both compressed (raw deflate) and uncompressed (plain XML) formats.
+ *
+ * This function is designed to work with Excel Open XML (.xlsx) worksheet files,
+ * which may be stored in either compressed or uncompressed format within the ZIP container.
+ *
+ * @param {Buffer} buffer - The file content to process, which may be:
+ *                         - Raw XML text
+ *                         - Deflate-compressed XML data (without zlib headers)
+ * @returns {string} - The extracted XML content as a UTF-8 string
+ * @throws {Error} - If the buffer is empty or cannot be processed
+ */
+export declare function extractXmlFromSheet(buffer: Buffer): string;
+//# sourceMappingURL=extract-xml-from-sheet.d.ts.map

package/build/lib/xml/extract-xml-from-sheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-xml-from-sheet.d.ts","sourceRoot":"","sources":["../../../src/lib/xml/extract-xml-from-sheet.ts"],"names":[],"mappings":";;AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAwC1D"}

package/build/lib/xml/extract-xml-from-sheet.js

@@ -0,0 +1,51 @@
+import { inflateRaw } from 'pako';
+/**
+ * Extracts and parses XML content from an Excel worksheet file (e.g., xl/worksheets/sheet1.xml).
+ * Handles both compressed (raw deflate) and uncompressed (plain XML) formats.
+ *
+ * This function is designed to work with Excel Open XML (.xlsx) worksheet files,
+ * which may be stored in either compressed or uncompressed format within the ZIP container.
+ *
+ * @param {Buffer} buffer - The file content to process, which may be:
+ *                         - Raw XML text
+ *                         - Deflate-compressed XML data (without zlib headers)
+ * @returns {string} - The extracted XML content as a UTF-8 string
+ * @throws {Error} - If the buffer is empty or cannot be processed
+ */
+export function extractXmlFromSheet(buffer) {
+    if (!buffer || buffer.length === 0) {
+        throw new Error('Empty buffer provided');
+    }
+    let xml;
+    // Check if the buffer starts with an XML declaration (<?xml)
+    const startsWithXml = buffer.subarray(0, 5).toString('utf8').trim().startsWith('<?xml');
+    if (startsWithXml) {
+        // Case 1: Already uncompressed XML - convert directly to string
+        xml = buffer.toString('utf8');
+    }
+    else {
+        // Case 2: Attempt to decompress as raw deflate data
+        try {
+            const inflated = inflateRaw(buffer, { to: 'string' });
+            // Validate the decompressed content contains worksheet data
+            if (inflated && inflated.includes('<sheetData')) {
+                xml = inflated;
+            }
+            else {
+                throw new Error('Decompressed data does not contain sheetData');
+            }
+        }
+        catch (e) {
+            console.error('Decompression failed:', e);
+            // Continue to fallback attempt
+        }
+    }
+    // Fallback: If no XML obtained yet, try direct UTF-8 conversion
+    if (!xml) {
+        xml = buffer.toString('utf8');
+    }
+    // Sanitize XML by removing control characters (except tab, newline, carriage return)
+    // This handles potential corruption from binary data or encoding issues
+    xml = xml.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
+    return xml;
+}

package/build/lib/xml/extract-xml-from-system-content.d.ts

@@ -0,0 +1,18 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/**
+ * Extracts and decompresses XML content from Excel system files (e.g., workbook.xml, [Content_Types].xml).
+ * Handles both compressed (raw DEFLATE) and uncompressed (plain XML) formats with comprehensive error handling.
+ *
+ * @param {Buffer} buffer - The file content to process, which may be:
+ *                         - Raw XML text
+ *                         - DEFLATE-compressed XML data (without zlib headers)
+ * @param {string} name - The filename being processed (for error reporting)
+ * @returns {string} - The extracted XML content as a sanitized UTF-8 string
+ * @throws {Error} - With descriptive messages for various failure scenarios:
+ *                  - Empty buffer
+ *                  - Decompression failures
+ *                  - Invalid XML content
+ */
+export declare const extractXmlFromSystemContent: (buffer: Buffer, name: string) => string;
+//# sourceMappingURL=extract-xml-from-system-content.d.ts.map

package/build/lib/xml/extract-xml-from-system-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-xml-from-system-content.d.ts","sourceRoot":"","sources":["../../../src/lib/xml/extract-xml-from-system-content.ts"],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,2BAA2B,WAAY,MAAM,QAAQ,MAAM,KAAG,MAqC1E,CAAC"}

package/build/lib/xml/extract-xml-from-system-content.js

@@ -0,0 +1,49 @@
+import { inflateRaw } from 'pako';
+/**
+ * Extracts and decompresses XML content from Excel system files (e.g., workbook.xml, [Content_Types].xml).
+ * Handles both compressed (raw DEFLATE) and uncompressed (plain XML) formats with comprehensive error handling.
+ *
+ * @param {Buffer} buffer - The file content to process, which may be:
+ *                         - Raw XML text
+ *                         - DEFLATE-compressed XML data (without zlib headers)
+ * @param {string} name - The filename being processed (for error reporting)
+ * @returns {string} - The extracted XML content as a sanitized UTF-8 string
+ * @throws {Error} - With descriptive messages for various failure scenarios:
+ *                  - Empty buffer
+ *                  - Decompression failures
+ *                  - Invalid XML content
+ */
+export const extractXmlFromSystemContent = (buffer, name) => {
+    // Validate input buffer
+    if (!buffer || buffer.length === 0) {
+        throw new Error(`Empty data buffer provided for file ${name}`);
+    }
+    let xml;
+    // Check for XML declaration in first 5 bytes (<?xml)
+    const startsWithXml = buffer.subarray(0, 5).toString('utf8').trim().startsWith('<?xml');
+    if (startsWithXml) {
+        // Case 1: Already uncompressed XML - convert directly to string
+        xml = buffer.toString('utf8');
+    }
+    else {
+        // Case 2: Attempt DEFLATE decompression
+        try {
+            const inflated = inflateRaw(buffer, { to: 'string' });
+            // Validate decompressed content contains XML declaration
+            if (inflated && inflated.includes('<?xml')) {
+                xml = inflated;
+            }
+            else {
+                throw new Error(`Decompressed data doesn't contain valid XML in ${name}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            throw new Error(`Failed to decompress ${name}: ${message}`);
+        }
+    }
+    // Sanitize XML by removing illegal control characters (per XML 1.0 spec)
+    // Preserves tabs (0x09), newlines (0x0A), and carriage returns (0x0D)
+    xml = xml.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '');
+    return xml;
+};

package/build/lib/xml/shift-row-indices.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Adjusts row indices in Excel XML row elements by a specified offset.
+ * Handles both row element attributes and cell references within rows.
+ *
+ * This function is particularly useful when merging sheets or rearranging
+ * worksheet content while maintaining proper Excel XML structure.
+ *
+ * @param {string[]} rows - Array of XML <row> elements as strings
+ * @param {number} offset - Numeric value to adjust row indices by:
+ *                         - Positive values shift rows down
+ *                         - Negative values shift rows up
+ * @returns {string[]} - New array with modified row elements containing updated indices
+ *
+ * @example
+ * // Shifts rows down by 2 positions
+ * shiftRowIndices([`<row r="1"><c r="A1"/></row>`], 2);
+ * // Returns: [`<row r="3"><c r="A3"/></row>`]
+ */
+export declare function shiftRowIndices(rows: string[], offset: number): string[];
+//# sourceMappingURL=shift-row-indices.d.ts.map

package/build/lib/xml/shift-row-indices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shift-row-indices.d.ts","sourceRoot":"","sources":["../../../src/lib/xml/shift-row-indices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAsBxE"}

package/build/lib/xml/shift-row-indices.js

@@ -0,0 +1,32 @@
+/**
+ * Adjusts row indices in Excel XML row elements by a specified offset.
+ * Handles both row element attributes and cell references within rows.
+ *
+ * This function is particularly useful when merging sheets or rearranging
+ * worksheet content while maintaining proper Excel XML structure.
+ *
+ * @param {string[]} rows - Array of XML <row> elements as strings
+ * @param {number} offset - Numeric value to adjust row indices by:
+ *                         - Positive values shift rows down
+ *                         - Negative values shift rows up
+ * @returns {string[]} - New array with modified row elements containing updated indices
+ *
+ * @example
+ * // Shifts rows down by 2 positions
+ * shiftRowIndices([`<row r="1"><c r="A1"/></row>`], 2);
+ * // Returns: [`<row r="3"><c r="A3"/></row>`]
+ */
+export function shiftRowIndices(rows, offset) {
+    return rows.map(row => {
+        // Process each row element through two replacement phases:
+        // 1. Update the row's own index (r="N" attribute)
+        let adjustedRow = row.replace(/(<row[^>]*\br=")(\d+)(")/, (_, prefix, rowIndex, suffix) => {
+            return `${prefix}${parseInt(rowIndex) + offset}${suffix}`;
+        });
+        // 2. Update all cell references within the row (r="AN" attributes)
+        adjustedRow = adjustedRow.replace(/(<c[^>]*\br=")([A-Z]+)(\d+)(")/g, (_, prefix, columnLetter, cellRowIndex, suffix) => {
+            return `${prefix}${columnLetter}${parseInt(cellRowIndex) + offset}${suffix}`;
+        });
+        return adjustedRow;
+    });
+}

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

@@ -0,0 +1,32 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { Buffer } from 'node:buffer';
+/**
+ * ZIP file signature constants in Buffer format.
+ * These magic numbers identify different sections of a ZIP file,
+ * as specified in PKWARE's APPNOTE.TXT (ZIP File Format Specification).
+ */
+/**
+ * Central Directory Header signature (0x504b0102).
+ * Marks an entry in the central directory, which contains metadata
+ * about all files in the archive.
+ * Format: 'PK\01\02'
+ * Found in the central directory that appears at the end of the ZIP file.
+ */
+export declare const CENTRAL_DIR_HEADER_SIG: Buffer;
+/**
+ * End of Central Directory Record signature (0x504b0506).
+ * Marks the end of the central directory and contains global information
+ * about the ZIP archive.
+ * Format: 'PK\05\06'
+ * This is the last record in a valid ZIP file.
+ */
+export declare const END_OF_CENTRAL_DIR_SIG: Buffer;
+/**
+ * Local File Header signature (0x504b0304).
+ * Marks the beginning of a file entry within the ZIP archive.
+ * Format: 'PK\03\04' (ASCII letters PK followed by version numbers)
+ * Appears before each file's compressed data.
+ */
+export declare const LOCAL_FILE_HEADER_SIG: Buffer;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/lib/zip/constants.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;GAIG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,QAAiC,CAAC;AAErE;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,QAAiC,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAiC,CAAC"}

package/build/lib/zip/constants.js

@@ -0,0 +1,29 @@
+import { Buffer } from 'node:buffer';
+/**
+ * ZIP file signature constants in Buffer format.
+ * These magic numbers identify different sections of a ZIP file,
+ * as specified in PKWARE's APPNOTE.TXT (ZIP File Format Specification).
+ */
+/**
+ * Central Directory Header signature (0x504b0102).
+ * Marks an entry in the central directory, which contains metadata
+ * about all files in the archive.
+ * Format: 'PK\01\02'
+ * Found in the central directory that appears at the end of the ZIP file.
+ */
+export const CENTRAL_DIR_HEADER_SIG = Buffer.from('504b0102', 'hex');
+/**
+ * End of Central Directory Record signature (0x504b0506).
+ * Marks the end of the central directory and contains global information
+ * about the ZIP archive.
+ * Format: 'PK\05\06'
+ * This is the last record in a valid ZIP file.
+ */
+export const END_OF_CENTRAL_DIR_SIG = Buffer.from('504b0506', 'hex');
+/**
+ * Local File Header signature (0x504b0304).
+ * Marks the beginning of a file entry within the ZIP archive.
+ * Format: 'PK\03\04' (ASCII letters PK followed by version numbers)
+ * Appears before each file's compressed data.
+ */
+export const LOCAL_FILE_HEADER_SIG = Buffer.from('504b0304', 'hex');

package/build/lib/zip/create.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { Buffer } from 'node:buffer';
+/**
+ * Creates a ZIP archive from a collection of files.
+ *
+ * @param {Object.<string, Buffer|string>} files - An object with file paths as keys and either Buffer or string content as values.
+ * @returns {Buffer} - The ZIP archive as a Buffer.
+ */
+export declare function create(files: {
+    [path: string]: Buffer | string;
+}): Buffer;
+//# sourceMappingURL=create.d.ts.map

package/build/lib/zip/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/lib/zip/create.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAWrC;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG,MAAM,CAkFzE"}

package/build/lib/zip/create.js

@@ -0,0 +1,80 @@
+import { Buffer } from 'node:buffer';
+import { deflateRawSync } from 'node:zlib';
+import { toBytes, dosTime, crc32 } from './utils.js';
+import { LOCAL_FILE_HEADER_SIG, CENTRAL_DIR_HEADER_SIG, END_OF_CENTRAL_DIR_SIG, } from './constants.js';
+/**
+ * Creates a ZIP archive from a collection of files.
+ *
+ * @param {Object.<string, Buffer|string>} files - An object with file paths as keys and either Buffer or string content as values.
+ * @returns {Buffer} - The ZIP archive as a Buffer.
+ */
+export function create(files) {
+    const fileEntries = [];
+    const centralDirectory = [];
+    let offset = 0;
+    for (const [filename, rawContent] of Object.entries(files).sort(([a], [b]) => a.localeCompare(b))) {
+        if (filename.includes('..')) {
+            throw new Error(`Invalid filename: ${filename}`);
+        }
+        const content = Buffer.isBuffer(rawContent) ? rawContent : Buffer.from(rawContent);
+        const fileNameBuf = Buffer.from(filename, 'utf8');
+        const modTime = dosTime(new Date());
+        const crc = crc32(content);
+        const compressed = deflateRawSync(content);
+        const compSize = compressed.length;
+        const uncompSize = content.length;
+        // Local file header
+        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),
+        ]);
+        const localEntry = Buffer.concat([
+            localHeader,
+            fileNameBuf,
+            compressed,
+        ]);
+        fileEntries.push(localEntry);
+        const centralEntry = Buffer.concat([
+            Buffer.from(CENTRAL_DIR_HEADER_SIG),
+            Buffer.from(toBytes(20, 2)), // Version made by
+            Buffer.from(toBytes(20, 2)), // Version needed
+            Buffer.from(toBytes(0, 2)), // Flags
+            Buffer.from(toBytes(8, 2)), // Compression
+            Buffer.from(modTime),
+            Buffer.from(toBytes(crc, 4)),
+            Buffer.from(toBytes(compSize, 4)),
+            Buffer.from(toBytes(uncompSize, 4)),
+            Buffer.from(toBytes(fileNameBuf.length, 2)),
+            Buffer.from(toBytes(0, 2)), // Extra field length
+            Buffer.from(toBytes(0, 2)), // Comment length
+            Buffer.from(toBytes(0, 2)), // Disk start
+            Buffer.from(toBytes(0, 2)), // Internal attrs
+            Buffer.from(toBytes(0, 4)), // External attrs
+            Buffer.from(toBytes(offset, 4)),
+            fileNameBuf,
+        ]);
+        centralDirectory.push(centralEntry);
+        offset += localEntry.length;
+    }
+    const centralDirSize = centralDirectory.reduce((sum, entry) => sum + entry.length, 0);
+    const centralDirOffset = offset;
+    const endRecord = Buffer.concat([
+        Buffer.from(END_OF_CENTRAL_DIR_SIG),
+        Buffer.from(toBytes(0, 2)), // Disk #
+        Buffer.from(toBytes(0, 2)), // Start disk #
+        Buffer.from(toBytes(centralDirectory.length, 2)),
+        Buffer.from(toBytes(centralDirectory.length, 2)),
+        Buffer.from(toBytes(centralDirSize, 4)),
+        Buffer.from(toBytes(centralDirOffset, 4)),
+        Buffer.from(toBytes(0, 2)), // Comment length
+    ]);
+    return Buffer.concat(fileEntries.concat(centralDirectory).concat([endRecord]));
+}

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

@@ -0,0 +1,3 @@
+export * from './create.js';
+export * from './read.js';
+//# sourceMappingURL=index.d.ts.map

package/build/lib/zip/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/zip/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC"}

package/build/lib/zip/index.js

@@ -0,0 +1,2 @@
+export * from './create.js';
+export * from './read.js';

package/build/lib/zip/read.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/**
+ * Parses a ZIP archive from a buffer and extracts the files within.
+ *
+ * @param {Buffer} buffer - The buffer containing the ZIP archive data.
+ * @returns {Object.<string, string>} - An object where keys are file names and values are file contents.
+ * @throws {Error} - Throws an error if an unsupported compression method is encountered or if decompression fails.
+ */
+export declare function read(buffer: Buffer): {
+    [s: string]: string;
+};
+//# sourceMappingURL=read.d.ts.map

package/build/lib/zip/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/lib/zip/read.ts"],"names":[],"mappings":";;AAEA;;;;;;GAMG;AAEH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAAE,CA+C7D"}

package/build/lib/zip/read.js

@@ -0,0 +1,53 @@
+import { inflateRawSync } from 'node:zlib';
+/**
+ * Parses a ZIP archive from a buffer and extracts the files within.
+ *
+ * @param {Buffer} buffer - The buffer containing the ZIP archive data.
+ * @returns {Object.<string, string>} - An object where keys are file names and values are file contents.
+ * @throws {Error} - Throws an error if an unsupported compression method is encountered or if decompression fails.
+ */
+export function read(buffer) {
+    const files = {};
+    let offset = 0;
+    while (offset + 4 <= buffer.length) {
+        const signature = buffer.readUInt32LE(offset);
+        if (signature !== 0x04034b50)
+            break;
+        const compressionMethod = buffer.readUInt16LE(offset + 8);
+        const fileNameLength = buffer.readUInt16LE(offset + 26);
+        const extraLength = buffer.readUInt16LE(offset + 28);
+        const fileNameStart = offset + 30;
+        const fileNameEnd = fileNameStart + fileNameLength;
+        const fileName = buffer.subarray(fileNameStart, fileNameEnd).toString();
+        const dataStart = fileNameEnd + extraLength;
+        let nextOffset = dataStart;
+        while (nextOffset + 4 <= buffer.length) {
+            if (buffer.readUInt32LE(nextOffset) === 0x04034b50)
+                break;
+            nextOffset++;
+        }
+        if (nextOffset + 4 > buffer.length) {
+            nextOffset = buffer.length;
+        }
+        const compressedData = buffer.subarray(dataStart, nextOffset);
+        let content = '';
+        try {
+            if (compressionMethod === 0) {
+                content = compressedData.toString();
+            }
+            else if (compressionMethod === 8) {
+                content = inflateRawSync(new Uint8Array(compressedData)).toString();
+            }
+            else {
+                throw new Error(`Unsupported compression method ${compressionMethod}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            throw new Error(`Error unpacking file ${fileName}: ${message}`);
+        }
+        files[fileName] = content;
+        offset = nextOffset;
+    }
+    return files;
+}

package/build/lib/zip/utils.d.ts

@@ -0,0 +1,61 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { Buffer } from 'buffer';
+/**
+ * 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.
+ *
+ * The algorithm follows these characteristics:
+ * - Polynomial: 0xEDB88320 (reversed representation of 0x04C11DB7)
+ * - Initial value: 0xFFFFFFFF (inverted by ~0)
+ * - Final XOR value: 0xFFFFFFFF (achieved by inverting the result)
+ * - Input and output reflection: Yes
+ *
+ * @param {Buffer} buf - The input buffer to calculate checksum for
+ * @returns {number} - The 32-bit unsigned CRC-32 checksum (0x00000000 to 0xFFFFFFFF)
+ */
+export declare function crc32(buf: Buffer): number;
+/**
+ * Converts a JavaScript Date object to a 4-byte Buffer in MS-DOS date/time format
+ * as specified in the ZIP file format specification (PKZIP APPNOTE.TXT).
+ *
+ * The MS-DOS date/time format packs both date and time into 4 bytes (32 bits) with
+ * the following bit layout:
+ *
+ * Time portion (2 bytes/16 bits):
+ * - Bits 00-04: Seconds divided by 2 (0-29, representing 0-58 seconds)
+ * - Bits 05-10: Minutes (0-59)
+ * - Bits 11-15: Hours (0-23)
+ *
+ * Date portion (2 bytes/16 bits):
+ * - Bits 00-04: Day (1-31)
+ * - Bits 05-08: Month (1-12)
+ * - Bits 09-15: Year offset from 1980 (0-127, representing 1980-2107)
+ *
+ * @param {Date} date - The JavaScript Date object to convert
+ * @returns {Buffer} - 4-byte Buffer containing:
+ *                    - Bytes 0-1: DOS time (hours, minutes, seconds/2)
+ *                    - Bytes 2-3: DOS date (year-1980, month, day)
+ * @throws {RangeError} - If the date is before 1980 or after 2107
+ */
+export declare function dosTime(date: Date): Buffer;
+/**
+ * Converts a numeric value into a fixed-length Buffer representation,
+ * storing the value in little-endian format with right-padding of zeros.
+ *
+ * This is particularly useful for binary protocols or file formats that
+ * require fixed-width numeric fields.
+ *
+ * @param {number} value - The numeric value to convert to bytes.
+ *        Note: JavaScript numbers are IEEE 754 doubles, but only the
+ *        integer portion will be used (up to 53-bit precision).
+ * @param {number} len - The desired length of the output Buffer in bytes.
+ *        Must be a positive integer.
+ * @returns {Buffer} - A new Buffer of exactly `len` bytes containing:
+ *        1. The value's bytes in little-endian order (least significant byte first)
+ *        2. Zero padding in any remaining higher-order bytes
+ * @throws {RangeError} - If the value requires more bytes than `len` to represent
+ *        (though this is currently not explicitly checked)
+ */
+export declare function toBytes(value: number, len: number): Buffer;
+//# sourceMappingURL=utils.d.ts.map

package/build/lib/zip/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/lib/zip/utils.ts"],"names":[],"mappings":";;AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAyChC;;;;;;;;;;;;GAYG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA2BzC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAyB1C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAkB1D"}

package/build/lib/zip/utils.js

@@ -0,0 +1,152 @@
+import { Buffer } from 'buffer';
+/**
+ * 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;
+})();
+/**
+ * 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.
+ *
+ * The algorithm follows these characteristics:
+ * - Polynomial: 0xEDB88320 (reversed representation of 0x04C11DB7)
+ * - Initial value: 0xFFFFFFFF (inverted by ~0)
+ * - Final XOR value: 0xFFFFFFFF (achieved by inverting the result)
+ * - Input and output reflection: Yes
+ *
+ * @param {Buffer} buf - The input buffer to calculate checksum for
+ * @returns {number} - The 32-bit unsigned CRC-32 checksum (0x00000000 to 0xFFFFFFFF)
+ */
+export function crc32(buf) {
+    // Initialize CRC with all 1's (0xFFFFFFFF) using bitwise NOT
+    let crc = ~0;
+    // Process each byte in the buffer
+    for (let i = 0; i < buf.length; i++) {
+        /*
+         * CRC update algorithm steps:
+         * 1. XOR current CRC with next byte (lowest 8 bits)
+         * 2. Use result as index in precomputed table (0-255)
+         * 3. XOR the table value with right-shifted CRC (8 bits)
+         *
+         * The operation breakdown:
+         * - (crc ^ buf[i]) - XOR with next byte
+         * - & 0xff - Isolate lowest 8 bits
+         * - crc >>> 8 - Shift CRC right by 8 bits (unsigned)
+         * - ^ crcTable[...] - XOR with precomputed table value
+         */
+        crc = (crc >>> 8) ^ crcTable[(crc ^ buf[i]) & 0xff];
+    }
+    /*
+     * Final processing:
+     * 1. Invert all bits (~crc) to match standard CRC-32 output
+     * 2. Convert to unsigned 32-bit integer (>>> 0)
+     */
+    return ~crc >>> 0;
+}
+/**
+ * Converts a JavaScript Date object to a 4-byte Buffer in MS-DOS date/time format
+ * as specified in the ZIP file format specification (PKZIP APPNOTE.TXT).
+ *
+ * The MS-DOS date/time format packs both date and time into 4 bytes (32 bits) with
+ * the following bit layout:
+ *
+ * Time portion (2 bytes/16 bits):
+ * - Bits 00-04: Seconds divided by 2 (0-29, representing 0-58 seconds)
+ * - Bits 05-10: Minutes (0-59)
+ * - Bits 11-15: Hours (0-23)
+ *
+ * Date portion (2 bytes/16 bits):
+ * - Bits 00-04: Day (1-31)
+ * - Bits 05-08: Month (1-12)
+ * - Bits 09-15: Year offset from 1980 (0-127, representing 1980-2107)
+ *
+ * @param {Date} date - The JavaScript Date object to convert
+ * @returns {Buffer} - 4-byte Buffer containing:
+ *                    - Bytes 0-1: DOS time (hours, minutes, seconds/2)
+ *                    - Bytes 2-3: DOS date (year-1980, month, day)
+ * @throws {RangeError} - If the date is before 1980 or after 2107
+ */
+export function dosTime(date) {
+    // Pack time components into 2 bytes (16 bits):
+    // - Hours (5 bits) shifted left 11 positions (bits 11-15)
+    // - Minutes (6 bits) shifted left 5 positions (bits 5-10)
+    // - Seconds/2 (5 bits) in least significant bits (bits 0-4)
+    const time = (date.getHours() << 11) | // Hours occupy bits 11-15
+        (date.getMinutes() << 5) | // Minutes occupy bits 5-10
+        (Math.floor(date.getSeconds() / 2)); // Seconds/2 occupy bits 0-4
+    // Pack date components into 2 bytes (16 bits):
+    // - (Year-1980) (7 bits) shifted left 9 positions (bits 9-15)
+    // - Month (4 bits) shifted left 5 positions (bits 5-8)
+    // - Day (5 bits) in least significant bits (bits 0-4)
+    const day = ((date.getFullYear() - 1980) << 9) | // Years since 1980 (bits 9-15)
+        ((date.getMonth() + 1) << 5) | // Month 1-12 (bits 5-8)
+        date.getDate(); // Day 1-31 (bits 0-4)
+    // Combine both 2-byte values into a single 4-byte Buffer
+    // Note: Using little-endian byte order for each 2-byte segment
+    return Buffer.from([
+        ...toBytes(time, 2), // Convert time to 2 bytes (LSB first)
+        ...toBytes(day, 2), // Convert date to 2 bytes (LSB first)
+    ]);
+}
+/**
+ * Converts a numeric value into a fixed-length Buffer representation,
+ * storing the value in little-endian format with right-padding of zeros.
+ *
+ * This is particularly useful for binary protocols or file formats that
+ * require fixed-width numeric fields.
+ *
+ * @param {number} value - The numeric value to convert to bytes.
+ *        Note: JavaScript numbers are IEEE 754 doubles, but only the
+ *        integer portion will be used (up to 53-bit precision).
+ * @param {number} len - The desired length of the output Buffer in bytes.
+ *        Must be a positive integer.
+ * @returns {Buffer} - A new Buffer of exactly `len` bytes containing:
+ *        1. The value's bytes in little-endian order (least significant byte first)
+ *        2. Zero padding in any remaining higher-order bytes
+ * @throws {RangeError} - If the value requires more bytes than `len` to represent
+ *        (though this is currently not explicitly checked)
+ */
+export function toBytes(value, len) {
+    // Allocate a new Buffer of the requested length, automatically zero-filled
+    const buf = Buffer.alloc(len);
+    // Process each byte position from least significant to most significant
+    for (let i = 0; i < len; i++) {
+        // Store the least significant byte of the current value
+        buf[i] = value & 0xff; // Mask to get bottom 8 bits
+        // Right-shift the value by 8 bits to process the next byte
+        // Note: This uses unsigned right shift (>>> would be signed)
+        value >>= 8;
+        // If the loop completes with value != 0, we've overflowed the buffer length,
+        // but this isn't currently checked/handled
+    }
+    return buf;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@js-ak/excel-toolbox",
+  "version": "1.0.0",
+  "description": "excel-toolbox",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "files": [
+    "build/lib",
+    "build/index.js",
+    "build/index.d.ts",
+    "LICENSE",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint . --ext .ts",
+    "test": "npm run build && node ./build/test/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JS-AK/excel-toolbox.git"
+  },
+  "keywords": [
+    "excel-toolbox"
+  ],
+  "author": "JS-AK",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/JS-AK/excel-toolbox/issues"
+  },
+  "homepage": "https://github.com/JS-AK/excel-toolbox#readme",
+  "devDependencies": {
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/commit-analyzer": "13.0.0",
+    "@semantic-release/git": "10.0.1",
+    "@semantic-release/github": "10.0.6",
+    "@semantic-release/npm": "12.0.1",
+    "@semantic-release/release-notes-generator": "14.0.0",
+    "@types/node": "22.14.0",
+    "@types/pako": "2.0.3",
+    "eslint": "9.24.0",
+    "eslint-plugin-sort-destructure-keys": "2.0.0",
+    "eslint-plugin-sort-exports": "0.9.1",
+    "globals": "16.0.0",
+    "semantic-release": "24.0.0",
+    "typescript": "5.4.5",
+    "typescript-eslint": "8.29.0"
+  },
+  "dependencies": {
+    "pako": "2.1.0"
+  }
+}