@cj-tech-master/excelts 3.1.0-canary.20260102041828.82ed571 → 3.1.0

package/dist/types/utils/zip/compress.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 "./compress.base";
+/**
+ * Check if native zlib is available (always true in Node.js)
+ */
+export declare function hasNativeZlib(): boolean;
+/**
+ * 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?: {
+    level?: number;
+}): 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?: {
+    level?: number;
+}): Uint8Array;
+/**
+ * Decompress data using Node.js native zlib
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export declare function decompress(data: Uint8Array): 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/types/utils/zip/crc32.browser.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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
+ */
+/**
+ * Calculate CRC32 checksum for the given data
+ *
+ * @param data - Input data as Uint8Array
+ * @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 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);
+ * ```
+ */
+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 declare function crc32Finalize(crc: number): number;

package/dist/types/utils/zip/crc32.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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
+ */
+/**
+ * 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
+ * Note: This always uses JS implementation for consistency in streaming
+ *
+ * @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 declare function crc32Finalize(crc: number): number;

package/dist/types/utils/zip/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Native ZIP utilities - Pure native implementation without third-party dependencies
+ *
+ * This module provides ZIP file creation using only native platform APIs:
+ * - Node.js: Uses native zlib module (C++ implementation, fastest)
+ * - Browser: Uses CompressionStream API (Chrome 80+, Firefox 113+, Safari 16.4+)
+ *
+ * Features:
+ * - Full ZIP format support (Local File Headers, Central Directory, EOCD)
+ * - DEFLATE compression (level 0-9 on Node.js, fixed level on browser)
+ * - STORE mode (no compression)
+ * - UTF-8 filename support
+ * - File comments and ZIP comments
+ * - Streaming API for large files
+ * - Both sync (Node.js) and async APIs
+ *
+ * @example Basic usage
+ * ```ts
+ * import { createZip } from "./utils/zip/index";
+ *
+ * const zipData = await createZip([
+ *   { name: "hello.txt", data: new TextEncoder().encode("Hello!") },
+ *   { name: "folder/nested.txt", data: new TextEncoder().encode("Nested file") }
+ * ], { level: 6 });
+ *
+ * // Write to file (Node.js)
+ * fs.writeFileSync("output.zip", zipData);
+ * ```
+ *
+ * @example Streaming usage
+ * ```ts
+ * import { ZipBuilder } from "./utils/zip/index";
+ *
+ * const builder = new ZipBuilder({ level: 1 });
+ *
+ * // Add files one by one
+ * const [header1, data1] = await builder.addFile({
+ *   name: "file1.txt",
+ *   data: new TextEncoder().encode("File 1 content")
+ * });
+ * stream.write(header1);
+ * stream.write(data1);
+ *
+ * // Finalize and write central directory
+ * for (const chunk of builder.finalize()) {
+ *   stream.write(chunk);
+ * }
+ * ```
+ */
+export { crc32, crc32Update, crc32Finalize } from "./crc32";
+export { compress, compressSync, decompress, decompressSync, hasNativeZlib, hasCompressionStream, type CompressOptions } from "./compress";
+export { createZip, createZipSync, ZipBuilder, type ZipEntry, type ZipOptions } from "./zip-builder";

