@js-ak/excel-toolbox 1.1.0 → 1.2.0

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

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractXmlFromSheet = void 0;
+const pako_1 = require("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
+ */
+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
+        const inflated = (0, pako_1.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");
+        }
+    }
+    // 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;
+}
+exports.extractXmlFromSheet = extractXmlFromSheet;

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

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractXmlFromSystemContent = void 0;
+const pako_1 = require("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
+ */
+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 = (0, pako_1.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;
+};
+exports.extractXmlFromSystemContent = extractXmlFromSystemContent;

package/build/cjs/lib/xml/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./build-merged-sheet.js"), exports);
+__exportStar(require("./extract-rows-from-sheet.js"), exports);
+__exportStar(require("./extract-xml-from-sheet.js"), exports);
+__exportStar(require("./extract-xml-from-system-content.js"), exports);
+__exportStar(require("./shift-row-indices.js"), exports);

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

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shiftRowIndices = void 0;
+/**
+ * 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>`]
+ */
+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;
+    });
+}
+exports.shiftRowIndices = shiftRowIndices;

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

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCAL_FILE_HEADER_SIG = exports.END_OF_CENTRAL_DIR_SIG = exports.CENTRAL_DIR_HEADER_SIG = void 0;
+const node_buffer_1 = require("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.
+ */
+exports.CENTRAL_DIR_HEADER_SIG = node_buffer_1.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.
+ */
+exports.END_OF_CENTRAL_DIR_SIG = node_buffer_1.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.
+ */
+exports.LOCAL_FILE_HEADER_SIG = node_buffer_1.Buffer.from("504b0304", "hex");

package/build/cjs/lib/zip/create-sync.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSync = void 0;
+const node_buffer_1 = require("node:buffer");
+const node_zlib_1 = require("node:zlib");
+const utils_js_1 = require("./utils.js");
+const constants_js_1 = require("./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.
+ */
+function createSync(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 = node_buffer_1.Buffer.isBuffer(rawContent) ? rawContent : node_buffer_1.Buffer.from(rawContent);
+        const fileNameBuf = node_buffer_1.Buffer.from(filename, "utf8");
+        const modTime = (0, utils_js_1.dosTime)(new Date());
+        const crc = (0, utils_js_1.crc32)(content);
+        const compressed = (0, node_zlib_1.deflateRawSync)(content);
+        const compSize = compressed.length;
+        const uncompSize = content.length;
+        // Local file header
+        const localHeader = node_buffer_1.Buffer.concat([
+            constants_js_1.LOCAL_FILE_HEADER_SIG,
+            (0, utils_js_1.toBytes)(20, 2),
+            (0, utils_js_1.toBytes)(0, 2),
+            (0, utils_js_1.toBytes)(8, 2),
+            modTime,
+            (0, utils_js_1.toBytes)(crc, 4),
+            (0, utils_js_1.toBytes)(compSize, 4),
+            (0, utils_js_1.toBytes)(uncompSize, 4),
+            (0, utils_js_1.toBytes)(fileNameBuf.length, 2),
+            (0, utils_js_1.toBytes)(0, 2),
+        ]);
+        const localEntry = node_buffer_1.Buffer.concat([
+            localHeader,
+            fileNameBuf,
+            compressed,
+        ]);
+        fileEntries.push(localEntry);
+        const centralEntry = node_buffer_1.Buffer.concat([
+            node_buffer_1.Buffer.from(constants_js_1.CENTRAL_DIR_HEADER_SIG),
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(20, 2)), // Version made by
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(20, 2)), // Version needed
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Flags
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(8, 2)), // Compression
+            node_buffer_1.Buffer.from(modTime),
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(crc, 4)),
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(compSize, 4)),
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(uncompSize, 4)),
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(fileNameBuf.length, 2)),
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Extra field length
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Comment length
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Disk start
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Internal attrs
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 4)), // External attrs
+            node_buffer_1.Buffer.from((0, utils_js_1.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 = node_buffer_1.Buffer.concat([
+        node_buffer_1.Buffer.from(constants_js_1.END_OF_CENTRAL_DIR_SIG),
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Disk #
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Start disk #
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(centralDirectory.length, 2)),
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(centralDirectory.length, 2)),
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(centralDirSize, 4)),
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(centralDirOffset, 4)),
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Comment length
+    ]);
+    return node_buffer_1.Buffer.concat(fileEntries.concat(centralDirectory).concat([endRecord]));
+}
+exports.createSync = createSync;

