@cj-tech-master/excelts 4.0.0 → 4.0.1

package/dist/browser/modules/archive/compress.browser.js

@@ -0,0 +1,93 @@
+/**
+ * Browser compression utilities
+ *
+ * Primary: CompressionStream API (Chrome 103+, Firefox 113+, Safari 16.4+)
+ * Fallback: Pure JS DEFLATE implementation for older browsers
+ *
+ * Supported browsers with fallback:
+ * - Chrome >= 89
+ * - Firefox >= 102
+ * - Safari >= 14.1
+ * - Edge >= 89
+ */
+import { compressWithStream, decompressWithStream, hasDeflateRawCompressionStream, hasDeflateRawDecompressionStream, resolveCompressThresholdBytes } from "./compress.base.js";
+import { inflateRaw, deflateRawCompressed } from "./deflate-fallback.js";
+import { DEFAULT_COMPRESS_LEVEL } from "./defaults.js";
+// Re-export shared types
+export {};
+/**
+ * Check if CompressionStream is available in this environment.
+ *
+ * Note: Some environments may expose CompressionStream but not support
+ * the "deflate-raw" format that ZIP requires.
+ */
+export function hasCompressionStream() {
+    return typeof CompressionStream !== "undefined";
+}
+/**
+ * Compress data using browser's native CompressionStream or JS 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 ?? DEFAULT_COMPRESS_LEVEL;
+    const thresholdBytes = resolveCompressThresholdBytes(options);
+    // Level 0 means no compression
+    if (level === 0) {
+        return data;
+    }
+    // Use native CompressionStream only for larger inputs.
+    if (hasDeflateRawCompressionStream() && data.byteLength > thresholdBytes) {
+        return compressWithStream(data);
+    }
+    // Fallback to pure JS implementation
+    return deflateRawCompressed(data);
+}
+/**
+ * Compress data synchronously using pure JS implementation
+ *
+ * @param data - Data to compress
+ * @param options - Compression options
+ * @returns Compressed data
+ */
+export function compressSync(data, options = {}) {
+    const level = options.level ?? DEFAULT_COMPRESS_LEVEL;
+    // Level 0 means no compression
+    if (level === 0) {
+        return data;
+    }
+    // Pure JS implementation
+    return deflateRawCompressed(data);
+}
+/**
+ * Decompress data using browser's native DecompressionStream or JS fallback
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export async function decompress(data, options = {}) {
+    const thresholdBytes = resolveCompressThresholdBytes(options);
+    // Use native DecompressionStream only for larger inputs.
+    if (hasDeflateRawDecompressionStream() && data.byteLength > thresholdBytes) {
+        return decompressWithStream(data);
+    }
+    // Fallback to pure JS implementation
+    return inflateRaw(data);
+}
+/**
+ * Decompress data synchronously using pure JS implementation
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export function decompressSync(data) {
+    return inflateRaw(data);
+}

package/dist/browser/modules/archive/compress.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Node.js compression utilities using native zlib
+ *
+ * Uses zlib module (C++ implementation, fastest) with "deflate-raw" format
+ * (raw DEFLATE without zlib header/trailer, required for ZIP files)
+ */
+export { type CompressOptions, hasCompressionStream } from "@archive/compress.base";
+import type { CompressOptions } from "@archive/compress.base";
+/**
+ * Compress data using Node.js native zlib
+ *
+ * @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 declare function compress(data: Uint8Array, options?: CompressOptions): Promise<Uint8Array>;
+/**
+ * Compress data synchronously using Node.js zlib
+ *
+ * @param data - Data to compress
+ * @param options - Compression options
+ * @returns Compressed data
+ */
+export declare function compressSync(data: Uint8Array, options?: CompressOptions): Uint8Array;
+/**
+ * Decompress data using Node.js native zlib
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export declare function decompress(data: Uint8Array, options?: CompressOptions): Promise<Uint8Array>;
+/**
+ * Decompress data synchronously using Node.js zlib
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export declare function decompressSync(data: Uint8Array): Uint8Array;

package/dist/browser/modules/archive/compress.js

@@ -0,0 +1,86 @@
+/**
+ * Node.js compression utilities using native zlib
+ *
+ * Uses zlib module (C++ implementation, fastest) with "deflate-raw" format
+ * (raw DEFLATE without zlib header/trailer, required for ZIP files)
+ */
+import { promisify } from "util";
+import * as zlib from "zlib";
+import { DEFAULT_COMPRESS_LEVEL } from "./defaults.js";
+// Re-export shared types and utilities
+export { hasCompressionStream } from "./compress.base.js";
+function uint8ArrayToBufferView(data) {
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+}
+const deflateRawAsync = promisify(zlib.deflateRaw);
+const inflateRawAsync = promisify(zlib.inflateRaw);
+import { resolveCompressThresholdBytes } from "./compress.base.js";
+/**
+ * Compress data using Node.js native zlib
+ *
+ * @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 ?? DEFAULT_COMPRESS_LEVEL;
+    const thresholdBytes = resolveCompressThresholdBytes(options);
+    // Level 0 means no compression
+    if (level === 0) {
+        return data;
+    }
+    // Small-input fast path: avoid threadpool overhead.
+    if (data.byteLength <= thresholdBytes) {
+        const result = zlib.deflateRawSync(uint8ArrayToBufferView(data), { level });
+        return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+    }
+    const result = await deflateRawAsync(uint8ArrayToBufferView(data), { level });
+    return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+}
+/**
+ * Compress data synchronously using Node.js zlib
+ *
+ * @param data - Data to compress
+ * @param options - Compression options
+ * @returns Compressed data
+ */
+export function compressSync(data, options = {}) {
+    const level = options.level ?? DEFAULT_COMPRESS_LEVEL;
+    if (level === 0) {
+        return data;
+    }
+    const result = zlib.deflateRawSync(uint8ArrayToBufferView(data), { level });
+    return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+}
+/**
+ * Decompress data using Node.js native zlib
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export async function decompress(data, options = {}) {
+    const thresholdBytes = resolveCompressThresholdBytes(options);
+    // Small-input fast path: avoid threadpool overhead.
+    if (data.byteLength <= thresholdBytes) {
+        const result = zlib.inflateRawSync(uint8ArrayToBufferView(data));
+        return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+    }
+    const result = await inflateRawAsync(uint8ArrayToBufferView(data));
+    return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+}
+/**
+ * Decompress data synchronously using Node.js zlib
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export function decompressSync(data) {
+    const result = zlib.inflateRawSync(uint8ArrayToBufferView(data));
+    return new Uint8Array(result.buffer, result.byteOffset, result.byteLength);
+}

package/dist/browser/modules/archive/crc32.base.d.ts

@@ -0,0 +1,25 @@
+/**
+ * CRC32 calculation core (shared between Node.js and browser).
+ *
+ * Implements CRC-32 IEEE 802.3 using the reversed polynomial 0xEDB88320.
+ *
+ * Notes:
+ * - Uses a lazily-initialized 256-entry lookup table.
+ * - Exposes an incremental update API for streaming use cases.
+ */
+/**
+ * Update a CRC32 value with a new data chunk.
+ *
+ * The CRC state here is the non-finalized (inverted) form:
+ * - initial state: 0xffffffff
+ * - finalize: xor with 0xffffffff
+ */
+export declare function crc32UpdateJS(crc: number, data: Uint8Array): number;
+/**
+ * Finalize CRC32 calculation.
+ */
+export declare function crc32Finalize(crc: number): number;
+/**
+ * Compute CRC32 for the full input using the JS table implementation.
+ */
+export declare function crc32JS(data: Uint8Array): number;

