@cj-tech-master/excelts 1.4.3 → 1.4.5

package/dist/esm/utils/zip/compress.js

@@ -0,0 +1,220 @@
+/**
+ * Native compression utilities using platform APIs
+ *
+ * - Node.js: Uses native zlib module (C++ implementation, fastest)
+ * - Browser: Uses CompressionStream API (Chrome 80+, Firefox 113+, Safari 16.4+)
+ *
+ * Both use "deflate-raw" format which is required for ZIP files
+ * (raw DEFLATE without zlib header/trailer)
+ */
+// Detect environment
+const isNode = typeof process !== "undefined" && process.versions?.node;
+// Lazy-loaded zlib module for Node.js
+let _zlib = null;
+let _zlibLoading = null;
+// Auto-initialize zlib in Node.js environment
+if (isNode) {
+    _zlibLoading = import("zlib")
+        .then(module => {
+        _zlib = module.default ?? module;
+        return _zlib;
+    })
+        .catch(() => {
+        _zlib = null;
+        return null;
+    });
+}
+/**
+ * Get zlib module (Node.js only)
+ * Returns null if not yet loaded or not in Node.js
+ */
+function getZlib() {
+    return _zlib;
+}
+/**
+ * Ensure zlib is loaded (Node.js only)
+ * Call this before using sync methods if you need to guarantee availability
+ */
+export async function ensureZlib() {
+    if (_zlibLoading) {
+        return _zlibLoading;
+    }
+    return _zlib;
+}
+/**
+ * Check if native zlib is available (Node.js)
+ */
+export function hasNativeZlib() {
+    const zlib = getZlib();
+    return zlib !== null && typeof zlib.deflateRawSync === "function";
+}
+/**
+ * Check if CompressionStream is available (Browser/Node.js 17+)
+ */
+export function hasCompressionStream() {
+    return typeof CompressionStream !== "undefined";
+}
+/**
+ * Compress data using the best available native method
+ *
+ * Priority:
+ * 1. Node.js zlib (if available) - fastest, supports compression levels
+ * 2. CompressionStream (browser/Node.js 17+) - no level support
+ * 3. Return uncompressed data (fallback)
+ *
+ * @param data - Data to compress
+ * @param options - Compression options
+ * @returns Compressed data
+ *
+ * @example
+ * ```ts
+ * const data = new TextEncoder().encode("Hello, World!");
+ * const compressed = await compress(data, { level: 6 });
+ * ```
+ */
+export async function compress(data, options = {}) {
+    const level = options.level ?? 6;
+    // Level 0 means no compression
+    if (level === 0) {
+        return data;
+    }
+    // Ensure zlib is loaded first
+    const zlib = await ensureZlib();
+    // Try Node.js zlib first (fastest, supports levels)
+    if (zlib && typeof zlib.deflateRawSync === "function") {
+        const result = zlib.deflateRawSync(Buffer.from(data), { level });
+        return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+    }
+    // Fall back to CompressionStream (browser/Node.js 17+)
+    if (typeof CompressionStream !== "undefined") {
+        return compressWithCompressionStream(data);
+    }
+    // No compression available - return original data
+    console.warn("No native compression available, returning uncompressed data");
+    return data;
+}
+/**
+ * Compress data synchronously using Node.js zlib
+ * Only available in Node.js environment
+ *
+ * @param data - Data to compress
+ * @param options - Compression options
+ * @returns Compressed data
+ * @throws Error if not in Node.js environment
+ */
+export function compressSync(data, options = {}) {
+    const level = options.level ?? 6;
+    if (level === 0) {
+        return data;
+    }
+    const zlib = getZlib();
+    if (!zlib || typeof zlib.deflateRawSync !== "function") {
+        throw new Error("Synchronous compression is only available in Node.js environment");
+    }
+    const result = zlib.deflateRawSync(Buffer.from(data), { level });
+    return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+}
+/**
+ * Compress using browser's native CompressionStream
+ * Uses "deflate-raw" format (required for ZIP files)
+ *
+ * Note: CompressionStream does not support compression level configuration
+ *
+ * @param data - Data to compress
+ * @returns Compressed data
+ */
+async function compressWithCompressionStream(data) {
+    const cs = new CompressionStream("deflate-raw");
+    const writer = cs.writable.getWriter();
+    const reader = cs.readable.getReader();
+    // Write data and close
+    writer.write(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+    writer.close();
+    // Read all compressed chunks
+    const chunks = [];
+    let totalLength = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        chunks.push(value);
+        totalLength += value.length;
+    }
+    // Combine chunks into single array
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return result;
+}
+/**
+ * Decompress data using the best available native method
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export async function decompress(data) {
+    // Ensure zlib is loaded first
+    const zlib = await ensureZlib();
+    // Try Node.js zlib first
+    if (zlib && typeof zlib.inflateRawSync === "function") {
+        const result = zlib.inflateRawSync(Buffer.from(data));
+        return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+    }
+    // Fall back to DecompressionStream
+    if (typeof DecompressionStream !== "undefined") {
+        return decompressWithDecompressionStream(data);
+    }
+    throw new Error("No native decompression available");
+}
+/**
+ * Decompress data synchronously using Node.js zlib
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ * @throws Error if not in Node.js environment
+ */
+export function decompressSync(data) {
+    const zlib = getZlib();
+    if (!zlib || typeof zlib.inflateRawSync !== "function") {
+        throw new Error("Synchronous decompression is only available in Node.js environment");
+    }
+    const result = zlib.inflateRawSync(Buffer.from(data));
+    return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+}
+/**
+ * Decompress using browser's native DecompressionStream
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+async function decompressWithDecompressionStream(data) {
+    const ds = new DecompressionStream("deflate-raw");
+    const writer = ds.writable.getWriter();
+    const reader = ds.readable.getReader();
+    // Write data and close
+    writer.write(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+    writer.close();
+    // Read all decompressed chunks
+    const chunks = [];
+    let totalLength = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        chunks.push(value);
+        totalLength += value.length;
+    }
+    // Combine chunks into single array
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return result;
+}

package/dist/esm/utils/zip/crc32.js

@@ -0,0 +1,116 @@
+/**
+ * CRC32 calculation utility for ZIP files
+ *
+ * - Node.js: Uses native zlib.crc32 (C++ implementation, ~100x faster)
+ * - Browser: Uses lookup table optimization
+ *
+ * The polynomial used is the standard CRC-32 IEEE 802.3:
+ * x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 + x^10 + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1
+ * Represented as 0xEDB88320 in reversed (LSB-first) form
+ */
+// Detect Node.js environment
+const isNode = typeof process !== "undefined" && process.versions?.node;
+// Lazy-loaded zlib module for Node.js
+let _zlib = null;
+let _zlibLoading = null;
+// Auto-initialize zlib in Node.js environment
+if (isNode) {
+    _zlibLoading = import("zlib")
+        .then(module => {
+        _zlib = module.default ?? module;
+        return _zlib;
+    })
+        .catch(() => {
+        _zlib = null;
+        return null;
+    });
+}
+/**
+ * Pre-computed CRC32 lookup table (256 entries)
+ * Generated using the standard polynomial 0xEDB88320
+ * Used as fallback when native zlib is not available
+ */
+const CRC32_TABLE = /* @__PURE__ */ (() => {
+    const table = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let crc = i;
+        for (let j = 0; j < 8; j++) {
+            crc = crc & 1 ? 0xedb88320 ^ (crc >>> 1) : crc >>> 1;
+        }
+        table[i] = crc;
+    }
+    return table;
+})();
+/**
+ * JavaScript fallback CRC32 implementation using lookup table
+ */
+function crc32JS(data) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < data.length; i++) {
+        crc = CRC32_TABLE[(crc ^ data[i]) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/**
+ * Calculate CRC32 checksum for the given data
+ * Uses native zlib.crc32 in Node.js for ~100x better performance
+ *
+ * @param data - Input data as Uint8Array or Buffer
+ * @returns CRC32 checksum as unsigned 32-bit integer
+ *
+ * @example
+ * ```ts
+ * const data = new TextEncoder().encode("Hello, World!");
+ * const checksum = crc32(data);
+ * console.log(checksum.toString(16)); // "ec4ac3d0"
+ * ```
+ */
+export function crc32(data) {
+    // Use native zlib.crc32 if available (Node.js)
+    if (_zlib && typeof _zlib.crc32 === "function") {
+        return _zlib.crc32(data) >>> 0;
+    }
+    // Fallback to JS implementation
+    return crc32JS(data);
+}
+/**
+ * Ensure zlib is loaded (for use before calling crc32)
+ */
+export async function ensureCrc32() {
+    if (_zlibLoading) {
+        await _zlibLoading;
+    }
+}
+/**
+ * Calculate CRC32 incrementally (useful for streaming)
+ * Call with initial crc of 0xffffffff, then finalize with crc32Finalize
+ * Note: This always uses JS implementation for consistency in streaming
+ *
+ * @param crc - Current CRC value (start with 0xffffffff)
+ * @param data - Input data chunk
+ * @returns Updated CRC value (not finalized)
+ *
+ * @example
+ * ```ts
+ * let crc = 0xffffffff;
+ * crc = crc32Update(crc, chunk1);
+ * crc = crc32Update(crc, chunk2);
+ * const checksum = crc32Finalize(crc);
+ * ```
+ */
+export function crc32Update(crc, data) {
+    for (let i = 0; i < data.length; i++) {
+        crc = CRC32_TABLE[(crc ^ data[i]) & 0xff] ^ (crc >>> 8);
+    }
+    return crc;
+}
+/**
+ * Finalize CRC32 calculation
+ * XOR with 0xffffffff and convert to unsigned 32-bit
+ *
+ * @param crc - CRC value from crc32Update
+ * @returns Final CRC32 checksum
+ */
+export function crc32Finalize(crc) {
+    return (crc ^ 0xffffffff) >>> 0;
+}

package/dist/esm/utils/zip/index.js

@@ -0,0 +1,55 @@
+/**
+ * Native ZIP utilities - Pure native implementation without third-party dependencies
+ *
+ * This module provides ZIP file creation using only native platform APIs:
+ * - Node.js: Uses native zlib module (C++ implementation, fastest)
+ * - Browser: Uses CompressionStream API (Chrome 80+, Firefox 113+, Safari 16.4+)
+ *
+ * Features:
+ * - Full ZIP format support (Local File Headers, Central Directory, EOCD)
+ * - DEFLATE compression (level 0-9 on Node.js, fixed level on browser)
+ * - STORE mode (no compression)
+ * - UTF-8 filename support
+ * - File comments and ZIP comments
+ * - Streaming API for large files
+ * - Both sync (Node.js) and async APIs
+ *
+ * @example Basic usage
+ * ```ts
+ * import { createZip } from "./utils/zip/index.js";
+ *
+ * const zipData = await createZip([
+ *   { name: "hello.txt", data: new TextEncoder().encode("Hello!") },
+ *   { name: "folder/nested.txt", data: new TextEncoder().encode("Nested file") }
+ * ], { level: 6 });
+ *
+ * // Write to file (Node.js)
+ * fs.writeFileSync("output.zip", zipData);
+ * ```
+ *
+ * @example Streaming usage
+ * ```ts
+ * import { ZipBuilder } from "./utils/zip/index.js";
+ *
+ * const builder = new ZipBuilder({ level: 1 });
+ *
+ * // Add files one by one
+ * const [header1, data1] = await builder.addFile({
+ *   name: "file1.txt",
+ *   data: new TextEncoder().encode("File 1 content")
+ * });
+ * stream.write(header1);
+ * stream.write(data1);
+ *
+ * // Finalize and write central directory
+ * for (const chunk of builder.finalize()) {
+ *   stream.write(chunk);
+ * }
+ * ```
+ */
+// CRC32 utilities
+export { crc32, crc32Update, crc32Finalize } from "./crc32.js";
+// Compression utilities
+export { compress, compressSync, decompress, decompressSync, hasNativeZlib, hasCompressionStream } from "./compress.js";
+// ZIP builder
+export { createZip, createZipSync, ZipBuilder } from "./zip-builder.js";