package/build/cjs/lib/zip/create.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.create = void 0;
+const node_buffer_1 = require("node:buffer");
+const node_util_1 = __importDefault(require("node:util"));
+const node_zlib_1 = __importDefault(require("node:zlib"));
+const deflateRaw = node_util_1.default.promisify(node_zlib_1.default.deflateRaw);
+const utils_js_1 = require("./utils.js");
+const constants_js_1 = require("./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.
+ */
+async 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 = node_buffer_1.Buffer.isBuffer(rawContent) ? rawContent : node_buffer_1.Buffer.from(rawContent);
+        const fileNameBuf = node_buffer_1.Buffer.from(filename, "utf8");
+        const modTime = (0, utils_js_1.dosTime)(new Date());
+        const crc = (0, utils_js_1.crc32)(content);
+        const compressed = await deflateRaw(content);
+        const compSize = compressed.length;
+        const uncompSize = content.length;
+        // Local file header
+        const localHeader = node_buffer_1.Buffer.concat([
+            constants_js_1.LOCAL_FILE_HEADER_SIG,
+            (0, utils_js_1.toBytes)(20, 2),
+            (0, utils_js_1.toBytes)(0, 2),
+            (0, utils_js_1.toBytes)(8, 2),
+            modTime,
+            (0, utils_js_1.toBytes)(crc, 4),
+            (0, utils_js_1.toBytes)(compSize, 4),
+            (0, utils_js_1.toBytes)(uncompSize, 4),
+            (0, utils_js_1.toBytes)(fileNameBuf.length, 2),
+            (0, utils_js_1.toBytes)(0, 2),
+        ]);
+        const localEntry = node_buffer_1.Buffer.concat([
+            localHeader,
+            fileNameBuf,
+            compressed,
+        ]);
+        fileEntries.push(localEntry);
+        const centralEntry = node_buffer_1.Buffer.concat([
+            node_buffer_1.Buffer.from(constants_js_1.CENTRAL_DIR_HEADER_SIG),
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(20, 2)), // Version made by
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(20, 2)), // Version needed
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Flags
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(8, 2)), // Compression
+            node_buffer_1.Buffer.from(modTime),
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(crc, 4)),
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(compSize, 4)),
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(uncompSize, 4)),
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(fileNameBuf.length, 2)),
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Extra field length
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Comment length
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Disk start
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Internal attrs
+            node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 4)), // External attrs
+            node_buffer_1.Buffer.from((0, utils_js_1.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 = node_buffer_1.Buffer.concat([
+        node_buffer_1.Buffer.from(constants_js_1.END_OF_CENTRAL_DIR_SIG),
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Disk #
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Start disk #
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(centralDirectory.length, 2)),
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(centralDirectory.length, 2)),
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(centralDirSize, 4)),
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(centralDirOffset, 4)),
+        node_buffer_1.Buffer.from((0, utils_js_1.toBytes)(0, 2)), // Comment length
+    ]);
+    return node_buffer_1.Buffer.concat(fileEntries.concat(centralDirectory).concat([endRecord]));
+}
+exports.create = create;

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

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./create-sync.js"), exports);
+__exportStar(require("./create.js"), exports);
+__exportStar(require("./read-sync.js"), exports);
+__exportStar(require("./read.js"), exports);

package/build/cjs/lib/zip/read-sync.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSync = void 0;
+const node_zlib_1 = require("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.
+ */
+function readSync(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 = (0, node_zlib_1.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;
+}
+exports.readSync = readSync;

package/build/cjs/lib/zip/read.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.read = void 0;
+const node_util_1 = __importDefault(require("node:util"));
+const node_zlib_1 = __importDefault(require("node:zlib"));
+const inflateRaw = node_util_1.default.promisify(node_zlib_1.default.inflateRaw);
+/**
+ * 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.
+ */
+async 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 = (await inflateRaw(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;
+}
+exports.read = read;

package/build/cjs/lib/zip/utils.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBytes = exports.dosTime = exports.crc32 = void 0;
+const node_buffer_1 = require("node: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)
+ */
+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;
+}
+exports.crc32 = crc32;
+/**
+ * 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
+ */
+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 node_buffer_1.Buffer.from([
+        ...toBytes(time, 2), // Convert time to 2 bytes (LSB first)
+        ...toBytes(day, 2), // Convert date to 2 bytes (LSB first)
+    ]);
+}
+exports.dosTime = dosTime;
+/**
+ * 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)
+ */
+function toBytes(value, len) {
+    // Allocate a new Buffer of the requested length, automatically zero-filled
+    const buf = node_buffer_1.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;
+}
+exports.toBytes = toBytes;