@cj-tech-master/excelts 4.0.0 → 4.0.1

package/dist/browser/modules/archive/extract.js

@@ -0,0 +1,106 @@
+/**
+ * Simple ZIP extraction utilities
+ * Provides easy-to-use Promise-based API for extracting ZIP files
+ * Works in both Node.js and browser environments
+ */
+import { ZipParser } from "./zip-parser.js";
+/**
+ * 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.js";
+ *
+ * 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 async function extractAll(zipData) {
+    const files = new Map();
+    const parser = new ZipParser(zipData);
+    for (const entry of parser.getEntries()) {
+        const data = await parser.extract(entry.path);
+        files.set(entry.path, {
+            path: entry.path,
+            data: data || new Uint8Array(0),
+            isDirectory: entry.isDirectory,
+            size: entry.uncompressedSize
+        });
+    }
+    return files;
+}
+/**
+ * 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.js";
+ *
+ * const zipData = fs.readFileSync("archive.zip");
+ * const content = await extractFile(zipData, "readme.txt");
+ * if (content) {
+ *   console.log(new TextDecoder().decode(content));
+ * }
+ * ```
+ */
+export async function extractFile(zipData, filePath) {
+    const parser = new ZipParser(zipData);
+    return parser.extract(filePath);
+}
+/**
+ * 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.js";
+ *
+ * const zipData = fs.readFileSync("archive.zip");
+ * const paths = await listFiles(zipData);
+ * console.log(paths); // ["file1.txt", "folder/file2.txt", ...]
+ * ```
+ */
+export async function listFiles(zipData) {
+    const parser = new ZipParser(zipData);
+    return parser.listFiles();
+}
+/**
+ * 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.js";
+ *
+ * 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 async function forEachEntry(zipData, callback) {
+    const parser = new ZipParser(zipData);
+    await parser.forEach(async (entry, getData) => {
+        return callback(entry.path, getData, entry);
+    });
+}
+// Re-export ZipParser for advanced usage
+export { ZipParser } from "./zip-parser.js";

package/dist/browser/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 "@archive/zip-builder";
+export { StreamingZip, ZipDeflateFile, Zip, ZipDeflate } from "@archive/streaming-zip";
+export { extractAll, extractFile, listFiles, forEachEntry, ZipParser, type ExtractedFile, type ZipParseOptions } from "@archive/extract";
+export type { ZipEntryInfo } from "@archive/zip-entry-info";

package/dist/browser/modules/archive/index.base.js

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+// ZIP builders
+export { createZip, createZipSync, ZipBuilder } from "./zip-builder.js";
+// Streaming ZIP (fflate-like API)
+export { StreamingZip, ZipDeflateFile, Zip, ZipDeflate } from "./streaming-zip.js";
+// Buffer-based unzip API (cross-platform)
+export { extractAll, extractFile, listFiles, forEachEntry, ZipParser } from "./extract.js";

package/dist/browser/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 "@archive/index.base";
+export { crc32, crc32Update, crc32Finalize } from "@archive/crc32.browser";
+export { compress, compressSync, decompress, decompressSync, hasCompressionStream, type CompressOptions } from "@archive/compress.browser";
+export { createDeflateStream, createInflateStream, hasDeflateRaw, type StreamCompressOptions } from "@archive/streaming-compress.browser";
+export { Parse, createParse, type ParseOptions, type ZipEntry as StreamZipEntry } from "@archive/parse.browser";

package/dist/browser/modules/archive/index.browser.js

@@ -0,0 +1,17 @@
+/**
+ * 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.js";
+// CRC32
+export { crc32, crc32Update, crc32Finalize } from "./crc32.browser.js";
+// Compression
+export { compress, compressSync, decompress, decompressSync, hasCompressionStream } from "./compress.browser.js";
+// Streaming compression
+export { createDeflateStream, createInflateStream, hasDeflateRaw } from "./streaming-compress.browser.js";
+// Stream-based unzip API (browser implementation)
+export { Parse, createParse } from "./parse.browser.js";
+// Buffer-based unzip API (cross-platform)
+// (re-exported from ./index.base)

package/dist/browser/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 "@archive/index.base";
+export { crc32, crc32Update, crc32Finalize } from "@archive/crc32";
+export { compress, compressSync, decompress, decompressSync, hasCompressionStream, type CompressOptions } from "@archive/compress";
+export { createDeflateStream, createInflateStream, hasDeflateRaw, type StreamCompressOptions } from "@archive/streaming-compress";
+export { Parse, createParse, type ParseOptions, type ZipEntry as StreamZipEntry } from "@archive/parse";

package/dist/browser/modules/archive/index.js

@@ -0,0 +1,15 @@
+/**
+ * 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.js";
+// CRC32
+export { crc32, crc32Update, crc32Finalize } from "./crc32.browser.js";
+// Compression
+export { compress, compressSync, decompress, decompressSync, hasCompressionStream } from "./compress.browser.js";
+// Streaming compression
+export { createDeflateStream, createInflateStream, hasDeflateRaw } from "./streaming-compress.browser.js";
+// Stream-based unzip API (Node.js; browser build aliases to ./parse.browser.ts)
+export { Parse, createParse } from "./parse.browser.js";

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

@@ -0,0 +1,198 @@
+import { Duplex, PassThrough, Transform, type Readable } from "@stream";
+import { ByteQueue } from "@archive/byte-queue";
+import { parseZipExtraFields, type ZipExtraFields, type ZipVars } from "@archive/utils/zip-extra-fields";
+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>;