@cj-tech-master/excelts 3.1.0 → 4.0.0

package/dist/esm/modules/archive/utils/timestamps.js

@@ -0,0 +1,48 @@
+import { buildExtendedTimestampExtraFieldFromDate, parseExtendedTimestampMtimeUnixSeconds } from "./zip-extra.js";
+/**
+ * DOS date/time helpers for ZIP files.
+ */
+/**
+ * Convert Date to DOS time/date fields.
+ *
+ * Note: uses local time fields (getHours/getMinutes/getSeconds),
+ * which matches common ZIP writer behavior.
+ */
+export function dateToDos(date) {
+    const dosTime = ((date.getHours() & 0x1f) << 11) |
+        ((date.getMinutes() & 0x3f) << 5) |
+        ((date.getSeconds() >> 1) & 0x1f);
+    const dosDate = (((date.getFullYear() - 1980) & 0x7f) << 9) |
+        (((date.getMonth() + 1) & 0x0f) << 5) |
+        (date.getDate() & 0x1f);
+    return [dosTime, dosDate];
+}
+/**
+ * Parse DOS date/time to JS Date.
+ */
+export function parseDosDateTimeUTC(date, time) {
+    const day = date & 0x1f;
+    const month = (date >> 5) & 0x0f;
+    const year = ((date >> 9) & 0x7f) + 1980;
+    const seconds = time ? (time & 0x1f) * 2 : 0;
+    const minutes = time ? (time >> 5) & 0x3f : 0;
+    const hours = time ? time >> 11 : 0;
+    return new Date(Date.UTC(year, month - 1, day, hours, minutes, seconds));
+}
+export function resolveZipLastModifiedDateFromUnixSeconds(dosDate, dosTime, mtimeUnixSeconds) {
+    if (mtimeUnixSeconds === undefined) {
+        return parseDosDateTimeUTC(dosDate, dosTime);
+    }
+    return new Date(mtimeUnixSeconds * 1000);
+}
+export function resolveZipLastModifiedDateFromExtraField(dosDate, dosTime, extraField) {
+    const unixSeconds = parseExtendedTimestampMtimeUnixSeconds(extraField);
+    return resolveZipLastModifiedDateFromUnixSeconds(dosDate, dosTime, unixSeconds);
+}
+export function buildZipTimestampExtraField(modTime, mode) {
+    return mode === "dos+utc" ? buildExtendedTimestampExtraFieldFromDate(modTime) : new Uint8Array(0);
+}
+export function dateToZipDos(modTime) {
+    const [dosTime, dosDate] = dateToDos(modTime);
+    return { dosTime, dosDate };
+}

package/dist/esm/modules/archive/utils/zip-extra-fields.js

@@ -0,0 +1,72 @@
+/**
+ * ZIP extra field parsing helpers.
+ *
+ * Kept standalone so both streaming parser (`parse.base.ts`) and buffer parser
+ * (`zip-parser.ts`) can share ZIP64 + Info-ZIP timestamp handling.
+ */
+import { parseExtendedTimestampMtimeUnixSeconds } from "./zip-extra.js";
+function readUint64LE(view, offset) {
+    // Convert to Number via 2x Uint32 to avoid BigInt requirements.
+    const low = view.getUint32(offset, true);
+    const high = view.getUint32(offset + 4, true);
+    return high * 0x100000000 + low;
+}
+export function parseZipExtraFields(extraField, vars) {
+    const extra = {};
+    if (extraField.length < 4) {
+        return extra;
+    }
+    const view = new DataView(extraField.buffer, extraField.byteOffset, extraField.byteLength);
+    let offset = 0;
+    while (offset + 4 <= extraField.length) {
+        const signature = view.getUint16(offset, true);
+        const partSize = view.getUint16(offset + 2, true);
+        const dataStart = offset + 4;
+        const dataEnd = dataStart + partSize;
+        if (dataEnd > extraField.length) {
+            break;
+        }
+        if (signature === 0x0001) {
+            // ZIP64 extended information.
+            // Field presence and order depends on which values are 0xFFFFFFFF in the header.
+            let cursor = dataStart;
+            if (vars.uncompressedSize === 0xffffffff && cursor + 8 <= dataEnd) {
+                extra.uncompressedSize = readUint64LE(view, cursor);
+                cursor += 8;
+            }
+            if (vars.compressedSize === 0xffffffff && cursor + 8 <= dataEnd) {
+                extra.compressedSize = readUint64LE(view, cursor);
+                cursor += 8;
+            }
+            if (vars.offsetToLocalFileHeader === 0xffffffff && cursor + 8 <= dataEnd) {
+                extra.offsetToLocalFileHeader = readUint64LE(view, cursor);
+            }
+        }
+        else if (signature === 0x5455) {
+            // Fast-path parse for Info-ZIP extended timestamp (mtime only).
+            if (partSize >= 1) {
+                const flags = extraField[dataStart];
+                if ((flags & 0x01) !== 0 && partSize >= 5) {
+                    extra.mtimeUnixSeconds = view.getUint32(dataStart + 1, true) >>> 0;
+                }
+                else {
+                    const unixSeconds = parseExtendedTimestampMtimeUnixSeconds(extraField.subarray(offset, dataEnd));
+                    if (unixSeconds !== undefined) {
+                        extra.mtimeUnixSeconds = unixSeconds;
+                    }
+                }
+            }
+        }
+        offset = dataEnd;
+    }
+    if (vars.compressedSize === 0xffffffff) {
+        vars.compressedSize = extra.compressedSize;
+    }
+    if (vars.uncompressedSize === 0xffffffff) {
+        vars.uncompressedSize = extra.uncompressedSize;
+    }
+    if (vars.offsetToLocalFileHeader === 0xffffffff) {
+        vars.offsetToLocalFileHeader = extra.offsetToLocalFileHeader;
+    }
+    return extra;
+}

