@cj-tech-master/excelts 4.0.0 → 4.0.1

package/dist/browser/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.browser.js";
+import { crc32 } from "./crc32.browser.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/browser/modules/archive/zip-constants.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ZIP format constants (PKWARE APPNOTE)
+ * Shared by ZIP writer and parser implementations.
+ */
+export declare const LOCAL_FILE_HEADER_SIG = 67324752;
+export declare const CENTRAL_DIR_HEADER_SIG = 33639248;
+export declare const END_OF_CENTRAL_DIR_SIG = 101010256;
+export declare const DATA_DESCRIPTOR_SIG = 134695760;
+export declare const ZIP64_END_OF_CENTRAL_DIR_SIG = 101075792;
+export declare const ZIP64_END_OF_CENTRAL_DIR_LOCATOR_SIG = 117853008;
+export declare const VERSION_NEEDED = 20;
+export declare const VERSION_MADE_BY = 20;
+export declare const COMPRESSION_STORE = 0;
+export declare const COMPRESSION_DEFLATE = 8;
+export declare const FLAG_UTF8 = 2048;
+export declare const FLAG_DATA_DESCRIPTOR = 8;
+export declare const UINT16_MAX = 65535;
+export declare const UINT32_MAX = 4294967295;

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

@@ -0,0 +1,29 @@
+/**
+ * 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 interface ZipEntryInfo {
+    /** File path within the ZIP */
+    path: string;
+    /** Whether this is a directory */
+    isDirectory: boolean;
+    /** Compressed size */
+    compressedSize: number;
+    /** Uncompressed size */
+    uncompressedSize: number;
+    /** Compression method (0 = stored, 8 = deflate) */
+    compressionMethod: number;
+    /** CRC-32 checksum */
+    crc32: number;
+    /** Last modified date */
+    lastModified: Date;
+    /** Offset to local file header */
+    localHeaderOffset: number;
+    /** File comment */
+    comment: string;
+    /** External file attributes */
+    externalAttributes: number;
+    /** Is encrypted */
+    isEncrypted: boolean;
+}

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

@@ -0,0 +1,23 @@
+import { type ZipTimestampMode } from "@archive/utils/timestamps";
+export interface ZipEntryMetadata {
+    nameBytes: Uint8Array;
+    commentBytes: Uint8Array;
+    dosTime: number;
+    dosDate: number;
+    extraField: Uint8Array;
+    compressionMethod: number;
+    flags: number;
+}
+export interface ZipEntryMetadataInput {
+    name: string;
+    comment?: string;
+    modTime: Date;
+    timestamps: ZipTimestampMode;
+    /** If true, set FLAG_DATA_DESCRIPTOR and expect CRC/sizes written later. */
+    useDataDescriptor: boolean;
+    /** If true, use DEFLATE; else STORE. */
+    deflate: boolean;
+}
+export declare function resolveZipCompressionMethod(deflate: boolean): number;
+export declare function resolveZipFlags(useDataDescriptor: boolean): number;
+export declare function buildZipEntryMetadata(input: ZipEntryMetadataInput): ZipEntryMetadata;

package/dist/browser/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)
+    };
+}

package/dist/browser/modules/archive/zip-parser.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure Uint8Array-based ZIP parser
+ * Works in both Node.js and browser environments
+ * No dependency on Node.js stream module
+ */
+import type { ZipEntryInfo } from "@archive/zip-entry-info";
+export type { ZipEntryInfo };
+/**
+ * ZIP parsing options
+ */
+export interface ZipParseOptions {
+    /** Whether to decode file names as UTF-8 (default: true) */
+    decodeStrings?: boolean;
+}
+/**
+ * High-level ZIP parser class
+ */
+export declare class ZipParser {
+    private data;
+    private entries;
+    private entryMap;
+    constructor(data: Uint8Array | ArrayBuffer, options?: ZipParseOptions);
+    /**
+     * Get all entries in the ZIP file
+     */
+    getEntries(): ZipEntryInfo[];
+    /**
+     * Get entry by path
+     */
+    getEntry(path: string): ZipEntryInfo | undefined;
+    /**
+     * Check if entry exists
+     */
+    hasEntry(path: string): boolean;
+    /**
+     * List all file paths
+     */
+    listFiles(): string[];
+    /**
+     * Extract a single file (async)
+     */
+    extract(path: string): Promise<Uint8Array | null>;
+    /**
+     * Extract a single file (sync)
+     *
+     * This is supported in both Node.js and browser builds.
+     */
+    extractSync(path: string): Uint8Array | null;
+    /**
+     * Extract all files (async)
+     */
+    extractAll(): Promise<Map<string, Uint8Array>>;
+    /**
+     * Extract all files (sync)
+     * Returns object with file paths as keys and Uint8Array content as values
+     */
+    extractAllSync(): Record<string, Uint8Array>;
+    /**
+     * Iterate over entries with async callback
+     */
+    forEach(callback: (entry: ZipEntryInfo, getData: () => Promise<Uint8Array>) => Promise<boolean | void>): Promise<void>;
+}