package/dist/browser/modules/archive/crc32.base.js

@@ -0,0 +1,51 @@
+/**
+ * CRC32 calculation core (shared between Node.js and browser).
+ *
+ * Implements CRC-32 IEEE 802.3 using the reversed polynomial 0xEDB88320.
+ *
+ * Notes:
+ * - Uses a lazily-initialized 256-entry lookup table.
+ * - Exposes an incremental update API for streaming use cases.
+ */
+let _crc32Table = null;
+function getCrc32Table() {
+    if (_crc32Table) {
+        return _crc32Table;
+    }
+    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;
+    }
+    _crc32Table = table;
+    return table;
+}
+/**
+ * Update a CRC32 value with a new data chunk.
+ *
+ * The CRC state here is the non-finalized (inverted) form:
+ * - initial state: 0xffffffff
+ * - finalize: xor with 0xffffffff
+ */
+export function crc32UpdateJS(crc, data) {
+    const table = getCrc32Table();
+    for (let i = 0; i < data.length; i++) {
+        crc = table[(crc ^ data[i]) & 0xff] ^ (crc >>> 8);
+    }
+    return crc;
+}
+/**
+ * Finalize CRC32 calculation.
+ */
+export function crc32Finalize(crc) {
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/**
+ * Compute CRC32 for the full input using the JS table implementation.
+ */
+export function crc32JS(data) {
+    return crc32Finalize(crc32UpdateJS(0xffffffff, data));
+}

package/dist/browser/modules/archive/crc32.browser.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CRC32 calculation utility for ZIP files (Browser version)
+ *
+ * Uses lookup table optimization - no Node.js dependencies
+ *
+ * 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
+ */
+export { crc32JS as crc32, crc32UpdateJS as crc32Update, crc32Finalize } from "@archive/crc32.base";
+/**
+ * Ensure CRC32 is ready (no-op in browser, for API compatibility)
+ */
+export declare function ensureCrc32(): Promise<void>;
+/**
+ * Calculate CRC32 incrementally (useful for streaming)
+ * Call with initial crc of 0xffffffff, then finalize with crc32Finalize
+ *
+ * @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);
+ * ```
+ */

package/dist/browser/modules/archive/crc32.browser.js

@@ -0,0 +1,32 @@
+/**
+ * CRC32 calculation utility for ZIP files (Browser version)
+ *
+ * Uses lookup table optimization - no Node.js dependencies
+ *
+ * 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
+ */
+export { crc32JS as crc32, crc32UpdateJS as crc32Update, crc32Finalize } from "./crc32.base.js";
+/**
+ * Ensure CRC32 is ready (no-op in browser, for API compatibility)
+ */
+export async function ensureCrc32() {
+    // No-op in browser
+}
+/**
+ * Calculate CRC32 incrementally (useful for streaming)
+ * Call with initial crc of 0xffffffff, then finalize with crc32Finalize
+ *
+ * @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);
+ * ```
+ */

package/dist/browser/modules/archive/crc32.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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
+ */
+import { crc32Finalize } from "@archive/crc32.base";
+/**
+ * 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 declare function crc32(data: Uint8Array): number;
+/**
+ * Ensure zlib is loaded (for use before calling crc32)
+ */
+export declare function ensureCrc32(): Promise<void>;
+/**
+ * Calculate CRC32 incrementally (useful for streaming)
+ * Call with initial crc of 0xffffffff, then finalize with crc32Finalize
+ * In Node.js, this uses native zlib.crc32 when available for performance.
+ * The internal CRC state remains the same as the JS table implementation:
+ * - initial state: 0xffffffff
+ * - finalize: xor with 0xffffffff
+ *
+ * @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 declare function crc32Update(crc: number, data: Uint8Array): number;
+/**
+ * Finalize CRC32 calculation
+ * XOR with 0xffffffff and convert to unsigned 32-bit
+ *
+ * @param crc - CRC value from crc32Update
+ * @returns Final CRC32 checksum
+ */
+export { crc32Finalize };

package/dist/browser/modules/archive/crc32.js

@@ -0,0 +1,97 @@
+/**
+ * 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
+ */
+import { isNode } from "../../utils/env.js";
+import { crc32JS, crc32UpdateJS, crc32Finalize } from "./crc32.base.js";
+// 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;
+    });
+}
+/**
+ * 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
+ * In Node.js, this uses native zlib.crc32 when available for performance.
+ * The internal CRC state remains the same as the JS table implementation:
+ * - initial state: 0xffffffff
+ * - finalize: xor with 0xffffffff
+ *
+ * @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) {
+    // If available, use native zlib.crc32 but preserve our internal state shape.
+    // zlib.crc32 returns a finalized CRC value and can accept the previous finalized
+    // CRC as the second parameter (chainable). Our internal state is the inverted
+    // (non-finalized) CRC, so convert with xor before/after.
+    if (_zlib && typeof _zlib.crc32 === "function") {
+        const prevFinal = (crc ^ 0xffffffff) >>> 0;
+        const nextFinal = _zlib.crc32(data, prevFinal) >>> 0;
+        return (nextFinal ^ 0xffffffff) >>> 0;
+    }
+    return crc32UpdateJS(crc, data);
+}
+/**
+ * Finalize CRC32 calculation
+ * XOR with 0xffffffff and convert to unsigned 32-bit
+ *
+ * @param crc - CRC value from crc32Update
+ * @returns Final CRC32 checksum
+ */
+export { crc32Finalize };