package/dist/esm/modules/archive/utils/zip-extra.js

@@ -0,0 +1,68 @@
+const EXTENDED_TIMESTAMP_ID = 0x5455;
+function clampUint32(value) {
+    if (!Number.isFinite(value)) {
+        return 0;
+    }
+    if (value <= 0) {
+        return 0;
+    }
+    // 0xFFFFFFFF fits JS safe integer.
+    if (value >= 0xffffffff) {
+        return 0xffffffff;
+    }
+    return value >>> 0;
+}
+export function unixSecondsFromDate(date) {
+    return clampUint32(Math.floor(date.getTime() / 1000));
+}
+/**
+ * Build Info-ZIP "Extended Timestamp" extra field (0x5455).
+ * We write only mtime (UTC, Unix seconds) to minimize size.
+ *
+ * Layout:
+ * - Header ID: 2 bytes (0x5455)
+ * - Data size: 2 bytes
+ * - Flags: 1 byte (bit0 = mtime)
+ * - mtime: 4 bytes (Unix seconds)
+ */
+export function buildExtendedTimestampExtraFieldFromUnixSeconds(unixSeconds) {
+    const ts = clampUint32(unixSeconds);
+    // flags(1) + mtime(4)
+    const payloadSize = 5;
+    const out = new Uint8Array(4 + payloadSize);
+    const view = new DataView(out.buffer);
+    view.setUint16(0, EXTENDED_TIMESTAMP_ID, true);
+    view.setUint16(2, payloadSize, true);
+    out[4] = 0x01; // mtime present
+    view.setUint32(5, ts, true);
+    return out;
+}
+export function buildExtendedTimestampExtraFieldFromDate(date) {
+    return buildExtendedTimestampExtraFieldFromUnixSeconds(unixSecondsFromDate(date));
+}
+/**
+ * Parse Info-ZIP "Extended Timestamp" extra field (0x5455) and return mtime.
+ * Returns Unix seconds (UTC) if present.
+ */
+export function parseExtendedTimestampMtimeUnixSeconds(extraField) {
+    const view = new DataView(extraField.buffer, extraField.byteOffset, extraField.byteLength);
+    let offset = 0;
+    while (offset + 4 <= extraField.length) {
+        const headerId = view.getUint16(offset, true);
+        const dataSize = view.getUint16(offset + 2, true);
+        const dataStart = offset + 4;
+        const dataEnd = dataStart + dataSize;
+        if (dataEnd > extraField.length) {
+            break;
+        }
+        if (headerId === EXTENDED_TIMESTAMP_ID && dataSize >= 1) {
+            const flags = extraField[dataStart];
+            if ((flags & 0x01) !== 0 && dataSize >= 5) {
+                // mtime is 4 bytes right after flags.
+                return view.getUint32(dataStart + 1, true) >>> 0;
+            }
+        }
+        offset = dataEnd;
+    }
+    return undefined;
+}

package/dist/esm/modules/archive/zip-builder.js

