@cj-tech-master/excelts 6.2.0 → 7.0.0-canary.20260329132155.5bf7cee

package/README.md

@@ -6,15 +6,12 @@ Modern TypeScript Excel Workbook Manager - Read, manipulate and write spreadshee
 
 ## About This Project
 
-ExcelTS is a modern TypeScript Excel workbook manager with:
+ExcelTS is a zero-dependency TypeScript toolkit for spreadsheets and documents:
 
-- 🚀 **Zero Runtime Dependencies** - Pure TypeScript implementation with no external packages
-- ✅ **Broad Runtime Support** - LTS Node.js, Bun, and modern browsers (Chrome, Firefox, Safari, Edge)
-- ✅ **Full TypeScript Support** - Complete type definitions and modern TypeScript patterns
-- ✅ **Modern Build System** - Using Rolldown for faster builds
-- ✅ **Enhanced Testing** - Migrated to Vitest with browser testing support
-- ✅ **ESM First** - Native ES Module support with CommonJS compatibility
-- ✅ **Named Exports** - All exports are named for better tree-shaking
+- 🚀 **Zero Runtime Dependencies** — Pure TypeScript, no external packages
+- 📦 **Five Modules** — Excel (XLSX/JSON), PDF (standalone engine + Excel bridge), CSV (RFC 4180), Archive (ZIP/TAR), Stream (cross-platform)
+- ✅ **Cross-Platform** — Node.js 22+, Bun, Chrome 89+, Firefox 102+, Safari 14.1+
+- ✅ **ESM First** — Native ES Modules with CommonJS compatibility and full tree-shaking
 
 ## Translations
 
