@cj-tech-master/excelts 1.4.2 → 1.4.4

package/dist/esm/utils/sheet-utils.js

@@ -4,30 +4,140 @@
  */
 import { Workbook } from "../doc/workbook.js";
 import { colCache } from "./col-cache.js";
-import { dateToExcel } from "./utils.js";
 import { format as cellFormat } from "./cell-format.js";
+/**
+ * Convert a Date object back to Excel serial number without timezone issues.
+ * This reverses the excelToDate conversion exactly.
+ * excelToDate uses: new Date(Math.round((v - 25569) * 24 * 3600 * 1000))
+ * So we reverse it: (date.getTime() / (24 * 3600 * 1000)) + 25569
+ */
+function dateToExcelSerial(d) {
+    return d.getTime() / (24 * 3600 * 1000) + 25569;
+}
+/**
+ * Check if format is a pure time format (no date components like y, m for month, d)
+ * Time formats only contain: h, m (minutes in time context), s, AM/PM
+ * Excludes elapsed time formats like [h]:mm:ss which should keep full serial number
+ */
+function isTimeOnlyFormat(fmt) {
+    // Remove quoted strings first
+    const cleaned = fmt.replace(/"[^"]*"/g, "");
+    // Elapsed time formats [h], [m], [s] should NOT be treated as time-only
+    // They need the full serial number to calculate total hours/minutes/seconds
+    if (/\[[hms]\]/i.test(cleaned)) {
+        return false;
+    }
+    // Remove color codes and conditions (but we already checked for [h], [m], [s])
+    const withoutBrackets = cleaned.replace(/\[[^\]]*\]/g, "");
+    // Check if it has time components (h, s, or AM/PM)
+    const hasTimeComponents = /[hs]/i.test(withoutBrackets) || /AM\/PM|A\/P/i.test(withoutBrackets);
+    // Check if it has date components (y, d, or m not adjacent to h/s which would make it minutes)
+    // In Excel: "m" after "h" or before "s" is minutes, otherwise it's month
+    const hasDateComponents = /[yd]/i.test(withoutBrackets);
+    // If it has time but no date components, it's a time-only format
+    // Also check for standalone 'm' that's not minutes (not near h or s)
+    if (hasDateComponents) {
+        return false;
+    }
+    // Check for month 'm' - if 'm' exists but not in h:m or m:s context, it's a date format
+    if (/m/i.test(withoutBrackets) && !hasTimeComponents) {
+        return false;
+    }
+    return hasTimeComponents;
+}
+/**
+ * Check if format is a date format (contains y, d, or month-m)
+ * Used to determine if dateFormat override should be applied
+ */
+function isDateFormat(fmt) {
+    // Remove quoted strings first
+    const cleaned = fmt.replace(/"[^"]*"/g, "");
+    // Elapsed time formats [h], [m], [s] are NOT date formats
+    if (/\[[hms]\]/i.test(cleaned)) {
+        return false;
+    }
+    // Remove color codes and conditions
+    const withoutBrackets = cleaned.replace(/\[[^\]]*\]/g, "");
+    // Check for year or day components
+    if (/[yd]/i.test(withoutBrackets)) {
+        return true;
+    }
+    // Check for month 'm' - only if it's NOT in time context (not near h or s)
+    // In Excel: "m" after "h" or before "s" is minutes, otherwise it's month
+    if (/m/i.test(withoutBrackets)) {
+        const hasTimeComponents = /[hs]/i.test(withoutBrackets) || /AM\/PM|A\/P/i.test(withoutBrackets);
+        // If no time components, 'm' is month
+        if (!hasTimeComponents) {
+            return true;
+        }
+        // If has time components, need to check if 'm' is month or minutes
+        // Simplified: if format has both date-like and time-like patterns, consider it a date format
+        // e.g., "m/d/yy h:mm" - has 'm' as month and 'mm' as minutes
+    }
+    return false;
+}
+/**
+ * Format a value (Date, number, boolean, string) according to the given format
+ * Handles timezone-independent conversion for Date objects
+ * @param value - The value to format
+ * @param fmt - The format string to use
+ * @param dateFormat - Optional override format for date values (not applied to time or elapsed time formats)
+ */
+function formatValue(value, fmt, dateFormat) {
+    // Date object - convert back to Excel serial number
+    if (value instanceof Date) {
+        let serial = dateToExcelSerial(value);
+        // For time-only formats, use only the fractional part (time portion)
+        if (isTimeOnlyFormat(fmt)) {
+            serial = serial % 1;
+            if (serial < 0) {
+                serial += 1;
+            }
+            return cellFormat(fmt, serial);
+        }
+        // Only apply dateFormat override to actual date formats
+        // (not elapsed time formats like [h]:mm:ss)
+        const actualFmt = dateFormat && isDateFormat(fmt) ? dateFormat : fmt;
+        return cellFormat(actualFmt, serial);
+    }
+    // Number/Boolean/String - let cellFormat handle it
+    return cellFormat(fmt, value);
+}
 /**
  * Get formatted display text for a cell value
  * Returns the value formatted according to the cell's numFmt
- * This matches Excel's display exactly
+ * This matches Excel's display exactly (timezone-independent)
+ * @param cell - The cell to get display text for
+ * @param dateFormat - Optional override format for date values
  */