@@ -0,0 +1,292 @@
+/**
+ * ZIP file format builder
+ *
+ * Implements ZIP file structure according to PKWARE's APPNOTE.TXT specification
+ * https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT
+ *
+ * ZIP file structure:
+ * ┌──────────────────────────┐
+ * │   Local File Header 1    │
+ * │   File Data 1            │
+ * ├──────────────────────────┤
+ * │   Local File Header 2    │
+ * │   File Data 2            │
+ * ├──────────────────────────┤
+ * │         ...              │
+ * ├──────────────────────────┤
+ * │  Central Directory 1     │
+ * │  Central Directory 2     │
+ * │         ...              │
+ * ├──────────────────────────┤
+ * │ End of Central Directory │
+ * └──────────────────────────┘
+ */
+import { compress, compressSync } from "./compress.js";
+import { crc32 } from "./crc32.js";
+import { concatUint8Arrays, sumUint8ArrayLengths } from "./utils/bytes.js";
+import {} from "./utils/timestamps.js";
+import { buildZipEntryMetadata, resolveZipCompressionMethod } from "./zip-entry-metadata.js";
+import { DEFAULT_ZIP_LEVEL, DEFAULT_ZIP_TIMESTAMPS } from "./defaults.js";
+import { buildCentralDirectoryHeader, buildEndOfCentralDirectory, buildLocalFileHeader } from "./zip-records.js";
+import { FLAG_UTF8, VERSION_MADE_BY, VERSION_NEEDED } from "./zip-constants.js";
+const LOCAL_FILE_HEADER_FIXED_SIZE = 30;
+function encodeZipComment(comment) {
+    // Keep empty comment as empty bytes (no encoding surprises).
+    return comment ? new TextEncoder().encode(comment) : new Uint8Array(0);
+}
+function shouldDeflate(level, data) {
+    return level > 0 && data.length > 0;
+}
+function computeLocalRecordSize(entry) {
+    return (LOCAL_FILE_HEADER_FIXED_SIZE +
+        entry.name.length +
+        entry.extraField.length +
+        entry.compressedData.length);
+}
+function buildProcessedEntry(entry, offset, settings, compressedData) {
+    const modDate = entry.modTime ?? settings.defaultModTime;
+    const isCompressed = shouldDeflate(settings.level, entry.data);
+    const metadata = buildZipEntryMetadata({
+        name: entry.name,
+        comment: entry.comment,
+        modTime: modDate,
+        timestamps: settings.timestamps,
+        useDataDescriptor: false,
+        deflate: isCompressed
+    });
+    return {
+        name: metadata.nameBytes,
+        data: entry.data,
+        compressedData,
+        crc: crc32(entry.data),
+        compressionMethod: resolveZipCompressionMethod(isCompressed),
+        modTime: metadata.dosTime,
+        modDate: metadata.dosDate,
+        extraField: metadata.extraField,
+        comment: metadata.commentBytes,
+        offset
+    };
+}
+function appendProcessedEntry(processedEntries, entry, compressedData, currentOffset, settings) {
+    const processedEntry = buildProcessedEntry(entry, currentOffset, settings, compressedData);
+    processedEntries.push(processedEntry);
+    return {
+        processedEntry,
+        nextOffset: currentOffset + computeLocalRecordSize(processedEntry)
+    };
+}
+function finalizeZip(processedEntries, zipComment, centralDirOffset) {
+    // Build ZIP structure
+    const chunks = [];
+    // Local file headers and data
+    for (const entry of processedEntries) {
+        chunks.push(buildLocalFileHeaderChunk(entry));
+        chunks.push(entry.compressedData);
+    }
+    chunks.push(...buildCentralDirectorySection(processedEntries, centralDirOffset, zipComment));
+    return concatUint8Arrays(chunks);
+}
+function buildLocalFileHeaderChunk(entry) {
+    return buildLocalFileHeader({
+        fileName: entry.name,
+        extraField: entry.extraField,
+        flags: FLAG_UTF8,
+        compressionMethod: entry.compressionMethod,
+        dosTime: entry.modTime,
+        dosDate: entry.modDate,
+        crc32: entry.crc,
+        compressedSize: entry.compressedData.length,
+        uncompressedSize: entry.data.length,
+        versionNeeded: VERSION_NEEDED
+    });
+}
+function buildCentralDirHeaderChunk(entry) {
+    return buildCentralDirectoryHeader({
+        fileName: entry.name,
+        extraField: entry.extraField,
+        comment: entry.comment,
+        flags: FLAG_UTF8,
+        compressionMethod: entry.compressionMethod,
+        dosTime: entry.modTime,
+        dosDate: entry.modDate,
+        crc32: entry.crc,
+        compressedSize: entry.compressedData.length,
+        uncompressedSize: entry.data.length,
+        localHeaderOffset: entry.offset,
+        versionMadeBy: VERSION_MADE_BY,
+        versionNeeded: VERSION_NEEDED
+    });
+}
+function buildCentralDirectorySection(processedEntries, centralDirOffset, zipComment) {
+    const chunks = [];
+    for (const entry of processedEntries) {
+        chunks.push(buildCentralDirHeaderChunk(entry));
+    }
+    const centralDirSize = sumUint8ArrayLengths(chunks);
+    chunks.push(buildEndOfCentralDirectory({
+        entryCount: processedEntries.length,
+        centralDirSize,
+        centralDirOffset,
+        comment: zipComment
+    }));
+    return chunks;
+}
+/**
+ * Create a ZIP file from entries (async)
+ *
+ * @param entries - Files to include in ZIP
+ * @param options - ZIP options
+ * @returns ZIP file as Uint8Array
+ *
+ * @example
+ * ```ts
+ * const zip = await createZip([
+ *   { name: "hello.txt", data: new TextEncoder().encode("Hello!") },
+ *   { name: "folder/file.txt", data: new TextEncoder().encode("Nested!") }
+ * ], { level: 6 });
+ * ```
+ */
+export async function createZip(entries, options = {}) {
+    const level = options.level ?? DEFAULT_ZIP_LEVEL;
+    const timestamps = options.timestamps ?? DEFAULT_ZIP_TIMESTAMPS;
+    const zipComment = encodeZipComment(options.comment);
+    const defaultModTime = new Date();
+    const settings = {
+        level,
+        timestamps,
+        defaultModTime
+    };
+    const compressOptions = {
+        level,
+        thresholdBytes: options.thresholdBytes
+    };
+    const compressedDatas = await Promise.all(entries.map(async (entry) => {
+        return shouldDeflate(level, entry.data) ? compress(entry.data, compressOptions) : entry.data;
+    }));
+    // Process entries
+    const processedEntries = [];
+    let currentOffset = 0;
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        const compressedData = compressedDatas[i];
+        const result = appendProcessedEntry(processedEntries, entry, compressedData, currentOffset, settings);
+        currentOffset = result.nextOffset;
+    }
+    return finalizeZip(processedEntries, zipComment, currentOffset);
+}
+/**
+ * Create a ZIP file from entries (sync)
+ *
+ * This is supported in both Node.js and browser builds.
+ */
+export function createZipSync(entries, options = {}) {
+    const level = options.level ?? DEFAULT_ZIP_LEVEL;
+    const timestamps = options.timestamps ?? DEFAULT_ZIP_TIMESTAMPS;
+    const zipComment = encodeZipComment(options.comment);
+    const defaultModTime = new Date();
+    const settings = {
+        level,
+        timestamps,
+        defaultModTime
+    };
+    const compressOptions = {
+        level,
+        thresholdBytes: options.thresholdBytes
+    };
+    // Process entries
+    const processedEntries = [];
+    let currentOffset = 0;
+    for (const entry of entries) {
+        // Compress data
+        const compressedData = shouldDeflate(level, entry.data)
+            ? compressSync(entry.data, compressOptions)
+            : entry.data;
+        const result = appendProcessedEntry(processedEntries, entry, compressedData, currentOffset, settings);
+        currentOffset = result.nextOffset;
+    }
+    return finalizeZip(processedEntries, zipComment, currentOffset);
+}
+/**
+ * Streaming ZIP builder for large files
+ * Writes chunks to a callback as they are generated
+ */
+export class ZipBuilder {
+    /**
+     * Create a new ZIP builder
+     * @param options - ZIP options
+     */
+    constructor(options = {}) {
+        this.entries = [];
+        this.currentOffset = 0;
+        this.finalized = false;
+        this.level = options.level ?? DEFAULT_ZIP_LEVEL;
+        this.zipComment = encodeZipComment(options.comment);
+        this.timestamps = options.timestamps ?? DEFAULT_ZIP_TIMESTAMPS;
+        this.compressOptions = {
+            level: this.level,
+            thresholdBytes: options.thresholdBytes
+        };
+        this.settings = {
+            level: this.level,
+            timestamps: this.timestamps,
+            defaultModTime: new Date()
+        };
+    }
+    /**
+     * Add a file to the ZIP (async)
+     * @param entry - File entry
+     * @returns Local file header and compressed data chunks
+     */
+    async addFile(entry) {
+        if (this.finalized) {
+            throw new Error("Cannot add files after finalizing");
+        }
+        // Compress data
+        const compressedData = shouldDeflate(this.level, entry.data)
+            ? await compress(entry.data, this.compressOptions)
+            : entry.data;
+        const result = appendProcessedEntry(this.entries, entry, compressedData, this.currentOffset, this.settings);
+        this.currentOffset = result.nextOffset;
+        return [buildLocalFileHeaderChunk(result.processedEntry), compressedData];
+    }
+    /**
+     * Add a file to the ZIP (sync)
+     * @param entry - File entry
+     * @returns Local file header and compressed data chunks
+     */
+    addFileSync(entry) {
+        if (this.finalized) {
+            throw new Error("Cannot add files after finalizing");
+        }
+        // Compress data
+        const compressedData = shouldDeflate(this.level, entry.data)
+            ? compressSync(entry.data, this.compressOptions)
+            : entry.data;
+        const result = appendProcessedEntry(this.entries, entry, compressedData, this.currentOffset, this.settings);
+        this.currentOffset = result.nextOffset;
+        return [buildLocalFileHeaderChunk(result.processedEntry), compressedData];
+    }
+    /**
+     * Finalize the ZIP and return central directory + end record
+     * @returns Central directory and end of central directory chunks
+     */
+    finalize() {
+        if (this.finalized) {
+            throw new Error("ZIP already finalized");
+        }
+        this.finalized = true;
+        return buildCentralDirectorySection(this.entries, this.currentOffset, this.zipComment);
+    }
+    /**
+     * Get current number of entries
+     */
+    get entryCount() {
+        return this.entries.length;
+    }
+    /**
+     * Get current ZIP data size (without central directory)
+     */
+    get dataSize() {
+        return this.currentOffset;
+    }
+}

