documonster 0.20.0 → 0.20.1

package/README.md

@@ -211,7 +211,7 @@ const buffer = await Workbook.toBuffer(wb);
 
 ```html
 <!-- Script tag (no bundler) — one IIFE per module, each under the shared `Documonster` global -->
-<script src="https://unpkg.com/documonster@0.20.0/dist/iife/documonster.excel.iife.min.js"></script>
+<script src="https://unpkg.com/documonster@0.20.1/dist/iife/documonster.excel.iife.min.js"></script>
 <script>
   const { Workbook, Cell } = Documonster.Excel;
   const wb = Workbook.create();

package/README_zh.md

@@ -198,7 +198,7 @@ const buffer = await Workbook.toBuffer(wb);
 
 ```html
 <!-- Script 标签（无需打包工具）— 每个模块一个 IIFE，共享同一个 `Documonster` 全局 -->
-<script src="https://unpkg.com/documonster@0.20.0/dist/iife/documonster.excel.iife.min.js"></script>
+<script src="https://unpkg.com/documonster@0.20.1/dist/iife/documonster.excel.iife.min.js"></script>
 <script>
   const { Workbook, Cell } = Documonster.Excel;
   const wb = Workbook.create();

package/dist/esm/modules/archive/compression/deflate-fallback.js

@@ -686,75 +686,45 @@ function buildCodeLengths(freqs, maxBits) {
         }
     }
     extractDepths(root, 0);
-    // --- Length limiting using the zlib bl_count redistribution algorithm ---
-    // Count code lengths at each bit depth
+    // --- Length limiting (zlib's gen_bitlen overflow handling) ---
+    //
+    // A Huffman tree over 286 symbols can be deeper than DEFLATE's 15 bits. Clamping the deep leaves to `maxBits`
+    // over-subscribes the code; it is then repaired one unit at a time by turning a leaf at the deepest length below
+    // `maxBits` into a node with two children one level down, and removing one leaf at `maxBits`. That keeps the number
+    // of leaves and lowers the Kraft sum by exactly one, so the code ends exactly complete — which zlib requires: an
+    // incomplete literal/length code is "invalid literal/lengths set", and every browser's DecompressionStream is zlib.
+    // The previous repair overshot and padded with phantom codes, which took real symbols' places and left the code
+    // incomplete: only this library's lenient inflater could read it back.
     const blCount = new Uint16Array(maxBits + 1);
     for (let i = 0; i < n; i++) {
         if (codeLens[i] > 0) {
-            if (codeLens[i] > maxBits) {
-                blCount[maxBits]++;
-                codeLens[i] = maxBits;
-            }
-            else {
-                blCount[codeLens[i]]++;
-            }
+            blCount[Math.min(codeLens[i], maxBits)]++;
         }
     }
-    // Check Kraft inequality: sum of 2^(maxBits - len) must equal 2^maxBits
+    const target = 1 << maxBits;
     let kraft = 0;
     for (let bits = 1; bits <= maxBits; bits++) {
         kraft += blCount[bits] << (maxBits - bits);
     }
-    const target = 1 << maxBits;
     if (kraft === target) {
-        return codeLens; // Already valid
+        return codeLens;
     }
