@cj-tech-master/excelts 3.1.0-canary.20260102071304.d80b29d → 4.0.0-canary.20260103013222.0e5d37f

package/dist/browser/modules/archive/utils/text.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared text encoding/decoding utilities.
+ *
+ * Caches encoder/decoder instances for performance.
+ */
+export declare const utf8Encoder: TextEncoder;
+export declare const utf8Decoder: TextDecoder;
+/**
+ * Encode a string as UTF-8.
+ */
+export declare function encodeUtf8(value: string): Uint8Array;
+/**
+ * Decode bytes as UTF-8.
+ */
+export declare function decodeUtf8(bytes: Uint8Array): string;
+/**
+ * Decode bytes as Latin-1/byte-to-char.
+ * Used as a fallback when UTF-8 flag is not set.
+ */
+export declare function decodeLatin1(bytes: Uint8Array): string;

package/dist/browser/modules/archive/utils/text.js

@@ -0,0 +1,33 @@
+/**
+ * Shared text encoding/decoding utilities.
+ *
+ * Caches encoder/decoder instances for performance.
+ */
+export const utf8Encoder = new TextEncoder();
+export const utf8Decoder = new TextDecoder("utf-8");
+/**
+ * Encode a string as UTF-8.
+ */
+export function encodeUtf8(value) {
+    return utf8Encoder.encode(value);
+}
+/**
+ * Decode bytes as UTF-8.
+ */
+export function decodeUtf8(bytes) {
+    return utf8Decoder.decode(bytes);
+}
+/**
+ * Decode bytes as Latin-1/byte-to-char.
+ * Used as a fallback when UTF-8 flag is not set.
+ */
+export function decodeLatin1(bytes) {
+    // Avoid spreading huge arrays; build incrementally.
+    let out = "";
+    const chunkSize = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+        const chunk = bytes.subarray(i, i + chunkSize);
+        out += String.fromCharCode(...chunk);
+    }
+    return out;
+}

package/dist/browser/modules/archive/utils/timestamps.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 declare function dateToDos(date: Date): [number, number];
+/**
+ * Parse DOS date/time to JS Date.
+ */
+export declare function parseDosDateTimeUTC(date: number, time?: number): Date;
+/**
+ * How to write timestamps in ZIP headers.
+ *
+ * ZIP always has DOS date/time fields; `dos+utc` additionally writes the Info-ZIP
+ * extended timestamp extra field (0x5455) for a UTC mtime.
+ */
+export type ZipTimestampMode = "dos" | "dos+utc";
+export declare function resolveZipLastModifiedDateFromUnixSeconds(dosDate: number, dosTime: number, mtimeUnixSeconds?: number): Date;
+export declare function resolveZipLastModifiedDateFromExtraField(dosDate: number, dosTime: number, extraField: Uint8Array): Date;
+export declare function buildZipTimestampExtraField(modTime: Date, mode: ZipTimestampMode): Uint8Array;
+export declare function dateToZipDos(modTime: Date): {
+    dosTime: number;
+    dosDate: number;
+};

package/dist/browser/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/browser/modules/archive/utils/zip-extra-fields.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+export interface ZipVars {
+    uncompressedSize: number;
+    compressedSize: number;
+    offsetToLocalFileHeader?: number;
+}
+export interface ZipExtraFields {
+    uncompressedSize?: number;
+    compressedSize?: number;
+    offsetToLocalFileHeader?: number;
+    /** Info-ZIP extended timestamp (0x5455) mtime, Unix seconds (UTC). */
+    mtimeUnixSeconds?: number;
+}
+export declare function parseZipExtraFields(extraField: Uint8Array, vars: ZipVars): ZipExtraFields;

package/dist/browser/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/browser/modules/archive/utils/zip-extra.d.ts

@@ -0,0 +1,18 @@
+export declare function unixSecondsFromDate(date: Date): number;
+/**
+ * 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 declare function buildExtendedTimestampExtraFieldFromUnixSeconds(unixSeconds: number): Uint8Array;
+export declare function buildExtendedTimestampExtraFieldFromDate(date: Date): Uint8Array;
+/**
+ * Parse Info-ZIP "Extended Timestamp" extra field (0x5455) and return mtime.
+ * Returns Unix seconds (UTC) if present.
+ */
+export declare function parseExtendedTimestampMtimeUnixSeconds(extraField: Uint8Array): number | undefined;

package/dist/browser/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/browser/modules/archive/zip-builder.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 { type CompressOptions } from "@archive/compress";
+import { type ZipTimestampMode } from "@archive/utils/timestamps";
+/**
+ * ZIP file entry
+ */
+export interface ZipEntry {
+    /** File name (can include directory path, use forward slashes) */
+    name: string;
+    /** File data (will be compressed unless level=0) */
+    data: Uint8Array;
+    /** File modification time (optional, defaults to current time) */
+    modTime?: Date;
+    /** File comment (optional) */
+    comment?: string;
+}
+/**
+ * ZIP builder options
+ */
+export interface ZipOptions extends CompressOptions {
+    /** ZIP file comment (optional) */
+    comment?: string;
+    /**
+     * Timestamp writing strategy.
+     * - "dos": only write DOS date/time fields (smallest output)
+     * - "dos+utc": also write UTC mtime in 0x5455 extra field (default, best practice)
+     */
+    timestamps?: ZipTimestampMode;
+}
+/**
+ * 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 declare function createZip(entries: ZipEntry[], options?: ZipOptions): Promise<Uint8Array>;
+/**
+ * Create a ZIP file from entries (sync)
+ *
+ * This is supported in both Node.js and browser builds.
+ */
+export declare function createZipSync(entries: ZipEntry[], options?: ZipOptions): Uint8Array;
+/**
+ * Streaming ZIP builder for large files
+ * Writes chunks to a callback as they are generated
+ */
+export declare class ZipBuilder {
+    private entries;
+    private currentOffset;
+    private level;
+    private zipComment;
+    private timestamps;
+    private compressOptions;
+    private settings;
+    private finalized;
+    /**
+     * Create a new ZIP builder
+     * @param options - ZIP options
+     */
+    constructor(options?: ZipOptions);
+    /**
+     * Add a file to the ZIP (async)
+     * @param entry - File entry
+     * @returns Local file header and compressed data chunks
+     */
+    addFile(entry: ZipEntry): Promise<Uint8Array[]>;
+    /**
+     * Add a file to the ZIP (sync)
+     * @param entry - File entry
+     * @returns Local file header and compressed data chunks
+     */
+    addFileSync(entry: ZipEntry): Uint8Array[];
+    /**
+     * Finalize the ZIP and return central directory + end record
+     * @returns Central directory and end of central directory chunks
+     */
+    finalize(): Uint8Array[];
+    /**
+     * Get current number of entries
+     */
+    get entryCount(): number;
+    /**
+     * Get current ZIP data size (without central directory)
+     */
+    get dataSize(): number;
+}