package/dist/esm/modules/archive/zip-constants.js

@@ -0,0 +1,23 @@
+/**
+ * ZIP format constants (PKWARE APPNOTE)
+ * Shared by ZIP writer and parser implementations.
+ */
+// Signatures
+export const LOCAL_FILE_HEADER_SIG = 0x04034b50;
+export const CENTRAL_DIR_HEADER_SIG = 0x02014b50;
+export const END_OF_CENTRAL_DIR_SIG = 0x06054b50;
+export const DATA_DESCRIPTOR_SIG = 0x08074b50;
+export const ZIP64_END_OF_CENTRAL_DIR_SIG = 0x06064b50;
+export const ZIP64_END_OF_CENTRAL_DIR_LOCATOR_SIG = 0x07064b50;
+// Versions
+export const VERSION_NEEDED = 20; // 2.0 - supports DEFLATE
+export const VERSION_MADE_BY = 20; // 2.0
+// Compression methods
+export const COMPRESSION_STORE = 0;
+export const COMPRESSION_DEFLATE = 8;
+// General purpose bit flags
+export const FLAG_UTF8 = 0x0800;
+export const FLAG_DATA_DESCRIPTOR = 0x0008;
+// ZIP64 / sentinel sizes
+export const UINT16_MAX = 0xffff;
+export const UINT32_MAX = 0xffffffff;