-    // Redistribute to satisfy Kraft's inequality.
-    // Strategy: move symbols from shorter lengths to maxBits until balanced.
-    // Each symbol moved from length `bits` to `maxBits` reduces kraft by
-    // (2^(maxBits-bits) - 1) — we remove a large weight and add a weight of 1.
     while (kraft > target) {
-        // Find a code length < maxBits that has symbols we can push down.
-        // Start from maxBits-1 to minimize the damage per move.
         let bits = maxBits - 1;
-        while (bits > 0 && blCount[bits] === 0) {
+        while (blCount[bits] === 0) {
             bits--;
         }
-        if (bits === 0) {
-            break; // Can't redistribute further
-        }
-        // Move one symbol from length `bits` to length `maxBits`
         blCount[bits]--;
-        blCount[maxBits]++;
-        // Kraft change: removed 2^(maxBits-bits), added 2^0 = 1
-        kraft -= (1 << (maxBits - bits)) - 1;
-    }
-    // If kraft < target (under-allocated), add dummy codes at maxBits.
-    // This can happen when we overshoot during redistribution.
-    while (kraft < target) {
-        blCount[maxBits]++;
-        kraft++;
-    }
-    // Reassign code lengths to symbols (preserve relative order: longer
-    // codes go to less frequent symbols, matching the Huffman property).
-    // Sort symbols by their original code length (longest first), then by
-    // frequency (rarest first) for same length.
-    const symbolsByLen = [];
-    for (let i = 0; i < n; i++) {
-        if (codeLens[i] > 0) {
-            symbolsByLen.push({ sym: i, origLen: codeLens[i], freq: freqs[i] });
-        }
+        blCount[bits + 1] += 2;
+        blCount[maxBits]--;
+        kraft--;
     }
-    symbolsByLen.sort((a, b) => b.origLen - a.origLen || a.freq - b.freq);
-    // Assign new lengths from the bl_count distribution
-    codeLens.fill(0);
-    let symIdx = 0;
+    // Hand the lengths out again, longest to the rarest symbols, as the Huffman tree would have.
+    const bySymbolRarity = activeSymbols.slice().sort((a, b) => a.freq - b.freq || b.sym - a.sym);
+    let next = 0;
     for (let bits = maxBits; bits >= 1; bits--) {
         for (let count = blCount[bits]; count > 0; count--) {
-            if (symIdx < symbolsByLen.length) {
-                codeLens[symbolsByLen[symIdx].sym] = bits;
-                symIdx++;
-            }
+            codeLens[bySymbolRarity[next++].sym] = bits;
         }
     }
     return codeLens;

package/dist/esm/modules/archive/compression/streaming-compress.js

@@ -153,10 +153,11 @@ export class SyncDeflater {
     _flushBatch(final) {
         let input;
         if (this._pending.length === 0) {
-            input = Buffer.alloc(0);
+            input = new Uint8Array(0);
         }
         else if (this._pending.length === 1) {
-            input = Buffer.from(this._pending[0]);
+            // zlib reads a `Uint8Array` as it is; copying it into a `Buffer` first only cost a second pass over the batch.
+            input = this._pending[0];
         }
         else {
             input = Buffer.concat(this._pending);

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

@@ -5,7 +5,7 @@ import { PullStream, runParseLoop, streamUntilValidatedDataDescriptor } from "./
  * Creates an InflateRaw stream using Node.js native zlib.
  */
 function createInflateRaw() {
-    return zlib.createInflateRaw();
+    return zlib.createInflateRaw({ chunkSize: 64 * 1024 });
 }
 const dataDescriptorSignature = DATA_DESCRIPTOR_SIGNATURE_BYTES;
 export function createParseClass(createInflateRawFn) {

package/dist/esm/modules/csv/stream/parser.js

@@ -869,7 +869,11 @@ export class CsvParserStream extends Transform {
         // Fast mode already split this record by its configured `lineEnding`; with a custom
         // separator, CR and LF in `raw` are ordinary content and must not alter `line`,
         // skipLines or toLine.
-        if (raw !== undefined && !this.parseConfig.fastMode) {
+        if (raw !== undefined &&
+            !this.parseConfig.fastMode &&
+            // A row holds a line break only inside a quoted field, which almost none do: a native search rules it out
+            // without walking every character of every row in script.
+            (raw.indexOf("\n") !== -1 || raw.indexOf("\r") !== -1)) {
             let newlines = 1;
             for (let i = 0; i < raw.length; i++) {
                 const ch = raw.charCodeAt(i);

package/dist/esm/modules/excel/stream/workbook-reader.browser.js

@@ -10,7 +10,7 @@
  */
 import { FileTooLargeError } from "../../archive/core/errors.js";
 import { createParse } from "#platform/modules/archive/unzip/stream";
-import { ExcelFileError } from "../errors.js";
+import { ExcelFileError, ExcelStreamStateError } from "../errors.js";
 import { HyperlinkReader } from "./hyperlink-reader.js";
 import { WorksheetReader } from "./worksheet-reader.js";
 import { XlsbWorksheetReader } from "./xlsb-worksheet-stream-reader.js";
@@ -97,6 +97,57 @@ function boundedPart(entry, limit) {
     entry.on("error", (err) => bounded.destroy(err));
     return entry.pipe(bounded);
 }
+export function handOut(source, what) {
+    let state = "unread";
+    const iterator = source[Symbol.asyncIterator]();
+    async function* chunks() {
+        if (state === "skipped") {
+            throw new ExcelStreamStateError(`read ${what}`, "the workbook reader had already moved past it; read each part before asking for the next");
+        }
+        state = "reading";
+        try {
+            // Not `yield* source`: a caller leaving early must not close the underlying iterator, because what it has not
+            // read still has to be drained through it — see `drain`.
+            for (let next = await iterator.next(); !next.done; next = await iterator.next()) {
+                yield next.value;
+            }
+            state = "done";
+        }
+        finally {
+            if (state !== "done") {
+                state = "left";
+            }
+        }
+    }
+    return {
+        chunks: chunks(),
+        finish() {
+            if (state === "unread") {
+                state = "skipped";
+                return "all";
+            }
+            return state === "left" ? "rest" : "nothing";
+        },
+        async drain() {
+            while (!(await iterator.next()).done) {
+                // discarded
+            }
+        }
+    };
+}
+/** Let the archive move past a ZIP part the caller did not read to the end. */
+async function releasePart(entry, part, viaStream) {
+    const left = part.finish();
+    if (left === "all" && !viaStream) {
+        // Untouched: the unzipper can skip its compressed bytes without inflating them, as for any part not asked for.
+        entry.autodrain();
+    }
+    else if (left !== "nothing") {
+        // Partly read, or behind a stream that already holds some of it: read the rest through the reader's own iterator,
+        // the path a full read takes, rather than switching the entry to a skip half-way.
+        await part.drain();
+    }
+}
 // ============================================================================
 // Base Class
 // ============================================================================
@@ -208,7 +259,9 @@ export class WorkbookReaderBase extends EventEmitter {
                         await value.read();
                         break;
                     case "hyperlinks":
+                        // Read here as a worksheet is: the archive cannot move past the part until it has been consumed.
                         this.emit(eventType, value);
+                        await value.read();
                         break;
                 }
             }
@@ -224,6 +277,11 @@ export class WorkbookReaderBase extends EventEmitter {
             if (eventType === "worksheet") {
                 yield value;
             }
+            else if (eventType === "hyperlinks") {
+                // This iterator yields worksheets only, so nothing else can consume the part, and the archive cannot move
+                // past it until something does.
+                await value.read();
+            }
         }
     }
     async *parse(input, options) {
@@ -680,6 +738,7 @@ export class WorkbookReaderBase extends EventEmitter {
             }
         });
         stream.pipe(zip);
+        const emitWorksheets = this.options.worksheets === "emit";
         for await (const entry of iterateStream(zip)) {
             let sheetNo;
             const normalizedPath = normalizeZipPath(entry.path);
@@ -727,19 +786,25 @@ export class WorkbookReaderBase extends EventEmitter {
                         default:
                             break;
                     }
-                    sheetNo = getXlsbWorksheetNo(normalizedPath)?.toString();
+                    // A part the caller has not asked for is not opened at all: it falls through to `autodrain`. One that is handed
+                    // out is drained once the caller moves past it — see `handOut`.
+                    sheetNo = emitWorksheets ? getXlsbWorksheetNo(normalizedPath)?.toString() : undefined;
                     if (sheetNo) {
                         // The same prerequisite test the XML branch makes, for the same reason: a cell record holds an index into
                         // the shared-string table rather than a string, so a sheet that arrives first has to be spooled and come
                         // back later. `_storeWaitingWorksheet` is shared.
                         if (this._xlsbSharedStrings !== undefined && !!this._xlsbWorkbook) {
-                            yield* this._parseXlsbWorksheet(iterateStream(entry), sheetNo);
+                            const part = handOut(iterateStream(entry), `worksheet ${sheetNo}`);
+                            yield* this._parseXlsbWorksheet(part.chunks, sheetNo);
+                            await releasePart(entry, part, false);
                             continue;
                         }
                         yield { eventType: "waiting-worksheet", sheetNo, entry };
                         continue;
                     }
-                    sheetNo = getWorksheetNoFromWorksheetPath(normalizedPath)?.toString();
+                    sheetNo = emitWorksheets
+                        ? getWorksheetNoFromWorksheetPath(normalizedPath)?.toString()
+                        : undefined;
                     if (sheetNo) {
                         // Performance: only wait for sharedStrings when they are actually needed.
                         // Also require workbook.xml to be parsed so worksheet name, id, and state
@@ -748,7 +813,9 @@ export class WorkbookReaderBase extends EventEmitter {
                             !!this.model &&
                             (this.options.sharedStrings !== "cache" || !!this.sharedStrings);
                         if (hasPrerequisites) {
-                            yield* this._parseWorksheet(iterateStream(entry), sheetNo);
+                            const part = handOut(iterateStream(entry), `worksheet ${sheetNo}`);
+                            yield* this._parseWorksheet(part.chunks, sheetNo);
+                            await releasePart(entry, part, false);
                             continue;
                         }
                         else {
@@ -757,8 +824,12 @@ export class WorkbookReaderBase extends EventEmitter {
                         }
                     }
                     sheetNo = getWorksheetNoFromWorksheetRelsPath(normalizedPath)?.toString();
-                    if (sheetNo) {
-                        yield* this._parseHyperlinks(iterateStream(boundedPart(entry, this._maxEntrySize)), sheetNo);
+                    if (sheetNo &&
+                        (this.options.hyperlinks === "cache" || this.options.hyperlinks === "emit")) {
+                        const source = boundedPart(entry, this._maxEntrySize);
+                        const part = handOut(iterateStream(source), `the hyperlinks of sheet ${sheetNo}`);
+                        yield* this._parseHyperlinks(part.chunks, sheetNo);
+                        await releasePart(entry, part, true);
                         continue;
                     }
                     break;
@@ -805,14 +876,15 @@ class WorkbookReader extends WorkbookReaderBase {
     }
     async *_processWaitingWorksheets(waitingWorksheets) {
         for (const ws of waitingWorksheets) {
-            const iterator = (async function* () {
-                for (const chunk of ws.data) {
-                    yield chunk;
-                }
-            })();
+            const part = handOut((async function* () {
+                yield* ws.data;
+            })(), `worksheet ${ws.sheetNo}`);
             yield* ws.isXlsb
-                ? this._parseXlsbWorksheet(iterator, ws.sheetNo)
-                : this._parseWorksheet(iterator, ws.sheetNo);
+                ? this._parseXlsbWorksheet(part.chunks, ws.sheetNo)
+                : this._parseWorksheet(part.chunks, ws.sheetNo);
+            // Released as the Node variant's spool file is, so a sheet read out of order fails the same way on both.
+            part.finish();
+            ws.data.length = 0;
         }
     }
 }

package/dist/esm/modules/excel/stream/workbook-reader.js

@@ -5,7 +5,7 @@
  */
 import { join } from "path";
 import { HyperlinkReader } from "./hyperlink-reader.js";
-import { WorkbookReaderBase, WorkbookReaderOptionsSchema } from "./workbook-reader.browser.js";
+import { WorkbookReaderBase, WorkbookReaderOptionsSchema, handOut } from "./workbook-reader.browser.js";
 import { WorksheetReader } from "./worksheet-reader.js";
 import { iterateStream } from "../utils/iterate-stream.js";
 import { createReadStream, createWriteStream, createTempDirSync, remove } from "#platform/utils/fs";
@@ -71,12 +71,15 @@ class WorkbookReader extends WorkbookReaderBase {
         for (const ws of waitingWorksheets) {
             await ws.writePromise;
             const fileStream = createReadStream(ws.path);
+            const part = handOut(iterateStream(fileStream), `worksheet ${ws.sheetNo}`);
             try {
                 yield* ws.isXlsb
-                    ? this._parseXlsbWorksheet(iterateStream(fileStream), ws.sheetNo)
-                    : this._parseWorksheet(iterateStream(fileStream), ws.sheetNo);
+                    ? this._parseXlsbWorksheet(part.chunks, ws.sheetNo)
+                    : this._parseWorksheet(part.chunks, ws.sheetNo);
             }
             finally {
+                // The file goes away now, so a reader not yet read must say so if it is read later rather than wait forever.
+                part.finish();
                 fileStream.close();
                 ws.cleanup();
             }

package/dist/esm/modules/excel/stream/xlsb-record-stream.js

@@ -37,26 +37,50 @@ import { recordSpec } from "../xlsb/spec/records.js";
  * what is consumed. The carry buffer grows only to the size of one record.
  */
 export async function* streamBiffRecords(chunks, part) {
-    let carry = new Uint8Array(0);
+    for await (const batch of streamBiffRecordBatches(chunks, part)) {
+        yield* batch;
+    }
+}
+/**
+ * {@link streamBiffRecords}, one array per input chunk instead of one step per record.
+ *
+ * A worksheet is millions of records — usually one per cell — and an async generator step is a promise round trip,
+ * which is what made those steps the largest single cost of a streamed XLSB read. A chunk's records are framed in one
+ * synchronous pass and handed over together; the caller still drives the stream chunk by chunk.
+ *
+ * Each record's payload is a view of a buffer this function owns and never writes to again, so a record stays valid
+ * after the next chunk arrives, however the source treats its own buffers.
+ */
+export async function* streamBiffRecordBatches(chunks, part) {
+    let carry = EMPTY;
     for await (const chunk of chunks) {
-        carry = concat(carry, Uint8Array.from(chunk));
+        if (chunk.length === 0) {
+            continue;
+        }
+        // Copied, because a source may reuse its chunk buffer and a record handed out must stay valid; joined to the
+        // unfinished tail in the same copy when there is one.
+        const buffer = concat(carry, chunk);
+        const records = [];
         let consumed = 0;
         for (;;) {
-            const framed = frame(carry, consumed, part);
+            const framed = frame(buffer, consumed, part);
             if (framed === undefined) {
                 break;
             }
             consumed = framed.next;
-            yield framed.record;
+            records.push(framed.record);
+        }
+        // Only the unconsumed tail is kept, copied, so a sheet does not pin every buffer it was delivered in.
+        carry = consumed === buffer.length ? EMPTY : buffer.slice(consumed);
+        if (records.length > 0) {
+            yield records;
         }
-        // Only the unconsumed tail is kept. Copying it rather than holding a view of the whole chunk is what keeps a
-        // sheet from pinning every buffer it was delivered in.
-        carry = consumed === 0 ? carry : carry.slice(consumed);
     }
     if (carry.length > 0) {
         throw new XlsbParseError(part, `${carry.length} trailing byte(s) do not form a record`);
     }
 }
+const EMPTY = new Uint8Array(0);
 /**
  * The record starting at `offset`, or `undefined` when the buffer does not hold all of it yet.
  *
@@ -115,11 +139,8 @@ function varUInt(buffer, start, maxBytes) {
     }
     return { value, next: offset };
 }
-/** `left` followed by `right`, avoiding a copy when `left` is empty — the common case after a clean chunk. */
+/** `left` followed by `right`, in a new buffer. */
 function concat(left, right) {
-    if (left.length === 0) {
-        return right;
-    }
     const joined = new Uint8Array(left.length + right.length);
     joined.set(left, 0);
     joined.set(right, left.length);

package/dist/esm/modules/excel/stream/xlsb-worksheet-reader.js

@@ -1,6 +1,6 @@
 import { rowCreate } from "../core/row.js";
 import { rowSetModel } from "../core/worksheet-core.js";
-import { streamBiffRecords } from "./xlsb-record-stream.js";
+import { streamBiffRecordBatches } from "./xlsb-record-stream.js";
 import { encodeCol } from "../utils/address.js";
 import { errorTextOf } from "../xlsb/error-values.js";
 import { BinaryReader } from "../../../utils/binary.js";
@@ -28,38 +28,42 @@ export async function* streamXlsbRows(chunks, part, context) {
         cells = [];
         return row;
     };
-    for await (const record of streamBiffRecords(chunks, part)) {
-        switch (record.name) {
-            case "BrtBeginSheetData":
-                inSheetData = true;
+    // Records arrive a chunk at a time; rows are still yielded one by one, so the caller sees the same sequence.
+    for await (const batch of streamBiffRecordBatches(chunks, part)) {
+        for (let index = 0; index < batch.length; index++) {
+            const record = batch[index];
+            switch (record.name) {
+                case "BrtBeginSheetData":
+                    inSheetData = true;
+                    continue;
+                case "BrtEndSheetData": {
+                    // Everything after this is sheet-level: merges, conditional formats, page setup. A forward reader has already
+                    // emitted its rows, so there is nothing left to attach them to — see the note at the top of this file.
+                    const last = flush();
+                    if (last !== undefined) {
+                        yield last;
+                    }
+                    inSheetData = false;
+                    continue;
+                }
+                default:
+                    break;
+            }
+            if (!inSheetData) {
                 continue;
-            case "BrtEndSheetData": {
-                // Everything after this is sheet-level: merges, conditional formats, page setup. A forward reader has already
-                // emitted its rows, so there is nothing left to attach them to — see the note at the top of this file.
-                const last = flush();
-                if (last !== undefined) {
-                    yield last;
+            }
+            if (record.name === "BrtRowHdr") {
+                const previous = flush();
+                if (previous !== undefined) {
+                    yield previous;
                 }
-                inSheetData = false;
+                currentRow = new BinaryReader(record.payload, 0, part).readUint32();
                 continue;
             }
-            default:
-                break;
-        }
-        if (!inSheetData) {
-            continue;
-        }
-        if (record.name === "BrtRowHdr") {
-            const previous = flush();
-            if (previous !== undefined) {
-                yield previous;
+            const cell = decodeCell(record, context, part);
+            if (cell !== undefined) {
+                cells.push(cell);
             }
-            currentRow = new BinaryReader(record.payload, 0, part).readUint32();
-            continue;
-        }
-        const cell = decodeCell(record, context, part);
-        if (cell !== undefined) {
-            cells.push(cell);
         }
     }
     const trailing = flush();

package/dist/esm/modules/excel/utils/copy-style.js

@@ -2,19 +2,33 @@
 const BORDER_EDGES = ["top", "left", "bottom", "right", "diagonal"];
 /** The facets of a style that own mutable sub-objects and therefore need copying. */
 const COPIED_FACETS = ["font", "alignment", "protection", "border", "fill"];
+/**
+ * Copy `obj` and each of its `nestKeys` sub-objects one level down.
+ *
+ * Written as one spread and direct assignments: this runs for every styled cell a streamed sheet yields, and the
+ * `reduce` into a second object that was then spread again built three objects per call to say what one does. The
+ * result is the same — every nested key already exists on the copy, so assigning it keeps its position.
+ */
 function oneDepthCopy(obj, nestKeys) {
-    return {
-        ...obj,
-        ...nestKeys.reduce((memo, key) => {
-            if (obj[key]) {
-                memo[key] = { ...obj[key] };
-            }
-            return memo;
-        }, {})
-    };
+    const copied = { ...obj };
+    for (let i = 0; i < nestKeys.length; i++) {
+        const key = nestKeys[i];
+        if (obj[key]) {
+            copied[key] = { ...obj[key] };
+        }
+    }
+    return copied;
 }
+const COLOR_KEYS = ["color"];
+const FILL_KEYS = ["fgColor", "bgColor", "center"];
+/** Whether `obj` has no own enumerable key — without allocating the key array `Object.keys` would. */
 function isEmptyObj(obj) {
-    return Object.keys(obj).length === 0;
+    for (const key in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            return false;
+        }
+    }
+    return true;
 }
 /**
  * Copy one style facet (`font`, `border`, `fill`, `alignment`, `protection`) deeply
@@ -44,7 +58,7 @@ function copyStyleFacet(key, value) {
     const facet = value;
     switch (key) {
         case "font":
-            return oneDepthCopy(facet, ["color"]);
+            return oneDepthCopy(facet, COLOR_KEYS);
         case "alignment":
         case "protection":
             return { ...facet };
@@ -61,15 +75,15 @@ function copyBorder(border) {
     const copied = { ...border };
     for (const edge of BORDER_EDGES) {
         if (border[edge]) {
-            copied[edge] = oneDepthCopy(border[edge], ["color"]);
+            copied[edge] = oneDepthCopy(border[edge], COLOR_KEYS);
         }
     }
     return copied;
 }
 function copyFill(fill) {
-    const copied = oneDepthCopy(fill, ["fgColor", "bgColor", "center"]);
+    const copied = oneDepthCopy(fill, FILL_KEYS);
     if (fill.stops) {
-        copied.stops = fill.stops.map((s) => oneDepthCopy(s, ["color"]));
+        copied.stops = fill.stops.map((s) => oneDepthCopy(s, COLOR_KEYS));
     }
     return copied;
 }