package/dist/types/utils/zip/streaming-zip.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Streaming ZIP creator - fflate-compatible API
+ *
+ * This module provides a streaming ZIP API compatible with fflate's Zip/ZipDeflate,
+ * but uses native zlib compression for better performance.
+ *
+ * Usage:
+ * ```ts
+ * const zip = new StreamingZip((err, data, final) => {
+ *   if (err) handleError(err);
+ *   else {
+ *     stream.write(data);
+ *     if (final) stream.end();
+ *   }
+ * });
+ *
+ * const file = new ZipDeflateFile("path/file.txt", { level: 6 });
+ * zip.add(file);
+ * file.push(data1);
+ * file.push(data2, true); // true = final chunk
+ *
+ * zip.end();
+ * ```
+ */
+/**
+ * Internal entry info for central directory
+ */
+interface ZipEntryInfo {
+    name: Uint8Array;
+    crc: number;
+    compressedSize: number;
+    uncompressedSize: number;
+    compressionMethod: number;
+    dosTime: number;
+    dosDate: number;
+    offset: number;
+}
+/**
+ * ZipDeflate-compatible file stream
+ * Collects data chunks, compresses on finalization
+ */
+export declare class ZipDeflateFile {
+    private chunks;
+    private totalSize;
+    private finalized;
+    private _ondata;
+    readonly name: string;
+    readonly level: number;
+    constructor(name: string, options?: {
+        level?: number;
+    });
+    /**
+     * Set data callback (called by StreamingZip)
+     */
+    set ondata(cb: (data: Uint8Array, final: boolean) => void);
+    /**
+     * Push data to the file
+     * @param data - Data chunk
+     * @param final - Whether this is the final chunk
+     */
+    push(data: Uint8Array, final?: boolean): void;
+    /**
+     * Flush collected data through compression and emit
+     */
+    private _flush;
+    /**
+     * Get entry info (called by StreamingZip after finalization)
+     */
+    getEntryInfo(): ZipEntryInfo | null;
+}
+/**
+ * Streaming ZIP - fflate Zip-compatible API
+ * Creates ZIP files in a streaming manner
+ */
+export declare class StreamingZip {
+    private callback;
+    private entries;
+    private currentOffset;
+    private ended;
+    /**
+     * Create a streaming ZIP
+     * @param callback - Called with (err, data, final) as data becomes available
+     */
+    constructor(callback: (err: Error | null, data: Uint8Array, final: boolean) => void);
+    /**
+     * Add a file to the ZIP
+     * @param file - ZipDeflateFile instance
+     */
+    add(file: ZipDeflateFile): void;
+    /**
+     * Finalize the ZIP
+     * Writes central directory and end-of-central-directory record
+     */
+    end(): void;
+}
+export { StreamingZip as Zip, ZipDeflateFile as ZipDeflate };

package/dist/types/utils/zip/zip-builder.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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 "./compress";
+/**
+ * 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;
+}
+/**
+ * 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, Node.js only)
+ *
+ * @param entries - Files to include in ZIP
+ * @param options - ZIP options
+ * @returns ZIP file as Uint8Array
+ * @throws Error if not in Node.js environment
+ */
+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 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, Node.js only)
+     * @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;
+}

package/dist/types/utils/zip-stream.browser.d.ts

@@ -0,0 +1,39 @@
+interface ZipWriterOptions {
+    /** Compression method: "DEFLATE" (default) or "STORE" (no compression) */
+    compression?: "DEFLATE" | "STORE";
+    compressionOptions?: {
+        /** Compression level 0-9: 0=none, 1=fast (default), 9=best */
+        level?: number;
+    };
+}
+interface AppendOptions {
+    name: string;
+    base64?: boolean;
+}
+type EventCallback = (...args: any[]) => void;
+declare class ZipWriter {
+    private stream;
+    private zipBuilder;
+    private finalized;
+    private pendingWrites;
+    private events;
+    constructor(options?: ZipWriterOptions);
+    on(event: string, callback: EventCallback): this;
+    once(event: string, callback: EventCallback): this;
+    off(event: string, callback: EventCallback): this;
+    emit(event: string, ...args: any[]): boolean;
+    removeListener(event: string, callback: EventCallback): this;
+    append(data: any, options: AppendOptions): void;
+    push(chunk: any): boolean;
+    finalize(): Promise<void>;
+    read(size?: number): any;
+    setEncoding(encoding: string): any;
+    pause(): any;
+    resume(): any;
+    isPaused(): boolean;
+    pipe(destination: any): any;
+    unpipe(destination?: any): void;
+    unshift(): void;
+    wrap(): void;
+}
+export { ZipWriter };

package/dist/types/utils/zip-stream.d.ts