package/dist/esm/modules/archive/zip-entry-info.js

@@ -0,0 +1,6 @@
+/**
+ * Shared ZIP entry metadata used by unzip parsers and higher-level extract APIs.
+ *
+ * This is intentionally platform-agnostic and does not depend on Node.js streams.
+ */
+export {};

package/dist/esm/modules/archive/zip-entry-metadata.js

@@ -0,0 +1,24 @@
+import { encodeUtf8 } from "./utils/text.js";
+import { buildZipTimestampExtraField, dateToZipDos } from "./utils/timestamps.js";
+import { COMPRESSION_DEFLATE, COMPRESSION_STORE, FLAG_DATA_DESCRIPTOR, FLAG_UTF8 } from "./zip-constants.js";
+export function resolveZipCompressionMethod(deflate) {
+    return deflate ? COMPRESSION_DEFLATE : COMPRESSION_STORE;
+}
+export function resolveZipFlags(useDataDescriptor) {
+    return useDataDescriptor ? FLAG_UTF8 | FLAG_DATA_DESCRIPTOR : FLAG_UTF8;
+}
+export function buildZipEntryMetadata(input) {
+    const nameBytes = encodeUtf8(input.name);
+    const commentBytes = encodeUtf8(input.comment ?? "");
+    const { dosTime, dosDate } = dateToZipDos(input.modTime);
+    const extraField = buildZipTimestampExtraField(input.modTime, input.timestamps);
+    return {
+        nameBytes,
+        commentBytes,
+        dosTime,
+        dosDate,
+        extraField,
+        compressionMethod: resolveZipCompressionMethod(input.deflate),
+        flags: resolveZipFlags(input.useDataDescriptor)
+    };
+}