@@ -104,7 +101,7 @@ cell.fill = {
   - Pivot tables
 
 - **PDF Export**
-  - Zero-dependency Excel-to-PDF conversion
+  - Full-featured, zero-dependency PDF engine (standalone or with Excel)
   - Full cell styling (fonts, colors, borders, fills, alignment)
   - Automatic pagination with repeat header rows
   - TrueType font embedding for Unicode/CJK text
@@ -141,7 +138,7 @@ import { Readable, pipeline, createTransform } from "@cj-tech-master/excelts/str
 
 Each subpath supports `browser`, `import` (ESM), and `require` (CJS) conditions. See the module READMEs for details:
 
-- [PDF Module](src/modules/pdf/README.md) - Zero-dependency Excel-to-PDF export with encryption and font embedding
+- [PDF Module](src/modules/pdf/README.md) - Full-featured zero-dependency PDF engine with encryption and font embedding
 - [CSV Module](src/modules/csv/README.md) - RFC 4180 parser/formatter, streaming, data generation
 - [Archive Module](src/modules/archive/README.md) - ZIP/TAR create/read/edit, compression, encryption
 - [Stream Module](src/modules/stream/README.md) - Cross-platform Readable/Writable/Transform/Duplex
@@ -151,7 +148,7 @@ Each subpath supports `browser`, `import` (ESM), and `require` (CJS) conditions.
 Export any workbook to PDF with zero external dependencies:
 
 ```javascript
-import { Workbook, exportPdf } from "@cj-tech-master/excelts";
+import { Workbook, excelToPdf } from "@cj-tech-master/excelts";
 
 const workbook = new Workbook();
 const sheet = workbook.addWorksheet("Report");
@@ -163,7 +160,7 @@ sheet.addRow({ product: "Widget", revenue: 1000 });
 sheet.getColumn("revenue").numFmt = "$#,##0.00";
 
 // One-line export
-const pdf = exportPdf(workbook, {
+const pdf = excelToPdf(workbook, {
   showGridLines: true,
   showPageNumbers: true,
   title: "Sales Report"
@@ -184,13 +181,13 @@ window.open(url);
 ```javascript
 const workbook = new Workbook();
 await workbook.xlsx.readFile("input.xlsx");
-const pdf = exportPdf(workbook);
+const pdf = excelToPdf(workbook);
 ```
 
 ### Encryption
 
 ```javascript
-const pdf = exportPdf(workbook, {
+const pdf = excelToPdf(workbook, {
   encryption: {
     ownerPassword: "admin",
     userPassword: "reader",
@@ -204,11 +201,42 @@ const pdf = exportPdf(workbook, {
 ```javascript
 import { readFileSync } from "fs";
 
-const pdf = exportPdf(workbook, {
+const pdf = excelToPdf(workbook, {
   font: readFileSync("NotoSansSC-Regular.ttf") // TrueType font for CJK text
 });
 ```
 
+### Standalone PDF (No Excel)
+
+Generate PDFs from plain data — no workbook, no Map objects, no boilerplate:
+
+```javascript
+import { pdf } from "@cj-tech-master/excelts/pdf";
+
+// Simplest — pass a 2D array
+const bytes = pdf([
+  ["Product", "Revenue"],
+  ["Widget", 1000],
+  ["Gadget", 2500]
+]);
+
+// With column widths and styled cells
+const bytes = pdf(
+  {
+    name: "Report",
+    columns: [
+      { width: 25, header: "Product" },
+      { width: 15, header: "Revenue" }
+    ],
+    data: [
+      ["Widget", 1000],
+      ["Gadget", 2500]
+    ]
+  },
+  { showGridLines: true }
+);
+```
+
 For the full API reference and all options, see the [PDF Module documentation](src/modules/pdf/README.md).
 
 ## Archive Utilities (ZIP/TAR)
@@ -506,8 +534,8 @@ import {
   xmlDecode,
 
   // PDF export
-  exportPdf, // Workbook -> Uint8Array (PDF)
-  PdfExporter, // Class-based PDF export
+  pdf, // Simplest: pdf([["A", 1], ["B", 2]]) → Uint8Array
+  excelToPdf, // Workbook -> Uint8Array (Excel-to-PDF)
   PageSizes, // Built-in page size definitions
   PdfError, // Base PDF error
   PdfRenderError, // Layout/rendering failures

package/README_zh.md

@@ -6,15 +6,12 @@
 
 ## 关于本项目
 
-ExcelTS 是现代化的 TypeScript Excel 工作簿管理器，具有以下特性:
+ExcelTS 是零依赖的 TypeScript 电子表格与文档工具包：
 
-- 🚀 **零运行时依赖** - 纯 TypeScript 实现，无任何外部包依赖
-- ✅ **广泛运行时支持** - 支持 LTS Node.js、Bun 及主流最新浏览器（Chrome、Firefox、Safari、Edge）
-- ✅ **完整的 TypeScript 支持** - 完整的类型定义和现代 TypeScript 模式
-- ✅ **现代构建系统** - 使用 Rolldown 进行更快的构建
-- ✅ **增强的测试** - 迁移到 Vitest 并支持浏览器测试
-- ✅ **ESM 优先** - 原生 ES Module 支持，兼容 CommonJS
-- ✅ **命名导出** - 所有导出都是命名导出，更好的 tree-shaking
+- 🚀 **零运行时依赖** — 纯 TypeScript 实现，无任何外部包依赖
+- 📦 **五大模块** — Excel（XLSX/JSON）、PDF（独立引擎 + Excel 桥接）、CSV（RFC 4180）、Archive（ZIP/TAR）、Stream（跨平台）
+- ✅ **跨平台** — Node.js 22+、Bun、Chrome 89+、Firefox 102+、Safari 14.1+
+- ✅ **ESM 优先** — 原生 ES Modules，兼容 CommonJS，完整 tree-shaking 支持
 
 ## 翻译
 
@@ -151,7 +148,7 @@ import { Readable, pipeline, createTransform } from "@cj-tech-master/excelts/str
 零依赖将任意工作簿导出为 PDF：
 
 ```javascript
-import { Workbook, exportPdf } from "@cj-tech-master/excelts";
+import { Workbook, excelToPdf } from "@cj-tech-master/excelts";
 
 const workbook = new Workbook();
 const sheet = workbook.addWorksheet("报告");
@@ -163,7 +160,7 @@ sheet.addRow({ product: "组件A", revenue: 1000 });
 sheet.getColumn("revenue").numFmt = "¥#,##0.00";
 
 // 一行导出
-const pdf = exportPdf(workbook, {
+const pdf = excelToPdf(workbook, {
   showGridLines: true,
   showPageNumbers: true,
   title: "销售报告"
@@ -184,13 +181,13 @@ window.open(url);
 ```javascript
 const workbook = new Workbook();
 await workbook.xlsx.readFile("input.xlsx");
-const pdf = exportPdf(workbook);
+const pdf = excelToPdf(workbook);
 ```
 
 ### 加密
 
 ```javascript
-const pdf = exportPdf(workbook, {
+const pdf = excelToPdf(workbook, {
   encryption: {
     ownerPassword: "admin",
     userPassword: "reader",
@@ -204,11 +201,42 @@ const pdf = exportPdf(workbook, {
 ```javascript
 import { readFileSync } from "fs";
 
-const pdf = exportPdf(workbook, {
+const pdf = excelToPdf(workbook, {
   font: readFileSync("NotoSansSC-Regular.ttf") // 嵌入 TrueType 字体以支持中文
 });
 ```
 
+### 独立 PDF 生成（无需 Excel）
+
+无需工作簿，直接从数组数据生成 PDF：
+
+```javascript
+import { pdf } from "@cj-tech-master/excelts/pdf";
+
+// 最简方式 — 传入二维数组
+const bytes = pdf([
+  ["产品", "收入"],
+  ["组件A", 1000],
+  ["组件B", 2500]
+]);
+
+// 带列宽和样式
+const bytes = pdf(
+  {
+    name: "报告",
+    columns: [
+      { width: 25, header: "产品" },
+      { width: 15, header: "收入" }
+    ],
+    data: [
+      ["组件A", 1000],
+      ["组件B", 2500]
+    ]
+  },
+  { showGridLines: true }
+);
+```
+
 完整 API 参考和所有选项请查看 [PDF 模块文档](src/modules/pdf/README.md)。
 
 ## 归档工具（ZIP/TAR）
@@ -504,8 +532,8 @@ import {
   xmlDecode,
 
   // PDF 导出
-  exportPdf, // Workbook -> Uint8Array (PDF)
-  PdfExporter, // 基于类的 PDF 导出
+  pdf, // 最简单：pdf([["A", 1], ["B", 2]]) → Uint8Array
+  excelToPdf, // Workbook -> Uint8Array（Excel 转 PDF）
   PageSizes, // 内置页面尺寸定义
   PdfError, // PDF 基础错误
   PdfRenderError, // 布局/渲染错误

package/dist/browser/index.browser.d.ts

@@ -37,6 +37,6 @@ export { xmlEncode, xmlDecode } from "./utils/utils.base.js";
 export { DateParser, DateFormatter, getSupportedFormats, type DateFormat } from "./utils/datetime.js";
 export { BaseError, type BaseErrorOptions, toError, errorToJSON, getErrorChain, getRootCause } from "./utils/errors.js";
 export { concatUint8Arrays, toUint8Array, stringToUint8Array, uint8ArrayToString } from "./utils/binary.js";
-export { PdfExporter, exportPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
+export { pdf, excelToPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
 export type { PdfExportOptions, PdfPageSize, PdfOrientation, PdfMargins, PageSizeName, PdfColor } from "./modules/pdf/index.js";
 export { ExcelError, isExcelError, ExcelFileError, ExcelDownloadError, ExcelNotSupportedError, ExcelStreamStateError, InvalidAddressError, ColumnOutOfBoundsError, RowOutOfBoundsError, MergeConflictError, InvalidValueTypeError, XmlParseError, WorksheetNameError, PivotTableError, TableError, ImageError, MaxItemsExceededError } from "./modules/excel/errors.js";

package/dist/browser/index.browser.js

@@ -58,7 +58,7 @@ export { concatUint8Arrays, toUint8Array, stringToUint8Array, uint8ArrayToString
 // =============================================================================
 // PDF Export (Browser-compatible, zero external dependencies)
 // =============================================================================
-export { PdfExporter, exportPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
+export { pdf, excelToPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
 // =============================================================================
 // Errors
 // =============================================================================

package/dist/browser/index.d.ts

@@ -19,7 +19,7 @@ export type { PivotTable, PivotTableModel, PivotTableValue, PivotTableSource, Ca
 export type { FormCheckboxModel, FormCheckboxOptions, FormControlRange, FormControlAnchor } from "./modules/excel/form-control.js";
 export type { WorkbookReaderOptions, ParseEvent, SharedStringEvent, WorksheetReadyEvent, HyperlinksEvent } from "./modules/excel/stream/workbook-reader.js";
 export type { WorksheetReaderOptions, WorksheetEvent, RowEvent, HyperlinkEvent, WorksheetHyperlink } from "./modules/excel/stream/worksheet-reader.js";
-export type { WorkbookWriterOptions, WorkbookZipOptions, ZipOptions, ZlibOptions } from "./modules/excel/stream/workbook-writer.js";
+export type { WorkbookWriterOptions, WorkbookZipOptions, ZlibOptions } from "./modules/excel/stream/workbook-writer.js";
 export type { CsvOptions, CsvInput } from "./modules/excel/workbook.js";
 export { CsvParserStream, CsvFormatterStream, createCsvParserStream, createCsvFormatterStream } from "./modules/csv/stream/index.js";
 export { DefinedNames, type DefinedNameModel } from "./modules/excel/defined-names.js";
@@ -37,6 +37,6 @@ export { xmlEncode, xmlDecode } from "./utils/utils.base.js";
 export { DateParser, DateFormatter, getSupportedFormats, type DateFormat } from "./utils/datetime.js";
 export { BaseError, type BaseErrorOptions, toError, errorToJSON, getErrorChain, getRootCause } from "./utils/errors.js";
 export { concatUint8Arrays, toUint8Array, stringToUint8Array, uint8ArrayToString } from "./utils/binary.js";
-export { PdfExporter, exportPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
+export { pdf, excelToPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
 export type { PdfExportOptions, PdfPageSize, PdfOrientation, PdfMargins, PageSizeName, PdfColor } from "./modules/pdf/index.js";
 export { ExcelError, isExcelError, ExcelFileError, ExcelDownloadError, ExcelNotSupportedError, ExcelStreamStateError, InvalidAddressError, ColumnOutOfBoundsError, RowOutOfBoundsError, MergeConflictError, InvalidValueTypeError, XmlParseError, WorksheetNameError, PivotTableError, TableError, ImageError, MaxItemsExceededError } from "./modules/excel/errors.js";

package/dist/browser/index.js

@@ -54,7 +54,7 @@ export { concatUint8Arrays, toUint8Array, stringToUint8Array, uint8ArrayToString
 // =============================================================================
 // PDF Export
 // =============================================================================
-export { PdfExporter, exportPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
+export { pdf, excelToPdf, PageSizes, PdfError, PdfRenderError, PdfFontError, PdfStructureError, isPdfError } from "./modules/pdf/index.js";
 // =============================================================================
 // Errors
 // =============================================================================

package/dist/browser/modules/archive/unzip/stream.base.js

@@ -4,6 +4,46 @@ import { ByteQueue } from "../shared/byte-queue.js";
 import { EMPTY_UINT8ARRAY } from "../shared/bytes.js";
 import { decodeZipPath, resolveZipStringCodec } from "../shared/text.js";
 import { PatternScanner } from "./pattern-scanner.js";
+/**
+ * Returns true when `err` is the Node.js ERR_STREAM_PREMATURE_CLOSE error.
+ *
+ * This error is emitted by `finished()` / `pipeline()` when a stream is
+ * destroyed before it has properly ended (e.g. a consumer breaks out of a
+ * `for await` loop, or the entry PassThrough is destroyed by an external
+ * consumer). In the context of ZIP parsing, a premature close on an *entry*
+ * stream is not a fatal error — the parse loop only needs to advance the ZIP
+ * cursor past the entry's compressed data.
+ */
+function isPrematureCloseError(err) {
+    if (!(err instanceof Error)) {
+        return false;
+    }
+    return err.code === "ERR_STREAM_PREMATURE_CLOSE" || err.message === "Premature close";
+}
+/**
+ * Wait for an entry's writable side to finish, tolerating premature close.
+ *
+ * The parse loop calls this after pumping all compressed data into an entry.
+ * It ensures the decompressed data has been flushed through the inflater →
+ * entry pipeline before advancing the ZIP cursor.
+ *
+ * If the consumer has already destroyed / autodraining the entry (e.g. early
+ * break, external destroy, Readable.from() wrapper), `finished()` rejects
+ * with ERR_STREAM_PREMATURE_CLOSE. This is not an error for the parse loop
+ * — the compressed data has been fully read from the ZIP cursor, so we
+ * can safely continue.
+ */
+async function awaitEntryCompletion(entry) {
+    try {
+        await finished(entry, { readable: false });
+    }
+    catch (err) {
+        if (!isPrematureCloseError(err)) {
+            throw err;
+        }
+        // Entry was destroyed/autodraining — treat as normal completion.
+    }
+}
 import { DEFAULT_PARSE_THRESHOLD_BYTES, buildZipEntryProps, getZipEntryType, hasDataDescriptorFlag, isFileSizeKnown, parseExtraField, readDataDescriptor, readLocalFileHeader, resolveZipEntryLastModifiedDateTime, runParseLoopCore, isValidZipRecordSignature } from "./parser-core.js";
 export const DEFAULT_UNZIP_STREAM_HIGH_WATER_MARK = 256 * 1024;
 export function autodrain(stream) {
@@ -415,6 +455,7 @@ export function streamUntilValidatedDataDescriptor(options) {
         }
         while (available > 0) {
             // Try to find and validate a descriptor candidate.
+            let pendingCandidate = false;
             while (true) {
                 const idx = scanner.find(source);
                 if (idx === -1) {
@@ -472,15 +513,67 @@ export function streamUntilValidatedDataDescriptor(options) {
                     scanner.searchFrom = idx + 1;
                     continue;
                 }
-                // Not enough bytes to validate yet. Re-check this candidate once more bytes arrive.
+                // Not enough bytes to validate yet. Re-check this candidate once
+                // more bytes arrive. Mark as pending so we don't accidentally
+                // advance searchFrom past it via onNoMatch().
                 scanner.searchFrom = idx;
+                pendingCandidate = true;
+                // If the source is finished (no more bytes will arrive), attempt a
+                // relaxed validation: accept the descriptor without checking the
+                // next-record signature. This handles the case where the descriptor
+                // is at the very end of the available data (e.g. the last entry in
+                // the ZIP, or the next-record header hasn't been fully buffered yet
+                // due to extreme input fragmentation).
+                if (source.isFinished() && idx + 16 <= available) {
+                    const descriptorCompressedSize = source.peekUint32LE(idx + 8);
+                    const expectedCompressedSize = (bytesEmitted + idx) >>> 0;
+                    if (descriptorCompressedSize !== null &&
+                        descriptorCompressedSize === expectedCompressedSize) {
+                        // Descriptor compressed size matches — accept it.
+                        if (idx > 0) {
+                            if (source.peekChunks && source.discard) {
+                                const parts = source.peekChunks(idx);
+                                let written = 0;
+                                for (const part of parts) {
+                                    output.write(part);
+                                    written += part.length;
+                                }
+                                if (written > 0) {
+                                    source.discard(written);
+                                    bytesEmitted += written;
+                                    scanner.onConsume(written);
+                                }
+                            }
+                            else {
+                                output.write(source.read(idx));
+                                bytesEmitted += idx;
+                                scanner.onConsume(idx);
+                            }
+                        }
+                        done = true;
+                        source.maybeReleaseWriteCallback?.();
+                        cleanup();
+                        output.end();
+                        return;
+                    }
+                }
                 break;
             }
-            // No validated match yet.
-            scanner.onNoMatch(available);
+            // Only advance the scanner's search cursor when there is no pending
+            // candidate waiting for more bytes. Without this guard, onNoMatch()
+            // would move searchFrom past the candidate, causing it to be skipped
+            // and the entry data to be flushed — leading to FILE_ENDED.
+            if (!pendingCandidate) {
+                scanner.onNoMatch(available);
+            }
             // Flush most of the buffered data but keep a tail so a potential signature
             // split across chunks can still be detected/validated.
-            const flushLen = Math.max(0, available - keepTailBytes);
+            // When a pending candidate exists, do NOT flush past it.
+            let maxFlush = available - keepTailBytes;
+            if (pendingCandidate) {
+                maxFlush = Math.min(maxFlush, scanner.searchFrom);
+            }
+            const flushLen = Math.max(0, maxFlush);
             if (flushLen > 0) {
                 if (source.peekChunks && source.discard) {
                     const parts = source.peekChunks(flushLen);
@@ -673,7 +766,7 @@ async function pumpKnownCompressedSizeToEntry(io, inflater, entry, compressedSiz
             inflater.end();
         }
         // Wait for all writes to complete (not for consumption).
-        await finished(entry, { readable: false });
+        await awaitEntryCompletion(entry);
     }
     finally {
         inflater.removeListener("error", onError);
@@ -787,8 +880,8 @@ async function readFileRecord(opts, io, emitter, inflateFactory, state, threshol
         const compressedData = await io.pull(compressedSize);
         const decompressedData = inflateRawSync(compressedData);
         entry.end(decompressedData);
-        // Wait for entry stream write to complete (not for read/consume)
-        await finished(entry, { readable: false });
+        // Wait for entry stream write to complete (not for read/consume).
+        await awaitEntryCompletion(entry);
         return;
     }
     const inflater = needsInflate
@@ -807,7 +900,30 @@ async function readFileRecord(opts, io, emitter, inflateFactory, state, threshol
         }
         return;
     }
-    await pipeline(io.streamUntilDataDescriptor(), inflater, entry);
+    // pipeline() destroys all streams if any stream errors or closes early.
+    // If the entry was destroyed by the consumer, pipeline rejects with
+    // ERR_STREAM_PREMATURE_CLOSE. This typically happens when the entry's
+    // writable side is force-destroyed and the entire parse operation is
+    // being torn down (abort/error).
+    try {
+        await pipeline(io.streamUntilDataDescriptor(), inflater, entry);
+    }
+    catch (pipelineErr) {
+        if (!isPrematureCloseError(pipelineErr)) {
+            throw pipelineErr;
+        }
+        // Entry was destroyed — attempt to read the data descriptor; if it
+        // fails (cursor misaligned), swallow the error since the entry was
+        // abandoned and the operation is ending.
+        try {
+            const dd = await readDataDescriptor(async (l) => io.pull(l));
+            entry.size = dd.uncompressedSize ?? 0;
+        }
+        catch {
+            // Cursor misaligned — not recoverable but not worth surfacing.
+        }
+        return;
+    }
     const dd = await readDataDescriptor(async (l) => io.pull(l));
     entry.size = dd.uncompressedSize ?? 0;
 }

package/dist/browser/modules/archive/unzip/stream.browser.js

@@ -488,7 +488,26 @@ export function createParseClass(createInflateRawFn) {
             this.finished = false;
             this._driverState = {};
             this._parsingDone = Promise.resolve();
+            // ---------------------------------------------------------------
+            // Parser completion — explicit deferred, independent of stream
+            // lifecycle events. Mirrors the Node.js Parse implementation.
+            // ---------------------------------------------------------------
+            this._parserDoneFlag = false;
+            this._parserError = null;
+            this._parserDeferred = null;
+            this._parserDonePromise = null;
+            // ---------------------------------------------------------------
+            // Entry queue — custom [Symbol.asyncIterator] reads from here.
+            // ---------------------------------------------------------------
+            this._entryQueue = [];
+            this._entryWaiter = null;
+            this._entriesDone = false;
             this._opts = opts;
+            // Route error events to the parser deferred.
+            this.on("error", (err) => {
+                this._rejectParserDeferred(err);
+                this._closeEntryQueue(err);
+            });
             // Default values are intentionally conservative to avoid memory spikes
             // when parsing large archives under slow consumers.
             const hi = Math.max(64 * 1024, opts.inputHighWaterMarkBytes ?? 2 * 1024 * 1024);
@@ -510,10 +529,13 @@ export function createParseClass(createInflateRawFn) {
                 },
                 pushEntry: (entry) => {
                     this.push(entry);
+                    this._enqueueEntry(entry);
                 },
                 // Browser version historically only pushed entries when forceStream=true.
                 // Keep this behavior to avoid changing stream piping semantics.
                 pushEntryIfPiped: (_entry) => {
+                    // Always feed the entry queue regardless of pipe state.
+                    this._enqueueEntry(_entry);
                     return;
                 },
                 emitCrxHeader: (header) => {
@@ -522,12 +544,6 @@ export function createParseClass(createInflateRawFn) {
                 },
                 emitError: (err) => {
                     this.__emittedError = err;
-                    // Ensure upstream writers don't hang waiting for a deferred write callback.
-                    if (this._writeCb) {
-                        const cb = this._writeCb;
-                        this._writeCb = undefined;
-                        cb(err);
-                    }
                     this.emit("error", err);
                 },
                 emitClose: () => {
@@ -556,11 +572,22 @@ export function createParseClass(createInflateRawFn) {
                 this._parsingDone = runParseLoop(this._opts, io, emitter, inflateFactory, this._driverState
                 // No inflateRawSync - always use streaming DecompressionStream in browser
                 );
-                this._parsingDone.catch((e) => {
+                this._parsingDone.then(() => {
+                    if (this.__emittedError) {
+                        this._rejectParserDeferred(this.__emittedError);
+                        this._closeEntryQueue(this.__emittedError);
+                    }
+                    else {
+                        this._resolveParserDeferred();
+                        this._closeEntryQueue();
+                    }
+                }, (e) => {
                     if (!this.__emittedError || this.__emittedError !== e) {
                         this.__emittedError = e;
                         this.emit("error", e);
                     }
+                    this._rejectParserDeferred(e);
+                    this._closeEntryQueue(e);
                     this.emit("close");
                 });
             });
@@ -864,11 +891,99 @@ export function createParseClass(createInflateRawFn) {
             });
         }
         promise() {
-            return new Promise((resolve, reject) => {
-                this.on("finish", resolve);
-                this.on("end", resolve);
-                this.on("error", reject);
+            if (this._parserDoneFlag) {
+                return this._parserError ? Promise.reject(this._parserError) : Promise.resolve();
+            }
+            if (this._parserDonePromise) {
+                return this._parserDonePromise;
+            }
+            this._parserDonePromise = new Promise((resolve, reject) => {
+                this._parserDeferred = { resolve, reject };
             });
+            return this._parserDonePromise;
+        }
+        // ---------------------------------------------------------------
+        // Parser completion deferred
+        // ---------------------------------------------------------------
+        _resolveParserDeferred() {
+            if (this._parserDoneFlag) {
+                return;
+            }
+            this._parserDoneFlag = true;
+            if (this._parserDeferred) {
+                const { resolve } = this._parserDeferred;
+                this._parserDeferred = null;
+                resolve();
+            }
+        }
+        _rejectParserDeferred(err) {
+            if (this._parserDoneFlag) {
+                return;
+            }
+            this._parserDoneFlag = true;
+            this._parserError = err;
+            if (this._parserDeferred) {
+                const { reject } = this._parserDeferred;
+                this._parserDeferred = null;
+                reject(err);
+            }
+        }
+        // ---------------------------------------------------------------
+        // Entry queue management
+        // ---------------------------------------------------------------
+        _enqueueEntry(entry) {
+            if (this._entryWaiter) {
+                const { resolve } = this._entryWaiter;
+                this._entryWaiter = null;
+                resolve({ value: entry, done: false });
+            }
+            else {
+                this._entryQueue.push(entry);
+            }
+        }
+        _closeEntryQueue(err) {
+            this._entriesDone = true;
+            if (this._entryWaiter) {
+                const waiter = this._entryWaiter;
+                this._entryWaiter = null;
+                if (err) {
+                    waiter.reject(err);
+                }
+                else {
+                    waiter.resolve({ value: undefined, done: true });
+                }
+            }
+        }
+        // ---------------------------------------------------------------
+        // Custom async iterator
+        // ---------------------------------------------------------------
+        [Symbol.asyncIterator]() {
+            const iterator = {
+                next: () => {
+                    if (this._entryQueue.length > 0) {
+                        return Promise.resolve({ value: this._entryQueue.shift(), done: false });
+                    }
+                    if (this._entriesDone) {
+                        if (this._parserError) {
+                            return Promise.reject(this._parserError);
+                        }
+                        return Promise.resolve({ value: undefined, done: true });
+                    }
+                    return new Promise((resolve, reject) => {
+                        this._entryWaiter = { resolve, reject };
+                    });
+                },
+                return: () => {
+                    this._entriesDone = true;
+                    this._entryQueue.length = 0;
+                    this._entryWaiter = null;
+                    return Promise.resolve({ value: undefined, done: true });
+                },
+                [Symbol.asyncIterator]() {
+                    return iterator;
+                }
+            };
+            return iterator;
         }
     };
 }