@@ -0,0 +1,33 @@
+import events from "events";
+interface ZipWriterOptions {
+    /** Compression method: "DEFLATE" (default) or "STORE" (no compression) */
+    compression?: "DEFLATE" | "STORE";
+    compressionOptions?: {
+        /** Compression level 0-9: 0=none, 1=fast (default), 9=best */
+        level?: number;
+    };
+}
+interface AppendOptions {
+    name: string;
+    base64?: boolean;
+}
+declare class ZipWriter extends events.EventEmitter {
+    private stream;
+    private zipBuilder;
+    private finalized;
+    private pendingWrites;
+    constructor(options?: ZipWriterOptions);
+    append(data: any, options: AppendOptions): void;
+    push(chunk: any): boolean;
+    finalize(): Promise<void>;
+    read(size?: number): any;
+    setEncoding(encoding: string): any;
+    pause(): any;
+    resume(): any;
+    isPaused(): boolean;
+    pipe(destination: any, options?: any): any;
+    unpipe(destination?: any): any;
+    unshift(chunk: any): any;
+    wrap(stream: any): any;
+}
+export { ZipWriter };

package/dist/types/xlsx/xform/base-xform.d.ts

@@ -0,0 +1,33 @@
+import { XmlStream } from "../../utils/xml-stream";
+interface ParseEvent {
+    eventType: string;
+    value: any;
+}
+declare class BaseXform {
+    map?: {
+        [key: string]: any;
+    };
+    model?: any;
+    prepare(_model?: any, _options?: any): void;
+    render(_xmlStream?: XmlStream, _model?: any): void;
+    parseOpen(_node: any): void;
+    parseText(_text: string): void;
+    parseClose(_name: string): boolean;
+    reconcile(_model: any, _options?: any): void;
+    reset(): void;
+    mergeModel(obj: any): void;
+    parse(saxParser: AsyncIterable<ParseEvent[]>): Promise<any>;
+    parseStream(stream: any): Promise<any>;
+    get xml(): string;
+    toXml(model: any): string;
+    static toAttribute(value: any, dflt?: any, always?: boolean): string | undefined;
+    static toStringAttribute(value: any, dflt?: any, always?: boolean): string | undefined;
+    static toStringValue(attr: any, dflt?: any): any;
+    static toBoolAttribute(value: any, dflt?: any, always?: boolean): string | undefined;
+    static toBoolValue(attr: any, dflt?: any): boolean;
+    static toIntAttribute(value: any, dflt?: any, always?: boolean): string | undefined;
+    static toIntValue(attr: any, dflt?: any): number;
+    static toFloatAttribute(value: any, dflt?: any, always?: boolean): string | undefined;
+    static toFloatValue(attr: any, dflt?: any): number;
+}
+export { BaseXform };

package/dist/types/xlsx/xform/book/defined-name-xform.d.ts

@@ -0,0 +1,17 @@
+import { BaseXform } from "../base-xform";
+interface DefinedNameModel {
+    name: string;
+    ranges: string[];
+    localSheetId?: number;
+}
+declare class DefinedNamesXform extends BaseXform {
+    private _parsedName?;
+    private _parsedLocalSheetId?;
+    private _parsedText;
+    constructor();
+    render(xmlStream: any, model: DefinedNameModel): void;
+    parseOpen(node: any): boolean;
+    parseText(text: string): void;
+    parseClose(): boolean;
+}
+export { DefinedNamesXform };

package/dist/types/xlsx/xform/book/sheet-xform.d.ts

@@ -0,0 +1,14 @@
+import { BaseXform } from "../base-xform";
+interface SheetModel {
+    id: number;
+    name: string;
+    state?: string;
+    rId: string;
+}
+declare class WorksheetXform extends BaseXform {
+    render(xmlStream: any, model: SheetModel): void;
+    parseOpen(node: any): boolean;
+    parseText(): void;
+    parseClose(): boolean;
+}
+export { WorksheetXform };

