@cj-tech-master/excelts 3.1.0 → 4.0.0

package/dist/types/modules/archive/byte-queue.d.ts

@@ -0,0 +1,18 @@
+export declare class ByteQueue {
+    private static readonly EMPTY;
+    private _buf;
+    private _start;
+    private _end;
+    private _cachedView;
+    private _cachedBuf;
+    private _cachedStart;
+    private _cachedEnd;
+    constructor(initial?: Uint8Array);
+    get length(): number;
+    isEmpty(): boolean;
+    view(): Uint8Array;
+    reset(data?: Uint8Array): void;
+    append(chunk: Uint8Array): void;
+    read(length: number): Uint8Array;
+    discard(length: number): void;
+}

package/dist/types/modules/archive/compress.base.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Base compression utilities using Web Streams API
+ * Shared between Node.js and Browser implementations
+ *
+ * Uses CompressionStream/DecompressionStream API with "deflate-raw" format
+ * (raw DEFLATE without zlib header/trailer, required for ZIP files)
+ *
+ * Browser fallback: For browsers without deflate-raw support (Firefox < 113, Safari < 16.4),
+ * see deflate-fallback.ts for pure JS implementation
+ */
+/**
+ * Compression options
+ */
+export interface CompressOptions {
+    /**
+     * Compression level (0-9)
+     * - 0: No compression (STORE)
+     * - 1: Fastest compression
+     * - 6: Default compression (good balance)
+     * - 9: Best compression (slowest)
+     *
+     * Note: CompressionStream does not support level configuration,
+     * it uses a fixed level (~6)
+     */
+    level?: number;
+    /**
+     * Threshold (in bytes) to choose the lower-overhead path.
+     *
+     * - Node.js: inputs <= threshold use sync zlib fast-path (avoid threadpool overhead)
+     * - Browser: inputs <= threshold use the pure-JS fallback (avoid stream scheduling overhead)
+     */
+    thresholdBytes?: number;
+}
+/**
+ * Default threshold (in bytes) to choose the lower-overhead path.
+ *
+ * This is a performance knob, not a correctness requirement.
+ */
+export declare const DEFAULT_COMPRESS_THRESHOLD_BYTES: number;
+/**
+ * Resolve the effective threshold bytes.
+ */
+export declare function resolveCompressThresholdBytes(options: CompressOptions): number;
+/**
+ * Check if CompressionStream is available
+ */
+export declare function hasCompressionStream(): boolean;
+/**
+ * Non-cached probe for CompressionStream("deflate-raw") support.
+ *
+ * Prefer this in code paths that want up-to-date environment checks
+ * (e.g. tests that stub globals).
+ */
+export declare function probeDeflateRawCompressionStream(): boolean;
+/**
+ * Non-cached probe for DecompressionStream("deflate-raw") support.
+ */
+export declare function probeDeflateRawDecompressionStream(): boolean;
+/**
+ * Non-cached probe for full deflate-raw Web Streams support.
+ *
+ * Returns true only if BOTH CompressionStream("deflate-raw") and
+ * DecompressionStream("deflate-raw") are supported.
+ */
+export declare function probeDeflateRawWebStreams(): boolean;
+/**
+ * Check if CompressionStream supports the "deflate-raw" format.
+ *
+ * This is a stricter check than {@link hasCompressionStream} because some
+ * environments expose CompressionStream but do not support "deflate-raw".
+ */
+export declare function hasDeflateRawCompressionStream(): boolean;
+/**
+ * Check if DecompressionStream supports the "deflate-raw" format.
+ */
+export declare function hasDeflateRawDecompressionStream(): boolean;
+/**
+ * Cached check for full deflate-raw Web Streams support.
+ *
+ * Returns true only if BOTH CompressionStream("deflate-raw") and
+ * DecompressionStream("deflate-raw") are supported.
+ */
+export declare function hasDeflateRawWebStreams(): boolean;
+/**
+ * Compress using CompressionStream API
+ * Uses "deflate-raw" format (required for ZIP files)
+ *
+ * @param data - Data to compress
+ * @returns Compressed data
+ */
+export declare function compressWithStream(data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Decompress using DecompressionStream API
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export declare function decompressWithStream(data: Uint8Array): Promise<Uint8Array>;

package/dist/types/modules/archive/compress.browser.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Browser compression utilities
+ *
+ * Primary: CompressionStream API (Chrome 103+, Firefox 113+, Safari 16.4+)
+ * Fallback: Pure JS DEFLATE implementation for older browsers
+ *
+ * Supported browsers with fallback:
+ * - Chrome >= 89
+ * - Firefox >= 102
+ * - Safari >= 14.1
+ * - Edge >= 89
+ */
+import { type CompressOptions } from "./compress.base.d.ts";
+export { type CompressOptions };
+/**
+ * Check if CompressionStream is available in this environment.
+ *
+ * Note: Some environments may expose CompressionStream but not support
+ * the "deflate-raw" format that ZIP requires.
+ */
+export declare function hasCompressionStream(): boolean;
+/**
+ * Compress data using browser's native CompressionStream or JS fallback
+ *
+ * @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?: CompressOptions): Promise<Uint8Array>;
+/**
+ * Compress data synchronously using pure JS implementation
+ *
+ * @param data - Data to compress
+ * @param options - Compression options
+ * @returns Compressed data
+ */
+export declare function compressSync(data: Uint8Array, options?: CompressOptions): Uint8Array;
+/**
+ * Decompress data using browser's native DecompressionStream or JS fallback
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export declare function decompress(data: Uint8Array, options?: CompressOptions): Promise<Uint8Array>;
+/**
+ * Decompress data synchronously using pure JS implementation
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export declare function decompressSync(data: Uint8Array): Uint8Array;

package/dist/types/modules/archive/compress.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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.d.ts";
+import type { CompressOptions } from "./compress.base.d.ts";
+/**
+ * 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?: CompressOptions): 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?: CompressOptions): Uint8Array;
+/**
+ * Decompress data using Node.js native zlib
+ *
+ * @param data - Compressed data (deflate-raw format)
+ * @returns Decompressed data
+ */
+export declare function decompress(data: Uint8Array, options?: CompressOptions): 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/modules/archive/crc32.base.d.ts

@@ -0,0 +1,25 @@
+/**
+ * CRC32 calculation core (shared between Node.js and browser).
+ *
+ * Implements CRC-32 IEEE 802.3 using the reversed polynomial 0xEDB88320.
+ *
+ * Notes:
+ * - Uses a lazily-initialized 256-entry lookup table.
+ * - Exposes an incremental update API for streaming use cases.
+ */
+/**
+ * Update a CRC32 value with a new data chunk.
+ *
+ * The CRC state here is the non-finalized (inverted) form:
+ * - initial state: 0xffffffff
+ * - finalize: xor with 0xffffffff
+ */
+export declare function crc32UpdateJS(crc: number, data: Uint8Array): number;
+/**
+ * Finalize CRC32 calculation.
+ */
+export declare function crc32Finalize(crc: number): number;
+/**
+ * Compute CRC32 for the full input using the JS table implementation.
+ */
+export declare function crc32JS(data: Uint8Array): number;

package/dist/types/modules/archive/crc32.browser.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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
+ */
+export { crc32JS as crc32, crc32UpdateJS as crc32Update, crc32Finalize } from "./crc32.base.d.ts";
+/**
+ * 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);
+ * ```
+ */

package/dist/types/modules/archive/crc32.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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
+ */
+import { crc32Finalize } from "./crc32.base.d.ts";
+/**
+ * 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
+ * In Node.js, this uses native zlib.crc32 when available for performance.
+ * The internal CRC state remains the same as the JS table implementation:
+ * - initial state: 0xffffffff
+ * - finalize: xor with 0xffffffff
+ *
+ * @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 { crc32Finalize };

package/dist/types/modules/archive/defaults.d.ts

@@ -0,0 +1,4 @@
+import type { ZipTimestampMode } from "./utils/timestamps.d.ts";
+export declare const DEFAULT_COMPRESS_LEVEL = 6;
+export declare const DEFAULT_ZIP_LEVEL = 6;
+export declare const DEFAULT_ZIP_TIMESTAMPS: ZipTimestampMode;

package/dist/types/modules/archive/extract.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Simple ZIP extraction utilities
+ * Provides easy-to-use Promise-based API for extracting ZIP files
+ * Works in both Node.js and browser environments
+ */
+import { type ZipEntryInfo } from "./zip-parser.d.ts";
+/**
+ * Extracted file entry
+ */
+export interface ExtractedFile {
+    /** File path within the ZIP */
+    path: string;
+    /** File content as Uint8Array */
+    data: Uint8Array;
+    /** Whether this is a directory */
+    isDirectory: boolean;
+    /** Uncompressed size */
+    size: number;
+}
+/**
+ * Extract all files from a ZIP buffer
+ *
+ * @param zipData - ZIP file data as Buffer, Uint8Array, or ArrayBuffer
+ * @returns Map of file paths to their content
+ *
+ * @example
+ * ```ts
+ * import { extractAll } from "./utils/unzip/extract";
+ *
+ * const zipData = fs.readFileSync("archive.zip");
+ * const files = await extractAll(zipData);
+ *
+ * for (const [path, file] of files) {
+ *   console.log(`${path}: ${file.data.length} bytes`);
+ * }
+ * ```
+ */
+export declare function extractAll(zipData: Uint8Array | ArrayBuffer): Promise<Map<string, ExtractedFile>>;
+/**
+ * Extract a single file from a ZIP buffer
+ *
+ * @param zipData - ZIP file data as Buffer, Uint8Array, or ArrayBuffer
+ * @param filePath - Path of the file to extract
+ * @returns File content as Uint8Array, or null if not found
+ *
+ * @example
+ * ```ts
+ * import { extractFile } from "./utils/unzip/extract";
+ *
+ * const zipData = fs.readFileSync("archive.zip");
+ * const content = await extractFile(zipData, "readme.txt");
+ * if (content) {
+ *   console.log(new TextDecoder().decode(content));
+ * }
+ * ```
+ */
+export declare function extractFile(zipData: Uint8Array | ArrayBuffer, filePath: string): Promise<Uint8Array | null>;
+/**
+ * List all file paths in a ZIP buffer (without extracting content)
+ *
+ * @param zipData - ZIP file data as Buffer, Uint8Array, or ArrayBuffer
+ * @returns Array of file paths
+ *
+ * @example
+ * ```ts
+ * import { listFiles } from "./utils/unzip/extract";
+ *
+ * const zipData = fs.readFileSync("archive.zip");
+ * const paths = await listFiles(zipData);
+ * console.log(paths); // ["file1.txt", "folder/file2.txt", ...]
+ * ```
+ */
+export declare function listFiles(zipData: Uint8Array | ArrayBuffer): Promise<string[]>;
+/**
+ * Iterate over ZIP entries with a callback (memory efficient for large ZIPs)
+ *
+ * @param zipData - ZIP file data as Buffer, Uint8Array, or ArrayBuffer
+ * @param callback - Async callback for each entry, return false to stop iteration
+ *
+ * @example
+ * ```ts
+ * import { forEachEntry } from "./utils/unzip/extract";
+ *
+ * await forEachEntry(zipData, async (path, getData) => {
+ *   if (path.endsWith(".xml")) {
+ *     const content = await getData();
+ *     console.log(new TextDecoder().decode(content));
+ *   }
+ *   return true; // continue iteration
+ * });
+ * ```
+ */
+export declare function forEachEntry(zipData: Uint8Array | ArrayBuffer, callback: (path: string, getData: () => Promise<Uint8Array>, entry: ZipEntryInfo) => Promise<boolean | void>): Promise<void>;
+export { ZipParser, type ZipEntryInfo, type ZipParseOptions } from "./zip-parser.d.ts";

package/dist/types/modules/archive/index.base.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Archive (ZIP) module - shared exports.
+ *
+ * This module contains exports that are identical across Node.js and browser.
+ * Platform-specific entrypoints (index.ts / index.browser.ts) should re-export
+ * from this file and then layer their platform-specific bindings.
+ */
+export { createZip, createZipSync, ZipBuilder, type ZipEntry, type ZipOptions } from "./zip-builder.d.ts";
+export { StreamingZip, ZipDeflateFile, Zip, ZipDeflate } from "./streaming-zip.d.ts";
+export { extractAll, extractFile, listFiles, forEachEntry, ZipParser, type ExtractedFile, type ZipParseOptions } from "./extract.d.ts";
+export type { ZipEntryInfo } from "./zip-entry-info.d.ts";

package/dist/types/modules/archive/index.browser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Archive (ZIP) module - unified ZIP + Unzip implementation (browser type surface).
+ *
+ * This file mirrors [src/modules/archive/index.ts] but explicitly re-exports
+ * browser-specific implementations so we can enforce export-surface parity.
+ */
+export * from "./index.base.d.ts";
+export { crc32, crc32Update, crc32Finalize } from "./crc32.browser.d.ts";
+export { compress, compressSync, decompress, decompressSync, hasCompressionStream, type CompressOptions } from "./compress.browser.d.ts";
+export { createDeflateStream, createInflateStream, hasDeflateRaw, type StreamCompressOptions } from "./streaming-compress.browser.d.ts";
+export { Parse, createParse, type ParseOptions, type ZipEntry as StreamZipEntry } from "./parse.browser.d.ts";

package/dist/types/modules/archive/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Archive (ZIP) module - unified ZIP + Unzip implementation.
+ *
+ * This module is intended to be extractable as a standalone package.
+ * It groups all ZIP creation and extraction utilities in one place.
+ */
+export * from "./index.base.d.ts";
+export { crc32, crc32Update, crc32Finalize } from "./crc32.d.ts";
+export { compress, compressSync, decompress, decompressSync, hasCompressionStream, type CompressOptions } from "./compress.d.ts";
+export { createDeflateStream, createInflateStream, hasDeflateRaw, type StreamCompressOptions } from "./streaming-compress.d.ts";
+export { Parse, createParse, type ParseOptions, type ZipEntry as StreamZipEntry } from "./parse.d.ts";

package/dist/types/modules/archive/parse.base.d.ts

@@ -0,0 +1,198 @@
+import { Duplex, PassThrough, Transform, type Readable } from "../stream/index.d.ts";
+import { ByteQueue } from "./byte-queue.d.ts";
+import { parseZipExtraFields, type ZipExtraFields, type ZipVars } from "./utils/zip-extra-fields.d.ts";
+export declare const CRX_HEADER_FORMAT: [string, number][];
+export declare const LOCAL_FILE_HEADER_FORMAT: [string, number][];
+export declare const DATA_DESCRIPTOR_FORMAT: [string, number][];
+export declare const CENTRAL_DIRECTORY_FILE_HEADER_FORMAT: [string, number][];
+export declare const END_OF_CENTRAL_DIRECTORY_FORMAT: [string, number][];
+export interface ZipEntryVarsMeta {
+    flags: number | null;
+    uncompressedSize: number;
+    lastModifiedDate: number | null;
+    lastModifiedTime: number | null;
+}
+export type { ZipVars, ZipExtraFields };
+export interface ZipEntryPropsMeta {
+    path: string;
+    pathBuffer: Uint8Array;
+    flags: {
+        isUnicode: boolean;
+    };
+}
+export interface CrxHeader {
+    version: number | null;
+    pubKeyLength: number | null;
+    signatureLength: number | null;
+    publicKey?: Uint8Array;
+    signature?: Uint8Array;
+}
+export interface LocalFileHeaderVars {
+    versionsNeededToExtract: number | null;
+    flags: number | null;
+    compressionMethod: number | null;
+    lastModifiedTime: number | null;
+    lastModifiedDate: number | null;
+    crc32: number | null;
+    compressedSize: number | null;
+    uncompressedSize: number | null;
+    fileNameLength: number | null;
+    extraFieldLength: number | null;
+}
+export interface DataDescriptorVars {
+    dataDescriptorSignature: number | null;
+    crc32: number | null;
+    compressedSize: number | null;
+    uncompressedSize: number | null;
+}
+export declare function decodeZipEntryPath(pathBuffer: Uint8Array): string;
+export declare function isZipUnicodeFlag(flags: number | null): boolean;
+export declare function isZipDirectoryPath(path: string): boolean;
+export declare function getZipEntryType(path: string, uncompressedSize: number): "Directory" | "File";
+export declare function buildZipEntryProps(path: string, pathBuffer: Uint8Array, flags: number | null): ZipEntryPropsMeta;
+export declare function resolveZipEntryLastModifiedDateTime(vars: ZipEntryVarsMeta, extraFields: ZipExtraFields): Date;
+export declare const parseExtraField: typeof parseZipExtraFields;
+export declare function hasDataDescriptorFlag(flags: number | null): boolean;
+export declare function isFileSizeKnown(flags: number | null, compressedSize: number | null): boolean;
+export type DrainStream = Transform & {
+    promise: () => Promise<void>;
+};
+export declare function autodrain(stream: {
+    pipe: (dest: Transform) => unknown;
+}): DrainStream;
+/**
+ * Collects all data from a readable stream into a single Uint8Array.
+ */
+export declare function bufferStream(entry: Readable): Promise<Uint8Array>;
+export type PullFn = (length: number) => Promise<Uint8Array>;
+export declare class PullStream extends Duplex {
+    protected readonly _queue: ByteQueue;
+    get buffer(): Uint8Array;
+    set buffer(value: Uint8Array);
+    cb?: () => void;
+    finished: boolean;
+    match?: number;
+    __emittedError?: Error;
+    constructor();
+    _write(chunk: Uint8Array | string, _encoding: string, callback: () => void): void;
+    _read(): void;
+    protected _maybeReleaseWriteCallback(): void;
+    /**
+     * The `eof` parameter is interpreted as `file_length` if the type is number
+     * otherwise (i.e. Uint8Array) it is interpreted as a pattern signaling end of stream
+     */
+    stream(eof: number | Uint8Array, includeEof?: boolean): PassThrough;
+    pull(eof: number | Uint8Array, includeEof?: boolean): Promise<Uint8Array>;
+    pullUntil(pattern: Uint8Array, includeEof?: boolean): Promise<Uint8Array>;
+}
+export type PullStreamPublicApi = {
+    buffer: Uint8Array;
+    cb?: () => void;
+    finished: boolean;
+    match?: number;
+    stream(eof: number | Uint8Array, includeEof?: boolean): PassThrough;
+    pull(eof: number | Uint8Array, includeEof?: boolean): Promise<Uint8Array>;
+    pullUntil(pattern: Uint8Array, includeEof?: boolean): Promise<Uint8Array>;
+};
+export declare function readCrxHeader(pull: PullFn): Promise<CrxHeader>;
+export declare function readLocalFileHeader(pull: PullFn): Promise<{
+    vars: EntryVars;
+    fileNameBuffer: Uint8Array;
+    extraFieldData: Uint8Array;
+}>;
+export declare function readDataDescriptor(pull: PullFn): Promise<DataDescriptorVars>;
+export declare function consumeCentralDirectoryFileHeader(pull: PullFn): Promise<void>;
+export declare function consumeEndOfCentralDirectoryRecord(pull: PullFn): Promise<void>;
+export interface ValidatedDataDescriptorScanResult {
+    /** Start index of the descriptor within `view`, or -1 when not found yet. */
+    foundIndex: number;
+    /** Where the caller should resume searching on the next scan of (a mostly unchanged) view. */
+    nextSearchFrom: number;
+}
+/**
+ * Scan for a validated DATA_DESCRIPTOR record boundary.
+ *
+ * Scanning for the 4-byte signature alone is unsafe because it can appear inside
+ * compressed data. We validate a candidate by requiring:
+ * - the next 4 bytes after the 16-byte descriptor form a known ZIP record signature, and
+ * - the descriptor's compressedSize matches the number of compressed bytes emitted so far.
+ */
+export declare function scanValidatedDataDescriptor(view: Uint8Array, dataDescriptorSignature: Uint8Array, bytesEmitted: number, startIndex?: number, out?: ValidatedDataDescriptorScanResult): ValidatedDataDescriptorScanResult;
+export interface StreamUntilValidatedDataDescriptorSource {
+    getView(): Uint8Array;
+    getLength(): number;
+    read(length: number): Uint8Array;
+    isFinished(): boolean;
+    onDataAvailable(cb: () => void): () => void;
+    maybeReleaseWriteCallback?: () => void;
+}
+export interface StreamUntilValidatedDataDescriptorOptions {
+    source: StreamUntilValidatedDataDescriptorSource;
+    dataDescriptorSignature: Uint8Array;
+    /** Keep enough bytes to validate: descriptor(16) + next record sig(4) = 20. */
+    keepTailBytes?: number;
+    errorMessage?: string;
+}
+/**
+ * Stream compressed file data until we reach a validated DATA_DESCRIPTOR boundary.
+ *
+ * This encapsulates the shared logic used by both Node and browser parsers.
+ */
+export declare function streamUntilValidatedDataDescriptor(options: StreamUntilValidatedDataDescriptorOptions): PassThrough;
+export interface ParseOptions {
+    verbose?: boolean;
+    forceStream?: boolean;
+}
+export interface EntryVars {
+    versionsNeededToExtract: number | null;
+    flags: number | null;
+    compressionMethod: number | null;
+    lastModifiedTime: number | null;
+    lastModifiedDate: number | null;
+    crc32: number | null;
+    compressedSize: number | null;
+    uncompressedSize: number | null;
+    fileNameLength: number | null;
+    extraFieldLength: number | null;
+    lastModifiedDateTime?: Date;
+    crxHeader?: CrxHeader;
+}
+export interface EntryProps {
+    path: string;
+    pathBuffer: Uint8Array;
+    flags: {
+        isUnicode: boolean;
+    };
+}
+export interface ZipEntry extends PassThrough {
+    path: string;
+    props: EntryProps;
+    type: "Directory" | "File";
+    vars: EntryVars;
+    extraFields: ZipExtraFields;
+    size?: number;
+    __autodraining?: boolean;
+    autodrain: () => DrainStream;
+    buffer: () => Promise<Uint8Array>;
+}
+export interface ParseDriverState {
+    crxHeader?: CrxHeader;
+    reachedCD?: boolean;
+}
+export interface ParseIO {
+    pull(length: number): Promise<Uint8Array>;
+    pullUntil(pattern: Uint8Array, includeEof?: boolean): Promise<Uint8Array>;
+    stream(length: number): PassThrough;
+    streamUntilDataDescriptor(): PassThrough;
+    setDone(): void;
+}
+export interface ParseEmitter {
+    emitEntry(entry: ZipEntry): void;
+    pushEntry(entry: ZipEntry): void;
+    pushEntryIfPiped(entry: ZipEntry): void;
+    emitCrxHeader(header: CrxHeader): void;
+    emitError(err: Error): void;
+    emitClose(): void;
+}
+export type InflateFactory = () => Transform | Duplex | PassThrough;
+export declare function runParseLoop(opts: ParseOptions, io: ParseIO, emitter: ParseEmitter, inflateFactory: InflateFactory, state: ParseDriverState): Promise<void>;