neozipkit 0.1.1

package/dist/shared/ZipKit.d.ts

@@ -0,0 +1,249 @@
+import ZipEntry from './ZipEntry';
+import Errors from './constants/Errors';
+import { LOCAL_HDR, ENCRYPT_HDR_SIZE, CMP_METHOD, CENTRAL_END, CENTRAL_DIR, ZIP64_CENTRAL_END, ZIP64_CENTRAL_DIR, GP_FLAG, TIMESTAMP_SUBMITTED, TIMESTAMP_METADATA, TOKENIZED_METADATA, LOCAL_FILE_HEADER, CENTRAL_FILE_HEADER, CENTRAL_DIRECTORY_END, HDR_ID } from './constants/Headers';
+export { ZipEntry, Errors, CMP_METHOD, TIMESTAMP_METADATA, TIMESTAMP_SUBMITTED, TOKENIZED_METADATA, LOCAL_HDR, ENCRYPT_HDR_SIZE, CENTRAL_END, CENTRAL_DIR, ZIP64_CENTRAL_END, ZIP64_CENTRAL_DIR, GP_FLAG, LOCAL_FILE_HEADER, CENTRAL_FILE_HEADER, CENTRAL_DIRECTORY_END, HDR_ID };
+/**
+ * Options for compressing files in a ZIP archive
+ */
+export interface CompressOptions {
+    level?: number;
+    password?: string | null;
+    useSHA256?: boolean;
+    useZstd?: boolean;
+}
+/**
+ * Callbacks for ZIP file creation process
+ */
+export interface CreateZipOptions {
+    onError?: (error: Error) => void;
+    onEntryDone?: (entry: ZipEntry, status: string) => void;
+    onReadEntryData?: (entry: ZipEntry) => Buffer;
+    onOutputBuffer?: (data: Buffer) => void;
+}
+/**
+ * Main class for ZIP file operations including compression, extraction, and encryption
+ */
+export default class ZipKit {
+    static readonly version: string;
+    static readonly releaseDate: string;
+    private inBuffer;
+    private zipEntries;
+    private sortName;
+    private centralDirSize;
+    private centralDirOffset;
+    private stampEntry;
+    zipComment: string | null;
+    static support: {
+        base64: boolean;
+        array: boolean;
+        string: boolean;
+        isNode: boolean;
+        buffer: boolean;
+        uint8array: boolean;
+        arrayBuffer: boolean;
+        blob: boolean;
+        streams: boolean;
+        fileReader: boolean;
+    };
+    /**
+     * Creates a new ZipKit instance
+     */
+    constructor();
+    /**
+     * Resets all ZIP-related data to initial state
+     */
+    resetZipData(): void;
+    /**
+     * Loads a ZIP file from a buffer
+     * @param inBuf - Buffer containing ZIP file data
+     */
+    loadZip(inBuf: Buffer): void;
+    /**
+     * Tests if data matches the CRC32 checksum
+     * @param entry - ZIP entry to check
+     * @param data - Data buffer to verify
+     * @returns boolean indicating if CRC matches
+     */
+    testCRC32(entry: ZipEntry, data: Buffer): boolean;
+    /**
+     * Tests if data matches the SHA256 hash
+     * @param entry - ZIP entry to check
+     * @param data - Data buffer to verify
+     * @returns boolean indicating if SHA256 matches
+     * @throws Error if entry has no SHA256 hash
+     */
+    testSHA256(entry: ZipEntry, data: Buffer): boolean;
+    /**
+     * Locates and parses the central end directory
+     * @param inBuffer - Buffer containing ZIP file data
+     * @returns Number of entries in ZIP file
+     * @throws Error if central directory is invalid
+     */
+    getCentralEnd(inBuffer: Buffer): number;
+    /**
+     * Creates the central end directory header
+     * @param centralDirSize - Size of central directory
+     * @param centralDirOffset - Offset to central directory
+     * @returns Buffer containing end directory header
+     */
+    centralEndHdr(centralDirSize: number, centralDirOffset: number): Buffer;
+    /**
+     * Reads and parses the ZIP file directory
+     * @param debug - Enable debug logging
+     * @returns Array of ZIP entries
+     */
+    getDirectory(debug?: boolean): ZipEntry[];
+    /**
+     * Gets a ZIP entry by filename
+     * @param fname - Filename to search for
+     * @returns ZipEntry if found, null otherwise
+     */
+    getZipEntry(fname: string): ZipEntry | null;
+    /**
+     * Creates a new ZIP entry
+     * @param fname - Filename for new entry
+     * @param comment - Optional entry comment
+     * @returns Created ZipEntry
+     */
+    createZipEntry(fname: string, comment?: string): ZipEntry;
+    /**
+     * Deletes an entry from the ZIP file
+     * @param fname - Filename to delete
+     * @returns boolean indicating if file was deleted
+     */
+    deleteFile(fname: string): boolean;
+    /**
+     * Parses local header and returns entry data
+     * @param entry - ZIP entry to parse
+     * @param withLocalHdrData - Include header in returned data
+     * @returns Buffer containing entry data
+     * @throws Error if header is invalid
+     */
+    parseLocalHeader(entry: ZipEntry, withLocalHdrData?: boolean): Buffer;
+    /**
+     * Copies an entry's data from source ZIP
+     * @param entry - Entry to copy
+     * @returns Buffer containing entry data with headers
+     */
+    copyEntry(entry: ZipEntry): Buffer;
+    /**
+     * Compresses data for a ZIP entry
+     * @param entry - ZIP entry to compress
+     * @param data - Data to compress
+     * @param options - Compression options
+     * @returns Buffer containing compressed data
+     */
+    compressData(entry: ZipEntry, data: Buffer, options?: CompressOptions): Promise<Buffer>;
+    /**
+     * Compresses data using deflate algorithm
+     * @param inbuf - Data to compress
+     * @param options - Compression options
+     * @returns Compressed data buffer
+     */
+    private deflate;
+    /**
+     * Compresses data using Zstandard (zstd) algorithm
+     * @param inbuf - Data to compress
+     * @param options - Compression options
+     * @returns Compressed data buffer
+     */
+    private zstdCompress;
+    /**
+     * Decompresses data using Zstandard (zstd) algorithm
+     * @param inbuf - Compressed data buffer
+     * @returns Decompressed data buffer
+     */
+    zstdDecompress(inbuf: Buffer): Promise<Buffer>;
+    /**
+     * Creates new Zip data file with the passed ZipEntries
+     * @param cmpOptions - Compression options
+     * @param zipOptions - Create ZIP options
+     * @returns Promise<number> - The offset of the last entry
+     */
+    createZipFileData(cmpOptions?: CompressOptions, zipOptions?: CreateZipOptions): Promise<number>;
+    /**
+     * Finishes Zip data file by adding any Metadata entries and the Central End Directory
+     * @param offset - The current offset in the zip data file
+     * @param onOutputBuffer - The callback function to output the data buffer
+     * @param metaEntry - The Metadata ZipEntry to add to the Zip file
+     */
+    finishZipFileData(offset: number, onOutputBuffer: (data: Buffer) => void, metaEntry?: ZipEntry): Promise<void>;
+    /**
+     * Unzips the data buffer using pako inflate method
+     * @param inbuf - Data buffer to inflate
+     * @returns Inflated data buffer
+     * @throws Error if extraction fails
+     */
+    inflate(inbuf: Buffer): Buffer;
+    /**
+     * Extracts the data from the ZipEntry and returns the data as a Buffer
+     * @param entry - ZIP entry to extract
+     * @param skipHashCheck - Whether to skip hash checking
+     * @returns Buffer containing extracted data or null if extraction fails
+     */
+    extract(entry: ZipEntry, skipHashCheck?: boolean): Promise<Buffer | null>;
+    /**
+     * Decrypts the entry data
+     * @param entry - ZIP entry to decrypt
+     * @param password - Password for decryption
+     * @returns Decrypted data buffer or null if decryption fails
+     */
+    decryptEntry(entry: ZipEntry, password: string): Buffer | null;
+    /**
+     * Checks if a filename is a blockchain metadata file that should be excluded from Merkle Root calculation
+     * @param filename - The filename to check
+     * @returns boolean - True if the file is a metadata file
+     */
+    private isMetadataFile;
+    /**
+     * Calculates the Merkle Root of the ZIP file
+     * Excludes blockchain metadata files (META-INF/*) to ensure consistent calculation
+     * @returns string - The Merkle Root of the ZIP file
+     */
+    getMerkleRoot(): string | null;
+    /**
+     * Checks if a ZIP file contains valid timestamp metadata
+     * @returns { merkleRoot: string | null, ots: Buffer | null }
+     * Returns the merkle root hash and timestamp metadata if found, null otherwise
+     */
+    checkForTimestamp(): string | null;
+    /**
+     * Gets the OTS from the timestamp metadata entry
+     * @returns Promise<Buffer | null> - The OTS from the timestamp metadata entry or null if not found
+     */
+    getOts(): Promise<Buffer | null>;
+    /**
+     * Creates a new timestamp metadata entry for the ZIP file
+     * Calculates merkle root from file hashes and obtains blockchain timestamp
+     * @returns Promise<ZipEntry | null> The created timestamp metadata entry or null if failed
+     */
+    createTimestampMetadataEntry(ots: Buffer | null): ZipEntry | null;
+    /**
+     * Sets the ZIP file comment
+     * @param msg - Comment to set
+     */
+    setZipComment(msg: string | null): void;
+    /**
+     * Gets the ZIP file comment
+     * @returns string | null - The ZIP file comment
+     */
+    getZipComment(): string | null;
+    /**
+     * Converts the compression method to a string
+     * @param cmpMethod - Compression method number
+     * @returns string - Compression method as a string
+     */
+    cmpMethodToString(cmpMethod: number): string;
+    /**
+     * Ensures ZIP entries are loaded
+     * @returns Array of ZIP entries
+     * @throws Error if no ZIP entries are loaded
+     */
+    private ensureZipEntries;
+    /**
+     * Ensures ZIP data buffer is loaded
+     * @returns Buffer containing ZIP data
+     * @throws Error if no ZIP data is loaded
+     */
+    private ensureBuffer;
+}