package/dist/types/xlsx/xform/book/workbook-calc-properties-xform.d.ts

@@ -0,0 +1,11 @@
+import { BaseXform } from "../base-xform";
+interface CalcPropertiesModel {
+    fullCalcOnLoad?: boolean;
+}
+declare class WorkbookCalcPropertiesXform extends BaseXform {
+    render(xmlStream: any, model: CalcPropertiesModel): void;
+    parseOpen(node: any): boolean;
+    parseText(): void;
+    parseClose(): boolean;
+}
+export { WorkbookCalcPropertiesXform };

package/dist/types/xlsx/xform/book/workbook-pivot-cache-xform.d.ts

@@ -0,0 +1,12 @@
+import { BaseXform } from "../base-xform";
+interface PivotCacheModel {
+    cacheId: string;
+    rId: string;
+}
+declare class WorkbookPivotCacheXform extends BaseXform {
+    render(xmlStream: any, model: PivotCacheModel): void;
+    parseOpen(node: any): boolean;
+    parseText(): void;
+    parseClose(): boolean;
+}
+export { WorkbookPivotCacheXform };

package/dist/types/xlsx/xform/book/workbook-properties-xform.d.ts

@@ -0,0 +1,11 @@
+import { BaseXform } from "../base-xform";
+interface WorkbookPropertiesModel {
+    date1904?: boolean;
+}
+declare class WorkbookPropertiesXform extends BaseXform {
+    render(xmlStream: any, model: WorkbookPropertiesModel): void;
+    parseOpen(node: any): boolean;
+    parseText(): void;
+    parseClose(): boolean;
+}
+export { WorkbookPropertiesXform };

package/dist/types/xlsx/xform/book/workbook-view-xform.d.ts

@@ -0,0 +1,17 @@
+import { BaseXform } from "../base-xform";
+interface WorkbookViewModel {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    firstSheet?: number;
+    activeTab?: number;
+    visibility?: string;
+}
+declare class WorkbookViewXform extends BaseXform {
+    render(xmlStream: any, model: WorkbookViewModel): void;
+    parseOpen(node: any): boolean;
+    parseText(): void;
+    parseClose(): boolean;
+}
+export { WorkbookViewXform };

package/dist/types/xlsx/xform/book/workbook-xform.d.ts

@@ -0,0 +1,23 @@
+import { BaseXform } from "../base-xform";
+import { StaticXform } from "../static-xform";
+declare class WorkbookXform extends BaseXform {
+    parser: any;
+    constructor();
+    prepare(model: any): void;
+    render(xmlStream: any, model: any): void;
+    parseOpen(node: any): boolean;
+    parseText(text: string): void;
+    parseClose(name: string): boolean;
+    reconcile(model: any): void;
+    static WORKBOOK_ATTRIBUTES: {
+        xmlns: string;
+        "xmlns:r": string;
+        "xmlns:mc": string;
+        "mc:Ignorable": string;
+        "xmlns:x15": string;
+    };
+    static STATIC_XFORMS: {
+        fileVersion: StaticXform;
+    };
+}
+export { WorkbookXform };

package/dist/types/xlsx/xform/comment/comment-xform.d.ts

@@ -0,0 +1,28 @@
+import { RichTextXform } from "../strings/rich-text-xform";
+import { BaseXform } from "../base-xform";
+interface NoteText {
+    font?: any;
+    text: string;
+}
+interface CommentNote {
+    texts: NoteText[];
+}
+interface CommentModel {
+    type: string;
+    note: CommentNote;
+    ref: string;
+    authorId?: number;
+}
+declare class CommentXform extends BaseXform {
+    model: CommentModel;
+    parser: any;
+    private _richTextXform?;
+    constructor(model?: CommentModel);
+    get tag(): string;
+    get richTextXform(): RichTextXform;
+    render(xmlStream: any, model?: CommentModel): void;
+    parseOpen(node: any): boolean;
+    parseText(text: string): void;
+    parseClose(name: string): boolean;
+}
+export { CommentXform };