package/dist/browser/modules/archive/defaults.d.ts

@@ -0,0 +1,4 @@
+import type { ZipTimestampMode } from "@archive/utils/timestamps";
+export declare const DEFAULT_COMPRESS_LEVEL = 6;
+export declare const DEFAULT_ZIP_LEVEL = 6;
+export declare const DEFAULT_ZIP_TIMESTAMPS: ZipTimestampMode;

package/dist/browser/modules/archive/defaults.js

@@ -0,0 +1,3 @@
+export const DEFAULT_COMPRESS_LEVEL = 6;
+export const DEFAULT_ZIP_LEVEL = 6;
+export const DEFAULT_ZIP_TIMESTAMPS = "dos+utc";

package/dist/browser/modules/archive/deflate-fallback.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Pure JavaScript DEFLATE implementation for browsers without CompressionStream support
+ *
+ * This fallback supports:
+ * - Decompression: Full DEFLATE decompression (RFC 1951)
+ * - Compression: STORE mode only (no compression, but valid DEFLATE format)
+ *
+ * Used automatically when CompressionStream with "deflate-raw" is unavailable:
+ * - Firefox < 113
+ * - Safari < 16.4
+ * - Chrome < 103
+ */
+/**
+ * Decompress DEFLATE data (raw format, no zlib header)
+ *
+ * @param data - Compressed data in deflate-raw format
+ * @returns Decompressed data
+ */
+export declare function inflateRaw(data: Uint8Array): Uint8Array;
+/**
+ * Compress data using DEFLATE STORE mode (no compression)
+ *
+ * This creates valid DEFLATE data but without actual compression.
+ * Files will be larger but this works on all browsers.
+ *
+ * @param data - Data to "compress"
+ * @returns DEFLATE-formatted data (stored, not compressed)
+ */
+export declare function deflateRawStore(data: Uint8Array): Uint8Array;
+/**
+ * Compress data using DEFLATE with fixed Huffman codes
+ *
+ * This provides real compression using LZ77 + fixed Huffman codes.
+ * Not as efficient as full DEFLATE but much better than STORE mode.
+ *
+ * @param data - Data to compress
+ * @returns Compressed data in deflate-raw format
+ */
+export declare function deflateRawCompressed(data: Uint8Array): Uint8Array;