-function getCellDisplayText(cell) {
+function getCellDisplayText(cell, dateFormat) {
     const value = cell.value;
     const fmt = cell.numFmt || "General";
     // Null/undefined
     if (value == null) {
         return "";
     }
-    // Date object - convert to Excel serial number
-    if (value instanceof Date) {
-        const serial = dateToExcel(value, false);
-        return cellFormat(fmt, serial);
+    // Date/Number/Boolean/String - format directly
+    if (value instanceof Date ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "string") {
+        return formatValue(value, fmt, dateFormat);
     }
-    // Number/Boolean/String - let cellFormat handle it
-    if (typeof value === "number" || typeof value === "boolean" || typeof value === "string") {
-        return cellFormat(fmt, value);
+    // Formula type - use the result value
+    if (typeof value === "object" && "formula" in value) {
+        const result = value.result;
+        if (result == null) {
+            return "";
+        }
+        if (result instanceof Date ||
+            typeof result === "number" ||
+            typeof result === "boolean" ||
+            typeof result === "string") {
+            return formatValue(result, fmt, dateFormat);
+        }
     }
-    // Fallback to cell.text for other types (rich text, hyperlink, error, formula, etc.)
+    // Fallback to cell.text for other types (rich text, hyperlink, error, etc.)
     return cell.text;
 }
 // =============================================================================
@@ -263,7 +373,7 @@ export function sheetToJson(worksheet, opts) {
             let isEmpty = true;
             for (let col = startCol; col <= endCol; col++) {
                 const cell = worksheet.getCell(row, col);
-                const val = o.raw === false ? getCellDisplayText(cell).trim() : cell.value;
+                const val = o.raw === false ? getCellDisplayText(cell, o.dateFormat).trim() : cell.value;
                 if (val != null && val !== "") {
                     rowData[col - startCol] = val;
                     isEmpty = false;
@@ -291,7 +401,7 @@ export function sheetToJson(worksheet, opts) {
             let isEmpty = true;
             for (let col = startCol; col <= endCol; col++) {
                 const cell = worksheet.getCell(row, col);
-                const val = o.raw === false ? getCellDisplayText(cell).trim() : cell.value;
+                const val = o.raw === false ? getCellDisplayText(cell, o.dateFormat).trim() : cell.value;
                 const key = encodeCol(col - 1); // 0-indexed for encodeCol
                 if (val != null && val !== "") {
                     rowData[key] = val;
@@ -318,7 +428,7 @@ export function sheetToJson(worksheet, opts) {
                 const colIdx = col - startCol;
                 const key = headerOpt[colIdx] ?? `__EMPTY_${colIdx}`;
                 const cell = worksheet.getCell(row, col);
-                const val = o.raw === false ? getCellDisplayText(cell).trim() : cell.value;
+                const val = o.raw === false ? getCellDisplayText(cell, o.dateFormat).trim() : cell.value;
                 if (val != null && val !== "") {
                     rowData[key] = val;
                     isEmpty = false;
@@ -360,7 +470,7 @@ export function sheetToJson(worksheet, opts) {
         let isEmpty = true;
         for (let col = startCol; col <= endCol; col++) {
             const cell = worksheet.getCell(row, col);
-            const val = o.raw === false ? getCellDisplayText(cell).trim() : cell.value;
+            const val = o.raw === false ? getCellDisplayText(cell, o.dateFormat).trim() : cell.value;
             const key = headers[col - startCol];
             if (val != null && val !== "") {
                 rowData[key] = val;

package/dist/esm/utils/unzip/extract.js

@@ -0,0 +1,160 @@
+/**
+ * Simple ZIP extraction utilities
+ * Provides easy-to-use Promise-based API for extracting ZIP files
+ */
+import { Readable } from "stream";
+import { createParse } from "./parse.js";
+/**
+ * Extract all files from a ZIP buffer
+ *
+ * @param zipData - ZIP file data as Buffer or Uint8Array
+ * @returns Map of file paths to their content
+ *
+ * @example
+ * ```ts
+ * import { extractAll } from "./utils/unzip/extract.js";
+ *
+ * const zipData = fs.readFileSync("archive.zip");
+ * const files = await extractAll(zipData);
+ *
+ * for (const [path, file] of files) {
+ *   console.log(`${path}: ${file.data.length} bytes`);
+ * }
+ * ```
+ */
+export async function extractAll(zipData) {
+    const files = new Map();
+    const buffer = Buffer.isBuffer(zipData) ? zipData : Buffer.from(zipData);
+    const parse = createParse({ forceStream: true });
+    const stream = Readable.from([buffer]);
+    stream.pipe(parse);
+    for await (const entry of parse) {
+        const zipEntry = entry;
+        const isDirectory = zipEntry.type === "Directory";
+        if (isDirectory) {
+            files.set(zipEntry.path, {
+                path: zipEntry.path,
+                data: Buffer.alloc(0),
+                isDirectory: true,
+                size: 0
+            });
+            zipEntry.autodrain();
+        }
+        else {
+            const data = await zipEntry.buffer();
+            files.set(zipEntry.path, {
+                path: zipEntry.path,
+                data,
+                isDirectory: false,
+                size: data.length
+            });
+        }
+    }
+    return files;
+}
+/**
+ * Extract a single file from a ZIP buffer
+ *
+ * @param zipData - ZIP file data as Buffer or Uint8Array
+ * @param filePath - Path of the file to extract
+ * @returns File content as Buffer, or null if not found
+ *
+ * @example
+ * ```ts
+ * import { extractFile } from "./utils/unzip/extract.js";
+ *
+ * const zipData = fs.readFileSync("archive.zip");
+ * const content = await extractFile(zipData, "readme.txt");
+ * if (content) {
+ *   console.log(content.toString("utf-8"));
+ * }
+ * ```
+ */
+export async function extractFile(zipData, filePath) {
+    const buffer = Buffer.isBuffer(zipData) ? zipData : Buffer.from(zipData);
+    const parse = createParse({ forceStream: true });
+    const stream = Readable.from([buffer]);
+    stream.pipe(parse);
+    for await (const entry of parse) {
+        const zipEntry = entry;
+        if (zipEntry.path === filePath) {
+            if (zipEntry.type === "Directory") {
+                return Buffer.alloc(0);
+            }
+            return zipEntry.buffer();
+        }
+        zipEntry.autodrain();
+    }
+    return null;
+}
+/**
+ * List all file paths in a ZIP buffer (without extracting content)
+ *
+ * @param zipData - ZIP file data as Buffer or Uint8Array
+ * @returns Array of file paths
+ *
+ * @example
+ * ```ts
+ * import { listFiles } from "./utils/unzip/extract.js";
+ *
+ * const zipData = fs.readFileSync("archive.zip");
+ * const paths = await listFiles(zipData);
+ * console.log(paths); // ["file1.txt", "folder/file2.txt", ...]
+ * ```
+ */
+export async function listFiles(zipData) {
+    const paths = [];
+    const buffer = Buffer.isBuffer(zipData) ? zipData : Buffer.from(zipData);
+    const parse = createParse({ forceStream: true });
+    const stream = Readable.from([buffer]);
+    stream.pipe(parse);
+    for await (const entry of parse) {
+        const zipEntry = entry;
+        paths.push(zipEntry.path);
+        zipEntry.autodrain();
+    }
+    return paths;
+}
+/**
+ * Iterate over ZIP entries with a callback (memory efficient for large ZIPs)
+ *
+ * @param zipData - ZIP file data as Buffer or Uint8Array
+ * @param callback - Async callback for each entry, return false to stop iteration
+ *
+ * @example
+ * ```ts
+ * import { forEachEntry } from "./utils/unzip/extract.js";
+ *
+ * await forEachEntry(zipData, async (path, getData) => {
+ *   if (path.endsWith(".xml")) {
+ *     const content = await getData();
+ *     console.log(content.toString("utf-8"));
+ *   }
+ *   return true; // continue iteration
+ * });
+ * ```
+ */
+export async function forEachEntry(zipData, callback) {
+    const buffer = Buffer.isBuffer(zipData) ? zipData : Buffer.from(zipData);
+    const parse = createParse({ forceStream: true });
+    const stream = Readable.from([buffer]);
+    stream.pipe(parse);
+    for await (const entry of parse) {
+        const zipEntry = entry;
+        let dataPromise = null;
+        const getData = () => {
+            if (!dataPromise) {
+                dataPromise = zipEntry.buffer();
+            }
+            return dataPromise;
+        };
+        const shouldContinue = await callback(zipEntry.path, getData, zipEntry);
+        // If callback didn't read data, drain it
+        if (!dataPromise) {
+            zipEntry.autodrain();
+        }
+        if (shouldContinue === false) {
+            break;
+        }
+    }
+}

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

@@ -10,3 +10,5 @@ export { bufferStream } from "./buffer-stream.js";
 export { parse as parseBuffer } from "./parse-buffer.js";
 export { parseDateTime } from "./parse-datetime.js";
 export { parseExtraField } from "./parse-extra-field.js";
+// Simple extraction API
+export { extractAll, extractFile, listFiles, forEachEntry } from "./extract.js";

package/dist/esm/utils/xml-stream.js

@@ -4,6 +4,8 @@ const OPEN_ANGLE = "<";
 const CLOSE_ANGLE = ">";
 const OPEN_ANGLE_SLASH = "</";
 const CLOSE_SLASH_ANGLE = "/>";
+// Chunk size for periodic consolidation (reduces final join overhead)
+const CHUNK_SIZE = 10000;
 function pushAttribute(xml, name, value) {
     xml.push(` ${name}="${xmlEncode(value.toString())}"`);
 }
@@ -21,15 +23,23 @@ function pushAttributes(xml, attributes) {
 class XmlStream {
     constructor() {
         this._xml = [];
+        this._chunks = [];
         this._stack = [];
         this._rollbacks = [];
     }
+    _consolidate() {
+        // Periodically join small strings into larger chunks to reduce final join overhead
+        if (this._xml.length >= CHUNK_SIZE) {
+            this._chunks.push(this._xml.join(""));
+            this._xml = [];
+        }
+    }
     get tos() {
         return this._stack.length ? this._stack[this._stack.length - 1] : undefined;
     }
     get cursor() {
         // handy way to track whether anything has been added
-        return this._xml.length;
+        return this._chunks.length * CHUNK_SIZE + this._xml.length;
     }
     openXml(docAttributes) {
         const xml = this._xml;
@@ -96,6 +106,7 @@ class XmlStream {
         }
         this.open = false;
         this.leaf = false;
+        this._consolidate();
     }
     leafNode(name, attributes, text) {
         this.openNode(name, attributes);
@@ -115,7 +126,8 @@ class XmlStream {
             xml: this._xml.length,
             stack: this._stack.length,
             leaf: this.leaf,
-            open: this.open
+            open: this.open,
+            chunksLength: this._chunks.length
         });
         return this.cursor;
     }
@@ -130,12 +142,22 @@ class XmlStream {
         if (this._stack.length > r.stack) {
             this._stack.splice(r.stack, this._stack.length - r.stack);
         }
+        if (this._chunks.length > r.chunksLength) {
+            this._chunks.splice(r.chunksLength, this._chunks.length - r.chunksLength);
+        }
         this.leaf = r.leaf;
         this.open = r.open;
     }
     get xml() {
         this.closeAll();
-        return this._xml.join("");
+        // Join chunks first, then remaining xml array
+        if (this._chunks.length === 0) {
+            return this._xml.join("");
+        }
+        if (this._xml.length > 0) {
+            this._chunks.push(this._xml.join(""));
+        }
+        return this._chunks.join("");
     }
 }
 XmlStream.StdDocAttributes = {

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;
+}